# Mindmap Engineering

> 思维导图工程化产出流程。凡任务涉及「导图、思维导图、xmind、全景图、结构图、脑图、按图梳理项目」——无论新做、改图、还是验收——都必须先加载本 skill：读标准基线与踩坑全集、走数据/构建分离流水线、词条收录走代入测试（信息增量定律）、过词条五闸+增量闸+QA 八检、validate 0 错、交付覆盖清单。不读标准直接动手=历史重演。

- Skill: `chestnuts-sisyphus/mindmap-engineering` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add chestnuts-sisyphus/mindmap-engineering`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chestnuts-sisyphus/mindmap-engineering/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: Chestnuts-Sisyphus (https://skillmd.com/u/chestnuts-sisyphus)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/chestnuts-sisyphus/mindmap-engineering

---


# 导图工程（mindmap-engineering）

产出符合既定标准的思维导图的工程化流程。**任何导图任务开工前，按顺序完成本文件的「开工三件事」，不许直接动手拼图。**

## 开工三件事

1. **读标准全集**：记忆库 `xmind-style-baseline`（视觉+内容双基线、QA 机器防线两代、踩坑全集）和 `xmind-cli-local-generation`（CLI 出图流程与坑）。改前先 grep 记忆目录——历史教训：agent 当晚未查记忆、自造 `"folded": true` 写错折叠键，打开无折叠实锤返工。
2. **标准不可擅改**：2-7 字铁律、禁标点等标准曾被擅改（先放宽 2-9 又改微命题 6-15）均被打回。标准以本 SKILL 为唯一正本；觉得标准不合理，按标准修订流程提出，**不许在产出中自行放宽**。
3. **确认交付口径**：一口气到终形态（禁挤牙膏式分批交付，批 merge 叠加曾把 CM 图结构搞烂）；闭包铁律（冷读者只看图懂一切）。

## 管辖与产物归属（2026-09-18 作者裁定）

本 skill 项目的边界**仅限导图生成与更新的能力本身**（标准、流水线、闸门、工具链）。能力的一切**产物**——成品图、阅读稿、体检报告、覆盖清单、被吸收进图的项目资产——**不归本能力项目管**，归**使用该能力出图的那个主体项目**管：产物落盘与状态回写进主体项目（交接文档/状态区/线手册），产物内容层面的欠账（闸门待分诊、覆盖留白、返修）是主体项目的工单。本 skill 只认领能力面问题（工具与闸的正确性、标准修订、管线升级）。改能力与清产物是两类任务，分开立项。

## 文中私有名字的指代（一句话讲清，便于外部读者解析）

正文偶尔出现三个不属于本包的名字，它们只是历史语境，不是依赖项：

- **Connectome** —— 作者侧一个长期项目的代号，也是本能力最早服务的那张大图的名字；文中只以图名/历史文件名出现。
- **ZCode** —— 上一代开发 agent 工具的产品名，本包的标准与闸门多数是在它的工作区里被反复返工磨出来的；本包不依赖它。
- **MindmapLoop** —— 作者侧「导图生长循环」实验会话的名称，指「让 agent 反复出图、再由冷读者盲读校准」那条试验线。

## 双基线速览（细节以记忆库为准）

**视觉**：白底、Rainbow 六色、右向（真源=rootTopic.extensions 的 right-number + sheet 级 skeleton，structureClass 不是真源；构建脚本必须自动设 right-number=一级分支数）；字体全局替换 Georgia+思源宋体，深层节点显式挂字体；`topicPositioning: "free"`；content.json 才是真数据，content.xml 是占位警告页。

**总定义（09-06）：导图 = 针对一个主体的穷尽延伸。** 三条推论：①单一主体——每个节点必须答得出「它是主体的哪一层延伸」，答不上=游离内容（跨支重复检示众）；②穷尽——主体的事实 100% 入图或显式留白（信息量对账管，双向闭包）；③延伸——读图=从主体沿叙事向外走，首现即释/类目合同/一级预算都是这条定义的机械推论。开工第一问：这张图的主体是什么，一句话钉死——主体含糊，分类层必臃肿。

**定义笔记化（2026-09-08 定稿、09-09 收录定律补全，旧【定义】节点体系整体退役）**：定义退出树节点，活在一份数据层的**词条表**里（词 → 一段话释义：白话+机制、术语照留、标点正常写）。构建时由注入纯函数（`def_notes.build_note_text`，项目侧数据层模块，非本包发布物）把释义**全附**到词的每个使用点 notes。定稿排版：**一条笔记=一棵文字小树**——顶格行=标题命中的词条；谁的定义文本里用到了别的词条，谁的行缩进两格挂在引入者下面；同级按引入先后；一个词在一条笔记里只出现一次（挂首引入处）。**链闭到底**：笔记里出现需要定义的词，其释义就在本条笔记下面排出来，依赖图无环（环=循环定义，闸拦死）。**职责分立**：笔记=释义（一段话说清指什么），树=展开（原话全文/例子/推导/罗列留在树上）。

**词条收录定律（09-09 定，取代事故名单式的不完全归纳）**：**信息增量**——把词的日常读法代入它在图里的每个使用点，有一处读歪才收录（释义写清歪在哪、正解是什么，进 TERM_LEDGER 台账）；处处读不歪不收录。词典日常词收录无台账理由=理由闸阻断；词典外词天然失真免理由。**生成自由**：树怎么长是 AI 的自由，标准只在成品把关——树孩子信息若已被笔记覆盖=零增量=重复释义，增量闸示众、AI 分诊（拆/留/进 REDUNDANT_KEEP 台账）。

**三源归约**：标题每个 token ∈ 词典（jieba，日常语言的机器化身）∪ 图内词条表 ∪ 豁免台账——字母串唯一通行证是词条表；词典词的透明组合（可分解为词典词）=日常语言可构造，不报候选。

**内容**：节点=微命题，**分级字数**——组织节点（有孩子）2-7 字导航标签、叶子节点（无孩子）2-12 字成句；禁 `：·→—/，、；。！？`；**拆链不删词铁律（09-12 定，可读性第一）**——一个节点装不下的信息量必须拆成父子命题链（父=类目短标签、子=成员成句，读下来是一句人话），**禁止删词凑字数（削足适履=违规）**，宁可多拆一层也不许压缩丢对象（2-7 字铁律下的压缩不能丢对象，命题链才是正解）；**建块点刀铁律（09-12 定）**——每个多子话题节点首子=「本块讲什么」白话，内容点明这一层是什么刀（为什么同级），父子=类目+成员、命题链读法天然说清上下级（循环五步→取题→挑本拍干哪根）；每级兄弟同一把分类刀（穷尽+互斥），混轴拉平=病；**冷读者叙事铁律（09-06 定稿，最高验收线=第一次了解的人只靠读图就懂全景+全部细节；笔记化后读图=标题流+点开笔记）**：①词条覆盖——标题里的非日常词必须收进词条表（覆盖闸，三源归约口径），释义由笔记全附到每个使用点；命名讨论（为什么叫X）照旧挂内容现场、不得先于介绍；②词条合同——释义禁复述术语（背题→背题致失效=回声，禁复述闸拦）、禁黑话释黑话、禁未接地代号；③类目合同——抽象类目首子=「本块讲什么」白话；④一级预算——root 直系 ≤9 支，二级分类收敛靠合并不靠新开；⑤成绩口径（上下文继承）——百分数/小数首次出现处两跳内须有「对象+占比」白话孩子；同支线后续数字继承上下文直接放行，数字有上下文不必重复解释，禁汉字拼数躲检查；⑥禁止前置词典支——词条表在数据层，树上不许出现词汇支（闪黑图前置词汇支已退役为笔记）；例子单独占层；无 labels/markers/关系线；折叠=递归多层预算（子树预算 50）+单链不折，折叠键是 `"branch": "folded"` 不是 `"folded": true`；叶子=原子事实，概括层必须列全成员。

## 流水线（数据/构建分离，别手拼 content.json）

范式按角色拆成五件（**包内已给出可跑的最小样例**：`examples/example_data.py` 是数据层、`examples/example_build.py` 是构建与组装并自带过闸自证，成品校验落在 `tools/validate_xmind.py`；而服务于某一具体项目的参考实现——改名映射、家族合并、计划表重组那套——随作者的本地工作区走，不随包发布，外部使用方按下面的角色自建同名职责即可，接口口径以本节为准）：

- 内容源（`cm_data_*.py`）—— `node = [title, [children]]`；每支平铺直挂，深层结构交给计划表
- 结构重组器（`cm_restructure.py`，非本包发布物）—— 改名映射（RENAME_MAP）→ 去重 → 家族合并（MERGE_FAMILIES，**跑不动点**）→ PLANS 计划表重组（覆盖断言：漏挂/多挂都报错）→ 一级收拢 → 扇出闸
- 组装器（`build_cm_closure.py`，非本包发布物）—— 组装+五道闸+QA 八检，自跑自检，不过不出图
- 通用 QA 模块（`mindmap_qa.py`，非本包发布物）—— 任何导图可 import；`qa_xmind(path)` 可对已出图 xmind 事后体检
- 笔记注入纯函数（`def_notes.py`，非本包发布物）—— 词条表→使用点 notes，文字小树排版

新导图至少做到：内容进数据文件、结构进构建脚本、机器检查进闸门。禁止手写几千节点的 content.json。

## QA 机器防线（两代，缺一不可出图）

**一代闸**（构建器内，阻断级）：禁标点；**词条五闸**（笔记化换防上岗，cm_restructure+def_notes）：禁复述闸（check_term_echo，回声定义=阻断）、**理由闸**（check_term_reason，词典日常词收录无失真理由=阻断）、死词条闸（check_dead_terms，全图标题零使用=阻断）、链闸（check_term_chain + check_term_cycles，释义里非日常词必须∈词条表+依赖无环=阻断）、覆盖闸（check_lexicon_closure 三源归约：词典∪词条表∪豁免台账，字母串未定义阻断、中文候选一次性建账）；**增量闸**（报告级，def_notes.check_note_redundancy，项目侧脚本非本包发布物：树孩子信息已被笔记覆盖=重复释义示众，AI 分诊拆/留/进 REDUNDANT_KEEP 台账）；**成绩口径闸**（数字裸奔阻断+上下文继承，check_number_grounding）；**一级预算闸**（root 直系>9=阻断）；字数 2-7（词条表键作 ASCII 标题豁免字数）；黑话闸（整题纯 ASCII 未注册=阻断；**混排标题里的英文串同样须注册**，数字尾巴代号/纯大写缩写/放行清单三类豁免）；扇出≤13+平铺堆主题闸。

**二代八检**（`mindmap_qa.py`，非本包发布物，每检都由一次真实返工沉淀）：

| 检查 | 级别 | 抓什么 | 历史实锤 |
|---|---|---|---|
| 链条改名 | 阻断 | RENAME_MAP 的 value 不得再是 key | 映射不迭代，A→B→C 只走一步，静默漏改 9 条 |
| 家族 canon 毒化 | 阻断 | fam[0] 不得是改名键 | FAMILY_CANON 反向解析回不存在的旧标题→覆盖断言远端报错 |
| **禁复述** | 阻断 | 释义以词名开头且只多≤3字=回声定义 | 背题→背题致失效（09-06 实锤） |
| **理由闸** | 阻断 | 词典日常词收录进词条表但台账无失真理由 | 09-09 废事故名单（不完全归纳），代入测试接位；拍板/终审/素材等纯日常词已删 |
| **死词条** | 阻断 | 词条全图标题零使用（只活在别的释义里不算使用） | 闪黑「驱动分支」零使用被拦下删除 |
| **链闭合+无环** | 阻断 | 释义里的非日常词必须∈词条表；A用B且B用A=循环定义 | 内核↔插件互引成环实拦；蒸馏↔资产改写 |
| **增量闸** | 报告 | 树孩子信息已被笔记覆盖=零增量=重复释义；整支皆释义可清成裸词条 | 09-09 首跑 CM 124 处全分诊（拆 118/留 6 进 REDUNDANT_KEEP）；记忆系统「管AI记事」类复述 |
| 字母码 | 报告 | 1-3 位纯字母 run（前后不贴数字） | 可蒸出af 全文裸奔；混合码漏过黑话闸 |
| 变体兄弟 | 报告 | 同父字符多重集相似度≥0.75 | 指标是自报黑箱×4 种词序并存；**按父节点身份分组**，同题跨支不是兄弟 |
| 机械包装组 | 报告 | 主体/明细N | 批合并脚手架残留 30 处，判「无逻辑」 |
| 导览缺失 | 报告 | 每支首子节点=本支讲什么+白话孩子 | 19 支补齐后才过冷读者测试 |
| 类目导览缺失 | 报告 | 二级类目（root 直系的孩子，≥2 子）首子=本块讲什么；名即内容的进 GUIDE_EXEMPT 台账带理由 | 09-06 两图类目层补齐白话导览 |
| 跨支重复 | 报告 | 同标题出现在多个一级支下=分类刀没切干净或漏归位 | 09-06 首跑即抓体裁专名跨支复用 |

**已退役**（问题域结构性消失）：定义挂点闸（LCA/主题支/前向引用）、唯一性闸、空壳闸、归位轮 auto_rehome_defs、词卡报告（定义不占树位，「挂哪」不存在）；事故黑话名单 INCIDENT_TERMS/TW_INCIDENTS（不完全归纳，09-09 废）→代入测试收录程序+理由闸接位。

**分诊纪律**：报告不是噪音是工单。逐条处置，三选一——①改名统一（RENAME_MAP，一步到终值）②家族合并（MERGE_FAMILIES）③进豁免台账（必须带理由：正交两半、互补命题、编号系列、名字已点刀）。数字序数同框（PIPL第四条×第六条）自动放行。交付时报告必须是 0 项或台账清零。**处置自主**：分诊按规则自决，不许挂起等人——进台账带理由即视为已处置，该拆的拆、该留的留、该改名的改名，一次到终态。

## 交付闸铁律（09-07 拍板：生成和更新必须走这条线，任何图 100% 合规）

0. **入线铁律（最高一条）**：思维导图的**生成和更新只有一条合法路径**——数据文件→构建器→五道闸+QA 八检→`tools/validate_xmind.py` 过闸→交付。禁手拼 content.json、禁手改 xmind 成品、禁绕开管线直接交付。图是谁产的（本会话、外派会话、其他 agent）无关紧要；没有数据文件的外部图需要修改时，先按数据/构建分离范式数据化，再走管线。
1. **闸只认树不认人**：交付前必须过成品校验闸 `python tools/validate_xmind.py <文件.xmind>`，退出码 0 才许交付。阻断级不过=回数据文件重建。（本文件旧版用抽象名 `validate_map` 指代这道闸，自 09-19 起一律改用上面这个可执行名，二者是同一道闸。）它实装内容标准最低集八项：禁标点、分级字数（组织节点 2-7／叶子 2-12，纯 ASCII 标题=词条表键豁免）、一级预算 ≤9、扇出 ≤13、笔记结构四不变量（行形态/顶格词名在标题/一词一次/依赖链闭无环）、right-number 与一级分支数一致、折叠键（只认 `"branch": "folded"`，`"folded": true` 一类桌面不读的键点名）、零视觉标记（节点不带 labels/markers、表内不挂关系线）；退出码 0=全过、1=点名违例（节点 ID + 规则名），坏包（非 zip／缺 content.json）退 2 而非静默通过；`--self-test` 用内置合成夹具自证每一检会响。它查的是**内容标准**，与官方 `xmind` CLI（本机实测 0.2.3）的 `validate <文件>` 各管一半——CLI 查五类结构问题：id 唯一性、range 边界、summary 配对、关系端点、theme 角色。退出码语义（本机逐条实跑）：0=结构通过（警告不影响退出码，`--json`/`--quiet` 可切输出形态）；1=失败且形态可辨（文件缺失 ENOENT / 非 zip 文件 / `Invalid .xmind: missing content.json` / 截断 zip / 缺参数 / 未知子命令）。把 PATH 清空后再跑仍以 1 退出并报 node 不可用，**不会静默假通过**；Windows 下它经 npm shim 安装，非 shell 上下文调用要用 `xmind.cmd`。两条闸都过才算交付（结构面 + 内容面），输入契约都是 `content.json` 的 rootTopic + children.attached 树。任何会话/工具可对**任何**成品图随时一键复验——没走这条线的图，验一次就现形。
2. **构建期笔记全附**：五个构建器（CM/终审包/二号机/成果图/闪黑研究）出图前由 `def_notes.build_note_text`（项目侧模块，非本包发布物）把词条表释义注入每个使用点 notes——全附由构造保证，新图构建自动继承。笔记结构不变量（行形态/顶格词名在标题/缩进=依赖/一词一次）由 `tools/validate_xmind.py` 对成品复验。
3. **死词条处置**：词条全图零使用=死词条闸拦。两条路——补一个真正用到它的标题（词有价值），或从词条表删除（概念没活进正文）。不许为过闸硬塞没头没尾的使用点。
4. **报告级≠放行**：`tools/validate_xmind.py` 的报告级候选若与构建器台账口径不同（体检用默认参数），需对照构建器的 ALLOWED_ASCII/variant_ignore/def_card_exempt 台账判读；无台账对照时逐条分诊。
5. **成品图修复路径**：只有数据文件、没有构建器的外部图（如无限进步会话产物）被闸拦下时，两条合法路——补数据文件走构建器重建，或交导图循环会话按数据/构建分离范式数据化。直接手改 xmind 交付=违规。

## 交付四件套

1. 双闸并列，缺一不算交付：
   - **结构面**——`xmind validate <文件.xmind>` 0 错 0 警告（官方 CLI，Windows 非 shell 上下文用 `xmind.cmd`）；
   - **内容面**——`python tools/validate_xmind.py <文件.xmind>` 退出码 0（包内成品校验闸，点名违例时退出码 1，坏包 2）。
2. 五道闸+QA 八检全绿，报告 0 项（或豁免台账全带理由）
3. 覆盖清单：入了哪些资产、哪些留白及原因、QA 分诊台账
4. 冷读者自验（AI 自足，不依赖外部验收）：每分支自拟「冷读者会问的问题」清单、2 跳内有答案（点开笔记也算答案）；路径连读成句；无裸名词、无削足适履压缩；读图=读标题流+点开带图标的笔记。自验不合格=回数据文件重建，不许交付。

## 更新已有导图（CM 图=推进标准时代的核心场景）

图会随主体状态持续更新。更新走 `references/update-protocol.md` 的六步协议，要点：

- **图是构建产物，禁手改 xmind**——唯一合法路径=改数据文件→重建；图是数据的确定性函数（幂等已验证）
- **归类优先（09-06 铁律）**：新内容先按骨架职责归入既有支/既有类目；词条（新术语）必须随正文首用处入图并带白话定义，**禁新开词典支、禁新开平行类目**——全骨架都容不下才允许动骨架，且要说明哪两支合并腾位
- 每次真实更新自动产出：时间戳备份（可整版回滚）+ `diff_report.txt`（增/删/改名三分类）+ 构建台账
- 闸门和 QA 每次都扫全图，标准只紧不松——旧内容违新标准同样被拦
- 更新收尾必须包含：diff_report 人工过目 + qa_report 分诊清零 + 覆盖清单

## 详细踩坑史

视觉坑、CLI 坑、内容组织坑、管线坑、协作坑的全量清单见 `references/pitfalls.md`——改图/排障前先读对应小节，别再踩一遍。更新流程细节见 `references/update-protocol.md`。

## 本包自身的发布闸（改 SKILL.md / references 后提交前必跑）

导图成品走上面的闸，**本包文本走这两道闸 + 一个发布入口**，两道闸退出码都为 0 才允许提交：

1. `python tools/preflight.py` —— 发布面预检（零写盘）：本机痕迹（8.3 短名通用式、盘符绝对路径、用户目录段、本机账号名）、凭据形态、相对链接与双链方括号指针的死链、被 `.gitignore` 排除的私有件点名、双语章节结构漂移、身份词回归。只报「文件:行号 + 规则名」，绝不输出命中内容。`--self-test` 用人造违规自证每类都会响。
2. `python tools/publish.py` —— 发布入口（三者中唯一写盘）：主正本文本套发布面变换表写入仓库镜像，并把 `tools/**` 分发回各处安装点正本，因此安装点内也有 `tools/`、上面两条闸在正本目录里同样可跑；幂等，`--check` 只报漂移不写盘。
3. `python tools/sync_check.py` —— 正本与镜像一致性：本地编辑正本（默认三处安装点，可用位置参数或 `MINDMAP_SKILL_MASTERS` 覆盖）与仓库公开文件逐文件比对；目录不存在即跳过，本机无正本时退出码 0（外部用户可忽略）。

**正本保留原文、发布面经变换**：两者之间隔着 `tools/preflight.py` 里那张发布面变换表（身份匿名化 + 本机路径通用化 + 指向包外文档的指针改写）。改文本一律改正本，再由 `tools/publish.py` 套这张表生成仓库内容；`sync_check` 按「仓库 == 变换后的正本」比对，所以「正本改了没发布」与「发布了没脱敏」都会报警。行尾统一 LF（`.gitattributes` 已钉）。