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，非本包发布物，每检都由一次真实返工沉淀）：

已退役（问题域结构性消失）：定义挂点闸（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 已钉）。