knowledge-book-analyzer

name

knowledge-book-analyzer

description

Analyze knowledge-heavy books, educational PDFs/EPUBs, nonfiction works, and long articles into evidence-based layered concept statistics, concept maps, argument chains, review cards, critical applications, and a Guofulun-style interactive visual HTML report. Use this whenever the user asks to analyze, quickly understand, reopen, or preserve a knowledge-book/long-article analysis, especially when concept frequency, keywords, theory models, or book knowledge maps matter.

Knowledge Book Analyzer

Core Rule

Prioritize accuracy over visual polish. Visualizations must be generated from extracted data or explicit analytical judgments, and important claims must be traceable to sections or evidence snippets.

Use this skill for knowledge-type works, not plot-first fiction analysis. If a user asks to reopen an existing analysis, first check the local registry with scripts/register_analysis.py find.

This skill has a visual contract: new reports should look and behave like the polished Guofulun analysis unless the user explicitly asks for a different design. Do not substitute a generic dashboard, pastel article layout, rounded-card template, or unrelated design system.

This skill also has a concept-statistics contract: do not mix raw terms, atomic concept groups, and parent theory models in one ranking. For example, a model such as "four elements" must not compete in the same concept list as its child concepts "observation / feeling / need / request".

Skill Quality Standard

This skill follows the public skill-creator pattern: capture intent, write a focused skill, include reusable resources, create test prompts, validate outputs, then iterate. Treat scripts/check_visual_parity.py as the first hard gate for visual/interaction regressions.

Quick Workflow

1. Find or create the project

   • If the user asks for an existing analysis, run: python scripts/register_analysis.py find "<title or alias>"
   • If no saved analysis exists, create a new output folder named after the work.

2. Extract and clean text

   • Prefer EPUB chapter HTML when available; otherwise extract PDF text.
   • Preserve section titles, order, and page/chapter metadata when possible.
   • Deduplicate repeated front matter, duplicated chapters, OCR echoes, and publisher junk.
   • Record quality notes before analysis.

3. Build the analysis data

   • Produce a structured JSON data file that includes metadata, sections, concepts, evidence snippets, chapter analyses, examples, summaries, flashcards, critical questions, and chart-ready aggregates.
   • Use the dimensions in references/analysis-dimensions.md.
   • Use the three-layer concept model from references/concept-statistics.md.
   • Include report.termStats for literal word counts, report.conceptCards for atomic concept groups, and report.theoryModels for parent frameworks or methods.
   • Every report.conceptCards item must include a theme field and a variants or keywords list that explains exactly which literal terms are included in that atomic concept group. Themes are visual-analysis categories such as 真实增长, 货币信用, or 冲突处理, not parent theory models.
   • Use conceptCards[].strength as a same-layer atomic concept-group count unless a report explicitly labels another metric. If you need a composite importance score, store it separately, such as salienceScore, and do not display it as a count.
   • Do not put a parent theory model into conceptCards when its children are already represented as atomic concepts.
   • If the extracted data schema differs from the Guofulun interactive_data.json schema, write an adapter layer in the generated report or a small transform script. Do not weaken the report UI because the data shape changed.

4. Write the knowledge report

   • Include every required section from references/report-spec.md.
   • Keep language analytical, not promotional.
   • Do not mention social media, posting, screenshots, or aesthetics as the purpose.

5. Build the interactive visual report

   • Make the visual report the main output.
   • Start by copying assets/knowledge_visual_layered_template.html. Do not design a new layout from scratch.
   • Preserve the Guofulun visual system unless the user explicitly asks for a different style: monochrome paper background, sticky black topbar, fixed left navigation rail, central content column, sticky right evidence inspector, bordered boards, no rounded card-heavy marketing style.
   • Preserve the layered template's theme color behavior: concept cards use themeColor(c.theme), the theme filter is populated from concept themes, constellation bubbles use the same theme colors from DATA.themes, and the star map must not fall back to black or collapse to one accent color.
   • Preserve the exact interaction model: concept cards, constellation bubbles, and chapter chips update the evidence panel; constellation hover/click highlights related concepts and relation lines; constellation clicks also show the concept group's variants/keywords; flashcards expand/collapse in place.
   • In the statistical validation section, the primary bar chart should show literal report.termStats true word frequencies. The concept constellation and concept cards show atomic concept-group counts, and must include a visible note explaining that those numbers combine variants.
   • Label the #models section as 知识模型提炼 in the UI. The section's reader-facing purpose is model/framework extraction, not teaching the reader the implementation details of concept statistics.
   • Include the same main sections and IDs: poster, structure, models, concepts, chapters, opposes, examples, learning, flashcards, critical, stats.
   • Adapt content, data, titles, concepts, examples, and evidence to the new source, but keep class names and section roles compatible with the template.
   • If a source has fewer chapters/concepts/examples than Guofulun, keep the same sections and explain gaps through quality notes or reduced card counts. Do not remove the section shell.

6. Validate

   • Verify the local HTML loads through http://127.0.0.1:<port>/..., not file://.
   • Check script syntax, missing data, visual overlap, unreadable contrast, and click behavior.
   • Run python scripts/check_visual_parity.py <report.html> before delivering the report.
   • Run python scripts/check_concept_layers.py <interactive_data.json> before delivering the report.
   • Use browser verification for the concept constellation: bubbles must not overlap, relation line widths must vary, hover/click must highlight related bubbles and lines, and clicking constellation bubbles must update the evidence inspector with the concept group's variants/keywords.
   • Start or restart a local preview server when needed.
   • If check_visual_parity.py fails, fix the report before showing it to the user.

7. Register the result

   • Save the analysis in the registry so future requests can find it: python scripts/register_analysis.py add --title "<title>" --slug "<slug>" --output-dir "<abs dir>" --main-html "<abs html>" --data-json "<abs json>" --source "<abs source>" --url "<local url>" --alias "<alias>"

Output Standards

• Explain concepts like teaching a smart 10-year-old, but keep the analysis professionally grounded.
• Separate statistical clues from interpretive claims.
• Treat frequency as evidence of salience, not automatic importance.
• For each core concept, include plain explanation, author usage, common misunderstanding, related sections, and evidence.
• For each chapter/section, include question, claim, reasoning chain, opposed view, examples, and top concepts.
• For examples, explain their function: proving a concept, explaining a mechanism, refuting a view, or showing a policy consequence.
• For learning output, include summaries, flashcards, and critical application questions.
• When visualizing relations, label that co-occurrence is not causality unless independently justified.

Useful Scripts

• scripts/register_analysis.py: add, list, or find saved analyses.
• scripts/serve_analysis.py: run a local static server for an analysis directory.
• scripts/check_visual_parity.py: check that a generated report preserves the Guofulun visual template structure and interactions.
• scripts/check_concept_layers.py: check that concept statistics use the required three-layer structure.
• assets/knowledge_visual_layered_template.html: canonical visual report template. Copy this first, then adapt it.
• assets/guofulun_visual_v1_template.html: earlier visual reference, kept for style comparison.

Self-Test Prompts

Use evals/evals.json for regression tests when improving this skill. At minimum, generated reports should pass scripts/check_visual_parity.py and scripts/check_concept_layers.py, load from a local HTTP server, include evidence-backed concept cards, and preserve constellation hover/click semantics.

References

• Read references/analysis-dimensions.md before designing a new analysis.
• Read references/concept-statistics.md before computing keywords, concept strength, or theory model coverage.
• Read references/report-spec.md before creating or modifying the HTML report.
• Read references/visual-parity-checklist.md when the output must match the Guofulun version closely.