mind-master

name	mind-master
description	Local-first Word/PDF to Markmap mind map workflow with LaTeX math, image selection, screenshot capture, validation, and SVG/PNG/PDF export.

Mind-Master Skill

Mind-Master turns a local Word or PDF document into a high-quality interactive mind map. It follows the ppt-master style: Skill entrypoint, durable reference specs, scripts for repeatable work, serial role handoff, and explicit GATE checkpoints.

The workflow is local-first. Do not upload source documents or generated assets by default.

Trigger Keywords

Use this skill when the user asks for:

• 制作思维导图
• 生成思维导图
• mind map
• mind-master
• 思维导图

Pipeline

DOCX/PDF
  -> [1. Convert Source to Markdown]
  -> [2. Initialize Project]
  -> [3. Extract Assets]
  -> [3.5 Split Section Maps, optional]
  -> [4. Strategist Outline]
  -> [5. Image/Screenshot Decision]
  -> [6. Executor Render]
  -> [7. Formula and Image Validation]
  -> [8. Export]

Highest-Priority Rules

1. Serial pipeline only. Each step consumes the previous step's output. Do not skip ahead.
2. GATE checkpoints are mandatory. At the end of each step, print a ✅ checkpoint with concrete delivered paths and wait for user confirmation before continuing.
3. Use --move for source import. After project_manager.py import-sources, the original source path should no longer retain the file.
4. Batch preread before Executor. Before the first Step 6 generation, read all relevant references/ files in one pass and do not reread them during generation.
5. Confirm design parameters before the first rendered mind map: canvas size, palette, font stack, max depth, node word limits, image mode.
6. External screenshot safety gate. Before opening any external URL, list every target URL and wait for explicit user confirmation. Local PDF screenshots are allowed without that URL gate.
7. Keep equations editable. Equations must remain LaTeX text in HTML and render through KaTeX. Do not rasterize formulas into images.
8. OCR informs image relevance only. Do not rewrite node text from OCR.
9. Output filtering hard constraints must land in three layers: reference docs, executor/render behavior, and validation checks. If any layer is missing, the constraint is not implemented.
10. Mind maps are text-first. Source figures normalize to preserve_full, preserve_crop, redraw_high_fidelity, redraw_concept, or omit; omit is the default. Screenshots/slides/photos must not be directly embedded through <img> as raw originals; use preserve_crop only for source-faithful learning evidence, and use redraw only through a registered SVG template.
11. GPT Image 2 inspired layouts are allowed only as a visual organization profile. They must keep source headings, source numbering, source_quote / source_span, tables, formulas, and figure decisions intact.
12. Never invent section numbers for derived nodes. Keywords, learning hints, or tuning implications must be titled with [*] and marked with derived_from_summary or grounded_hint; they must not become fake sections such as 5.4 or 5.5.
13. Every retained or redrawn figure must include 1 to 2 callouts, each with a short conclusion and a source_quote found in the active source.
14. Learning-poster profiles render paragraph evidence as compact numbered short sentences. Do not cut English words when shortening; keep full source_quote / source_span for validation.
15. Course-note nodes should carry icon metadata when the node type is recognizable, using simple line icons such as database, file-text, gauge, line-chart, scale, running, lightbulb, settings, list-checks, key, and wrench.
16. Compact learning poster layouts must render retained/redrawn figures as evidence cards with evidence_title, source figure label, image/redraw, and source-backed callouts. Keywords, Momentum advantages, and tuning hints must merge into one bottom learning band, not scatter as fake numbered sections.
17. Finished learning posters must be packed against the measured .balanced-layout content bbox: prefer a 16:9 canvas, accept 4:3 only when content requires it, keep top/edge/center voids small, and validate left-branch height, evidence-card compactness, compact comparison tables, and the three-column learning band.
18. Finished poster mode forbids visible overflow outside card boundaries. Evidence card images/redraws, captions, source labels, callout chips, and overlay chips must remain inside .balanced-evidence-card; fix overflow through layout/CSS/validation, not by hiding source-backed content.
19. Balanced poster connectors are semantic parent-child links, not decorative background curves. Root/H2/H3 cards must carry connector metadata (data-node-id, data-parent-id, data-connector-role, data-side), and connectors must route from parent edge ports to child edge ports with visible endpoint markers.

Required References

Read only what the current stage needs, except Step 6 where batch preread is required.

• references/shared-standards.md: global design and content limits
• references/strategist.md: Step 4 planning role
• references/executor-base.md: Step 6 common execution rules
• references/executor-classic.md: classic radial style
• references/executor-logic.md: logic tree or fishbone style
• references/executor-org.md: org or hierarchy style
• references/mindmap-formats.md: JSON, Markdown, HTML, SVG, PNG, PDF contracts
• references/math-rendering.md: OMML, LaTeX, MathML, KaTeX rules
• references/image-policy.md: image selection, screenshots, preserve/crop/redraw policy, callouts, copyright, readability

Project Path Contract

Default project root:

projects/<project_name>/

Required project layout:

projects/<project_name>/
├── manifest.json
├── sources/
├── assets/
│   ├── images/
│   │   └── index.json
│   └── equations/
├── intermediate/
│   ├── source.md
│   ├── sections/
│   │   ├── index.json
│   │   └── <section_id>.md
│   ├── outline.json
│   └── mindmap.json
├── exports/
│   ├── <project_name>.html
│   ├── <project_name>.svg
│   ├── <project_name>.png
│   └── <project_name>.pdf
└── maps/
    └── <section_id>/
        ├── intermediate/
        │   ├── outline.json
        │   ├── mindmap.json
        │   └── validation.json
        └── exports/
            ├── <section_id>.html
            ├── <section_id>.svg
            ├── <section_id>.png
            └── <section_id>.pdf

Section map mode:

• Use one project per source document or document set.
• Use one maps/<section_id>/ workspace per major document section when the source is naturally divided into lessons, chapters, or modules.
• For course notes such as # 第5节课 and # 第6节课, each H1 section becomes one independent mind map. The H1 is the map root; its H2 headings become the first-level branches.
• Do not generate all lesson maps into the repository root. Keep shared source assets under the project, and keep each map's outline, validation, and exports inside its own maps/<section_id>/ directory.

Style Selection Gate

Before Step 4, ensure the user has selected one style:

• classic: classic radial mind map
• logic: logic tree or fishbone-style reasoning map
• org: organization or hierarchy map

Default: classic.

If the project has not been initialized yet, ask before Step 2 because manifest.json records the style. If an existing project is already initialized, read manifest.json; if style is missing or inconsistent with the user request, stop and ask.

Required prompt:

Style GATE: 请选择导图风格：classic / logic / org。默认 classic。确认后我会把选择写入 manifest.json，并在 Step 4 前使用同一风格规划 outline。

Design Parameter Gate

Before the first Step 6 render, print:

• canvas size
• palette
• font stack
• max depth
• node word limits
• image embedding mode: relative or base64
• export scale

Required prompt:

Design GATE: 我将使用以下设计参数生成第一版导图，请确认后继续：
- canvas: <width>x<height>
- palette: <name>
- fonts: <font stack>
- max_depth: <n>
- node_limits: 一级≤12字，二级≤18字，叶子≤30字
- image_mode: <relative|base64>
- export_scale: <n>

Image Policy Gate

Before Step 5 opens external URLs, print every planned URL and wait for confirmation.

Required prompt:

Image/Screenshot GATE: 我准备对以下外部 URL 截图。请确认后我才会打开这些 URL：
1. <url> - <reason>

If there are no external URL intents, say so and continue. Local PDF page rendering does not require this URL gate, but still record generated screenshots in assets/images/index.json.

Document images extracted in Step 1 still pass through Step 3 classification. The image index must include type, is_data_chart, and redraw_required for every image before Step 4/5 decisions.

Step 1. Convert Source to Markdown

Role: source converter.

Inputs:

• source document: <path/to/source.docx> or <path/to/source.pdf>
• project path if already created: projects/<project_name>/

Command for DOCX:

python skills/mind-master/scripts/source_to_md/doc_to_md.py \
  --source <path/to/source.docx> \
  --project projects/<project_name>

Command for PDF:

python skills/mind-master/scripts/source_to_md/pdf_to_md.py \
  --source <path/to/source.pdf> \
  --project projects/<project_name>

Outputs:

• projects/<project_name>/intermediate/source.md
• extracted inline images under projects/<project_name>/assets/images/
• unresolved formulas as [EQUATION_UNRESOLVED:<id>]
• printed asset list

Checkpoint:

GATE 1 ✅ Source converted to Markdown.
Deliverables:
- source markdown: projects/<project_name>/intermediate/source.md
- inline images: projects/<project_name>/assets/images/
- equation cache: projects/<project_name>/assets/equations/
Confirm to continue to Step 2.

Failure helper:

• references/math-rendering.md#error-helper
• references/mindmap-formats.md#error-helper

Step 2. Initialize Project

Role: project manager.

Inputs:

• project name
• selected style: classic, logic, or org

Command:

python skills/mind-master/scripts/project_manager.py init <project_name> --style <classic|logic|org>

Optional source import:

python skills/mind-master/scripts/project_manager.py import-sources \
  projects/<project_name> \
  --move <path/to/source.docx>

Outputs:

• project directory skeleton
• projects/<project_name>/manifest.json
• source files moved into projects/<project_name>/sources/

Checkpoint:

GATE 2 ✅ Project initialized.
Deliverables:
- manifest: projects/<project_name>/manifest.json
- sources: projects/<project_name>/sources/
- assets: projects/<project_name>/assets/
- intermediate: projects/<project_name>/intermediate/
- exports: projects/<project_name>/exports/
Confirm to continue to Step 3.

Failure helper:

• references/mindmap-formats.md#error-helper

Step 3. Extract Assets

Role: asset extractor.

Inputs:

• projects/<project_name>/sources/
• projects/<project_name>/intermediate/source.md

Command:

python skills/mind-master/scripts/extract_assets.py projects/<project_name>

Outputs:

• projects/<project_name>/assets/images/index.json
• all extracted document images under projects/<project_name>/assets/images/
• image metadata fields: type, is_data_chart, redraw_required, decision_hint, optional redraw_template_id, optional redraw_instruction
• optional ocr_text fields when OCR is available

Checkpoint:

GATE 3 ✅ Assets extracted.
Deliverables:
- image index: projects/<project_name>/assets/images/index.json
- images: projects/<project_name>/assets/images/
Confirm to continue to Step 3.5 if section map mode is needed, otherwise Step 4.

Failure helper:

• references/image-policy.md#error-helper

Step 3.5. Split Section Maps

Role: section splitter.

Use this optional step when one source document should produce multiple maps, such as one map per lesson or chapter.

Inputs:

• projects/<project_name>/intermediate/source.md

Command:

python skills/mind-master/scripts/split_sections.py projects/<project_name>

Outputs:

• projects/<project_name>/intermediate/sections/index.json
• projects/<project_name>/intermediate/sections/<section_id>.md
• projects/<project_name>/maps/<section_id>/

Checkpoint:

GATE 3.5 ✅ Section workspaces created.
Deliverables:
- section index: projects/<project_name>/intermediate/sections/index.json
- section sources: projects/<project_name>/intermediate/sections/
- map workspaces: projects/<project_name>/maps/
Confirm which section_id to continue to Step 4.

Step 4. Strategist Outline

Role: strategist.

Before starting:

1. Confirm style if not already confirmed.
2. Read references/shared-standards.md.
3. Read references/strategist.md.
4. Read references/image-policy.md only for candidate image semantics, not final image decisions.

Inputs:

• projects/<project_name>/intermediate/source.md, or projects/<project_name>/intermediate/sections/<section_id>.md in section map mode
• projects/<project_name>/assets/images/index.json
• projects/<project_name>/manifest.json

Command pattern:

python skills/mind-master/scripts/project_manager.py validate projects/<project_name>

The actual outline authoring is done by the agent according to references/strategist.md.

Output:

• projects/<project_name>/intermediate/outline.json, or projects/<project_name>/maps/<section_id>/intermediate/outline.json in section map mode

Checkpoint:

GATE 4 ✅ Strategist outline complete.
Deliverables:
- outline: projects/<project_name>/intermediate/outline.json
Confirm to continue to Step 5.

Failure helper:

• references/strategist.md#error-helper
• references/shared-standards.md#error-helper

Step 5. Image/Screenshot Decision

Role: image curator and screenshot operator.

Before selecting images:

1. Read assets/images/index.json.
2. Normalize every figure to one of preserve_full, preserve_crop, redraw_high_fidelity, redraw_concept, or omit; default to omit.
3. Use preserve_full only when the full original is clear and all of it is evidence.
4. Use preserve_crop when the original figure is useful but needs white-space/title/noise removal; keep provenance in crop_source_id, crop_box, crop_focus, and crop_path.
5. Use redraw_high_fidelity when the original must be structurally preserved but is unreadable at map size; use redraw_concept only when a simplified concept sketch is enough. Missing templates must downgrade to omit.
6. Do not set legacy decision: "image" for screenshots, slides, or photos unless the renderer can normalize it to preserve_crop, redraw_high_fidelity, redraw_concept, or omit.

Before external URL screenshots:

1. Read all screenshot_intents from outline.json.
2. Print the Image/Screenshot GATE prompt with every external URL.
3. Wait for user confirmation before opening those URLs.

Inputs:

• projects/<project_name>/intermediate/outline.json, or projects/<project_name>/maps/<section_id>/intermediate/outline.json in section map mode
• projects/<project_name>/assets/images/index.json
• optional local PDF paths in projects/<project_name>/sources/

Command for URL or PDF screenshot after gate:

python skills/mind-master/scripts/screenshot_capture.py \
  --url <url|file://...pdf#page=3> \
  --selector "<css selector>" \
  --out projects/<project_name>/assets/images/screenshots/<shot_id>.png \
  --full-page false \
  --wait-for networkidle

Outputs:

• updated projects/<project_name>/assets/images/index.json
• selected image IDs recorded for Step 6
• screenshots under projects/<project_name>/assets/images/screenshots/

Checkpoint:

GATE 5 ✅ Image and screenshot decisions complete.
Deliverables:
- updated image index: projects/<project_name>/assets/images/index.json
- screenshots: projects/<project_name>/assets/images/screenshots/
Confirm to continue to Step 6.

Failure helper:

• references/image-policy.md#error-helper

Step 6. Executor Render

Role: executor.

Batch preread requirement:

Read these files once before generation:

• references/shared-standards.md
• references/executor-base.md
• references/executor-<style>.md
• references/mindmap-formats.md
• references/math-rendering.md
• references/image-policy.md

Do not reread them while generating the same version.

Inputs:

• projects/<project_name>/intermediate/outline.json
• projects/<project_name>/assets/images/index.json
• projects/<project_name>/manifest.json

Command:

python skills/mind-master/scripts/render_mindmap.py projects/<project_name> \
  --section-id <section_id> \
  --style <classic|logic|org> \
  --image-mode relative

Outputs:

• projects/<project_name>/intermediate/mindmap.json
• projects/<project_name>/intermediate/mindmap.md
• projects/<project_name>/intermediate/layout_self_check.md
• projects/<project_name>/exports/<project_name>.html

Checkpoint:

GATE 6 ✅ Mind map rendered.
Deliverables:
- mindmap json: projects/<project_name>/intermediate/mindmap.json
- mindmap markdown: projects/<project_name>/intermediate/mindmap.md
- layout self-check: projects/<project_name>/intermediate/layout_self_check.md
- html: projects/<project_name>/exports/<project_name>.html
Confirm to continue to Step 7.

Failure helper:

• references/executor-base.md#error-helper
• references/executor-<style>.md#error-helper
• references/math-rendering.md#error-helper

Step 7. Formula and Image Validation

Role: validator.

Inputs:

• projects/<project_name>/exports/<project_name>.html
• projects/<project_name>/intermediate/mindmap.json
• projects/<project_name>/assets/images/index.json

Command:

python skills/mind-master/scripts/batch_validate.py projects/<project_name>

Checks:

• no .katex-error
• every image has alt text
• every referenced image exists
• screenshot/slide/photo assets are not directly embedded unless explicitly preserved as data charts
• repeated generic placeholder SVG curves are absent
• max depth is respected
• node word limits are respected
• H2/H3 coverage is complete through coverage_report
• source H2/H3 section numbers are visible in rendered node titles and section_id metadata
• every source table, display formula, and active-section image has an explicit disposition
• no rendered node introduces a source-style section number absent from the active source
• derived nodes are explicitly marked with derived=true or grounded_hint=true, include derived_from, and never use source-style section numbers
• figure decisions use only preserve_full, preserve_crop, redraw_high_fidelity, redraw_concept, or omit
• retained/redrawn images meet readability thresholds and carry grounded callouts
• short text compression does not cut English words, and auto density nodes stay inside their owning source_span
• keywords nodes render as capsule terms when source terms support them
• summary details are complete source-backed sentences, not noun phrases
• H3 nodes carry at least four details or are merged before render
• layout_profile has a legal mode, density score, and complete first-level branch weights
• exported PNG/SVG aspect ratio is not an extreme vertical strip when exports exist
• source_fidelity remains complete after layout switching
• poster_packing measures content_bbox_ratio, top_blank_ratio, center_void_ratio, edge_blank_ratio, and poster_aspect_ratio
• batch_height_compactness measures left_branch_height_ratio, table_compactness, and evidence_grid_compactness
• evidence_compactness checks visible evidence titles/callouts, media-area ratio, and card height
• evidence_overlay_metadata checks that optional figure overlays have source-backed metadata and render visibly
• connector_target_clarity checks that connectors attach to explicit source/target card edge ports
• connector_endpoint_visible checks that every connector has a visible terminal marker
• connector_crossing_limit checks connector-to-connector crossings remain minimal
• connector_outside_card_ratio checks connector samples stay outside non-target card bodies
• connector_parent_child_mapping checks rendered connector source/target IDs match node parent metadata
• evidence_card_containment checks all evidence-card internal elements stay inside the card
• evidence_chip_overflow checks callout chips wrap/clamp instead of spilling outside the card
• overlay_inside_media_bounds checks overlay chips stay within the evidence media area
• node_overflow_detection checks rendered nodes do not visibly overflow their own boxes
• evidence_caption_containment checks captions and source labels remain inside the evidence card
• learning_band_compactness requires exactly three columns, at most 10 rendered keywords, and a 12-15% max band height

Regression command before Step 8:

python -m unittest discover -s skills/mind-master/tests -p "test_*.py"

Any regression failure blocks export.

Checkpoint:

GATE 7 ✅ Formula and image validation passed.
Deliverables:
- validated html: projects/<project_name>/exports/<project_name>.html
- validation report: projects/<project_name>/intermediate/validation.json
Confirm to continue to Step 8.

Failure helper:

• references/math-rendering.md#error-helper
• references/image-policy.md#error-helper
• references/shared-standards.md#error-helper

Step 8. Export

Role: exporter.

Inputs:

• projects/<project_name>/exports/<project_name>.html

Command:

python skills/mind-master/scripts/export_mindmap.py projects/<project_name> \
  --section-id <section_id> \
  --html projects/<project_name>/exports/<project_name>.html \
  --scale 2

Outputs:

• projects/<project_name>/exports/<project_name>.svg
• projects/<project_name>/exports/<project_name>.png
• projects/<project_name>/exports/<project_name>.pdf

Checkpoint:

GATE 8 ✅ Export complete.
Deliverables:
- html: projects/<project_name>/exports/<project_name>.html
- svg: projects/<project_name>/exports/<project_name>.svg
- png: projects/<project_name>/exports/<project_name>.png
- pdf: projects/<project_name>/exports/<project_name>.pdf
Workflow complete.

Failure helper:

• references/mindmap-formats.md#error-helper

Agent Operating Notes

• Rebuild context from docs/session_state.md first if it exists, then docs/progress.md, then evidence summaries under results/latest.
• Check dirty files before editing.
• Prefer existing scripts over ad hoc shell fragments once scripts exist.
• Keep generated artifacts inside projects/<project_name>/.
• When a step is blocked, report the exact missing input and the helper section to inspect next.