@chengzhao-dev/dsh-quarto-book 0.6.18 → 0.6.20

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`）。对照见 `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,40 +35,15 @@
 
 代码块导语禁用「N 段命令定义」式元计数：直接点名这段规则定义的对象，不用「先…再…最后…」，不叫读者回数段落；改写对照见 `examples/03-qmd-elements.md`「代码块导语元计数对照」。
 
-### 代码块 filename 标注
+### 三级标题最小模块
 
-来源文件、执行位置、输出场景写在代码块标题里，正文不重复「下面是 xxx 的源码/一段命令」这类视觉上已存在的信息。
-
-**片段优先**：每个 `##`（或 `###`）只展示正式代码里与本节任务最相关的一块并精讲，默认内联摘录，不用 include 拷贝整个文件；紧邻常量与其直接使用行合成的单围栏算「一块」（判定见下文「内容块前后的闭环」）：
-
-````markdown
-```{.cpp filename="main.cpp"}
-#include <iostream>
-
-int main() {
- std::cout << "Hello, World!\n";
- return 0;
-}
-```
-````
+一个三级标题下面的正文由一到两个最小模块组成。一个模块是一个整体，次序固定：标题已经给出对象；标题下一句导语；有并列取值时跟着列表，一项一个取值、一项一句；代码块、表格或图放在列表和收束段之间；没有列表时放在导语和收束段之间；收束段只写各项共同的契约；Callout 可有可没有，写了就放在收束段之后。短模块可以只有导语和代码块。示例章「操作与成败」里的 `Move` 与 `PlaceResult` 各是一个短模块，下一个短模块用自己的导语接上。第二个模块用来解释前一个时，衔接句就是第二个模块的导语。示例章「数据项坐标」用「下面的图标出这块状态面板上可用的 `(row, col)`。」接上图。讲一个函数时，先一个模块讲 `.h`，再用导语接 `.cpp`。列表写选法，围栏与源文件逐字一致，收束段不把列表再写一遍。禁止「每个状态码对应」，也禁止以 `` `类型::kName`： `` 开头的释义项。正面例子是 示例章「操作的强度」。
 
-- 片段逐字摘自源文件，不改写、合并或重排源代码行；注释与空行可整段省略，省略处不写标记行，口径见下节。
-- **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（`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 收尾，正文不再保留同一句。旁注是读者跳过也能完成本节、回看能少走弯路的补充：可重新生成的产物、版本差异、可选替代、边界条件。本节结论、下一步动作、必经步骤与成功判据留在正文。
 
-- 读者正文不摘文件级 Doxygen 头：`/// @file`、`/// @brief` 与文件范围段都不进正文，围栏从其后开始。
-- 围栏保留的声明带 `///` 注释时，整段必须与源文件该声明上方一致，`@param`、`@return` 与空 `///` 行一并保留；整段不摘可以，只摘概述行不行。
-- 润色或回读发现围栏与源文件不一致，打开该源文件把围栏改一致；只读对应声明。
+收尾 Callout 放在本节最后一块之后、下一个标题之前；每节至多一个收尾 Callout。正文必须脱离前文也能读懂：点名对象，写出前提与结果，不复用上一段的句子；超过两段或需要列举时改用 `###` 小节。正反例见 `examples/03-qmd-elements.md`「节末旁注改为 Callout 收尾」。
 
 ### 代码块门槛
 
@@ -88,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]"`，不靠浏览器均分。
@@ -144,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`「六段块序列」 |
-
-### 豁免与边界
+表格格里写完整可核对的信息，不写电报式省略。对象先行：先给对象，再给约束或结果。格子不写「名词：一句」，列已经把名称和说明分开。agents 文档的表格允许短语压缩，但不能和新决定相反。
 
-- 块级前后闭环（三级标题最小模块）见本文件；本文件管段落与小节之间的衔接，不重复块内规则。
-- 多命令代码块后的逐条讲解，见 `steps/04-paragraphs.md`「段落规则」。
-- 小节承接正文权重与盒子密度见本文件。
-- 散文冒号豁免清单与表格单元格、协议字面量的豁免见 `steps/04-paragraphs.md`「散文伪标签冒号禁令」；代码注释的冒号句式不属本技能。
+### 盒子密度
 
-### 机械检查
+盒子指代码块、表格、提示框、引用块、图表容器，含 `{mermaid}` 图与 `{python}` 坐标图单元。密度按本节与「机械检查」的软门禁人工判断，不设硬阈值。
 
-- 引章两个散文段、导语 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` 全量执行；段中心写不出与对话件数不做正则，留给步骤与案例。
+盒子按最小模块计：一个模块一块代码、表或图；同一三级标题两个模块时可以有两块，中间必须有衔接句。Callout 不算这块主内容。它们底色与边框一致、左右内缩相同，连续出现时读者分不清内容边界，页面从「读一段做一步」退化成「抄一屏」。因此一条主线动作配一段自己的承接正文，相邻盒子最多一处，其余被正文隔开。每两个盒子之间至少有一段交代判断依据的话；代码块与图之间的固定桥接序列见「代码与图的桥接」。
 
-### 表格格
-
-表格格里写完整可核对的信息，不写电报式省略。对象先行：先给对象，再给约束或结果。格子不写「名词：一句」，列已经把名称和说明分开。agents 文档的表格允许短语压缩，但不能和新决定相反。
+修法是补承接正文，而不是删盒子。盒子承担可复制性，正文承担判断依据，两者不可互换。
 
 ### 正文与 Callout 的重量平衡
 
@@ -206,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` 全量执行；段中心写不出与对话件数不做正则。
+
+## 情况
+
+### 情况：紧邻常量与其直接使用
+
+常量定义和它唯一的使用点紧邻时，可以放进同一个围栏；跨节使用的常量各自成块。
 
 ### 情况：目录树
 
@@ -266,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` 留到下一次激活。

package/skills/writing-quarto/steps/04-paragraphs.md

@@ -148,7 +148,7 @@
 章引言和每个 `##` 的首句，主语必须是本章标题的对象。不要用这个对象被谁使用、能推出什么结果来替换它；那些内容属于后文专门的小节。
 
 - 不佳（标题是棋盘，首句却把格子用途列成一段）：棋盘是 3 行 3 列，共九个格子。每次落子先检查坐标；满盘、三连和赢家都从这些格子判断。
-- 改写：棋盘是 3 行 3 列，共九个格子，`Board` 保存这些格子。写入与读出的接口声明在 `board.h`，实现放在 `board.cpp`。
+- 改写：井字棋棋盘是 3 行 3 列，共九个格子。这些格子由 `Board` 保存，写入与读出也由它提供；声明在 board.h，实现在 board.cpp。
 
 判定信号：首句主语是「格子 / 对局 / 终端」等下游对象，而标题是「棋盘 / 对局 / 程序结构」；把首句主语换成标题对象后句子仍成立，说明原句已经漂移。01 设计章按规则讲范围，不受本条限制。
 
@@ -169,6 +169,7 @@
 - 相邻段落同义合并：相邻两段各自换一种说法讲同一事实时合并为一段，由后段的机制或结论接住前段的对象；合并后其余段落、列表和 Callout 不得再以第三种说法复述该事实。改写对照见 `examples/04-paragraph-cases.md`。
 - 相邻两段不得各成独立说明书：第一段讲工具、第二段讲目录而彼此无衔接时，第二段段首要接住第一段的对象（工具基线 → 这些工具在编号目录上如何使用）；只删不接，两段仍然是两个条目。改写对照见 `examples/02-structure-shape.md`。
 - 目录树后的正文不复述树内行尾注释：树注释已逐文件交代职责，再列一段「A 组件、B 目录与 C 目录各自带 CMakeLists.txt」是把树翻译成说明书目录。树注释的标记方式（目录 `#/` 与文件 `#` 分两列、文字对齐、字母序、个数对齐）见 `steps/03-blocks.md`「情况：目录树」；本条只管树后正文。树后保留的一句读法说明直述机制（「文件名给出位置，行尾注释说明职责」），不写「X 回答 A，Y 回答 B」的问答式并列；换成工具配置、依赖方向或「不参与 / 不依赖」类边界，即使树注释没写过，也删除或下沉，不得靠「新工程信息」留下（改写对照见 `examples/02-structure-shape.md`「目录式堆砌」「树后换对象收束句」）。
+- 目录树或列表已经写出的专名，下一段若还要点其中超过三个，就改成统称回指：用「这些目录」「这份库」「程序和测试」承接话题，不再逐个重写；第一次介绍名称时仍写具体目录，主次判定见 `steps/05-sentences.md`「概念负荷」。
 - 同一禁令延伸到代码围栏：块后不复述围栏内注释、单段并列对象按对象拆段的写法，见 `steps/03-blocks.md`「内容块前后的闭环」与本文件「段落规则」（对照见 `examples/03-block-after.md`「块后复述注释」「单段混并列对象」）。
 - **多代码块小节先判一次只摘一块**：同源围栏是否合并、每个围栏前的导语怎么写、每段最多「一句 + 一个配套块」，见 `steps/03-blocks.md`「内容块前后的闭环」；函数或枚举围栏前固定两句的动词与 `///` 一致判法见 `steps/05-sentences.md`；块后收束与两个最小模块的衔接见 `steps/03-blocks.md`「三级标题最小模块」，本文件不另写一份。改写对照见 `examples/03-excerpt-lead.md`「多代码块一句导语」「递进片段合并」。
 - 表格与对照表的承接句、表后结论句见 `steps/03-blocks.md`「短表与宽表」；禁用「X 与 Y 是两个容易混淆的词：」式元标签开场。