內容優先 Markmap 思維導圖
把項目、文檔、代碼庫或概念整理成可以用 Markmap 渲染的 Markdown，並在需要時校驗結構、生成 HTML。
核心規則
- 先整體後局部：根主題說明對象和目的，再展開真實主概念、流程、模塊和細節。
- 用材料本身組織導圖。不要為了照顧小白閱讀而發明空泛分類標題。
- 去掉只起分類作用的標題，例如「項目定位」「運行機制」「開發版圖」「核心概念」「主要模塊」「使用場景」等，除非這些詞本來就是原文的一部分。
- 每個節點的直接子節點最多 7 個；優先控制在 5 個左右，只有內容確實需要時才擴展到 6-7 個。
- 不要因為真實內容很多就平舖超過 7 個分支；應按材料裡的真實子主題繼續分組。
- 如果某個層級看起來需要超過 7 個分支，先合併相近內容，再按「整體 -> 分組 -> 局部細節」重排。
- 類比是可選的。只有確實幫助記憶時才使用，並放在內容標籤之後；不能讓類比變成節點主體。
- 不要編造確定性。總結倉庫前先看 README、文檔、包配置、測試、源碼目錄和本地腳本。
- 保持導圖簡潔。節點用短內容標籤，必要時補一句有依據的說明。
處理複雜倉庫或長文檔時，先讀 references/analogy-structure.md。
工作流程
- 先檢查材料。
- 倉庫：先看
README、AGENTS.md/CLAUDE.md、包配置、文檔和頂層目錄。 - 文檔：先找主題、主張、章節、重複概念和需要記憶的術語。
- 倉庫：先看
- 從整體到局部起草 Markdown。
- 使用一個 H1 根標題說明對象。
- 使用
##展開真實內容主幹，不使用「給讀者看的分類桶」。 - 每個節點優先寫材料中的真實概念、系統、流程、文件路徑、API、主張或職責。
- 只在細節能幫助理解時繼續展開，不強行湊分支。
- 每個父節點的直接子節點最多 7 個，優先 5 個左右；超過 7 個時按真實子主題重新分組。
- 用腳本校驗 Markdown：
python3 ~/.codex/skills/markmap-analogy-mindmap/scripts/validate_and_render.py input.md --validate-only
- 需要交付 HTML 時，渲染 Markmap：
python3 ~/.codex/skills/markmap-analogy-mindmap/scripts/validate_and_render.py input.md -o output.html
- 如果校驗失敗，先修導圖結構。除非用戶明確要求非標準導圖，否則不要繞過「空泛分類」和「層級分支過多」檢查。
Markmap 渲染
腳本會按順序嘗試：
markmapnpx --yes markmap-cli- 本機
/root/markmap裡的已構建 CLI
如果沒有可用渲染器，就把已通過校驗的 Markdown 作為交付物，並說明 HTML 未生成。
輸出要求
- 創建文件後，返回
.md和.html路徑。 - 說明檢查過哪些來源，以及校驗/渲染命令結果。
- 除非用戶要求修改源倉庫，否則只讀源材料。
- 中文用戶默認輸出中文導圖；只有命令、路徑、API、包名、術語必須保留英文時才用英文。