# Markmap Analogy Mindmap

> 生成以内容为主的 Markmap 思维导图，用于项目、文档、代码库或概念梳理。Use when Codex needs to create Markdown/HTML mind maps that explain source material from whole to parts, keep real content as the structure, and by default limit every level to at most 5 direct children unless the user explicitly allows more.

- Skill: `fengyunzaidushi/markmap-analogy-mindmap` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add fengyunzaidushi/markmap-analogy-mindmap`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fengyunzaidushi/markmap-analogy-mindmap/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: fengyunzaidushi (https://skillmd.com/u/fengyunzaidushi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/fengyunzaidushi/markmap-analogy-mindmap

---


# 内容优先 Markmap 思维导图

把项目、文档、代码库或概念整理成可以用 Markmap 渲染的 Markdown，并在需要时校验结构、生成 HTML。

## 核心规则

- 先整体后局部：根主题说明对象和目的，再展开真实主概念、流程、模块和细节。
- 用材料本身组织导图。不要为了照顾小白阅读而发明空泛分类标题。
- 去掉只起分类作用的标题，例如“项目定位”“运行机制”“开发版图”“核心概念”“主要模块”“使用场景”等，除非这些词本来就是原文的一部分。
- 每个节点的直接子节点默认最多 5 个，这是默认硬约束，不是建议值。
- 只有用户明确声明“可以更多分支/可以超过 5 个/最多 N 个”时，才允许提高上限；提高后仍应尽量克制。
- 不要因为真实内容很多就平铺超过 5 个分支；应按材料里的真实子主题继续分组。
- 如果某个层级看起来需要超过 5 个分支，先合并相近内容，再按“整体 -> 分组 -> 局部细节”重排。
- 类比是可选的。只有确实帮助记忆时才使用，并放在内容标签之后；不能让类比变成节点主体。
- 不要编造确定性。总结仓库前先看 README、文档、包配置、测试、源码目录和本地脚本。
- 保持导图简洁。节点用短内容标签，必要时补一句有依据的说明。

处理复杂仓库或长文档时，先读 `references/analogy-structure.md`。

## 工作流程

1. 先检查材料。
   - 仓库：先看 `README`、`AGENTS.md`/`CLAUDE.md`、包配置、文档和顶层目录。
   - 文档：先找主题、主张、章节、重复概念和需要记忆的术语。
2. 从整体到局部起草 Markdown。
   - 使用一个 H1 根标题说明对象。
   - 使用 `##` 展开真实内容主干，不使用“给读者看的分类桶”。
   - 每个节点优先写材料中的真实概念、系统、流程、文件路径、API、主张或职责。
   - 只在细节能帮助理解时继续展开，不强行凑分支。
   - 每个父节点的直接子节点默认最多 5 个；超过 5 个时按真实子主题重新分组。
3. 用脚本校验 Markdown：

```bash
python3 ~/.codex/skills/markmap-analogy-mindmap/scripts/validate_and_render.py input.md --validate-only
```

如果用户明确允许更多分支，才可指定更高上限：

```bash
python3 ~/.codex/skills/markmap-analogy-mindmap/scripts/validate_and_render.py input.md --max-children 7 --validate-only
```

4. 需要交付 HTML 时，渲染 Markmap：

```bash
python3 ~/.codex/skills/markmap-analogy-mindmap/scripts/validate_and_render.py input.md -o output.html
```

5. 如果校验失败，先修导图结构。除非用户明确要求非标准导图，否则不要绕过“空泛分类”和“层级分支过多”检查。

## Markmap 渲染

脚本会按顺序尝试：

1. `markmap`
2. `npx --yes markmap-cli`
3. 本机 `/root/markmap` 里的已构建 CLI

如果没有可用渲染器，就把已通过校验的 Markdown 作为交付物，并说明 HTML 未生成。

## 输出要求

- 创建文件后，返回 `.md` 和 `.html` 路径。
- 说明检查过哪些来源，以及校验/渲染命令结果。
- 除非用户要求修改源仓库，否则只读源材料。
- 中文用户默认输出中文导图；只有命令、路径、API、包名、术语必须保留英文时才用英文。