对话档案 D12 · 使用说明书 14 篇（11-12~11-13）
一句话：给一个自己天天在改的站点写说明书，难点不是写，是「写的时候功能还在变」——14 篇、8.5 万字、89 张自动截出来的配图，每篇都要靠 11 条断言证明自己没写错。
一、这段对话怎么走的
三段会话，全部在 C:/Users/cag/WorkBuddy/2026-11-11-09-21-47 目录下，但项目位置指向 C:/Users/cag/WorkBuddy/2026-10-11-06-00-16/notes（用户在第一句就专门注明「不是 2026-11-11 那个目录！」）。三段都是「一条超长指令 + 全自动跑完」，中途几乎不需要人干预。
| 阶段 | 用户要求 | 产出 | 卡点 |
|---|---|---|---|
| M1 底座 | 建手册的承载方式 | lib/manuals.ts（MANUAL_PAGES 注册表 / manualHref / manualNoteIds / bind）、PageManual(pageKey @id, noteId) 映射表、HelpButton、ManualBackBar；PageHeader 变 async 接 helpKey；12 篇统一挂在顶层笔记「使用说明书」下 | 手册是普通笔记，必须从检索与「最近笔记」里排除（dropManual），另开指令 说明书检索: |
| M2 截图流水线 | 每篇要配图 | scripts/manual-shots.mjs：注入 2px 红框 + 20px 序号角标再裁切 | 三个坑：scroll-behavior:smooth 让坐标量偏；clip 是文档坐标而 boundingBox 是视口坐标，混算必错位；贴视口边缘的角标被裁掉 |
| M3 发布流水线 | md 是唯一源 | scripts/manual-publish.ts：自动建目录笔记、按 pageKey 建/更新手册笔记、写映射；内容没变跳过，变了存新版本 | 配图不能走 /api/assets/upload（时间戳+uuid 命名，重拍换地址），改为 publish() 直写 <pageKey>-<8位组号>.png，重拍覆盖同名 |
| 4 首批 8 篇 | 11-12 白天 | home / sheet-detail / note / note-settings / import / panes / tree / sheets | 每篇写完跑 verify-manual.js，11 条断言 |
| 5 续写 4 篇 | 「剩余几篇全部完成并逐一验收」 | keywords / whitebook / whitebook-reader / whitebook-manage | 自动化定时任务驱动；i 按钮在手册发布前不渲染，必须先发布再拍照 |
| 6 补两篇 | 11-13 功能新增 | favorites（13 篇）、versions（14 篇，管理员版本清理页） | favorites 空态图被真实收藏挡住，需「先记 id 再取消、拍完还原」 |
最终 notes/manuals/ 下 14 个文件，实测约 8.5 万字、89 张配图，单篇功能条目最多的是 sheet-detail.md（F1–F39，457 行、1.5 万字、11 张图），最少的是 keywords.md（F1–F7，96 行、3 张图）。每篇结构固定：一句话 → 什么时候来 → 页面速览 → 结构 → 分组功能清单 → 本页没有的功能 → 常见任务 → 验收。
二、用户的关键原话
「继续编写"笔记库"站点（notes）剩余的使用说明书手册，把剩余几篇全部完成并逐一验收。【项目位置】C:\Users\cag\WorkBuddy\2026-10-11-06-00-16\notes（不是 2026-11-11 那个目录！）【已完成】8 篇手册：home、sheet-detail、note、note-settings、import、panes、tree、s……」
这是三段会话里唯一的用户消息，也是一份标准的「交接包」：目标、绝对路径、排除项、已完成清单、剩余清单、验收方式。括号里的「不是 2026-11-11 那个目录」尤其关键——同时存在两个同名 notes 项目，不写这句，第一轮探索就可能改错仓库。
「把剩余几篇全部完成并逐一验收。」
「逐一」是硬约束：不是写完 4 篇统一跑一次，而是每篇单独发布、单独验收、单独报告。这条约束直接决定了流水线的形状——manual-publish.ts 必须支持单篇幂等发布，verify-manual.js 必须接受路由参数。
「写一个skill,给定网站,截图全网站生成一张长图。」（D13，同日）
说明书配图的截图需求，最终催生了一个独立 skill。这条线说明：同一种自动化只要重复三次以上，就值得抽成工具。
三、成本与效率
台账口径 1324 万 token：1127.8 万（11-12 14:58）+ 130.7 万（11-13 01:00）+ 约 65.6 万。tmp-scan.json 能单列到的只有前两段，第三段在扫描里未单独成条，此处按台账计入。
前两段的形态很特别：各只有 1 条用户消息，却分别跑了 102 次和 42 次工具。也就是说，1127.8 万 token 全部花在「一条指令之后的自主执行」上——平均每次工具调用摊 11 万 token，每条消息摊 1127.8 万。
按产出折算：1324 万 token 换 14 篇 8.5 万字、89 张图、154 条验收断言（14×11）。单篇约 95 万 token，单字约 156 token——比手写贵得多，但省掉的是「每改一次功能就手工重拍一遍图」的长期成本：配图文件名确定性化之后，重拍覆盖同名文件，手册里的图片地址永不失效。
四、曲折点与评判
1. 先发布还是先拍照（★★★★☆）
manualHref 在手册未发布时返回 null，HelpButton 直接 return null——于是拍照脚本找不到 .help-btn，超时。正确顺序是先发布手册、再拍配图：因为配图文件名是确定性的（<pageKey>-<8位组号>.png），发布时 md 引用已经写好，图片晚到也能正常显示，不需要二次发布。这个顺序反直觉（一般会想「先有图再发布」），但在这个架构下是唯一可行解。
2. 坐标系统的三次翻车（★★★★☆）
第一版量 scrollTo 后的位置，被 scroll-behavior:smooth 的动画骗了，截图和红框错开；第二版混用 clip（文档坐标）与 boundingBox（视口坐标），整组偏移；第三版贴顶的框角标被裁。最终方案是「注入透明 .mh-clip 取景框 + locator.screenshot()，滚动偏移全交给 Playwright」——不再自己算坐标，让框架算。这是典型的「三次修补不如换抽象」。
3. 写文档时才发现代码错了（★★★★★）
写 sheet-detail 时读了实现，发现三处事实错误：合并单元格其实保留所有非空内容（按换行拼），不是只留左上角；清空内容保留格式，所以「看起来没删干净」；粘贴纯文本只有含制表符才拆格。另修正「表头打印重复」（站点无打印）、「设表头强制居中」（手动对齐过则不变）。写说明书的副产品是替产品做了一次事实审计——这是本段最被低估的收益。
4. 空态图与真实数据打架（★★★☆☆）
favorites 篇要拍空态，但用户账号里有真实收藏。不能清库。做法是先记下全部收藏 id 再取消，after 钩子里加回，并排除本轮 seed 新增的 id（否则还原后越积越多）。同类问题在 tree 篇也出现：空态图拍成了「已选中」态，靠重载页面恢复。测试要动真实数据时，「记录—变更—还原」三段式是唯一安全写法。
五、提示词与流程改进
反例：「给笔记站写使用说明书。」
模型会从代码猜功能，写出「本页支持导出 PDF」这种站点根本没有的能力（sheet-detail 初稿就写过「表头打印重复」）。
正例：「每篇结构固定：一句话 / 什么时候来 / 页面速览 / 分组功能清单（F 编号）/ 本页没有的功能 / 常见任务 / 验收。配图用 manual-shots.mjs 按选择器注入红框与序号，功能描述必须与代码一致，不确定的写『日志未留存』。」
给了模板、给了工具、给了事实纪律，产出才可复用。
反例：「图配几张，看着来。」
正例：「每篇 3–12 张，覆盖：整页速览 1 张、每个功能组至少 1 张、空态 1 张；文件名 <pageKey>-<8位组号>.png，重拍覆盖同名。」命名规则一确定，图片就变成了可重生成的构建产物，而不是需要手工维护的资产。
反例：「写完检查一下。」
正例：「verify-manual.js <route> 必须 11/11：i 按钮唯一且带 ?from=manual:、跳转 200、返回条文案正确、手册页不再显示 i、配图 N/N 解码、0 个 4xx、0 JS 报错。」把验收写成脚本参数，才能「逐一验收」。
六、可复用结论
- 文档流水线要「md 为唯一源 + 确定性资源名」。 内容改了重新发布，图重拍了覆盖同名，两者都不产生孤儿、不需要人工改引用。
- 写文档是低成本的产品审计。 14 篇里有 5 处功能描述被代码推翻，这些错误如果只靠测试，很难被发现。
- 长任务交接包 = 目标 + 绝对路径 + 排除项 + 已完成清单 + 验收方式。 一条消息跑 102 次工具，靠的就是这五项齐全。