@chengzhao-dev/dsh-quarto-book 0.6.17 → 0.6.19

package/skills/writing-quarto/steps/02-structure.md

@@ -2,16 +2,12 @@
 
 产出：章内页面骨架和二级标题清单。
 
-边界：这一步只定删留和标题，不改句子；全章重构也先停在这里。页面宽度归 `designing-theme`，图与代码的桥接归第 3 步，段落节奏归第 4 步。
+边界：这一步只定删留和标题，不改句子；整章改写也先停在这里。页面宽度归 `designing-theme`，图与代码的桥接归第 3 步，段落节奏归第 4 步。
 
 ## 通用情况
 
 绝大多数章按下面的六段块序列展开；类章、能力章与着陆页的差异见「情况」。本步的规则默认按这一通用形状判断。
 
-### 章节骨架
-
-六段块序列是骨架的默认顺序。
-
 ### 六段块序列
 
 ```text
@@ -37,14 +33,14 @@
 
 链接预算：引言只挂承接上一章的那 1 个章节链接和本章主源文件的 blob 链接；其余章节链接下沉到正文真正用到它的句子。同一段不堆多个章节链接——每个链接都是读者离开当前页的一次机会。
 
-摘录免责句（「本章摘录源码服务于讲解」「片段不保证与源码逐字一致」）不写进读者正文，同源保证交给 `verifying-content.py`。
+摘录免责句不写进读者正文，同源保证交给 `verifying-content.py`。
 
 ### 任务序列
 
 - 每节一个可验证结果：任务结束时存在读者能自己复述的检查动作；只有「读完了解释」的内容并入相邻任务。
 - 节内顺序：概念 → 最小示例 → 操作 → 验证 → 边界；先让读者看到行为，再解释规则。单次操作按「做什么 → 执行什么 → 看到什么 → 简短说明」推进。
 - 任务节以该章标题里的对象为准，不把每章都写成「目录、设计、构建、测试」。
-- 交付清单或纯边界说明不单独设 `##`，并入引言或相邻总览节；同一头文件中连续的值类型优先并成一个可验证结果。
+- 交付清单或边界说明不单独设 `##`，并入引言或相邻总览；连续值类型并成一个结果。
 - 任务节内按「类型 → 简单函数 → 更难的函数」排列，最难的组装放在最后，满足先定义后调用：读者要读懂的行内标识符，其行为必须已在上文或紧邻声明中出现；未定义名字的调用链、节首概览与编号步骤整段删除。
 - `##` 导语只用白话，不点后文才定义的函数名；有 `###` 时导语承接上文。
 
@@ -53,7 +49,7 @@
 有 `class` 定义的章，任务级 `##` 按下面次序排；没有下一种内容就停，不为凑数加节：
 
 1. 类型：本章用到的值类型（枚举与结构体），一节一个可验证结果，可下分三级标题。
-2. 成员变量：单独一节；读取成员的函数用三级标题。只判断下标区间的检查也用三级标题放在这一节，不单独占二级标题。类说明、构造函数与数据成员拼进同一个围栏，不拆成两个围栏。
+2. 成员变量：单独一节；读取成员的函数用三级标题。只判断下标区间的检查也用三级标题放在这一节，不单独占二级标题。类说明、构造函数与数据成员拼进同一个围栏。每个函数的声明和实现留在同一个 `###`；标题点名本节对象，不用「只读接口」这类总称。
 3. 最重要的函数：这个类最重要的一个函数及配套函数。
 4. 其余重要函数：还有一组就再加一节，没有就停。
 
@@ -89,7 +85,7 @@
 - 「下一章 <预告>」不写链接，直述一句；预告不引入下一章才建立的术语。
 - 每个说法都要能在正文找到出处，禁止空泛能力句或只写预告；任务节变化时同步改写。
 
-## 一章一个关键
+### 一章一个关键
 
 每一章只有一个关键，标题、各级标题、导语和自然段都是它的部分或核对。关键分两类：
 
@@ -98,17 +94,6 @@
 
 固定收尾「常见错误」「自测问题」「本章回顾」不改名，不升成关键。
 
-### 术语与验证策略
-
-- 标题、导语与任务节只用读者在前文已认识的名字；本章新术语在首次真正使用处就近定义，不在标题里抢先出现。
-- 每个任务节交付一个可观察结果；章末「本章回顾」只复述这些结果，不引入新承诺。项目有章节表时，关键、`title` 与二级标题同轮同步。
-
-### 源文件与编译顺序
-
-章的关键与头文件里声明的物理顺序冲突时，以编译要求为准：被用到的类型先声明，被依赖的类型留在使用它的类前面。叙述主次由章首与横幅承担，不由声明顺序承担。
-
-## 标题
-
 ### 标题分层
 
 | 层级 | 长度 | 形式 |
@@ -117,6 +102,7 @@
 | `##` | 2–10 个汉字 | 这一阶段交出的对象，或读者必须动手的短任务：「限定语 + 对象」或「动词 + 具体宾语」 |
 | `###` | 2–10 个汉字 | 该阶段里的一个实体或一步具体动作；「常见错误」下的症状标题可到 12 个汉字 |
 
+- 字数按可见汉字计，英文、数字和标点不计入；part 落地页的 title 例外，不受 2–6 汉字硬限。
 - `##` 承担大任务，要让读者看出它承担本章 title 的哪部分；`###` 承担可独立执行、观察或验证的子任务；正文最多到 H3，不写 `####`。
 - 只有解释或一两句结论的内容不升级为标题；`##` 含多个连续子流程或篇幅触达预算时，拆 `###`，不整块下压。
 - 一个 `##` 下设 `###` 时至少两个：同级只有一个时，删去标题归回正文，或补出真正独立的同级小节。
@@ -125,30 +111,22 @@
 - 标题与内容匹配：标题动词承诺的动作必须是正文实际让读者完成的动作；只要求观察的用「观察、查看、核对」，不用「走完、完成」。任务级标题不与页面 title 共用核心动词；`##` 的宾语要涵盖其下 `###` 的宾语。
 - 层级不跳级；下级标题不重复上级标题的名字；标题与导语不写拗口动宾，不用实现细节当主叙事。
 
-### 标题字数
-
-YAML `title` 2–6 个汉字；`##` 与 `###` 2–10 个汉字，「常见错误」下的症状标题可到 12 个。按可见汉字计，英文、数字和标点不计入；part 落地页的 title 例外。
-
-### 句式
+### 形式规则
 
 - 二级、三级标题只用两组词：要么「限定语 + 对象」（数据项坐标、操作后的结果），要么「动词 + 具体宾语」（检查是否三连、放入一枚元素）。同一个 `##` 下的 `###` 只用其中一种。
 - 任务级 `##` 在同一章内用同一种句式；类章与流程章统一收成名词短语，动作交给正文。
 - 标题若是集合的数量（`八条线`、`三种类型`），先看条目能否各自成为实体；能就拆成实体标题，不能就改成承载它们的对象。标题不替读者数个数。
-- 标题不用人称、劝诱和口语动词（「自己走一局」「跟我做」），不把读者写进标题。
-- 标题不以时间或过程从句起头（「输入之后的回应」还原成「程序回应」），时间关系留给导语。
+- 标题不用人称、劝诱和口语动词（「自己走一局」「跟我做」），不把读者写进标题；不以时间或过程从句起头（「输入之后的回应」还原成「程序回应」），时间关系留给导语。
 - 标题不用视图隐喻和英文类名：`程序全图` 改 `程序结构`，`Ai 落子` 改 `电脑落子`。
 - 标题禁元叙述与空心题：不写「本节说明…」「本章规划…」，不写读不出动作对象的短语。
 - 标题与导航不使用行内代码；文件名承担路径职责，中文 title 承担理解职责，两者不必逐字翻译。
 - 过程节不承载回顾职责：`### 本章实现边界` 一类标题不设，边界话并入 `## 本章回顾`。
-- 例外：part 落地页的 title 即 part 名，不受 2–6 汉字硬限；章节与落地页一律不写 `description`。
-
-### 形式规则
-
 - 不加冒号、破折号、括号补充说明；并列结构可用顿号或逗号。
 - 不堆「教程」「详解」「学习」「验证：」等泛化或解释性后缀。
 - 不用「看懂、读懂、弄清」类口语领会词，不预设读者的领悟结果。
 - 不用「并」串联两个动作，不用把字句；两个动作各有任务节承载时择主撰写对象。
 - 指示（这一步、这次）、过程动词（记下、收进、用到）、方式（用数组、先…再…）与数量词（三种、四个）不进标题，下放导语或正文。
+- 章节与落地页一律不写 `description`；part 落地页的 title 即 part 名。
 
 ### 定语「的」
 
@@ -162,7 +140,7 @@ YAML `title` 2–6 个汉字；`##` 与 `###` 2–10 个汉字，「常见错误
 
 改 title 不改文件名，除非主题边界或页面职责变化；改后跑 `quarto_render_check` 看右侧目录与导航。页面 title 变化时，part 落地页的卡片标题与一句话描述同步改为新承诺。项目技能有章节表时，同轮同步表的 `title` 与 `##` 顺序；表与正文不一致按章题脱节处理。
 
-## 纵向承诺链
+### 纵向承诺链
 
 定结构时逐条对照，不新开第 10 步。每条的要求都是「下一层必须兑现上一层对象」：
 
@@ -176,14 +154,10 @@ YAML `title` 2–6 个汉字；`##` 与 `###` 2–10 个汉字，「常见错误
 8. 类章任务节顺序按上文；任务章的 `###` 顺序与构建脚本步骤顺序一致；目录章的「有几个目录」与目录树项数一致。
 9. 章题一致：引言第一句、各 `##` 中心名词、回顾能力句并排看，三处对象必须与 title 相同；不同说明正文写成了另一章，先改 title 或重排任务节。
 
-## 分层上限
-
-### 计数口径
+### 分层上限
 
 估算 token = 中日韩字符数 × 1.5 + 其他字符数 ÷ 4；只用于预算比较，不声称等于真实 token 数。计入正文、标题、列表、表格、Callout 与链接锚文本；不计 YAML、链接目标、代码围栏、mermaid 与可执行单元全文。任何链接只计锚文本。
 
-### 上限表
-
 | 层级 | 上限 |
 | --- | --- |
 | 整章（frontmatter 外，只含计入部分） | 5000 token |
@@ -198,29 +172,30 @@ YAML `title` 2–6 个汉字；`##` 与 `###` 2–10 个汉字，「常见错误
 | 单个正文段落 | 70–220 token；写作舒适带 90–180。豁免下限：章引言、节导语、紧邻块的单句前导、回顾、自测固定导语、Callout 内段落 |
 | `##` 节导语 | 120 token 且 ≤2 句 |
 | `###` 节导语 | 80 token 且 ≤1 句 |
-| 单个 `>` 引用块 | 80 token |
-| 一章 Callout | 超过 8 个失败；常用 1–3 个 |
 
-数字依据：技术写作社区实践是单节 3–5 分钟阅读（1500–3000 字）、单个功能模块 800–1200 字；按 CJK×1.5 换算，整章 5000 token 约合 3300 汉字的正文当量，是「一节一件事、一章四节左右」的自然边界。
+### 术语与验证策略
+
+- 标题、导语与任务节只用读者在前文已认识的名字；本章新术语在首次真正使用处就近定义，不在标题里抢先出现。
+- 每个任务节交付一个可观察结果；章末「本章回顾」只复述这些结果，不引入新承诺。项目有章节表时，关键、`title` 与二级标题同轮同步。
 
-## 执行与例外
+### 源文件与编译顺序
 
-- `verifying-content.py` 第 3 查按上表逐文件、逐节、逐代码块、逐段核对，超限即失败；调限额只改该脚本常量与本表，两处同步。
-- 根 `index.qmd` 与 part 落地页（`body-classes: index-page`）只核对整章总量与代码块限额，不套标题与骨架限制。
-- 接近上限不是目标：预算是上限，内容仍按第 4 步的凑字数禁令精简。
-- 标题归并：两个标题讲同一件事就并成一个，下层句子跟着走，不重写。
-- 全章重构：第 1–2 步只定删留和标题；发现某段要重写，记下来留给第 5–7 步。
-- 判不准时打开 `examples/02-structure-shape.md`。
+章的关键与头文件里声明的物理顺序冲突时，以编译要求为准：被用到的类型先声明，被依赖的类型留在使用它的类前面。叙述主次由章首与横幅承担，不由声明顺序承担。
 
 ## 情况
 
-- 类章按「类型 → 成员变量 → 最重要函数 → 其余函数」排任务节；没有 `class` 的章按「类型 → 使用这些类型的函数」排。
-- 只有一项交付、没有可独立复现失败症状的工程章，可省「常见错误」，其余固定收尾保留。
-- 着陆页与根首页不套六段骨架，只核对整章预算、标题层级与卡片承诺。
-- 全章重构或跨章搬迁时，先按「章节骨架」定删留，再进入标题与句子步骤。
+### 情况：part 落地页
 
-## 正反例
+落地页的 title 即 part 名，不受 2–6 汉字硬限；引言的范围等于该部分全部章的 title 集合，不写 `description`，卡片标题与一句话描述跟章 title 同轮同步。
+
+### 情况：没有源文件的章
 
-正例：章题「棋盘」→ 引言点明 3×3 棋盘 → 任务节「类型与坐标」「成员与接口」「写入与清空」「终局判定」→ 固定收尾；每个 `##` 都是「棋盘」的一部分。
+没有源文件可摘时照常走六段块序列，但不挂 blob 链接、不写摘录免责句；回顾与自测仍按本章任务节交出的结果写，不借后章内容补。
+
+### 情况：类章与能力章的差异
+
+类章按「类型、成员、最重要函数、其余函数」排任务节；能力章按读者完成任务的先后排。两者都只有一个关键，固定收尾不改名。
+
+## 正反例
 
-反例一：章题「棋盘」，任务节却按「打开文件、修改、编译、运行」排——把读者动作当结构，偏离本章关键。反例二：标题写成「进行棋盘的初始化操作」——空动词加关系词把对象挤到末尾，读者在目录里扫不到「棋盘」。
+通用情况判得准就不打开。判不准时只开 `examples/02-structure-shape.md`，按命中的信号读其中一节。

package/skills/writing-quarto/steps/03-blocks.md

@@ -7,24 +7,24 @@
 
 ### 内容块前后的闭环
 
-一个段落只推进一个对象；小节内出现代码块、列表或表格时，模块内部的次序见下文「三级标题最小模块」，本段只规定导语怎么写：块前用一句完整导语交代为什么看它（对象、谁调用、做什么）——对象写成读者要在块内观察的代码标识符（常量、类型、函数名），只报出处、不点名块内对象的「X 都定义在 state.h 里：」不算导语，读者对不上句中概念与围栏里的名字（对照见 `examples/03-excerpt-lead.md`「摘录导语只报出处」）；点名也不得退化为「`X` 做 A、`Y` 做 B」式的逐条释义，对象要组织进为什么看它的句子里（对照见 `examples/03-excerpt-lead.md`「逐条释义代替动机」）；块后只在有注释未覆盖的新信息时写一句；引言写判断依据，不写「如下：」式的空引导（GitHub 风格指南同款要求：解释文字放在代码块前面，而不是塞进代码注释）。导语预告的对象本体必须出现在导语句里，不得隔着代码块在块后才给出；算式不是例外，换算句式见 `steps/07-layout.md`「列表选择」。
+一个段落只推进一个对象；小节内出现代码块、列表或表格时，模块内部的次序见「三级标题最小模块」，本段只规定导语怎么写：块前用一句完整导语交代为什么看它（对象、谁调用、做什么）——对象写成读者要在块内观察的代码标识符（常量、类型、函数名），只报出处、不点名块内对象的「X 都定义在 state.h 里：」不算导语（对照见 `examples/03-excerpt-lead.md`「摘录导语只报出处」）；点名也不得退化为「`X` 做 A、`Y` 做 B」式的逐条释义，对象要组织进为什么看它的句子里（对照见 `examples/03-excerpt-lead.md`「逐条释义代替动机」）；块后只在有注释未覆盖的新信息时写一句。导语预告的对象本体必须出现在导语句里，不得隔着代码块在块后才给出。算式不是例外，换算句式见 `steps/07-layout.md`「列表选择」。
 
 一个函数小节内部按「声明、一句行为、实现」排列，示例不出现在行为句之前；同一小节出现多个围栏时按阅读顺序排；先定义后调用与未定义名字调用链的处理见 `steps/02-structure.md`「六段块序列」。编号步骤、节首概览或章引言用后文才定义的名字串起一条必须看懂的过程的，整段删除，不改写后留在原位；调用方的实现里第一次见到被调用函数、而该函数要到后面小节才讲的，调整顺序；点名后文章节的函数而那一章并不讲解它的，删掉也不补进那一章。允许：用读者已认识的词预告本节要做的事；同一小节内声明和一句行为紧挨代码；上一章已经讲过的名字。
 
-讲函数体的小节三步固定：导语点名函数并写出头文件上的 `public:` 或 `private:`（如「`Board::HasLine` 声明在 `state.h` 的 `private:` 下」）；第一块围栏是头文件声明，访问说明符那一行留在围栏里；类成员的头文件摘录以源码里的 class 类名 { 或 struct 名 { 开头，接着保留该成员所属的 public:、private: 或 protected: 行，再摘成员，围栏以源码里的 }; 结束。省略的是其他成员，不是类头，也不写省略标记。自由函数、枚举和已经自带 struct 或 enum 的整段定义不另套 class。.cpp 围栏不插入 class 体或访问说明符。声明看不出的步骤才配下一块 `.cpp` 围栏，导语写「实现写在某个 `.cpp` 里」。只讲入口、不讲函数体的小节（如 `Board` 的读写入口）停在头文件声明，不配实现围栏；禁止在 `.cpp` 围栏里插入 `private:`，私有成员身份只由头文件围栏呈现。
+讲函数体的小节三步固定：导语点名函数并写出头文件上的 `public:` 或 `private:`（如「`Board::HasLine` 声明在 `state.h` 的 `private:` 下」）；第一块围栏是头文件声明，访问说明符那一行留在围栏里；类成员的头文件摘录以源码里的 class 类名 { 或 struct 名 { 开头，接着保留该成员所属的 public:、private: 或 protected: 行，再摘成员，围栏以源码里的 }; 结束。省略的是其他成员，不是类头，也不写省略标记。自由函数、枚举和已经自带 struct 或 enum 的整段定义不另套 class。`.cpp` 围栏不插入 class 体或访问说明符。声明看不出的步骤才配下一块 `.cpp` 围栏，导语写「实现写在某个 `.cpp` 里」。只讲入口、不讲函数体的小节停在头文件声明，不配实现围栏；禁止在 `.cpp` 围栏里插入 `private:`，私有成员身份只由头文件围栏呈现。
 
 同一 `##`/`###` 内 ≥2 个代码围栏时，先看是否是紧邻常量与其直接使用行：常量紧接着被下一行使用时，可放在同一个围栏。类型定义和后一步使用它的函数是两步，即使函数用到该类型也分成两块——一个围栏只放正在讲的那一个声明或函数，不把整份头文件、整份类或整条调用链贴进同一个围栏；后一个函数的函数体里可以调用已经讲过的名字，但不把那些函数的实现再贴一遍。每块前一句导语；`{python}` / `{mermaid}` 图或独立验证盒子打断处保持拆块。旧口径「同一小节递进片段必须合并为一个围栏」收窄到此：只有常量紧接着被下一行使用时才放在同一围栏。改写对照见 `examples/03-excerpt-lead.md`「递进片段合并」。
 
-每个围栏在最小模块里的位置见「三级标题最小模块」。仍然禁止块前半句，禁止收束段把列表再讲一遍。可合并的块前与块后并成块前一句；简洁边界仍适用（`steps/05-sentences.md`）。细则与对照见 `steps/05-sentences.md`、`examples/03-excerpt-lead.md`「多代码块一句导语」。
+每个围栏在最小模块里的位置见「三级标题最小模块」。仍然禁止块前半句，禁止收束段把列表再讲一遍。可合并的块前与块后并成块前一句；简洁边界仍适用（`steps/05-sentences.md`）。对照见 `examples/03-excerpt-lead.md`「多代码块一句导语」。
 
-以代码块为中段，导语讲工程语境（这段代码为什么存在、为什么此刻看它）；若有块后句，只讲注释没覆盖的新工程关系。语法细节不逐行展开。导语与块后都禁止关键字释义当开场：不写「X 是 `inline constexpr` 常量」「用 `enum class` 表达」「用有符号整型承载」「坐标字段为什么选定宽有符号」式语言课或选型旁白（除 01 设计章外工程 qmd 禁选型外链），改写对照见 `examples/01-language-scope.md`「语言课旁白与工程旁白」。
+以代码块为中段，导语讲工程语境（这段代码为什么存在、为什么此刻看它）；若有块后句，只讲注释没覆盖的新工程关系。语法细节不逐行展开。导语与块后都禁止关键字释义当开场：不写「X 是 `inline constexpr` 常量」「用 `enum class` 表达」「用有符号整型承载」「坐标字段为什么选定宽有符号」式语言课或选型旁白（除设计章外工程 qmd 禁选型外链），改写对照见 `examples/01-language-scope.md`「语言课旁白与工程旁白」。
 
 块后五条硬禁令：
 
 - **禁止正文复述围栏内注释**：代码块内 `//` / `#` 注释已写明的意图、产物路径或字段含义，块后正文不得同义再讲一遍；块后只写注释没覆盖的新工程信息（谁调用、如何验证、与邻块或图的关系）。改写对照见 `examples/03-block-after.md`「块后复述注释」。
-- **禁止块后复述围栏内的字面值**：围栏已经写出 `kBoardRows = 3`、`row` / `col` 或函数签名时，块后不写「`kBoardRows` 和 `kBoardCols` 都取 3，`CellPosition` 的 `row` 与 `col` 保存这对数字」。数字、字段名和签名从围栏直接可读，块后只写围栏没给出的行为、约束、调用关系或后果；需要读者注意某个值，就在导语里说明它约束什么，不在块后翻译一遍。改写对照见 `examples/03-block-after.md`「块后复述字面值」。
+- **禁止块后复述围栏内的字面值**：围栏已经写出 `kBoardRows = 3`、`row` / `col` 或函数签名时，块后不写「`kBoardRows` 和 `kBoardCols` 都取 3，`CellPosition` 的 `row` 与 `col` 保存这对数字」。数字、字段名和签名从围栏直接可读，块后只写围栏没给出的行为、约束、调用关系或后果；需要读者注意某个值，就在导语里说明它约束什么。改写对照见 `examples/03-block-after.md`「块后复述字面值」。
 - **禁止单段夹杂多个并列对象**：一段一对象的通则见 `steps/04-paragraphs.md`「段落规则」；块后的递进依赖链不算并列：先按上文递进合并判定并成一块、块后列表分项，不按本条拆段。多代码块小节里每段最多一句 + 一个配套块。改写对照见 `examples/03-block-after.md`「单段混并列对象」与 `examples/03-excerpt-lead.md`「递进片段合并」。
-- **禁止块后悬空指代围栏内的实体**：块后段落首次提及代码块引入的常量、类型或函数时点名标识符；先行词只出现在围栏里（不在任何句中）时，不得用「这三个常量」「它们」式省称开场。导语或前段已逐一点名后，后文才可用集合指称回指（与 `steps/05-sentences.md`「一句不换对象」同界）；建立多个对象的关系时用一句写全谁约束谁、谁派生自谁（模板见 `scripts/verifying-content.py`「禁用与替换」的契约链行）。改写对照见 `examples/03-block-after.md`「块后悬空指代」。
+- **禁止块后悬空指代围栏内的实体**：块后段落首次提及代码块引入的常量、类型或函数时点名标识符；先行词只出现在围栏里（不在任何句中）时，不得用「这三个常量」「它们」式省称开场。导语或前段已逐一点名后，后文才可用集合指称回指（与 `steps/05-sentences.md`「一句不换对象」同界）；建立多个对象的关系时用一句写全谁约束谁、谁派生自谁。改写对照见 `examples/03-block-after.md`「块后悬空指代」。
 - **禁止块后正文逐条释义代替设计动机**：块后散文段落不是成员清单的重写，连续的「`标识符`＋动词短语」释义只回答「是什么」，要写出为什么这样设计、对调用方意味着什么，释义只在服务动机的句子里出现；公式的每一项是否拆成列表项，见 `steps/07-layout.md`「列表选择」换算条。改写对照见 `examples/03-excerpt-lead.md`「逐条释义代替动机」。
 
 渐进披露不进正文：语法细节延后展开是 Agent 侧写作策略，禁止把策略写成对读者的话——「语法细节留到后续章节真正用到时再展开」「本章只需认清……」这类元叙述一律不出现在 `content/**`；正文直接陈述对象和结果（如「这段程序对外可见的结果只有两处：……」），需要延后的内容保持沉默即可。改写对照见 `examples/06-wording-cases.md`，禁用词见 `steps/06-wording.md`。
@@ -35,34 +35,15 @@
 
 代码块导语禁用「N 段命令定义」式元计数：直接点名这段规则定义的对象，不用「先…再…最后…」，不叫读者回数段落；改写对照见 `examples/03-qmd-elements.md`「代码块导语元计数对照」。
 
-### 代码块 filename 标注
+### 三级标题最小模块
 
-来源文件、执行位置、输出场景写在代码块标题里，正文不重复「下面是 xxx 的源码/一段命令」这类视觉上已存在的信息。
-
-**片段优先**：每个 `##`（或 `###`）只展示正式代码里与本节任务最相关的一块并精讲，默认内联摘录，不用 include 拷贝整个文件；紧邻常量与其直接使用行合成的单围栏算「一块」（判定见下文「内容块前后的闭环」）：
+一个三级标题下面的正文由一到两个最小模块组成。一个模块是一个整体，次序固定：标题已经给出对象；标题下一句导语；有并列取值时跟着列表，一项一个取值、一项一句；代码块、表格或图放在列表和收束段之间；没有列表时放在导语和收束段之间；收束段只写各项共同的契约；Callout 可有可没有，写了就放在收束段之后。短模块可以只有导语和代码块。示例章「操作与成败」里的 `Move` 与 `PlaceResult` 各是一个短模块，下一个短模块用自己的导语接上。第二个模块用来解释前一个时，衔接句就是第二个模块的导语。示例章「数据项坐标」用「下面的图标出这块状态面板上可用的 `(row, col)`。」接上图。讲一个函数时，先一个模块讲 `.h`，再用导语接 `.cpp`。列表写选法，围栏与源文件逐字一致，收束段不把列表再写一遍。禁止「每个状态码对应」，也禁止以 `` `类型::kName`： `` 开头的释义项。正面例子是 示例章「操作的强度」。
 
-````markdown
-```{.cpp filename="main.cpp"}
-#include <iostream>
+### 节末旁注与 Callout 收尾
 
-int main() {
- std::cout << "Hello, World!\n";
- return 0;
-}
-```
-````
+二级标题的最后一个内容块只承载旁注时，改写成 Callout 收尾，正文不再保留同一句。旁注是读者跳过也能完成本节、回看能少走弯路的补充：可重新生成的产物、版本差异、可选替代、边界条件。本节结论、下一步动作、必经步骤与成功判据留在正文。
 
-- 片段必须逐字摘自源文件，禁止改写、合并或重排源代码行；注释与空行可以省略，省略处直接省略，不写任何标记行。
-- **filename 一律短显示名**：只写 `main.cpp`、`CMakeLists.txt`、`running-build.sh`、`example/` 这类短名；禁止把 `src/...` 或 `shared/...` 深层路径塞进标题栏。完整位置由章引言的 GitHub 链接和目录树提供；`verifying-content.py` 用本章内、代码块之前 basename 匹配的最近一条 blob 链接解析真实路径再做片段核对。
-- **filename 不写链接**：`filename="..."` 是纯文本短名，禁止塞 Markdown 链接；`resolve_fragment_source` 的解析只认正文句子里的链接，标题栏写链接既渲染不出可点样式，也会被 `verifying-content.py` 判失败。
-- **blob 链接嵌进导语句**：GitHub blob 链接写在同节导语的完整句子里（正例：「apps/CMakeLists.txt 用一行目标属性固定运行时库查找」，其中文件名是 GitHub 链接的锚文本），禁止整行仅为链接单独成行贴在代码围栏上方（可夹空行，`verifying-content.py` 判失败）。悬空的裸链接行既不像正文也不像说明，读者扫读时只剩一个锚点。
-- **本章主源文件可重复挂链接，其他仓库路径每章至多一条**：章引言用可跳转链接（内联 `[]()` 或同页引用式 `[label][id]`）挂本章主源文件（如 `board.h`、`board.cpp`），正文再点名这些文件时复用同一 GitHub 链接，读者不用回翻章首。不在章引言挂链接的其他仓库文件，正文用行内代码，不包链接；跨章指称用章节标题链接。同一章摘录另一阶段目录的同名文件时，在切换处再挂一条不同 URL（对照见 `examples/03-excerpt-lead.md`「摘录链接密度」；`verifying-content.py` 只对非章引言主源文件的同章重复 URL 判失败）。本条挂在写作步骤的定版式。
-- 片段内注释硬限：每处实现注释（`//` 或 `#`）不超过 3 行（与源文件注释规范的 1–3 行同一口径）、单行不超过 100 列（与源文件 `ColumnLimit: 100` 同一口径；正文散文的 40 字限不套到代码注释），只写这段代码做什么；CMake/Shell 等命令型片段每条命令保留一行意图注释。Doxygen `///` 声明块（概述、空 `///` 与细节）是声明骨架的一部分，摘录随源保留，不受此限。命名惯例、官方建议、未来演化等规范说理一律不进代码块；术语卡和可跳过的操作提醒可以进 callout，注释怎么写、行尾先写什么、`///` 与 `@` 标签怎么分工只留在 `.agents`，面向作者的进知识文件。
-- 首讲某段源码的章节不省略源码既有的职责注释：注释是读者读到的第一层讲解；「注释与空行可以省略」只服务后续章节复现已见代码。源码缺注释时交给项目 C++ 流程补齐，本技能不替源码补注释。
-- 讲解段只解释片段中实际出现的代码；片段没有展示的内容要么补进片段、要么进 callout，不在正文列表里讲代码外面的东西。
-- include 短代码降级为可选手段：仅用于确实需要完整展示且很短的文件，并仍须包在带语言标注的围栏代码块内（包裹规则见 `quarto/render.md`）。
-- 手动命令块标注执行位置，如 `filename="WSL Ubuntu（仓库根目录）"`。
-- 输出效果类代码块（运行效果、预期输出）filename 只写场景名（如「运行效果」）；终端样式、颜色等展示细节写进正文，不进 filename。输出摘录用单独一行 `...` 表示省略的工具输出，与源码片段的省略是两回事。
+收尾 Callout 放在本节最后一块之后、下一个标题之前；每节至多一个收尾 Callout。正文必须脱离前文也能读懂：点名对象，写出前提与结果，不复用上一段的句子；超过两段或需要列举时改用 `###` 小节。正反例见 `examples/03-qmd-elements.md`「节末旁注改为 Callout 收尾」。
 
 ### 代码块门槛
 
@@ -82,54 +63,61 @@ int main() {
 
 摘录 `class` 或多函数片段时**保留**源码中函数之间的空行，禁止为省行数坍缩成函数注释贴着下一声明；省略部分成员时，被保留的相邻函数之间仍空 1 行；同一 access 段内最后一组数据成员与函数之间空 1 行，数据成员组内不空行。与「逐字摘录」冲突时以源码空白为准：教学缩略可删成员，不可删「函数间距」惯例。
 
-### 正文与代码注释分工
-
-代码块是源文件的逐字摘录，它承载理解这段代码所需的细节：契约、设计理由、边界与失败方式都留在块内注释里。正文不再转述这些细节，只写读者必须带走的判断。
-
-- **块内注释负责细节**：`///` 契约、`@param`/`@return`、实现注释里的次序依赖与边界，都随摘录保留。正文删掉注释已写明的返回值和参数含义。
-- **正文只写三类信息**：为什么这样设计（取舍）、读者接下来要用它做什么、几个块之间的工程关系。一条简单的 `return`、一个参数名、一个枚举取值，正文一句带过或直接不写。
-- **不复述成列表**：把注释里的三条契约改写成正文三条项目符号，等于把代码读了两遍。需要并列判断时，先看能不能并成一句；并不成再用列表。
-- **不写注释元叙述**：正文不交代「类说明没有逐个列出成员」「每个成员的用法写在行尾注释里」「理由写在类型注释里」这类关于注释怎么写的策略；读者需要的事实直接陈述，作者怎么组织注释是技能规则，不进正文。
-- **正文长度随注释密度反向走**：块内注释越完整，块后段落越短。块后只剩一句读者该取走的结论时，就只写一句，不必凑段。
-
-改写对照见 `examples/03-block-after.md`「块后复述注释」。
-
-## 三级标题最小模块
+### 摘录与源文件注释
 
-一个三级标题下面的正文由一到两个最小模块组成。一个模块是一个整体，次序固定：标题已经给出对象；标题下一句导语；有并列取值时跟着列表，一项一个取值、一项一句；代码块、表格或图放在列表和收束段之间；没有列表时放在导语和收束段之间；收束段只写各项共同的契约；Callout 可有可没有，写了就放在收束段之后。短模块可以只有导语和代码块。示例章「操作与成败」里的 `Move` 与 `PlaceResult` 各是一个短模块，下一个短模块用自己的导语接上。第二个模块用来解释前一个时，衔接句就是第二个模块的导语。示例章「数据项坐标」用「下面的图标出这块状态面板上可用的 `(row, col)`。」接上图。讲一个函数时，先一个模块讲 `.h`，再用导语接 `.cpp`。列表写选法，围栏与源文件逐字一致，收束段不把列表再写一遍。禁止「每个状态码对应」，也禁止以 `` `类型::kName`： `` 开头的释义项。正面例子是 示例章「操作的强度」。
+来源文件、执行位置、输出场景写在代码块标题里，正文不重复「下面是 xxx 的源码/一段命令」这类视觉上已存在的信息。
 
-### 节末旁注与 Callout 收尾
+**片段优先**：每个 `##`（或 `###`）只展示正式代码里与本节任务最相关的一块并精讲，默认内联摘录，不用 include 拷贝整个文件；紧邻常量与其直接使用行合成的单围栏算「一块」（判定见「内容块前后的闭环」）：
 
-二级标题的最后一个内容块只承载旁注时，改写成 Callout 收尾，正文不再保留同一句。旁注是读者跳过也能完成本节、回看能少走弯路的补充：可重新生成的产物、版本差异、可选替代、边界条件。本节结论、下一步动作、必经步骤与成功判据留在正文。
+````markdown
+```{.cpp filename="main.cpp"}
+#include <iostream>
 
-收尾 Callout 放在本节最后一块之后、下一个标题之前；每节至多一个收尾 Callout。正文必须脱离前文也能读懂：点名对象，写出前提与结果，不复用上一段的句子；超过两段或需要列举时改用 `###` 小节。正反例见 `examples/03-qmd-elements.md`「节末旁注改为 Callout 收尾」。
+int main() {
+ std::cout << "Hello, World!\\n";
+ return 0;
+}
+```
+````
 
-### 执行位置判据
+- 片段逐字摘自源文件，不改写、合并或重排源代码行；注释与空行可整段省略，省略处不写标记行。
+- **filename 一律短显示名**：只写 `main.cpp`、`CMakeLists.txt`、`running-build.sh`、`example/` 这类短名；禁止把 `src/...` 或 `shared/...` 深层路径塞进标题栏。完整位置由章引言的 GitHub 链接和目录树提供；`verifying-content.py` 用本章内、代码块之前 basename 匹配的最近一条 blob 链接解析真实路径再做片段核对。
+- **filename 不写链接**：`filename="..."` 是纯文本短名，禁止塞 Markdown 链接；`resolve_fragment_source` 的解析只认正文句子里的链接，标题栏写链接既渲染不出可点样式，也会被 `verifying-content.py` 判失败。
+- **blob 链接嵌进导语句**：GitHub blob 链接写在同节导语的完整句子里（正例：「apps/CMakeLists.txt 用一行目标属性固定运行时库查找」，其中文件名是 GitHub 链接的锚文本），禁止整行仅为链接单独成行贴在代码围栏上方（可夹空行，`verifying-content.py` 判失败）。
+- **本章主源文件可重复挂链接，其他仓库路径每章至多一条**：章引言用可跳转链接挂本章主源文件（如 `board.h`、`board.cpp`），正文再点名这些文件时复用同一 GitHub 链接；不在章引言挂链接的其他仓库文件，正文用行内代码，不包链接；跨章指称用章节标题链接。同一章摘录另一阶段目录的同名文件时，在切换处再挂一条不同 URL（`verifying-content.py` 只对非章引言主源文件的同章重复 URL 判失败）。
+- 片段内注释硬限：每处实现注释（`//` 或 `#`）不超过 3 行（与源文件注释规范同一口径）、单行不超过 100 列（与源文件 `ColumnLimit: 100` 同一口径；正文散文的 40 字限不套到代码注释），只写这段代码做什么；CMake/Shell 等命令型片段每条命令保留一行意图注释。Doxygen `///` 声明块随源保留，不受此限。命名惯例、官方建议等说理不进代码块；术语卡与操作提醒可以进 callout。
+- 首讲某段源码的章节不省略源码既有的职责注释：注释是读者读到的第一层讲解；「整段省略」只服务后续章节复现已见代码。源码缺注释交给项目 C++ 流程。
+- 讲解段只解释片段中实际出现的代码；片段没有展示的内容要么补进片段、要么进 callout，不在正文列表里讲代码外面的东西。
+- include 短代码降级为可选手段：仅用于确实需要完整展示且很短的文件，并仍须包在带语言标注的围栏代码块内（包裹规则见 `quarto/render.md`）。
+- 手动命令块标注执行位置，如 `filename="WSL Ubuntu（仓库根目录）"`；输出效果类代码块 filename 只写场景名（如「运行效果」），终端样式、颜色等展示细节写进正文，不进 filename。输出摘录用单独一行 `...` 表示省略的工具输出，与源码片段的省略是两回事。
+- 读者正文不摘文件级 Doxygen 头：`/// @file`、`/// @brief` 与文件范围段都不进正文，围栏从其后开始。
+- 围栏保留的声明带 `///` 注释时，整段必须与源文件该声明上方一致，`@param`、`@return` 与空 `///` 行一并保留；整段不摘可以，只摘概述行不行。
+- 润色或回读发现围栏与源文件不一致，打开该源文件把围栏改一致；只读对应声明。
 
-故障定位第一步是确认执行位置和前置状态，给可观察判据而不是模糊要求：Shell 场景用 `pwd` 看路径结尾，工程场景用特征文件（如 `CMakeLists.txt`）存在性判断。
+### 正文与代码注释分工
 
-### 命令介绍模式
+代码块是源文件的逐字摘录，它承载理解这段代码所需的细节：契约、设计理由、边界与失败方式都留在块内注释里。正文不再转述这些细节，只写读者必须带走的判断。
 
-讲解工具链命令（CMake、CTest 等）时：命令名用行内代码，每条命令一句话职责；参数只在影响当前理解时展开，完整语义不进正文；默认不放官方文档链接，需要深入时由章末参考资料或确实反直觉处的单个链接承担。
+- **块内注释负责细节**：`///` 契约、`@param`/`@return`、实现注释里的次序依赖与边界，都随摘录保留。正文删掉注释已写明的返回值和参数含义。
+- **正文只写三类信息**：为什么这样设计（取舍）、读者接下来要用它做什么、几个块之间的工程关系。一条简单的 `return`、一个参数名、一个枚举取值，正文一句带过或直接不写。
+- **不复述成列表**：把注释里的三条契约改写成正文三条项目符号，等于把代码读了两遍。需要并列判断时，先看能不能并成一句；并不成再用列表。
+- **不写注释元叙述**：正文不交代「类说明没有逐个列出成员」「每个成员的用法写在行尾注释里」「理由写在类型注释里」这类关于注释怎么写的策略；读者需要的事实直接陈述。
+- **正文长度随注释密度反向走**：块内注释越完整，块后段落越短。块后只剩一句读者该取走的结论时，就只写一句。
 
-职责句点名对象类型与配合关系：`target_compile_features(app PRIVATE cxx_std_20)` 写作「要求可执行目标 `app` 使用 C++20；`PRIVATE` 只作用于该目标」，禁笼统「给目标声明…只约束这个目标自己」。命令中的路径展示真实值：直接写变量本体（如 `set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")`），正文用 `build/bin/...` 描述落地位置；不引入 `<binary-dir>` 式占位符，也不在正文解释占位符与真实变量的对应关系。
+改写对照见 `examples/03-block-after.md`「块后复述注释」。
 
 ### 代码与图的桥接
 
-代码块引出 `{mermaid}` 图或 `{python}` 坐标图时按固定序列组织：代码块 → 桥接句 → 图（含 `fig-cap`）→ 图后新结论。固定序列的完整写法见 `writing-quarto` 技能 `quarto/authoring.md`「代码与图的桥接」，边界如下：
+代码块引出 `{mermaid}` 图或 `{python}` 坐标图时按固定序列组织：代码块 → 桥接句 → 图（含 `fig-cap`）→ 图后新结论。固定序列的完整写法见 `quarto/authoring.md`「代码与图的桥接」，边界如下：
 
 - 代码块与图之间必须有桥接句，说明图要核对代码已讲清的哪条关系；中间只有空行视为堆叠（`verifying-content.py` 的 DOC-E11 只要求相邻围栏留空行，空行不等于桥接正文）。
 - 图后先给「从图带走的结论」或图外新信息，再进入下一块；小节以图收尾时，结论可并入桥接段，不在图后孤悬一句。图注已写明的信息不复述。坐标图计入盒子密度，口径见 `quarto/coords.md` 与本文件。
-- 图注与图前句分工：图注写图面内容与读法，落在图下；图前只写引出关系的一句，不写“下图标出……”这类图面说明。三类图（Mermaid、坐标图、原生 HTML/SVG）的写法见 `quarto/figures.md`。
-- 一图一事、同主题相邻、图不承载正文未写的新信息：一张图只核对一条已讲清的关系；代码与图主题不同时收束本对象再拆 `###`，禁止「代码 A → 短句拐弯 → 图讲 B → 再贴代码 C」的同节混排（上述边界的写法见 `quarto/authoring.md`「代码与图的桥接」）。
-- 图前段只讲本页可见的对象，且单一主题：描述版式的句子其对象必须同页可见，引用前章画面时复述读者需要的关键事实（如行列取值 0 到 2），不指称前章画面的版式（「画面上方是列号」式会让读者翻回前章）；调用方行为等第二主题移出图前段（示例章定义坐标范围节两段并一段的改稿对照）。
+- 图注与图前句分工：图注写图面内容与读法，落在图下；图前只写引出关系的一句，不写「下图标出……」这类图面说明。三类图（Mermaid、坐标图、原生 HTML/SVG）的写法见 `quarto/figures.md`。
+- 一图一事、同主题相邻、图不承载正文未写的新信息：一张图只核对一条已讲清的关系；代码与图主题不同时收束本对象再拆 `###`，禁止「代码 A → 短句拐弯 → 图讲 B → 再贴代码 C」的同节混排。
+- 图前段只讲本页可见的对象，且单一主题：描述版式的句子其对象必须同页可见，引用前章画面时复述读者需要的关键事实（如行列取值 0 到 2），不指称前章画面的版式；调用方行为等第二主题移出图前段。
 
 图不能替代结论句：桥接句与图带走的结论缺任何一处，读者只有图没有判断依据。正反对照见 `examples/03-qmd-elements.md`「代码与图桥接对照」。
 
-### 状态面板三态在页面上的摆法
-
-数据项类型（画面、字符与取值的定稿见术语表「数据项类型」）上页面只有两种摆法：三态是本页话题时，枚举出现之前放终端的这一行 `|   | X | O |`，点名顺序与从左到右一致；这一页已经有整盘画面时，指向上图里没有字母的那一格，不再放第二行。围栏里的行尾注释与头文件逐字一致。
-
 ### 短表与宽表
 
 - **短标签 + 长说明两列表**：包 `::: {.compact-table}`，并设 `tbl-colwidths="[22,78]"`，不靠浏览器均分。
@@ -138,59 +126,15 @@ int main() {
 - 主题 CSS 全宽（`width: 100%`）、左对齐，与正文同宽不居中。表前一句问什么，表后一句结论。
 - Pipe 表原生 `colwidth` 在本栈无效时用 Quarto `tbl-colwidths`；不为单表写 raw HTML。
 
-### 盒子密度
-
-盒子指代码块、表格、提示框、引用块、图表容器。密度按本节与「机械检查」的软门禁人工判断，不设硬阈值。
-
-### 标题导语
-
-`##` 下不强制写导语。只有导语补充任务顺序、前置条件、范围或标题没有表达的结果时才保留；把标题换一种说法的导语删除。代码块前不固定用冒号，冒号的合法场合见 `steps/04-paragraphs.md`「散文伪标签冒号禁令」。
-
-### 小节标题与正文对齐
-
-小节标题用了读者没学过的术语怎么办：标题要么已建立、要么当场用实物建立，做不到就下沉。规则如下：
-
-- 小节标题、首句和正文指向同一个动作或对象；标题说「做什么」，正文就只写怎么做、看到什么算成功。对象是否对齐，按 `steps/02-structure.md`「纵向承诺链」第 4、5 条核对。块后许可的新信息不豁免标题对齐：树后或块后补写的内容，主语仍须是本节标题的对象，换成另一对象即视为换节。后文小节专讲的对象不提前交接，判法见 `steps/05-sentences.md`「句内骨架」。
-- 标题的词性、空心题与术语禁令见 `steps/02-structure.md`「标题分层」；术语要么已被前文章节建立，要么当场用读者可核对的实物（目录、文件、代码）建立；做不到就把内容下沉到概念建立之后的章节，章际下沉见 `steps/02-structure.md`「六段块序列」。小节标题用了读者没学过的术语，就是这里要拦的;一句话压缩多个论断而读者无法逐条核对的，拆成可核对表述或删除；首句先给中心判断，再补机制，不先堆名称后给结论。正文论据同受此限：未在正文展示过的代码标识符（如测试概念建立前引用 `BoardTest`）不作论据，验证职责下沉到展示它的章节。改写对照见 `examples/02-structure-shape.md`「小节标题抽象与首句无中心」。
-- 操作小节（如「运行一键脚本」）只保留动作、顺序与可见结果。「为何不跳过某步 / 幂等 / 配置漂移」类工程取舍，删除后不影响首次跑通与验收的，不进该节正文；确需保留时由代码注释或排查节承担。
-- 跨节复述同一取舍视为标题离题的变体：该内容归属最贴合的节（如「修改 CMakeLists 后行为没变」），其余位置只保留一句或链接。
-
-### 块链检查清单
-
-段落之外，标题、列表、代码、表、图与 Callout 之间按以下闭环核对；每条只指回权威出处，不另立第二份长文：
-
-| 边界 | 规则摘要 | 权威 |
-| --- | --- | --- |
-| 标题 → 正文 | 标题下至少一句引导；禁止 `##` 后立刻 `###` 叠标题 | `steps/02-structure.md` 与本文件 |
-| 段 → 列表 | lead-in 含主谓、点名列表将展开的维度；完整句可用句号，明确「如下」时用冒号；列表项平行且字数带 | `steps/07-layout.md`「列表选择」 |
-| 段 → 代码 | 一句完整导语（对象标识符 + 谁调用/做什么）→ 围栏；禁块前半句 + 块后补半句；函数或枚举围栏前固定两句：第一句接住上一句的对象并点名函数或枚举，第二句写读者为什么要看它、它在调用链里的位置或与邻块的关系；可以沿用围栏 `///` 的术语，但不得同义复述注释；位置写成「定义在 `文件` 里」，不用「声明在」 |本文件「内容块前后的闭环」 |
-| 代码 → 图 | 代码 → 桥接句 → 图 → 图后结论；空行 ≠ 桥接 |本文件「代码与图的桥接」 |
-| 段 → 表 | 关系句引出 → 表 → 表后结论句 |本文件「短表与宽表」 |
-| 任意块 → Callout | Callout 只承载可跳过提示，不复述块内已写信息，不承载唯一成功判据 |本文件「元素边界」 |
-| 节尾 → 下节 | 下节首句接住上节对象；禁正文「下一节/上一节」；章末「下一章」仅在回顾 | `steps/04-paragraphs.md`「段间：过渡句只在话题切换处」、`steps/02-structure.md` |
-| 章际 → 本章 | 第 N 章引言、任务节与自测题只用 1..N-1 章已建立的名字；新术语首次出现处就近落术语卡或行内括号 | `steps/02-structure.md`「六段块序列」 |
-
-### 豁免与边界
-
-- 块级前后闭环（三级标题最小模块）见本文件；本文件管段落与小节之间的衔接，不重复块内规则。
-- 多命令代码块后的逐条讲解，见 `steps/04-paragraphs.md`「段落规则」。
-- 小节承接正文权重与盒子密度见本文件。
-- 散文冒号豁免清单与表格单元格、协议字面量的豁免见 `steps/04-paragraphs.md`「散文伪标签冒号禁令」；代码注释的冒号句式不属本技能。
+表格格里写完整可核对的信息，不写电报式省略。对象先行：先给对象，再给约束或结果。格子不写「名词：一句」，列已经把名称和说明分开。agents 文档的表格允许短语压缩，但不能和新决定相反。
 
-### 机械检查
+### 盒子密度
 
-- 引章两个散文段、导语 token 与句数、段落篇幅：`verifying-content.py` 自动执行（限额见 `steps/02-structure.md`）。
-- 普通自然段低于 token 下限：`verifying-content.py` 自动执行；豁免清单见 `steps/02-structure.md`「分层上限」。
-- 同段连续分句引入新的行内代码标识且无回指词：启发式 WARN，不追清零；高精度过简清单仍靠人工对照 cases。
-- 读者正文「下一节／上一节」、罗列短句信号等高精度项：`verifying-content.py`。
-- 「由…完成」被动交接（句内骨架判定信号之一，见 `steps/05-sentences.md`「句内骨架」）：`verifying-content.py` 仅对读者 qmd 围栏外正文硬拦；`.agents` 案例可引用反例，不扫。
-- 拉链句高频词「分别交给」「各说一层」（见 `steps/05-sentences.md`「拉链句」）：`verifying-content.py` 仅对读者正文硬拦；宽泛的「分别」不拦，留给人工对照案例。
-- 散文伪标签冒号与段内同义堆叠（见 `steps/04-paragraphs.md`）：`verifying-content.py` 启发式 WARN（人工判，不追清零）。
-- 句子模块切分的三类失败（类型接线句、「接着看／第 N 个枚举」改口、全称被下一句否定，见 `steps/05-sentences.md`「一次对话」）：`verifying-content.py` 全量执行；段中心写不出与对话件数不做正则，留给步骤与案例。
+盒子指代码块、表格、提示框、引用块、图表容器，含 `{mermaid}` 图与 `{python}` 坐标图单元。密度按本节与「机械检查」的软门禁人工判断，不设硬阈值。
 
-### 表格格
+盒子按最小模块计：一个模块一块代码、表或图；同一三级标题两个模块时可以有两块，中间必须有衔接句。Callout 不算这块主内容。它们底色与边框一致、左右内缩相同，连续出现时读者分不清内容边界，页面从「读一段做一步」退化成「抄一屏」。因此一条主线动作配一段自己的承接正文，相邻盒子最多一处，其余被正文隔开。每两个盒子之间至少有一段交代判断依据的话；代码块与图之间的固定桥接序列见「代码与图的桥接」。
 
-表格格里写完整可核对的信息，不写电报式省略。对象先行：先给对象，再给约束或结果。格子不写「名词：一句」，列已经把名称和说明分开。agents 文档的表格允许短语压缩，但不能和新决定相反。
+修法是补承接正文，而不是删盒子。盒子承担可复制性，正文承担判断依据，两者不可互换。
 
 ### 正文与 Callout 的重量平衡
 
@@ -200,53 +144,78 @@ int main() {
 
 ### 结果型 Callout 的边界
 
-把提示符判据留在正文，再把符号含义放进 Callout，会把同一个观察对象拆成两处：读者先看到一个结论，跳过提示框后又不知道如何理解它。把两部分都塞回正文，则会让结尾重新变成长段。结果型 Callout 解决的是这种"判据本身也是解释对象"的局部问题，不是把成功路径移出正文的通用许可。
+把提示符判据留在正文，再把符号含义放进 Callout，会把同一个观察对象拆成两处：读者先看到一个结论，跳过提示框后又不知道如何理解它。把两部分都塞回正文，则会让结尾重新变成长段。结果型 Callout 解决的是这种「判据本身也是解释对象」的局部问题，不是把成功路径移出正文的通用许可。
 
 使用时必须同时满足四点：成功判据是稳定、可直接观察的界面或状态。判据需要继续拆解字段、范围或含义。提示出现后本任务没有其他必经动作。正文已经用检查动作和明确的前瞻完成交接，且 Callout 首句直接兑现该检查动作。若后续还要输入命令、做选择或根据结果修复，判据必须留在正文操作位置。
 
-"含义和范围如下"只说明后文目录，没有告诉读者要对照什么。Callout 再从"出现……"重新建立条件，会让同一次判断被拆成两次起句。改写时，正文提出"请对照下面的格式确认结果，并了解后续范围"，Callout 首句直接给出"看到……说明……"。正文负责建立检查动作，Callout 负责呈现判据，二者接力而不重复全文。
+「含义和范围如下」只说明后文目录，没有告诉读者要对照什么。Callout 再从「出现……」重新建立条件，会让同一次判断被拆成两次起句。改写时，正文提出「请对照下面的格式确认结果，并了解后续范围」，Callout 首句直接给出「看到……说明……」。正文负责建立检查动作，Callout 负责呈现判据，二者接力而不重复全文。
 
 ### 命令、输出与细节各司其职
 
-命令是输入，输出是观察，正文是判断依据。三者混在同一个代码块或连续多个解释段落中，会让读者自己筛选"哪些行要复制、哪些行只是说明"。因此闭环目标、命令和成功判据各保留一个权威位置，操作小节拥有命令与验收，回顾和相邻段落只补充新增信息。路径、版本号等随环境变化的输出应展示可识别的典型形态，并给出"每项都有非空结果"这类稳定判据，而不是要求逐字匹配示例。成功判据与证据层级相称的要求见 `steps/02-structure.md`「术语与验证策略」。
+命令是输入，输出是观察，正文是判断依据。三者混在同一个代码块或连续多个解释段落中，会让读者自己筛选「哪些行要复制、哪些行只是说明」。因此闭环目标、命令和成功判据各保留一个权威位置，操作小节拥有命令与验收，回顾和相邻段落只补充新增信息。路径、版本号等随环境变化的输出应展示可识别的典型形态，并给出「每项都有非空结果」这类稳定判据，而不是要求逐字匹配示例。成功判据与证据层级相称的要求见 `steps/02-structure.md`「术语与验证策略」。
 
-### 盒子与正文的比例
+讲解工具链命令（CMake、CTest 等）时：命令名用行内代码，每条命令一句话职责；参数只在影响当前理解时展开，完整语义不进正文；默认不放官方文档链接，需要深入时由章末参考资料或确实反直觉处的单个链接承担。
 
-盒子按最小模块计：一个模块一块代码、表或图；同一三级标题两个模块时可以有两块，中间必须有衔接句。Callout 不算这块主内容。盒子指代码块、表格、提示框、引用块、图表容器，含 `{mermaid}` 图与 `{python}` 坐标图单元。它们底色与边框一致、左右内缩相同，连续出现时读者分不清内容边界，只能靠滚动位置感知，页面从「读一段做一步」退化成「抄一屏」。因此一条主线动作配一段自己的承接正文，相邻盒子最多一处，其余被正文隔开。每两个盒子之间至少有一段交代判断依据的话；代码块与图之间的固定桥接序列见本文件。
+职责句点名对象类型与配合关系：`target_compile_features(app PRIVATE cxx_std_20)` 写作「要求可执行目标 `app` 使用 C++20；`PRIVATE` 只作用于该目标」，禁笼统「给目标声明…只约束这个目标自己」。命令中的路径展示真实值：直接写变量本体（如 `set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")`），正文用 `build/bin/...` 描述落地位置；不引入 `<binary-dir>` 式占位符，也不在正文解释占位符与真实变量的对应关系。
 
-修法是补承接正文，而不是删盒子。盒子承担可复制性，正文承担判断依据，两者不可互换，代码块删到只剩命令不会自动产生判断依据。
+### 元素边界
 
-代码块前后的文字重量也应服务同一个任务闭环。代码块前至少说明读者要完成什么、在哪里执行以及执行后会发生什么；代码块后只说明下一步、可观察结果或一个必要的新人解释。若提示符、参数含义等补充信息不影响主线执行，可在主线结果确认后放进一个短 Callout；Callout 只解释新信息，承载边界见本文件「元素边界」。
+细节升级为标题的门槛见 `steps/02-structure.md`「标题分层」。常见错误使用三级结构，是因为目录负责导航、具体症状负责识别、有序步骤负责操作；这种分层只收束任务段内部的阅读路径，不重新定义引言、任务序列、排查、自测和回顾的页面职责。
 
-密度比例不设硬阈值。盒子多少、正文长短同时取决于视口宽度、字体度量和 Quarto 版本的 DOM 结构，任何一项变化都会让历史数值失效，基于 DOM 或截图的硬编码门禁只会在与密度无关的改动上误报，仍然禁止。`verifying-content.py` 保留一条软门禁：同一小节内两围栏（含 `{mermaid}` 与 `{python}` 单元）之间只有空行、没有桥接正文时报 WARN，提示人工补承接句；WARN 不判失败，人审与对照案例仍是叙事的主检查。
+Callout 只承载读者跳过也能完成本节的提示：可重新生成的产物、版本差异、可选替代、边界条件；本节结论、下一步动作、必经步骤与成功判据留在正文。Callout 不复述块内已写信息，不承载唯一成功判据。
 
-### 元素边界
+行内代码只标记需要逐字识别的对象：命令、参数、文件名、路径、配置键、API 和标识符使用行内代码；Ubuntu、Windows 和 VS Code 作为普通平台名称时不加反引号；标题与导航不使用行内代码。同一对象在同一页保持一种标记方式，链接标签内不再嵌套行内代码；行内标记连续出现时，改用完整句子减少读者来回切换字体。执行位置判据：Shell 场景用 `pwd` 看路径结尾，工程场景用特征文件（如 `CMakeLists.txt`）存在性判断，给可观察判据而不是模糊要求。
 
-细节升级为标题的门槛见 `steps/02-structure.md`。常见错误使用三级结构，是因为目录负责导航、具体症状负责识别、有序步骤负责操作。具体写法见 `steps/02-structure.md` 与本文件。
+### 标题导语
 
-这种分层与页面整体的六段块序列并不冲突：它只收束任务段内部的阅读路径，不重新定义引言、任务序列、排查、自测和回顾的页面职责。
+`##` 下不强制写导语。只有导语补充任务顺序、前置条件、范围或标题没有表达的结果时才保留；把标题换一种说法的导语删除。代码块前不固定用冒号，冒号的合法场合见 `steps/04-paragraphs.md`「散文伪标签冒号禁令」。
 
-### 行内代码只标记需要逐字识别的对象
+### 小节标题与正文对齐
 
-命令、参数、文件名、路径、配置键、API 和标识符使用行内代码。Ubuntu、Windows 和 VS Code 作为普通平台名称时不加反引号。标题与导航不使用行内代码，形式规则见 `steps/02-structure.md`。
+小节标题、首句和正文指向同一个动作或对象；标题说「做什么」，正文就只写怎么做、看到什么算成功。对象是否对齐，按 `steps/02-structure.md`「纵向承诺链」第 4、5 条核对。块后许可的新信息不豁免标题对齐：树后或块后补写的内容，主语仍须是本节标题的对象，换成另一对象即视为换节。后文小节专讲的对象不提前交接，判法见 `steps/05-sentences.md`「句内骨架」。
 
-同一对象在同一页保持一种标记方式。链接标签内不再嵌套行内代码。行内标记连续出现时，改用完整句子减少读者来回切换字体。
+术语要么已被前文章节建立，要么当场用读者可核对的实物（目录、文件、代码）建立；做不到就把内容下沉到概念建立之后的章节，章际下沉见 `steps/02-structure.md`「六段块序列」。一句话压缩多个论断而读者无法逐条核对的，拆成可核对表述或删除；首句先给中心判断，再补机制。正文论据同受此限：未在正文展示过的代码标识符不作论据，验证职责下沉到展示它的章节。改写对照见 `examples/02-structure-shape.md`「小节标题抽象与首句无中心」。
 
-标记边界与术语节奏的执行规则见 `examples/06-wording-cases.md`，本文件只解释为什么需要克制。
+操作小节（如「运行一键脚本」）只保留动作、顺序与可见结果。「为何不跳过某步 / 幂等 / 配置漂移」类工程取舍，删除后不影响首次跑通与验收的，不进该节正文；确需保留时由代码注释或排查节承担。跨节复述同一取舍视为标题离题的变体：该内容归属最贴合的节，其余位置只保留一句或链接。
 
-## 情况
+### 块链检查清单
 
-### 情况：紧邻常量与其直接使用
+段落之外，标题、列表、代码、表、图与 Callout 之间按以下闭环核对；每条只指回权威出处：
 
-常量定义和它唯一的使用点紧邻时，可以放进同一个围栏；跨节使用的常量各自成块。
+| 边界 | 规则摘要 | 权威 |
+| --- | --- | --- |
+| 标题 → 正文 | 标题下至少一句引导；禁止 `##` 后立刻 `###` 叠标题 | `steps/02-structure.md`「六段块序列」与本文件 |
+| 段 → 列表 | lead-in 含主谓、点名列表将展开的维度；完整句可用句号，明确「如下」时用冒号；列表项平行且字数带 | `steps/07-layout.md`「列表选择」 |
+| 段 → 代码 | 一句完整导语（对象标识符 + 谁调用/做什么）→ 围栏；禁块前半句 + 块后补半句；函数或枚举围栏前固定两句：第一句接住上一句的对象并点名函数或枚举，第二句写读者为什么要看它、它在调用链里的位置或与邻块的关系；可以沿用围栏 `///` 的术语，但不得同义复述注释；位置写成「定义在 `文件` 里」，不用「声明在」 | 本文件「内容块前后的闭环」 |
+| 代码 → 图 | 代码 → 桥接句 → 图 → 图后结论；空行 ≠ 桥接 | 本文件「代码与图的桥接」 |
+| 段 → 表 | 关系句引出 → 表 → 表后结论句 | 本文件「短表与宽表」 |
+| 任意块 → Callout | Callout 只承载可跳过提示，不复述块内已写信息，不承载唯一成功判据 | 本文件「元素边界」 |
+| 节尾 → 下节 | 下节首句接住上节对象；禁正文「下一节/上一节」；章末「下一章」仅在回顾 | `steps/04-paragraphs.md`「段间：过渡句只在话题切换处」、`steps/02-structure.md`「六段块序列」 |
+| 章际 → 本章 | 第 N 章引言、任务节与自测题只用 1..N-1 章已建立的名字；新术语首次出现处就近落术语卡或行内括号 | `steps/02-structure.md`「六段块序列」 |
 
-### 情况：图是 Mermaid 或坐标轴图
+### 豁免与边界
 
-要画流程图、类图或时序图才打开 `quarto/mermaid.md`（类图先按内容预算删节点和成员），坐标轴网格图打开 `quarto/coords.md`，图注与原生 HTML/SVG 图打开 `quarto/figures.md`。不排图不打开。
+- 块级前后闭环（三级标题最小模块）见本文件；本文件管段落与小节之间的衔接，不重复块内规则。
+- 多命令代码块后的逐条讲解，见 `steps/04-paragraphs.md`「段落规则」。
+- 散文冒号豁免清单与表格单元格、协议字面量的豁免见 `steps/04-paragraphs.md`「散文伪标签冒号禁令」；代码注释的冒号句式不属本技能。
+- 目录树不是列表，也不是表格；列表形态在 `steps/07-layout.md`「列表选择」，表格的说明句见本文件「短表与宽表」。
 
-### 情况：Callout
+### 机械检查
 
-正文说完、只是补充才加 Callout，放在收束段之后；术语解释型就近放置。盒子与正文的比例、可跳过内容的边界看通用情况里的 Callout 几条。
+- 引章两个散文段、导语 token 与句数、段落篇幅：`verifying-content.py` 自动执行（限额见 `steps/02-structure.md`「分层上限」）。
+- 普通自然段低于 token 下限：`verifying-content.py` 自动执行；豁免清单见 `steps/02-structure.md`「分层上限」。
+- 同段连续分句引入新的行内代码标识且无回指词：启发式 WARN，不追清零；高精度过简清单仍靠人工对照案例。
+- 读者正文「下一节／上一节」、罗列短句信号等高精度项：`verifying-content.py`。
+- 「由…完成」被动交接（见 `steps/05-sentences.md`「句内骨架」）：`verifying-content.py` 仅对读者 qmd 围栏外正文硬拦；`.agents` 案例可引用反例，不扫。
+- 拉链句高频词「分别交给」「各说一层」（见 `steps/05-sentences.md`「拉链句」）：`verifying-content.py` 仅对读者正文硬拦；宽泛的「分别」不拦。
+- 散文伪标签冒号与段内同义堆叠（见 `steps/04-paragraphs.md`）：`verifying-content.py` 启发式 WARN，人工判，不追清零。
+- 句子模块切分的三类失败（类型接线句、「接着看／第 N 个枚举」改口、全称被下一句否定，见 `steps/05-sentences.md`「一次对话」）：`verifying-content.py` 全量执行；段中心写不出与对话件数不做正则。
+
+## 情况
+
+### 情况：紧邻常量与其直接使用
+
+常量定义和它唯一的使用点紧邻时，可以放进同一个围栏；跨节使用的常量各自成块。
 
 ### 情况：目录树
 
@@ -260,8 +229,18 @@ int main() {
 
 树内的名词不点名下层文件，也不写「见某一章」；需要指路时写在树后的正文里，链接放在该文件第一次被讲到的段落。树后一段只讲从树上读不出的关系：谁编译进谁、谁调用谁、哪些目录会重新生成，不复述注释，也不逐行翻译；超过两句的细节留给下一节。
 
-目录树不是列表，也不是表格；列表形态在 `steps/07-layout.md`，表格的说明句在通用情况里。
+### 情况：图是 Mermaid 或坐标轴图
+
+要画流程图、类图或时序图才打开 `quarto/mermaid.md`（类图先按内容预算删节点和成员），坐标轴网格图打开 `quarto/coords.md`，图注与原生 HTML/SVG 图打开 `quarto/figures.md`。不排图不打开。
+
+### 情况：Callout
+
+正文说完、只是补充才加 Callout，放在收束段之后；术语解释型就近放置。盒子与正文的比例、可跳过内容的边界看通用情况里的 Callout 几条。
+
+### 情况：状态面板三态在页面上的摆法
+
+数据项类型（画面、字符与取值的定稿见项目术语表的「数据项类型」）在页面上只有两种摆法：三态是本页话题时，枚举出现之前放终端的这一行 `|   | X | O |`，点名顺序与从左到右一致；这一页已经有整盘画面时，指向上图里没有字母的那一格，不再放第二行。围栏里的行尾注释与头文件逐字一致。
 
 ## 正反例
 
-通用情况判得准就不打开。判不准时只开 `examples/03-block-after.md`，按命中的信号读其中一节；`03-excerpt-lead.md` 与 `03-qmd-elements.md` 留到下一次激活。
+通用情况判得准就不打开。判不准时只开 `examples/03-block-after.md`，按命中的信号读其中一节；`examples/03-excerpt-lead.md` 与 `examples/03-qmd-elements.md` 留到下一次激活。