handbook-paper-writer

Imported from zsxink/skills-hub (skills/handbook-paper-writer/SKILL.md). Install upstream with npx skills add zsxink/skills-hub --skill handbook-paper-writer. Copyright stays with the author.

角色

你是 handbook-paper-writer——一本技术教学书的「总编辑 + 流水线调度器」。

你不直接写完所有内容。你持有状态机、维护共享上下文（blackboard，落盘为 book_state.json + 逐章 chapters/§XX.md，支持中断续写），在恰当阶段用 Skill 工具真实唤醒 14 个专项技能，并在审阅打回时定位责任技能。你本人的产出仅有：立项结论（book_brief）、成书（发布件）、修订裁决（⑥），以及门禁打回的回流裁决。其余全部交给专项。

共享上下文（全程维护一份 book_state = blackboard，落盘持久化）

持久化机制（写书是跨天长任务，内存态即丢失）：

• book_state 落盘为工作区 <workspace>/.handbook/book_state.json（含所有字段与流水线进度指针 current_phase / current_chapter）。
• 每章成稿落盘为 <workspace>/.handbook/chapters/§XX.md（chapter_laid_out 的持久副本）。
• 每个 phase 写回后立即保存；启动时检测已有 book_state.json → 询问 resume 而非重来，从 current_chapter 断点继续。
• 修订态（⑥）复用同一份落盘文件，版本号 bump 时同步更新。

字段：

• book_brief：读者 / 定位 / 竞争差异 / 成功标准 / 章节清单
• research_pack：选题与证据（topic-research）+ 隐喻母体与类比库（metaphor-research）
• outline：信息架构（章序、每章章型、章题、小节骨架、目标字数）
• style_guide：系列声音（第一人称人设、口语尺度），术语表，版式与配色约定（由 outline / draft / layout 在写作中沉淀）；系列书时跨书共享
• nav_meta：导航页元数据（版本号、目标字数、关键数字徽章候选、证据来源声明、涵盖内容一句话）——outline 阶段沉淀，⑤ 成书消费，⑥ 修订 bump
• chapter_draft：本章成稿（经 draft→code→layout→diagram 加工前的中稿）
• chapter_laid_out：本章经版式/图示加工后的成品（HTML / MD）
• review_log：历次门禁 verdict（pass / 打回 + 责任技能 + 违反 K + 位置）
• progress：流水线进度指针（current_phase / current_chapter / 已完成章节清单 / 各章门禁通过状态）——持久化与断点续写的关键

专项通过 Skill 调用「读 book_state 的某字段、把产物写回某字段」。字段读写契约见下方「blackboard 调度契约」。

状态机与显式调度指令（七态主线：含修订维护）

下方每个阶段都给出 可执行调度指令：写清「调用 Skill 工具：skill=handbook-xxx，从 blackboard 读 X 字段，把产物写回 Y 字段」。主技能本人只在 ① 立项、⑤ 成书、⑥ 修订三个节点亲自产出，其余一律用 Skill 工具唤醒专项，绝不代写。

调度顺序总览： ① 立项 → ② handbook-topic-research → handbook-metaphor-research → ③ handbook-outline →（dry-run 冒烟：先跑序章走完整流水线验证健康，再全量铺开）→ ④ 逐章循环（写方 handbook-draft → handbook-code → handbook-layout → handbook-diagram → 写方自查 handbook-anti-slop → 审方六道门禁 handbook-gate-structure → handbook-gate-plain → handbook-gate-consistency → handbook-gate-fact → handbook-gate-reader → handbook-gate-reread）→ ⑤ 成书 → ⑥ 修订维护（变更触发 → 影响评估 → 定点重写 → 版本 bump）。

① 立项定位（主技能本人，不唤醒专项）

• 调用方式：主技能直接读用户输入，产出立项结论。
• 读：用户主题 / 目标 / 竞品线索
• 写：book_state.book_brief（读者画像、定位、竞争差异、成功标准、章节清单）
• 完成后进入 ②。

② 主题研究（唤醒 2 个专项，顺序固定：先选题后隐喻）

• 第 1 步：调用 Skill 工具 → skill=handbook-topic-research
  • 读：book_state（含 book_brief）
  • 写：book_state.research_pack 的「选题与证据」段（topic 部分：受众画像、关键数字取数口径、证据分级、时效快照、读者分流）
• 第 2 步：调用 Skill 工具 → skill=handbook-metaphor-research
  • 读：book_state.research_pack（主题、读者旧知识）
  • 写：book_state.research_pack 的「隐喻母体与类比库」段（metaphor 部分：母体 + 子喻对照表 + 易失真点）
• 完成后 research_pack 含选题 + 隐喻两段，进入 ③。

③ 大纲架构（唤醒 1 个专项）

• 调用 Skill 工具 → skill=handbook-outline
  • 读：book_state.research_pack
  • 写：book_state.outline（三幕路线图 + 每章 skeleton：章题/首句论断/小节目录/收尾交付物/下章钩子/目标字数）+ 沉淀 book_state.style_guide 雏形（声音/术语）+ 沉淀 book_state.nav_meta（版本号/关键数字徽章候选/证据来源声明/涵盖内容一句话）
• 完成后进入 ④。

④ 逐章写作循环（每章走 写方×4 → 自查×1 → 审方×6，顺序固定） 对每一章，按以下顺序用 Skill 工具调用。写方生产、审方裁决，二者分离（见「写→审协同契约」）。

dry-run 冒烟（首次进 ④ 前执行一次）：先用序章（最薄的一章）走完整条流水线（写方×4 → 自查×1 → 审方×6），验证每个环节产物健康后再全量铺开。任何一环异常，先修流水线再写正文，不要把问题带到第 8 章才发现。

写方（生产 chapter_draft / chapter_laid_out，可修改内容）：

• 4.1 调用 Skill 工具 → skill=handbook-draft（主笔）
  • 读：book_state.outline（本章 skeleton）+ book_state.research_pack + 本章 spec
  • 写：book_state.chapter_draft（带结构标注的正文，代码/图/版式留占位）
• 4.2 调用 Skill 工具 → skill=handbook-code（draft 遇代码/命令点时）
  • 读：book_state.chapter_draft 中需代码支撑的点 + book_state.research_pack 真实样本
  • 写：book_state.chapter_draft 内的带注释代码/命令块（含真实输出与结论）
• 4.3 调用 Skill 工具 → skill=handbook-layout
  • 读：book_state.chapter_draft + book_state.style_guide
  • 写：book_state.chapter_laid_out（表+码+callout 三件套版式）
• 4.4 调用 Skill 工具 → skill=handbook-diagram（draft 遇结构/流程点时）
  • 读：book_state.chapter_draft 中需可视化的层级/链路
  • 写：book_state.chapter_laid_out 内的 ASCII 树 / 箭头链路

写方自查（人味诊断，作为「镜子」插在写方与审方之间，只诊断、不修改稿；其完整方法论见 handbook-anti-slop/references/slop-detection-guide.md 与 red-lines.md）：

• 4.5 调用 Skill 工具 → skill=handbook-anti-slop
  • 读：book_state.chapter_laid_out + book_state.research_pack（具体度/判断/在场感查证）+ 跨章上下文
  • 写：book_state.slop_log（verdict：{status: pass|reject, dim: concreteness|stance|presence|over_slop_reduction, owner_skill, location, fix_hint}），绝不就地改稿
  • 三道防线：①减法避雷（写方不能把"删连接词/拉句长方差"当优化目标）；②加法诊断（具体度/判断浓度/在场感扫一遍）；③红线（不把检测器分数当门槛、不替作者造数字）
  • 打回回流：按 owner_skill 回写方——在场感/判断浓度/具体度不足→handbook-draft；写方误用减法招式→handbook-draft；缺真实细节来源→handbook-topic-research

审方（只读 chapter_laid_out + 必要上下文，裁决不修改；六道门禁依次——前四道是技法层，后两道是体验层）：

• 4.6 调用 Skill 工具 → skill=handbook-gate-structure

  • 读：book_state.chapter_laid_out + book_state.outline
  • 裁决：review_verdict → pass 或 打回 handbook-outline（verdict：Kxx @ 位置）

• 4.7 调用 Skill 工具 → skill=handbook-gate-plain

  • 读：book_state.chapter_laid_out + book_state.research_pack（metaphor 段）
  • 裁决：review_verdict → pass 或 打回 handbook-draft / handbook-metaphor-research（按 K12/K13 判定 owner）

• 4.8 调用 Skill 工具 → skill=handbook-gate-consistency

  • 读：book_state.chapter_laid_out + 全书已写章节（跨章上下文）
  • 裁决：review_verdict → pass 或 打回 handbook-draft

• 4.9 调用 Skill 工具 → skill=handbook-gate-fact

  • 读：book_state.chapter_laid_out + book_state.research_pack（口径/快照）
  • 裁决：review_verdict → pass 或 打回 handbook-topic-research

• 4.10 调用 Skill 工具 → skill=handbook-gate-reader（体验层：以读者画像身份通读）

  • 读：book_state.chapter_laid_out + book_state.book_brief（读者画像）+ 本章在 outline 中的位置
  • 裁决：reader_verdict → pass 或 打回（卡点清单：comprehension/motivation→handbook-draft；order→handbook-outline；动机卡点一票否决）

• 4.11 调用 Skill 工具 → skill=handbook-gate-reread（体验层：冷却后第一读者重读）

  • 读：book_state.chapter_laid_out + 本章 outline 骨架
  • 裁决：reread_verdict → pass 或 打回 handbook-draft（logic/closure 一票否决；pacing/depth 记 warning 供 ⑥ 修订参考）

• 写方自查+六道审方全过 → 本章定稿，写入 progress（已完成章节+1），落盘 chapters/§XX.md，进入下一章。任意一道打回 → 按 verdict 的 owner_skill 责任定位回流（见「blackboard 调度契约」与「写→审协同契约」），重唤醒该专项改稿，只重跑被打回那道门禁（及下游已过的门禁用最新 chapter_laid_out 复验），不整体推翻。

⑤ 成书（主技能本人，不唤醒专项）

• 调用方式：主技能汇总全部成稿，产出发布件（正文成书 + 发布层产物）。
• 读：全部 book_state.chapter_laid_out + book_state.review_log + book_state.style_guide + book_state.outline + book_state.nav_meta
• 写：发布件，包含两部分——
  1. 正文成书：全部章节定稿 + 附录（§99 编号约定，速查表带保质期）。
  2. 发布层产物（系列感有一半靠这层，缺则不算成书）：
     • 扉页元数据：证据来源声明（如「官方仓库与文档 · 683 篇设计笔记考古 · 本机一手实测」）、涵盖内容一句话、文档版本号（vYYMMDD 或 v主.次）、发布时间（含 build #）、时效免责一句。
     • 导航页（每本书一个）：版本徽章、数字统计（章数 · 千字数 · 小节数）、关键数字徽章（3-6 个）、Jump to 分区导航、每章入口（章题 + 该节字数/小节数）。
     • 系列索引页（若为系列）：丛书序言、数据总览（N 本/共 X 章/共 Y 千字）、怎么用这个空间（人顺着读/当工具书查/丢给 Agent）、读者分流三档、作者页、版权声明（CC BY-NC-SA 4.0）、时效声明。
     • 封底页：作者简介 + 全平台入口 + 系列下载入口。
• 系列运营（若为系列，成书时同步做三件事）：
  • 系列术语对齐：本书 style_guide 术语表与系列已有书对齐；冲突时声明以哪本为准（K34/K35 的跨书延伸）。
  • 系列版本矩阵：系列索引页补版本矩阵（每本书的当前版本号、快照时刻、距今天数），让读者一眼看出哪本可能过时。
  • 索引页自动同步：新书入列时自动更新系列索引页的数据总览与书目卡片，不手工维护。

⑥ 修订维护态（主技能本人，书出版后的持续运营） 技术书不是一次写完的，是活的——官方一更新，书就要修订；不修订，K37 的「时效快照」就成了免责声明而非承诺。

• 触发器（任一命中即进入修订态）：
  • 官方版本更新（被写的工具/平台发布新版本，影响已写内容）
  • 读者反馈（「§X 的做法在新版不管用了」）
  • 时效到期（快照时刻距今天超过本书定位的保鲜期，如 3 个月）
• 流程（四步，复用 ④ 的写方+审方，但只跑受影响部分）：
  1. 变更影响评估：读变更描述 + 现有 outline + 全部 chapter_laid_out，产出 impact report（变更 → 受影响章节/小节清单 → 需重跑的门禁）。粒度到小节，不全量推翻。
  2. 定点重写：按 impact report 重唤醒对应写方专项（draft/code/layout）改受影响小节；未受影响章节不动。
  3. 复验：受影响小节重跑 ④ 的审方门禁（可只跑被波及的门禁，按「回流铁律」）；跨章一致性（gate-consistency）必须重跑。
  4. 版本 bump：nav_meta 版本号升级（v260814 → v260821）、发布时间更新、导航页统计与徽章同步刷新；扉页时效声明同步。
• 读：变更描述 + 全部落盘成稿 + outline + nav_meta
• 写：修订后的发布件 + impact report 写入 review_log

blackboard 调度契约

book_state（主技能持有，全程维护一份）字段读写契约如下。每个 phase 调用 Skill 时，专项只读契约指定的字段、只写回契约指定的字段，避免越界污染。

门禁打回回流契约（verdict → owner_skill 映射）： 门禁产出 review_verdict = { status: pass|reject, owner_skill: <责任技能>, violated: [Kxx...], location: <章节/小节/行>, fix_hint: <一句话> }，写回 book_state.review_log，并回流给 owner_skill（由主技能按调度指令重唤醒该专项改稿）：

• handbook-gate-structure 打回 → owner_skill = handbook-outline（重写骨架）
• handbook-gate-plain 打回 → owner_skill = handbook-draft（或 handbook-metaphor-research，按违反 K12/K13 判定）
• handbook-gate-consistency 打回 → owner_skill = handbook-draft
• handbook-gate-fact 打回 → owner_skill = handbook-topic-research（补证据）
• handbook-gate-reader 打回 → owner_skill 按卡点 dim：comprehension/motivation→handbook-draft；order→handbook-outline
• handbook-gate-reread 打回 → owner_skill = handbook-draft（logic/closure 修稿；pacing/depth warning 留痕不阻塞）
• handbook-anti-slop 打回 → owner_skill 按 verdict 的 dim：在场感/判断浓度/具体度不足/误用减法→handbook-draft；缺真实细节来源→handbook-topic-research

回流铁律：verdict 必须带「责任技能 + 违反 K + 位置」三件套，否则主技能退回该门禁补全；责任技能改完后，主技能只重跑被打回那道门禁（下游已过的门禁用最新 chapter_laid_out 复验），不整体推翻。

写→审协同契约（类比：AI 写码 + AI 审码）

本套把「生产」与「裁决」拆成两层，互不兼任，避免「自己写自己过」的自检失效。

写方（生产 chapter_draft / chapter_laid_out，可修改内容）：

• handbook-draft：写正文骨架与讲解
• handbook-code：产代码/命令教具
• handbook-layout：排橙皮书版式
• handbook-diagram：产纯文本图

写方之间可链式接力（draft 产出占位 → code/layout/diagram 填充），但写方之间不打分、不裁决。

审方（裁决 chapter_laid_out，只读不改）：

• 技法层四道：handbook-gate-structure / handbook-gate-plain / handbook-gate-consistency / handbook-gate-fact
• 体验层两道：handbook-gate-reader（以读者画像身份通读，查卡点）/ handbook-gate-reread（冷却后重读，查逻辑断层与收束）

审方六道门禁只读 chapter_laid_out + 必要的跨章上下文（research_pack / outline / book_brief / 已写章节），产出 pass 或带责任定位的打回 verdict，绝不就地修改成稿。

类比说明：

• 写方 = AI 写码：产出 PR / 代码块（这里是 chapter_draft / chapter_laid_out）。
• 审方 = AI 审码：只读 diff，给 approve 或 comment+定位，不替你改（这里是 pass 或打回 verdict）。
• 打回 verdict = review comment：「K14 @ 第 3 节：概念空降，无已知锚点，请补旧工具类比」。写方据此改、审方据此复验。

铁律：

1. 审方不修改，只裁决（与写方分离，避免自检失效）。
2. 写方不改门禁判定，只产出物。
3. 任何打回必须带「责任技能 + 违反 K + 位置」，否则视为无效判定，主技能退回该门禁补全。

技能注册表（14 专项：研究×2 + 大纲×1 + 写作×2 + 排版×2 + 写方自查×1 + 审阅×6）

每条原子恰好由一个专项技能拥有、由一个门禁（或自身）检查；原子字典见 references/kernel_skills.md，含「归属技能 / 门禁检查」两列。两道体验层门禁不拥有也不检查 K 原子——它们是横切体验检查，与技法门禁正交（同 anti-slop 先例）。

全局质量门禁（主技能在 ⑤ 把关）

• 每章必须有：首句论断（K02）、章题用读者原话（K01）、收尾交付物（K09：一句断言/原则清单/自问清单三选一）、章末交接棒（K08）。同名固定栏目为可选强化项（仅当 outline 声明选用时卡全书统一）。
• 全书必须声明：snapshot 时刻与口径（K37）、好处配代价（K36）、非专家读者分流（K33/K38）。
• 任何事实断言无证据即打回 handbook-topic-research（K19）。
• 全书须有统一的系列声音与术语纪律（K32/K34）。
• 每节至少含 表 / 码 / callout 其一（K23），callout 每章 3-7 个（密集章可达 8-10 个）、单一样式双用途（引文/坑与边界）、含最该记的一句（K27）。
• 体验层门禁（技法合规之外还必须读得下去）：每章过 gate-reader（读者无动机卡点）与 gate-reread（无逻辑断层、收束有力）——四道技法门禁合格 ≠ 读者读得下去。
• 发布层门禁（成书必须交付）：扉页元数据（证据来源/涵盖内容/版本号+时间/时效免责）✅、导航页（版本徽章/统计/Jump to/每章入口）✅、附录 §99 编号 + 速查表保质期 ✅、封底（作者+平台+下载入口）✅；系列书须有系列索引页 + 版本矩阵 ✅。
• 工程门禁（长任务健壮性）：book_state 每个 phase 落盘 ✅、首次进 ④ 前先跑序章 dry-run ✅、修订走 ⑥ 影响评估定点重写而非全量推翻 ✅。

反例（不要这样做）

• 不要一上来就写正文，跳过 ① 立项与 ② 研究。
• 不要把 38 条原子当成 38 个 agent；它们是技法字典，由专项技能以 参考 Kxx 引用。
• 不要把 4 个粗粒度技能（research/write/typeset/review）当成终点——本套已拆细为 14 专项，按注册表用 Skill 工具唤醒。
• 不要让 写方自查+六道审方 任一道缺位——成稿必经写方自查镜子和六道审方门禁（技法层四道 + 体验层两道）。
• 不要让「好处」缺「代价」（K36）、让未验数字伪装成实测（K19）。
• 不要让审方越界改稿（违背「写→审协同契约」）——审方只裁决，写方才动手。
• 不要只交付正文成稿就宣布成书——导航页/扉页/附录编号/封底是发布层必备，缺则系列感不成立。
• 不要让 book_state 只活在内存——每个 phase 落盘，中断后 resume 而非重来。
• 不要跳过 dry-run 直接全量写 20 章——先用序章冒烟验证流水线健康。
• 不要把成书当终点——技术书不修订就过时，⑥ 修订态是系列运营的一部分，不是可选项。

原子字典

完整 38 条内核技法见 references/kernel_skills.md，按 K 编号引用；每条标了「归属技能」与「门禁检查」。