万象-交接手册生成

解决的问题：先分线，再动手

「交接」按交出去的东西分三条线，动手前先判线：

手册线的典型场景：用户要把自己手上全部后续工作交给另一个人（或另一个 AI 会话）独立完成。
难点不在"把步骤写下来"，而在三件事（三线共用）：

1. 写的人以为对方知道，其实对方什么都不知道 —— 环境、约定、踩过的坑，全在写的人的脑子里。
2. 不勘察就动笔 = 写一篇正确的空话 —— 路径、版本号、计数没核验过，接手者照做立刻碰壁。
3. 不敢写"我不知道" —— 把未知点藏起来，接手者踩到坑时会以为是自己错了。
   手册里的路径、版本号、计数如果没有实地核验，接手者照做会立刻碰壁，然后就不再信任这份手册。

三线共用的方法论：勘察优先 → 分线定骨架 → 未知点单列成章 → 找资源写成升级链。

三线常配合：手册是"长期教材"，快照是"当前页码"，打包是"实物搬运"。
手册要指向快照（在权威源索引里列出快照路径与核验方法），不要试图把状态抄进手册。

另外两篇：交付域的前置动作（D / E）

A/B/C 三条线管的是「把东西交出去」；D/E 两篇管的是「交出去之前，东西本身对不对、看不看得懂」：

为什么放在同一部：这三件事是同一个任务链的三段 ——
D 保证东西是真的（口径一致）→ E 保证东西看得懂（出图）→ A/B/C 保证东西交得出去。

篇序按「校验 → 出图 → 交接」，但真要按哪篇动手，看任务本身，不强制顺序。
五篇共用的方法论只有一条：别凭印象，去核实物 ——
D 篇把它写成了铁律（期望值从实物取），A 篇的勘察、B 篇的校验值、C 篇的可核验项，用的是同一条。

第 A 篇 · 交接手册（知识线）

A1 勘察（不做这步不许动笔）

动笔前必须把手册里要写的每个"具体值"实地核一遍。核到能写进手册的那个粒度。

勘察清单（按需裁剪，但前四项必做）

勘察的三条纪律

1. 核验过的写具体值 + 核验时间（核验于 2026-08-28）。没核过的不要写具体值，
   写成"待核验"并放进第 9 章。两者混在一起最危险。
2. 核验结果与既有文档冲突时，信实测，并且把冲突本身写进手册（这是接手者需要的判断依据）。
3. 勘察本身会发现"用户没提到但很重要"的事。例如：两个仓库都只有本地提交、没有 remote
   → 这往往是接手者该做的第一件事，而且常常是唯一必须用户本人动手的环节。这类发现要提到显眼处。

A2 11 章骨架（按这个顺序写）

> 顺序不是随意的：先让接手者知道"你是谁、在哪、别碰什么"，再给流程，最后给"不知道怎么办"。

A3 第 0 章与第 9 章怎么写（这两章决定手册的成色）

第 0 章 · 开门三件事

先给环境事实表（解释"为什么本机手册在这台电脑上不一定成立"）：

| 事实 | 后果 |
|---|---|
| 工作目录是 X，但大部分资产在 Y | 别只在当前目录找 |
| shell 是 Z | 路径要这样写 |
| Python/Node 在哪个绝对路径 | 用绝对路径，不用裸命令 |

再给红线清单（10 条左右，编号，每条一句话）。
红线要选"一旦违反就无法回滚或代价极大"的，例如：
- 不要同步派生产物（必冲突且覆盖经验）
- 不要手工全文替换命名（会伤触发词，实测踩过）
- 不要无脑跑某个危险命令（会把计数归零）
- 不要收外部反馈里的"实现"（法律后果：对方可主张共有著作权）
- 不要在个人目录做递归删除

> 红线的写法要点：每条后面用括号点出后果。只说"不要做 X"，接手者会想"为什么不能"。

第 9 章 · 未知点·风险·需确认

这一章要拆成五节，性质完全不同，别混在一起：

9.1 的每项必须带三列：现状 / 为什么需要用户定 / 确认方法。
"确认方法"是让接手者能自己判断这一项是否已解决——没有确认方法的未决项，等于没写。

9.5 的方法论内核：先判性质。

这是「我不知道」（信息缺口）→ 去查：先验真伪，再取一手源，交叉验证
这是「我做不到」（能力缺口）→ 走第 8 章升级链
这是「没定」（决策缺口）   → 问用户，不要替他决定

> 三类缺口解法完全不同。 把决策缺口当信息缺口去"查"，就是在替用户做决定。
> 把能力缺口当信息缺口去"查"，就是查一下午然后说"查不到"。

9.5 还要给查证纪律：
- 查之前先立判据："什么叫查到了？"写下来再去查。
- 一手源优先 + 至少两个独立来源。
- 警惕假成功：实测教训要写进去（如镜像源 HTTP 200 但 0 字节，只看状态码会被骗）。
- 留痕：源清单含 URL、抓取时间、字节数、原文关键段。

A4 第 8 章怎么写：找资源必须是升级链，不是一句话

❌ 差写法：「如果不会，可以用技能市场搜一下。」

✅ 好写法：编好号的逐级升级链 + 失败出口。

① 任务是否命中已有技能？ → 先查本地技能库（看 name / description / triggers）
② 没命中 → 搜技能市场（找现成的；关键词用中英双语，命中率更高）
③ 市场也没有 → 自己造（用 skill-creator）
④ 需要外部连接器/数据源？ → 搜连接器候选 → 提交给用户决定
⑤ 需要专业判断、深度研究、多角色协作？ → 找专家（说明入口在哪）
⑥ 跨会话/跨项目历史？ → 用历史检索工具（比逐个读文件高效）

必配的三张表：

A5 其他成文要点

1. 每条流程都要有"判据"列，且判据必须可查：文件在不在、计数几个、状态码多少。
   绝不写"完成即可""感觉通了"。判据不可查的流程等于没有流程。
2. 把"用户踩过并自行纠正的错"写进去，包括写的人自己犯的错。
   例：曾把某现象错误归因为"上下文将满"，后自行推翻。
   这类"已纠正的认知"最有价值 —— 接手者最容易踩同一个坑。
3. 区分"环境差异"与"环境缺陷"：同一台机器上"某命令通 / 某命令不通"要按域名/场景实测，
   不要一概而论。写"某个工具一律不通"会误导接手者放弃可用的通道。
4. 视觉/格式规范类内容给可执行参数（色值、字号、边距、尺寸），不给形容词。
5. 结尾留"最后三问"，并引用用户的原话纪律（如"没有出处的追溯，和编造没有区别"）。
   用户的原话比转述更有约束力。
6. 在文件头部写清"本手册的诚实边界"：已核验 / 会过期 / 不是设计文档。
   并给出过期判断方法。

A6 手册的反例断言（只会说"通过"的校验等于没有校验）

写完手册后，自查这几条，任一条不过就重写对应部分：

1. 随便挑 3 个写进手册的具体路径，逐个 ls 确认存在？
   （有 1 个不存在的 → 勘察没做完）
2. 随便挑 3 个写进手册的命令，逐个确认前置变量/路径已给？
   （缺前置 → 接手者第一条命令就失败）
3. 第 9 章每一条未决事项，都有"确认方法"吗？
   （缺 → 接手者无法自己判断是否已解决）
4. 第 8 章的升级链，有失败出口吗？
   （只写"去哪里找"、没写"找不到怎么办" → 接手者会硬扛或编造）
5. 红线清单，每一条都点了"后果"吗？
   （不点后果 → 接手者不理解，会绕过）
6. 手册里有没有"我不知道"？
   （一条都没有 → 大概率是过度自信，回去找真实未知）

第 B 篇 · 交接打包（实物线）

B1 解决的问题

用户要把一个任务的全部内容搬到别处（另一个账号 / 另一台电脑 / 另一个人），并强调不能少任何信息。
难点不在"复制文件"，而在三件事：

1. "任务名"是显示名，不是路径 —— 用户口中的"体系研究"在磁盘上是 2026-09-03-10-52-15，
   全盘搜"体系研究"会一个结果都没有。
2. 最关键的证据（对话原文）可能被产品层拦住 —— 这时不能放弃，也不能编，
   要把「只有用户本人能做的那一步」做成一个双击即成的脚本，并把这件事明确写在交接说明里。
3. "不能少任何信息"与"包越小越好"直接冲突 —— 按用户口径优先：宁可带上两百个调试中间产物，
   也不要自作主张裁剪。

B2 解析「任务名」→ 磁盘工作区（先做这步，不要全盘搜索）

WorkBuddy 的工作区显示名（用户改过的名字）存在：

~/.workbuddy/workspace-display-names.json

结构：

{ "version": 1,
  "workspaces": {
    "c:/users/<用户名>/workbuddy/<工作区时间戳>": {
      "id": "...", "path": "<工作区>",
      "displayName": "体系研究", "updatedAt": 1789712165930 } } }

> 教训（实打实踩过）：上一次为了找"体系研究"，做了全盘 find、遍历 20 个工作区、
> 按内容 grep、搜资料库空间根目录 —— 全部落空，最后是这一张映射表一眼解决的。
> 用户说的"任务名"，先去这里查。

顺带可得：用户界面上的"任务"在这里就是工作区；一个工作区下可以有多个会话。

B3 六类数据源定位表

③ 的查法（只查目标工作区）：

sqlite3.connect('~/.workbuddy/workbuddy.db')
# sessions 关键列：id, cwd, title, custom_title, created_at, updated_at,
#                  last_activity_at, status, model, expert_id, permission_mode
# where cwd like '%<工作区名>%'

> custom_title 非空 = 用户自己命名的会话；为空多半是自动任务会话。
> 例：6 个标题为「回流回执定时拉取」的会话是定时自动任务，不是人工对话 ——
> 清单里要标出来，否则接手者会以为是 6 段对话。

B4 会话原文被拦住了怎么办（这一步决定成败）

事实：~/.workbuddy/projects/ 对 AI 是产品级硬拦截。实测四条通道全部拒绝：

• 直接读文件 → Permission ... has been denied
• 列目录（ls）→ 拒绝
• 匹配文件（Glob）→ 拒绝
• 以该目录为根检索（Grep）→ 拒绝
• 提升沙箱权限（dangerouslyDisableSandbox）→ 仍然拒绝（说明不是沙箱范围问题）

正确做法：不硬闯，改成「把这一步交还给用户」，并做成双击脚本。

> ⚠️ 不要用"换个检索根目录绕过去"这类办法。那是绕过产品防护，且极其脆弱。

补齐脚本的三个硬要求

1. 脚本内容必须纯 ASCII。
   - 定位自身用 %~dp0，用户目录用 %USERPROFILE%，不写任何中文路径字面量；
   - 中文只出现在文件名上是安全的（ASCII 内容在 GBK/UTF-8 下同码）；
   - 目标目录名也用 ASCII（如 transcripts），避免 chcp 落差。
2. 分步、可断点：1-复制原始记录 → 2-生成逐字稿 → 3-重新打包，
   中间失败时用户能看出是哪一步坏的。
3. 最后一步「重新打包」必须也脚本化，并带自检 —— 这一条最容易漏，代价也最大：
   前两步只把文件放进目录，zip 不会自动更新；用户直接发旧包，
   失败是静默的（对方打开才发现缺东西，而那时已经发出去了）。
   打包脚本必须：进门前检查 transcripts/ 是否为空并警告 →
   打完包后复核 zip 内是否真的含目标目录，明确打印 [OK] 已入包 / [NOT OK] 未入包。

复制脚本骨架：

@echo off
chcp 65001 >nul
setlocal
set DEST=%~dp0transcripts
if not exist "%DEST%" mkdir "%DEST%"
set SRC=%USERPROFILE%\.workbuddy\projects
for %%D in ("<编码后的工作区目录名>") do (
  if exist "%SRC%\%%~D" copy /Y "%SRC%\%%~D\*.jsonl" "%DEST%\" >nul
)
dir /b "%DEST%"
pause

> 工作区目录名是 cwd 编码形式：把 C:\a\b-c 里的 \ 换成 -、去掉盘符冒号，
> 得到 c-Users-<用户名>-WorkBuddy-<时间戳> 这样的形态。

jsonl → Markdown 转换器的三条设计纪律

1. 宁可多留，不可漏 —— 未识别的记录类型不丢弃，原样落到「未识别记录」附录。
2. message.content 既可能是字符串也可能是块数组，两种都要处理（text / thinking /
   tool_use / tool_result）。
3. 逐条标注时间戳与角色，让接手者能重建时序。

B5 装配交接包（目录骨架）

<交接包>/
├── 00-交接说明（先读我）.md      ← 索引 + 补齐指引 + 缺口与风险
├── 01-过程记录汇总.md            ← memory 日志逐字合并，按时间排序，每条带溯源头+校验值
├── 02-会话清单与时间线.md        ← sessions 表导出
├── 03-变更时间线.md              ← changes-index 汇总
├── 04-成果清单.md                ← 全部文件名与大小
├── 05-用户要求与裁定全记录.md    ← 归类整理（原话 + 出处）
├── 06-附-用户相关原文摘录.md      ← 机读版：全部含关键词的原文行 + 文件:行号
├── MANIFEST.md                   ← 全量 sha256（前16位）
├── 实物/<工作区1>/               ← 完整复制
├── 过程索引/{changes-index,artifact-index}/
├── transcripts/                  ← 待用户补齐
├── 会话逐字稿/                   ← 待生成
├── 1-补齐会话原始记录.bat
├── 2-生成逐字稿.bat
└── convert_transcripts.py

关键取舍：

• 01 必须逐字合并，不许概括。概括 = 丢信息，与"不能少任何信息"直接冲突。
  已在每条前面标注来源路径、字节数、sha256，保证可回原文件核对。
• 05 是整理版（人读），06 是机读版（全量原文行 + 行号）。两份都要，
  因为"整理"必然有取舍，而取舍要可被检验。
• 不裁剪调试文件。项目里那两百个 _*.txt 看着像垃圾，其实是"结论怎么来的"的证据链。

B6 缺口与风险（交接说明里必须单列）

按三类分开写，不要混成一锅：

风险至少覆盖：口令/令牌（本类包常含 endpoint 与 token，只能给用户本人的另一账号）、
隐私与项目名（用户若有过"对外文档不得出现项目名"的要求，转述时必须遵守）、
体积、绝对路径依赖（另一台机器路径不同，脚本不可直接跑）。

B7 说清「一个包搞定不了完全继承」

交接说明里必须有一段划清边界，否则用户会以为发了 zip 就万事大吉。
至少三条独立数据线，并存、不互替：

写法：明确给出分岔判据 ——
「若『继承』只是给过去看 → zip 够；若还包括让对方拥有同样的技能与记忆 → 不够」。

B8 打包的反例断言（只报"通过"的校验等于没有校验）

1. 交接说明里有没有「唯一需要你手工补的一步」一节？
   —— 有：正确。没有且声称已完整：大概率漏了对话原文。
2. 过程记录汇总里有没有揭示原始来源路径与校验值？
   —— 有：可回溯。没有：无法核对，等于二手转述。
3. 补齐脚本里有没有中文路径字面量？
   —— 有：断言失败（编码落差会静默复制错文件）。
4. 会话清单里有没有把自动任务会话与人工对话分开标注？
   —— 没有：接手者会把 6 条定时任务当成 6 段对话。
5. 未识别的 jsonl 记录类型是否被丢弃？
   —— 丢弃：断言失败（"不能少任何信息"当场破功）。
6. 是否做过"全盘 find 任务名"这种动作？
   —— 做过：说明跳过了第一步，应当先去读 workspace-display-names.json。

B9 打包常见坑

第 C 篇 · 接续快照（状态线）

C1 解决的问题

长会话快满时，硬撑是最坏的选择：工具开始出错（编辑类工具静默不落盘）、判断开始飘。
但直接开新会话也会断——因为"现在在哪"从来没有一个权威位置，它散在历次对话里。

别指望"上下文水位"信号。 本机没有可靠的 token 计数器暴露给模型；而"编辑工具静默失败"
在会话早期就会出现，它不是水位信号。所以正解不是找触发器，而是让快照始终是最新的。

> ⚠️ 2026-09-23 订正（半推翻本条）：上面「本机没有可靠的 token 计数器」对"模型"成立，对"脚本"不成立。
> 实测证据：transcript（~/.workbuddy/projects/<会话目录>/<uuid>.jsonl）中每条 message 带
> message.usage.input_tokens（本次会话实测 46,572 → 144,372 单调递增），除以窗口上限（ACP 默认 200000）
> 即得水位百分比；且 CLI 的事件枚举里 PreCompact 是真实 hook 事件，在上下文压缩前触发。
> 故「找触发器」这条路是通的，只是执行者必须是脚本（模型自己看不到，脚本能看到）。
> → 自动通道见 omni-context-relay（万象-会话交接与任务迁移）；本篇 C 篇继续负责手动、始终最新的那一半。
> 完整证据链：omni-context-relay/references/机制实证.md。

C2 三层分工（这是机制的核心）

为什么路标必须放用户级：只有那一层会被自动注入。新会话开局唯一能自动拿到的信息就是它，
所以"该去读哪个文件"这句话必须写在那一层——这是整条链路里唯一能自动化的环节。

C3 快照的五段（缺一段就会接不上）

1. 一句话：这个项目在干什么。新会话不知道背景，一句话省掉十次追问。
2. 权威源索引：要什么 → 读哪份。按需读，别全读（否则新会话又把上下文烧一遍）。
3. 当前活状态：带生成时间。版本号、地址、账本条数、定时任务 id、待交付物。
   凡是能核验的都写具体值——便于下次比对判断是否过期。
4. 下一步：按优先级，具体到文件与命令。「继续优化」等于没写。
5. 环境坑 + 纪律：本机特有的坑（工具行为、取输出的方式）与判据纪律。

C4 快照铁律

1. 只放状态与索引，不放内容。 规则留在 MEMORY.md，设计留在设计文档。
   快照一旦开始抄内容，它自己就变成一份要啃的长文——问题原封不动地复活了。
2. 自带生成时间，并承认它会过期。 写「生成 YYYY-MM-DD HH:MM」。
3. 下一步必须可执行：写清动哪个文件、跑哪条命令、给谁。
4. 可核验项写具体值：如版本号、指纹、条目数。新会话读到时可比对权威源，
   不一致即说明快照过期——这是让过期自己暴露的办法，比靠记忆可靠。
5. 不要把快照写成成果汇报。 成果汇报是给用户的（讲"做了什么"）；
   快照是给接续者的（讲"现在在哪、下一步做什么"）。两者读者不同，内容不同。
6. 列表与引用块不能交错。 把引用块（>）插在列表项之间，会把列表劈成两半，
   后面的列表项与前面脱节。先写完所有列表项，再写引用块／小节。
   这个坑曾在同一天内犯两次（两次都是"中途加说明块"时插错位置），
   说明靠注意力防不住：落盘后必须读回核对列表是否连贯。

C4b 接力动作：投喂 + 复述回读（2026-09-21 立）

> 来源：视频号博主「噗噗Ning-AI」（2026-09-19）｜台账 §129。
> 吸纳的是它的验证动作 —— 这一步是本篇原本缺的（此前只解决"写什么"）。

协议两步，缺第二步等于没接上：

1. 投喂：新会话里只给这份快照／进展文件，不重复交代背景。
   （若仍需要口头补背景 ⇒ 快照没写对，回去补 C3。）
2. 复述回读（关键）：紧跟一句 —— 「根据这个文件，你对当前进度的理解是什么？」
   对方复述对了才算进入状态；复述不对 ⇒ 快照有歧义或缺口，先修快照再干活。

为什么"复述"是唯一低成本的真对齐手段：声明「我理解了」零成本，复述有成本——
它必须把状态重新组织一遍，组织不出来就暴露缺口。这与本篇 §A6／§B8 的反例断言同源：
只会说「通过」的校验等于没有校验。

边界：复述正确 ≠ 可以放手。领域知识、隐性约定仍按 C2 三层各归其位。

C5 何时刷新

顺序不能反：先更新快照，再开新会话。

C6 环境适配（本机）

• Bash 已损坏；PowerShell 不回显子进程 stdout，位置参数与环境变量传递不稳定。
  → 定式：脚本自己落盘 → 再读文件。「exit 0 + 无输出」不等于成功，要看落盘产物。
• ★ 绝不内联多行 Python：python -c "…" 里只要出现 ) ( ' 等字符、且脚本超过
  几行，Git Bash 会把内容当 shell 命令执行，逐行报 xxx: command not found，
  而 exit code 可能是 0 —— 看起来像"脚本跑完了"。
  → 一律 Write 成 .py 文件再跑；超过 3 行就不要内联。
• 编辑类工具会静默不落盘（报成功但文件未变）。
  → 批量改写用带断言（恰好命中 1 次）的 Python 替换，落盘后读回核对，并编译一次。
• ★ 引用块别插进列表中间：会把列表劈成两半、后面的列表项脱节。
  同一坑在本机犯过两次（用户级 MEMORY.md 一次、快照一次）。
  → 定式：先列完所有列表项，再写引用块/小节；落盘后读回核对列表是否连贯。
• 不要写 .ps1/.bat 承载非 ASCII 路径。

C7 收尾话术

刷新完给用户一句话即可：「快照已更新（时间），可以开新会话了；第一句发：读 <快照绝对路径>。」
不要复述快照内容——那正是要避免的重复。

第 D 篇 · 文档 ↔ 实物 一致（交付前校验）

> 交付前自查。治的病是：同一个数字、同一个承诺在项目里写了多处，改的时候只改了一处。
> 核心理念一句话 —— 判据的期望值从实物取，不写死（写死的判据自己也会陈旧，开始误报真缺陷、放过假一致）。
> 三条铁律：期望值从实物取 / 双向比（文档说的代码有没有、代码有的文档说没说、旧值是否绝迹）/ 改完全包复扫。
> 最狠的一类是「承诺了代码里根本没有的行为」—— 它不是数字错，是假话。对做合规审查的人，这是信任杀手。
> 本篇自带示例脚本：scripts/check_example.py（带断言、幂等的替换脚本定式，见 D5）。

D1 这个技能治什么病

同一个数字、同一个承诺，在项目里被写了多处，改的时候只改了一处。

典型症状（都是在真实项目里踩出来的）：

最后一条最致命：它不是数字错，是"承诺了一个代码里没有的行为"。
对做合规审查的人来说，这类问题是信任杀手。

D2 铁律一：判据的期望值从实物取，不写死

这是本篇（D 篇）最重要的一条，也是它区别于普通"检查清单"的地方。

# ❌ 错：写死期望值。判据自己也会陈旧 —— 这正是要治的病。
assert "note 140 字" in readme

# ✅ 对：先从代码取实值，再拿实值去比文档
m = re.search(r"LIMITS\s*=\s*\{(.*?)\n\}", code, re.S)
lim = {k: int(v) for k, v in re.findall(r'"(\w+)"\s*:\s*(\d+)', m.group(1))}
for k, v in lim.items():
    assert "`%s` %d 字" % (k, v) in readme   # 期望值来自代码

为什么：写死的判据会在你改设计时同步过期，于是它开始"误报真缺陷"
或"放过假一致"。判据必须跟着实物走。

D3 铁律二：双向比，不只单向

单向只查"文档声明的，代码里有没有"。必须反向也查：

1. 正向：文档声明的每个字段／路由／数字，代码里存在吗？
2. 反向：代码里有的每个字段／路由／常量，文档都说了吗？
   （代码新增一个字段但文档没更新 → 对外的人按旧文档写，就漏填了）
3. 反例：文档里不该再出现的旧值／已被证伪的说法，是否真的消失了？

D4 铁律三：改完必须全包复扫

只改你手上打开的那一份，是最常见的失败方式。

# 改完之后，遍历整个包，扫旧值是否绝迹
pat = re.compile(r"约?\s*90\s*行")
left = [os.path.relpath(os.path.join(dp, f), PKG)
        for dp, _, fns in os.walk(PKG) for f in fns
        if pat.search(open(os.path.join(dp, f), encoding="utf-8").read())]
assert not left, "仍有残留: %s" % left

并且：复扫时要把所有同类表述都列出来核对，不只看你改的那条 ——
可能还有第三种写法（如"90 行"／"约 90 行"／"九〇行"）。

D5 实操：写替换脚本的定式

不要用编辑器逐处手改（会漏、会静默失败）。写一个带断言的替换脚本：

def replace_once(path, old, new, label):
    """恰好命中 1 次才替换；命中 0 次时若新文已在则视为已完成（幂等）"""
    b = open(path, encoding="utf-8").read()
    c = b.count(old)
    if c == 0:
        if new in b:
            return "skip"          # 幂等：重复执行不报错
        raise SystemExit("锚点不存在: %s" % label)
    if c != 1:
        raise SystemExit("锚点不唯一(%d 次): %s" % (c, label))
    open(path, "w", encoding="utf-8").write(b.replace(old, new))
    return "ok"

三条要点：

1. 锚点必须唯一（count == 1）—— 否则会误改。
2. 幂等：重复执行时，若新文已在则跳过，不报错。
   （但看到"锚点命中 0 次"要先查是不是已经改过了，别急着改脚本。）
3. 落盘后读回核对，改完代码要编译一次。

D6 必查清单（按"最容易出错"排序）

D7 与其他技能的分工

• 万象-网页开发与验收（B 篇 · 网页验收）：HTML 渲染、响应式、截图 —— 那是"页面看起来对不对"。
• 本篇（D 篇）：文档说的和代码做的对不对 —— 与页面渲染无关。
• 万象-网页开发与验收（D 篇 · 检索取证）：从外部找资料时的真伪核查；本篇（D 篇）是内部自洽性核查。

D8 踩过的判据坑（复用时要避开）

真实项目里十次判据失败，九次是判据错、内容没错。
反复栽在同一件事上：取数范围没框住，或参照系选错。

引申六条：

1. 凡判据形如"不许出现 X"，都要问：X 出现在禁令句里算不算？
   关键词在"要求做"与"禁止做"两种上下文里含义正好相反，
   裸子串匹配会把两者判成同一结果。
2. 解析常量要按真实语法：集合／字典／表达式（16 * 1024）都要能认，
   否则判据会拿到错的实值 —— 而"期望值从实物取"的前提是取得对。
3. 同一个符号可能既被定义又被调用：拿 find() 定位调用点时，
   要用 (?<!def ) 之类排除定义行；更稳的是用行号分段再判。
4. 取数窗口必须两级框住：止于下一个同类锚点，且止于句末标点。
   只要窗口是"固定字符数"，早晚会跨到隔壁去。
   → 判据的取数范围本身就是判据的一部分，和期望值一样要经得起复查。
5. 期望值只能从"实物"取，不能从"派生物"取。
   判断链上分三层：实物（磁盘上的文件、目录）→ 派生物（缓存、快照、
   由实物算出的状态文件）→ 二手转述（文档、报表、台账）。
   判据要拿实物当期望值；拿派生物当期望值，就等于把派生物的错误洗成"通过"。
   这条比铁律一更进一步：铁律一说"别写死"，这条说"连从哪儿取都要挑"。
6. 判据的作用域要先分类，再判定。
   同一份文档里不同章节的表格结构可能不同（列数、字段名都不一样）。
   判据必须先认清楚"这一行属于哪张表"，再决定该拿什么去比。
   一把抓的判据会把"这张表本来就不列这个字段"误报成"字段缺失"。

还有一条不是判据错、但更值得记：测试自己造假。

真实项目里曾出现"断言未配置某项 → 期望 A，实测 B"。查下来被测系统是对的，
错在测试以为"我没设环境变量"就等于"没配" —— 而配置还有第二个来源
（同目录的配置文件兜底），那个文件恰好存在。
→ 需要"未配置"这类前置状态时，必须显式把它造出来
（临时改名／搬到隔离目录），并在 finally 里还原；
不能指望"我没主动设"就等于"它是空的"。

最后一条元教训：判据只会说"通过"时，它等于没有判据。

要证明判据能拦下坏的输入，就得人为做坏再跑一遍。
做法：拿正例跑通后，逐项改坏输入的一处（改一个数字、挪一个字段、混一个旧值），
要求判据必须报警；它若还说"通过"，说明这条判据是摆设。
真实项目里用这个手法一次就抓出上面第 9 条 ——
判据把派生物的谎照抄了过去，正例跑起来完全看不出问题。
→ 每条关键判据配一条反例，是这套手法里性价比最高的动作。

D9 交付时的说法

报告要能让人一眼核对，不能只说"通过"：

✅ README 声明 note=140          `note` 140 字
✅ README note=140 与代码一致     代码=140
❌ 取不到 ALLOW_FIELDS           ← 连失败原因和取值方式都写出来

只会说"通过"的校验，等于没有校验。 自测里要带反例断言：
故意喂一个错的，确认判据真的会报错。

第 E 篇 · 图表绘制（出图交付）

> 出图交付。把结构化内容变成真的能渲染出来的图。
> 两级交付：对话内即时看（show_widget 内嵌 Mermaid）／独立 HTML 文件（写盘 → present_files）；两者可同时做。
> 最容易翻车的是中文：mindmap 节点禁冒号/括号/引号、缩进必须 2 空格一致、不支持边标签 —— 八条见 E3。
> 本篇自带单文件模板：assets/standalone.html（复制后只改 <title>、图内容、关系表三处即可交付）。

把结构化内容转成 Mermaid 图，并保证真的能渲染出来。

E1 两种输出方式

两者可以同时做：先在对话里给图，再落一份文件。

E2 固定初始化模板（已验证可用）

CDN 只允许 cdn.jsdelivr.net / cdnjs.cloudflare.com / esm.sh / unpkg.com。用 jsdelivr 的 UMD 包最稳：

<script src="https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js"></script>
<script>
mermaid.initialize({
  startOnLoad:true, theme:'base', securityLevel:'loose',
  mindmap:{padding:16},
  themeVariables:{
    cScale0:'#D6E2F0', cScale1:'#E8EEF6', cScale2:'#FBEDED',
    cScale3:'#E4F0EA', cScale4:'#F6F1E4', cScale5:'#EDE9F4',
    cScaleLabelColor:'#10253F', cScalePeer0:'#10253F',
    lineColor:'#9AA8B8', fontSize:'15px'
  }
});
</script>
<div class="mermaid">
mindmap
  root((中心主题))
    ...
</div>

主题适配：上面是浅色填充 + 深蓝文字，适用于 IDE 浅色主题。深色主题时把填充换成深色（如 #1E2A3A），cScaleLabelColor 换成浅色（如 #E8EEF6）。配色必须随 <user_info> 的 IDE Theme 走。

E3 中文避坑清单（最容易翻车的地方）

1. mindmap 节点禁止用冒号、圆括号、方括号、引号。会直接解析失败。
   - 错：一 现状：谁在管　对：一 现状 谁在管
   - 用空格、顿号、中文"达""占"等字替代标点。
2. mindmap 缩进必须一致，用 2 空格：root 2 格、一级 4 格、二级 6 格。混用会报错。
3. mindmap 不支持边标签（不能写 A -->|原因| B）。关系要表达，就在图外用表格或文字说明。
4. flowchart 节点含标点或空格时必须加引号：A["文本: 含冒号"] --> B("圆角")。
5. %、<br/> 可用，但 <br/> 需 securityLevel:'loose'。
6. 百分比、箭头字符（→ ＞）在 mindmap 中安全，可放心用于精简表达。
7. 节点文字控制在 12 字以内，过长会自动换行把图撑变形。
8. 一级分支控制在 4–6 个，mindmap 会自动左右均衡分布；超过 8 个图会挤成一团。

E4 常用图类型速查

mindmap       思维导图：中心主题与层级拆分
flowchart     流程图 / 判定链：LR TD 方向，菱形判断 {}
sequenceDiagram  时序图：participant、->>、-->>
gantt         甘特图：section、task、日期
pie           饼图：title、"标签" : 数值
classDiagram  类图
erDiagram     ER 图
quadrantChart 四象限图
timeline      时间线

判定链首选 flowchart，示例：

flowchart TD
  A[小区有物业合同?] -->|是| B[物业按约管理]
  A -->|否| C[街道托底]

E5 思维导图的内容组织原则

用户要求"梳理逻辑主线"时，按这个套路提炼：

1. 中心主题：一句话概括目标，用"做什么 → 达到什么"，如"业委会筹备 让业主权力可执行"。不要用名词堆砌。
2. 一级分支：按时间轴或因果链拆分，常见骨架——现状诊断 → 目标 → 条件门槛 → 操作流程 → 依据/约束。
3. 二级要点：每个一级分支下 3 个左右，合并重复、去冗余，只留关键动作或判据。
4. 层级不超过三层（中心 + 一级 + 二级）。
5. 关系标注：Mermaid 画不出关系，必须在图后补一张关系表（并列 / 因果 / 递进 / 贯穿），再用一到两句话概括整体思路。

E6 渲染后自检

• [ ] 所有节点文字都渲染出来了，没有变成 [#quot;...] 之类的转义残留
• [ ] 没有冒号、括号导致解析失败（失败时页面会显示原始代码或报错块）
• [ ] 中文没有变成方块（字体栈里要有 Microsoft YaHei）
• [ ] 浅色主题下文字是深色，深色主题下文字是浅色
• [ ] 图宽超出容器时，容器有 overflow-x:auto

E7 故障排查

E8 现成模板

assets/standalone.html 是完整可运行的单文件模板：含 Mermaid CDN、浅色主题配置、关系说明表格位、打印样式。复制后只改三处即可交付：
1. <title>
2. .mermaid 代码块内的图内容
3. 关系说明表与概括文字

常见误用与常见问题（FAQ）

常见误用（反模式）

常见问题

• Q：先做什么？ A：先分线，再动手（见「解决的问题：先分线，再动手」）。
• Q：哪两章决定手册成色？ A：第 0 章（开门三件事）与第 9 章（未知点·风险·需确认）。
• Q：第 8 章怎么写？ A：找资源必须是升级链，不是一句「找 XX」。
• Q：要不要把别人踩过的错写进去？ A：要 —— 把「用户踩过并自行纠正的错」写进去，包括写的人自己犯的错。
• Q：交接包里要单列什么？ A：缺口与风险（B6）；并说清「一个包搞定不了完全继承」（B7）。
• Q：脱敏怎么处理？ A：用户若有过「对外文档不得出现项目名」的要求，转述时必须遵守。

附 · 融合说明与来源追溯

本技能是五篇合一的融合作品，来源与位次依据如下（人可读版；机器可读版在 frontmatter 的 source_book 与 copyright.notice）。

为什么合成一部。 五篇共用同一条方法论：别凭印象，去核实物。A 篇的勘察、B 篇的校验值、C 篇的可核验项、D 篇的判据期望值、E 篇的渲染后自检，用的是同一条；分散在五部里，每次都要先选技能、再对齐口径。合一后省掉选技能这一步，底座也只剩一份。

篇界即判据边界。 A/B/C 按「交出去的是什么」分线；D/E 是交付前的两件前置（东西本身对不对、看不看得懂）。真要按哪篇动手，看任务本身，不强制顺序。

溯源引用说明。 上表里的旧名（handoff-*、文档代码一致、图表绘制）是历史留痕，不是可调用的技能名；正文别处若出现它们，一律按本表理解。