@chengzhao-dev/dsh-quarto-book 0.4.3 → 0.6.0

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

@@ -7,32 +7,32 @@
 
 ### 内容块前后的闭环
 
-一个段落只推进一个对象；小节内出现代码块、列表或表格时，模块内部的次序见下文「三级标题最小模块」，本段只规定导语怎么写：块前用一句完整导语交代为什么看它（对象、谁调用、做什么）——对象写成读者要在块内观察的代码标识符（常量、类型、函数名），只报出处、不点名块内对象的「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`「逐条释义代替动机」）；块后只在有注释未覆盖的新信息时写一句；引言写判断依据，不写「如下：」式的空引导（GitHub 风格指南同款要求：解释文字放在代码块前面，而不是塞进代码注释）。导语预告的对象本体必须出现在导语句里，不得隔着代码块在块后才给出；算式不是例外，换算句式见 `steps/07-layout.md`「列表选择」。
 
-一个函数小节内部按「声明、一句行为、实现」排列，示例不出现在行为句之前；同一小节出现多个围栏时按阅读顺序排；先定义后调用与未定义名字调用链的处理见`steps/02-structure.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:`，私有成员身份只由头文件围栏呈现。
 
-同一 `##`/`###` 内 ≥2 个代码围栏时，先看是否是紧邻常量与其直接使用行：常量紧接着被下一行使用时，可放在同一个围栏。类型定义和后一步使用它的函数是两步，即使函数用到该类型也分成两块——一个围栏只放正在讲的那一个声明或函数，不把整份头文件、整份类或整条调用链贴进同一个围栏；后一个函数的函数体里可以调用已经讲过的名字，但不把那些函数的实现再贴一遍。每块前一句导语；`{python}` / `{mermaid}` 图或独立验证盒子打断处保持拆块。旧口径「同一小节递进片段必须合并为一个围栏」收窄到此：只有常量紧接着被下一行使用时才放在同一围栏。改写对照见`examples/03-excerpt-lead.md`「递进片段合并」。
+同一 `##`/`###` 内 ≥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`）。细则与对照见 `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` 表达」「用有符号整型承载」「坐标字段为什么选定宽有符号」式语言课或选型旁白（除 01 设计章外工程 qmd 禁选型外链），改写对照见 `examples/01-language-scope.md`「语言课旁白与工程旁白」。
 
 块后四条硬禁令：
 
-- **禁止正文复述围栏内注释**：代码块内 `//` / `#` 注释已写明的意图、产物路径或字段含义，块后正文不得同义再讲一遍；块后只写注释没覆盖的新工程信息（谁调用、如何验证、与邻块或图的关系）。改写对照见`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/07-layout.md`「列表选择」换算条。改写对照见`examples/03-excerpt-lead.md`「逐条释义代替动机」。
+- **禁止正文复述围栏内注释**：代码块内 `//` / `#` 注释已写明的意图、产物路径或字段含义，块后正文不得同义再讲一遍；块后只写注释没覆盖的新工程信息（谁调用、如何验证、与邻块或图的关系）。改写对照见 `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/07-layout.md`「列表选择」换算条。改写对照见 `examples/03-excerpt-lead.md`「逐条释义代替动机」。
 
-渐进披露不进正文：语法细节延后展开是 Agent 侧写作策略，禁止把策略写成对读者的话——「语法细节留到后续章节真正用到时再展开」「本章只需认清……」这类元叙述一律不出现在 `content/**`；正文直接陈述对象和结果（如「这段程序对外可见的结果只有两处：……」），需要延后的内容保持沉默即可。改写对照见`examples/06-wording-cases.md`，禁用词见`steps/06-wording.md`。
+渐进披露不进正文：语法细节延后展开是 Agent 侧写作策略，禁止把策略写成对读者的话——「语法细节留到后续章节真正用到时再展开」「本章只需认清……」这类元叙述一律不出现在 `content/**`；正文直接陈述对象和结果（如「这段程序对外可见的结果只有两处：……」），需要延后的内容保持沉默即可。改写对照见 `examples/06-wording-cases.md`，禁用词见 `steps/06-wording.md`。
 
-列表与表格同律：表格前用一句完整的话交代它回答什么问题，表格后补一行读者该取走的结论；列表通则见`steps/04-paragraphs.md`「段落规则」。命令、输出与正文三分见本文件「命令、输出与细节各司其职」。
+列表与表格同律：表格前用一句完整的话交代它回答什么问题，表格后补一行读者该取走的结论；列表通则见 `steps/04-paragraphs.md`「段落规则」。命令、输出与正文三分见本文件「命令、输出与细节各司其职」。
 
-多命令块：块后逐条讲解的格式见`steps/04-paragraphs.md`「段落规则」，引导词加粗与行内代码不叠加的边界见`steps/07-layout.md`。引言与收束按上段列表通则，不再按命令分段成多个段落。
+多命令块：块后逐条讲解的格式见 `steps/04-paragraphs.md`「段落规则」，引导词加粗与行内代码不叠加的边界见 `steps/07-layout.md`。引言与收束按上段列表通则，不再按命令分段成多个段落。
 
-代码块导语禁用「N 段命令定义」式元计数：直接点名这段规则定义的对象，不用「先…再…最后…」，不叫读者回数段落；改写对照见`examples/03-qmd-elements.md`「代码块导语元计数对照」。
+代码块导语禁用「N 段命令定义」式元计数：直接点名这段规则定义的对象，不用「先…再…最后…」，不叫读者回数段落；改写对照见 `examples/03-qmd-elements.md`「代码块导语元计数对照」。
 
 ### 代码块 filename 标注
 
@@ -55,11 +55,11 @@ int main() {
 - **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` 判失败）。悬空的裸链接行既不像正文也不像说明，读者扫读时只剩一个锚点。
-- **摘录链接每章每条仓库路径至多一条**：章引言是全章链接位，首次点名源文件并挂链接（如「声明在头文件 `state.h`，实现在源文件 `state.cpp`」，这两个名字是该章仅有的源文件链接）；后文和各节导语改成行内代码，不再包 `[]()`，导语讲块里要看的标识符；同一章摘录另一阶段目录的同名文件时，在切换处再挂一条不同 URL（对照见`examples/03-excerpt-lead.md`「摘录链接密度」；`verifying-content.py` 对同章同 URL 重复判失败）。本条挂在写作步骤的定版式。
+- **摘录链接每章每条仓库路径至多一条**：章引言是全章链接位，首次点名源文件并挂链接（如「声明在头文件 `state.h`，实现在源文件 `state.cpp`」，这两个名字是该章仅有的源文件链接）；后文和各节导语改成行内代码，不再包 `[]()`，导语讲块里要看的标识符；同一章摘录另一阶段目录的同名文件时，在切换处再挂一条不同 URL（对照见 `examples/03-excerpt-lead.md`「摘录链接密度」；`verifying-content.py` 对同章同 URL 重复判失败）。本条挂在写作步骤的定版式。
 - 片段内注释硬限：每处实现注释（`//` 或 `#`）不超过 2 行、单行不超过 100 列（与源文件 `ColumnLimit: 100` 同一口径；正文散文的 40 字限不套到代码注释），只写这段代码做什么；CMake/Shell 等命令型片段每条命令保留一行意图注释。Doxygen `///` 声明块（概述、空 `///` 与细节）是声明骨架的一部分，摘录随源保留，不受此限。命名惯例、官方建议、未来演化等规范说理一律不进代码块；术语卡和可跳过的操作提醒可以进 callout，注释怎么写、行尾先写什么、`///` 与 `@` 标签怎么分工只留在 `.agents`，面向作者的进知识文件。
-- 首讲某段源码的章节不省略源码既有的职责注释：注释是读者读到的第一层讲解；「注释与空行可以省略」只服务后续章节复现已见代码。源码缺注释先按`steps/03-blocks.md`补注释，摘录逐字继承；自明成员按该规范不注，不因「全部注释」补自明行。
+- 首讲某段源码的章节不省略源码既有的职责注释：注释是读者读到的第一层讲解；「注释与空行可以省略」只服务后续章节复现已见代码。源码缺注释时交给项目 C++ 流程补齐，本技能不替源码补注释。
 - 讲解段只解释片段中实际出现的代码；片段没有展示的内容要么补进片段、要么进 callout，不在正文列表里讲代码外面的东西。
-- include 短代码降级为可选手段：仅用于确实需要完整展示且很短的文件，并仍须包在带语言标注的围栏代码块内（包裹规则见`quarto/render.md`）。
+- include 短代码降级为可选手段：仅用于确实需要完整展示且很短的文件，并仍须包在带语言标注的围栏代码块内（包裹规则见 `quarto/render.md`）。
 - 手动命令块标注执行位置，如 `filename="WSL Ubuntu（仓库根目录）"`。
 - 输出效果类代码块（运行效果、预期输出）filename 只写场景名（如「运行效果」）；终端样式、颜色等展示细节写进正文，不进 filename。输出摘录用单独一行 `...` 表示省略的工具输出，与源码片段的省略是两回事。
 
@@ -69,13 +69,13 @@ int main() {
 
 **禁止出围栏**：
 
-- 单次比较或直接 `return` 的平凡实现（判例：`IsInRange` 的两行 `return` 比较）——改写入口列表 + 失败策略列表，对照见`examples/05-sentence-brevity.md`「过简实现围栏」。
+- 单次比较或直接 `return` 的平凡实现（判例：`IsInRange` 的两行 `return` 比较）——改写入口列表 + 失败策略列表，对照见 `examples/05-sentence-brevity.md`「过简实现围栏」。
 - 仅为证明「源码有此函数」而贴出的实现。
 - 打断小节中心的硬插块。
 
 ### 类与多函数摘录的垂直空白
 
-摘录 `class` 或多函数片段时**保留**源码中函数之间的空行，禁止为省行数坍缩成函数注释贴着下一声明；省略部分成员时，被保留的相邻函数之间仍空 1 行；同一 access 段内最后一组数据成员与函数之间空 1 行，数据成员组内不空行（规则与矩阵见`steps/03-blocks.md`「类与多函数摘录的垂直空白」）。与「逐字摘录」冲突时以源码空白为准：教学缩略可删成员，不可删「函数间距」惯例。
+摘录 `class` 或多函数片段时**保留**源码中函数之间的空行，禁止为省行数坍缩成函数注释贴着下一声明；省略部分成员时，被保留的相邻函数之间仍空 1 行；同一 access 段内最后一组数据成员与函数之间空 1 行，数据成员组内不空行（规则与矩阵见 `steps/03-blocks.md`「类与多函数摘录的垂直空白」）。与「逐字摘录」冲突时以源码空白为准：教学缩略可删成员，不可删「函数间距」惯例。
 
 ### 三级标题最小模块
 
@@ -96,11 +96,11 @@ int main() {
 代码块引出 `{mermaid}` 图或 `{python}` 坐标图时按固定序列组织：代码块 → 桥接句 → 图（含 `fig-cap`）→ 图后新结论。固定序列的完整写法见 `writing-quarto` 技能 `quarto/authoring.md`「代码与图的桥接」，两条硬边界：
 
 - 代码块与图之间必须有桥接句，说明图要核对代码已讲清的哪条关系；中间只有空行视为堆叠（`verifying-content.py` 的 DOC-E11 只要求相邻围栏留空行，空行不等于桥接正文）。
-- 图后先给「从图带走的结论」或图外新信息，再进入下一块；小节以图收尾时，结论可并入桥接段，不在图后孤悬一句。图注已写明的信息不复述。坐标图计入盒子密度，口径见`quarto/coords.md` 与 `steps/03-blocks.md`。
+- 图后先给「从图带走的结论」或图外新信息，再进入下一块；小节以图收尾时，结论可并入桥接段，不在图后孤悬一句。图注已写明的信息不复述。坐标图计入盒子密度，口径见 `quarto/coords.md` 与 `steps/03-blocks.md`。
 - 一图一事、同主题相邻、图不承载正文未写的新信息：一张图只核对一条已讲清的关系；代码与图主题不同时收束本对象再拆 `###`，禁止「代码 A → 短句拐弯 → 图讲 B → 再贴代码 C」的同节混排（三条边界的写法见 `quarto/authoring.md`「代码与图的桥接」）。
 - 图前段只讲本页可见的对象，且单一主题：描述版式的句子其对象必须同页可见，引用前章画面时复述读者需要的关键事实（如行列取值 0 到 2），不指称前章画面的版式（「画面上方是列号」式会让读者翻回前章）；调用方行为等第二主题移出图前段（示例章定义坐标范围节两段并一段的改稿对照）。
 
-图不能替代结论句：桥接句与图带走的结论缺任何一处，读者只有图没有判断依据。正反对照见`examples/03-qmd-elements.md`「代码与图桥接对照」。
+图不能替代结论句：桥接句与图带走的结论缺任何一处，读者只有图没有判断依据。正反对照见 `examples/03-qmd-elements.md`「代码与图桥接对照」。
 
 ### 状态面板三态在页面上的摆法
 
@@ -116,18 +116,18 @@ int main() {
 
 ### 盒子密度
 
-盒子指代码块、表格、提示框、引用块、图表容器。密度阈值与权衡的唯一出处见`steps/03-blocks.md`，本条不重写数字。
+盒子指代码块、表格、提示框、引用块、图表容器。密度阈值与权衡的唯一出处见 `steps/03-blocks.md`，本条不重写数字。
 
 ### 标题导语
 
-`##` 下不强制写导语。只有导语补充任务顺序、前置条件、范围或标题没有表达的结果时才保留；把标题换一种说法的导语删除。代码块前不固定用冒号，冒号的合法场合见`steps/04-paragraphs.md`「散文伪标签冒号禁令」。
+`##` 下不强制写导语。只有导语补充任务顺序、前置条件、范围或标题没有表达的结果时才保留；把标题换一种说法的导语删除。代码块前不固定用冒号，冒号的合法场合见 `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`「小节标题抽象与首句无中心」。
+- 小节标题、首句和正文指向同一个动作或对象；标题说「做什么」，正文就只写怎么做、看到什么算成功。对象是否对齐，按 `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 后行为没变」），其余位置只保留一句或链接。
 
@@ -148,21 +148,21 @@ int main() {
 
 ### 豁免与边界
 
-- 块级前后闭环（三级标题最小模块）见`steps/03-blocks.md`；本文件管段落与小节之间的衔接，不重复块内规则。
-- 多命令代码块后的逐条讲解，见`steps/04-paragraphs.md`「段落规则」。
-- 小节承接正文权重与盒子密度见`steps/03-blocks.md`。
-- 散文冒号豁免清单与表格单元格、协议字面量的豁免见`steps/04-paragraphs.md`「散文伪标签冒号禁令」；代码注释的冒号句式按`steps/05-sentences.md`「情况：围栏里的注释」判。
+- 块级前后闭环（三级标题最小模块）见 `steps/03-blocks.md`；本文件管段落与小节之间的衔接，不重复块内规则。
+- 多命令代码块后的逐条讲解，见 `steps/04-paragraphs.md`「段落规则」。
+- 小节承接正文权重与盒子密度见 `steps/03-blocks.md`。
+- 散文冒号豁免清单与表格单元格、协议字面量的豁免见 `steps/04-paragraphs.md`「散文伪标签冒号禁令」；代码注释的冒号句式不属本技能。
 
 ### 机械检查
 
-- 引章两个散文段、导语 token 与句数、段落篇幅：`verifying-content.py` 自动执行（限额见`steps/02-structure.md`）。
-- 普通自然段低于 token 下限：`verifying-content.py` 自动执行；豁免清单见`steps/02-structure.md`「分层上限」。
+- 引章两个散文段、导语 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` 全量执行；段中心写不出与对话件数不做正则，留给步骤与案例。
+- 「由…完成」被动交接（句内骨架判定信号之一，见 `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` 全量执行；段中心写不出与对话件数不做正则，留给步骤与案例。
 
 ### 表格格
 
@@ -184,31 +184,31 @@ int main() {
 
 ### 命令、输出与细节各司其职
 
-命令是输入，输出是观察，正文是判断依据。三者混在同一个代码块或连续多个解释段落中，会让读者自己筛选"哪些行要复制、哪些行只是说明"。因此闭环目标、命令和成功判据各保留一个权威位置，操作小节拥有命令与验收，回顾和相邻段落只补充新增信息。路径、版本号等随环境变化的输出应展示可识别的典型形态，并给出"每项都有非空结果"这类稳定判据，而不是要求逐字匹配示例。成功判据与证据层级相称的要求见`steps/02-structure.md`「术语与验证策略」。
+命令是输入，输出是观察，正文是判断依据。三者混在同一个代码块或连续多个解释段落中，会让读者自己筛选"哪些行要复制、哪些行只是说明"。因此闭环目标、命令和成功判据各保留一个权威位置，操作小节拥有命令与验收，回顾和相邻段落只补充新增信息。路径、版本号等随环境变化的输出应展示可识别的典型形态，并给出"每项都有非空结果"这类稳定判据，而不是要求逐字匹配示例。成功判据与证据层级相称的要求见 `steps/02-structure.md`「术语与验证策略」。
 
 ### 盒子与正文的比例
 
-盒子按最小模块计：一个模块一块代码、表或图；同一三级标题两个模块时可以有两块，中间必须有衔接句。Callout 不算这块主内容。盒子指代码块、表格、提示框、引用块、图表容器，含 `{mermaid}` 图与 `{python}` 坐标图单元。它们底色与边框一致、左右内缩相同，连续出现时读者分不清内容边界，只能靠滚动位置感知，页面从「读一段做一步」退化成「抄一屏」。因此一条主线动作配一段自己的承接正文，相邻盒子最多一处，其余被正文隔开。每两个盒子之间至少有一段交代判断依据的话；代码块与图之间的固定桥接序列见`steps/03-blocks.md`。
+盒子按最小模块计：一个模块一块代码、表或图；同一三级标题两个模块时可以有两块，中间必须有衔接句。Callout 不算这块主内容。盒子指代码块、表格、提示框、引用块、图表容器，含 `{mermaid}` 图与 `{python}` 坐标图单元。它们底色与边框一致、左右内缩相同，连续出现时读者分不清内容边界，只能靠滚动位置感知，页面从「读一段做一步」退化成「抄一屏」。因此一条主线动作配一段自己的承接正文，相邻盒子最多一处，其余被正文隔开。每两个盒子之间至少有一段交代判断依据的话；代码块与图之间的固定桥接序列见 `steps/03-blocks.md`。
 
 修法是补承接正文，而不是删盒子。盒子承担可复制性，正文承担判断依据，两者不可互换，代码块删到只剩命令不会自动产生判断依据。
 
-代码块前后的文字重量也应服务同一个任务闭环。代码块前至少说明读者要完成什么、在哪里执行以及执行后会发生什么；代码块后只说明下一步、可观察结果或一个必要的新人解释。若提示符、参数含义等补充信息不影响主线执行，可在主线结果确认后放进一个短 Callout；Callout 只解释新信息，承载边界见`steps/03-blocks.md`「元素边界」。
+代码块前后的文字重量也应服务同一个任务闭环。代码块前至少说明读者要完成什么、在哪里执行以及执行后会发生什么；代码块后只说明下一步、可观察结果或一个必要的新人解释。若提示符、参数含义等补充信息不影响主线执行，可在主线结果确认后放进一个短 Callout；Callout 只解释新信息，承载边界见 `steps/03-blocks.md`「元素边界」。
 
 密度比例不设硬阈值。盒子多少、正文长短同时取决于视口宽度、字体度量和 Quarto 版本的 DOM 结构，任何一项变化都会让历史数值失效，基于 DOM 或截图的硬编码门禁只会在与密度无关的改动上误报，仍然禁止。`verifying-content.py` 保留一条软门禁：同一小节内两围栏（含 `{mermaid}` 与 `{python}` 单元）之间只有空行、没有桥接正文时报 WARN，提示人工补承接句；WARN 不判失败，人审与对照案例仍是叙事的主检查。
 
 ### 元素边界
 
-细节升级为标题的门槛见`steps/02-structure.md`。常见错误使用三级结构，是因为目录负责导航、具体症状负责识别、有序步骤负责操作。具体写法见`steps/02-structure.md` 与 `steps/03-blocks.md`。
+细节升级为标题的门槛见 `steps/02-structure.md`。常见错误使用三级结构，是因为目录负责导航、具体症状负责识别、有序步骤负责操作。具体写法见 `steps/02-structure.md` 与 `steps/03-blocks.md`。
 
 这种分层与页面整体的六段块序列并不冲突：它只收束任务段内部的阅读路径，不重新定义引言、任务序列、排查、自测和回顾的页面职责。
 
 ### 行内代码只标记需要逐字识别的对象
 
-命令、参数、文件名、路径、配置键、API 和标识符使用行内代码。Ubuntu、Windows 和 VS Code 作为普通平台名称时不加反引号。标题与导航不使用行内代码，形式规则见`steps/02-structure.md`。
+命令、参数、文件名、路径、配置键、API 和标识符使用行内代码。Ubuntu、Windows 和 VS Code 作为普通平台名称时不加反引号。标题与导航不使用行内代码，形式规则见 `steps/02-structure.md`。
 
 同一对象在同一页保持一种标记方式。链接标签内不再嵌套行内代码。行内标记连续出现时，改用完整句子减少读者来回切换字体。
 
-标记边界与术语节奏的执行规则见`examples/06-wording-cases.md`，本文件只解释为什么需要克制。
+标记边界与术语节奏的执行规则见 `examples/06-wording-cases.md`，本文件只解释为什么需要克制。
 
 ## 情况
 

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

@@ -9,13 +9,13 @@
 
 一段最多容纳一个主题。其余规则：
 
-- 每段只有一个主题或中心句；中心句放在段首，后面的句子都服务于它。段内句子改完后，段首仍是中心句，一段仍只有一个对象；句子的六个成分见`steps/05-sentences.md`「六个成分」。
-- 一段一对象：同一段不夹杂两个并列对象，对象切换必须新起段；配套列表只服务本段对象，不得跨对象拼装列表项（对照见`examples/03-block-after.md`「单段混并列对象」）。
+- 每段只有一个主题或中心句；中心句放在段首，后面的句子都服务于它。段内句子改完后，段首仍是中心句，一段仍只有一个对象；句子的六个成分见 `steps/05-sentences.md`「六个成分」。
+- 一段一对象：同一段不夹杂两个并列对象，对象切换必须新起段；配套列表只服务本段对象，不得跨对象拼装列表项（对照见 `examples/03-block-after.md`「单段混并列对象」）。
 - 段落不超过 7 行，最佳 4 行以内；超过即拆或改列表。
 - 多个独立概念禁止塞进同一段：承接、目标、范围边界、阅读顺序、术语解释各归各段。
 - 段落之间用一个空行分隔，段首不缩进。
-- 代码块后的逐条讲解用无序列表：每项格式为「行内代码标识符 + 全角冒号 + 一句职责」（如 `` `enable_testing()`：开启 CTest。``），描述从简，全页标记方式一致；列表前保留一句引言交代工程语境，列表后需要时补一句收束或尾置 Callout。有先后顺序的排查步骤仍用有序列表；块前导语直接点名对象做什么，不用「先…再…最后…」，元计数禁令见`steps/03-blocks.md`。
-- 删段还是拆段，先按`steps/05-sentences.md`「一次对话」数这段有几件内容再定删或拆；判定全文见该文件「一次对话」。
+- 代码块后的逐条讲解用无序列表：每项格式为「行内代码标识符 + 全角冒号 + 一句职责」（如 `` `enable_testing()`：开启 CTest。``），描述从简，全页标记方式一致；列表前保留一句引言交代工程语境，列表后需要时补一句收束或尾置 Callout。有先后顺序的排查步骤仍用有序列表；块前导语直接点名对象做什么，不用「先…再…最后…」，元计数禁令见 `steps/03-blocks.md`。
+- 删段还是拆段，先按 `steps/05-sentences.md`「一次对话」数这段有几件内容再定删或拆；判定全文见该文件「一次对话」。
 
 #### 拆段触发表
 
@@ -23,32 +23,32 @@
 
 | 信号 | 动作 |
 | --- | --- |
-| 段内出现第二个互不依赖的对象或主题 | 新起段；新段首句接住上段对象（衔接见`steps/04-paragraphs.md`「段间：过渡句只在话题切换处」） |
+| 段内出现第二个互不依赖的对象或主题 | 新起段；新段首句接住上段对象（衔接见 `steps/04-paragraphs.md`「段间：过渡句只在话题切换处」） |
 | 段内出现「话题标签：解释」词条式冒号，或两个以上互不依赖的中心并列推进 | 按「拆核四步（多核混段的拆段方法）」判关系：递进同段衔接推进，并列拆段；词条式冒号改完整主谓句（见「散文伪标签冒号禁令」） |
-| 一段同时承担「承接上一章」+「本章交付物清单」+「源文件位置」+「摘录声明」 | 章引言不拆段，形态硬限与摘录声明删除见`steps/02-structure.md`；其他段落按职责拆段，交付物多项且需扫读 → 列表（目录式堆砌对照见`examples/02-structure-shape.md`） |
+| 一段同时承担「承接上一章」+「本章交付物清单」+「源文件位置」+「摘录声明」 | 章引言不拆段，形态硬限与摘录声明删除见 `steps/02-structure.md`；其他段落按职责拆段，交付物多项且需扫读 → 列表（目录式堆砌对照见 `examples/02-structure-shape.md`） |
 | 超过约 4 行舒适带、或逼近 7 行 / 篇幅 token 上限 | 先找逻辑边界拆，禁止为凑行数在句中腰斩 |
 | 连续 ≥3 段纯散文且无列表/代码/图 | 改写见本文件「句序与段落形态」 |
 | 满篇单句段、句间无衔接 | 合并为连贯多句段，或改成列表 |
-| 逗号、句号后分句换新主语、新事实，无回指、无承接词 | 过简断裂改写见`steps/05-sentences.md`「过简断裂禁令」 |
-| 一段出现第 4 个互不依赖的主概念 | 拆段或改列表见`steps/05-sentences.md`「概念负荷」 |
-| 一句多中心、分号串两事、>40 字多动作 | 先拆句，再判是否还需拆段；同档并句不按超长句拆，异档不并进一句，判定见`steps/05-sentences.md`「同档并句」 |
+| 逗号、句号后分句换新主语、新事实，无回指、无承接词 | 过简断裂改写见 `steps/05-sentences.md`「过简断裂禁令」 |
+| 一段出现第 4 个互不依赖的主概念 | 拆段或改列表见 `steps/05-sentences.md`「概念负荷」 |
+| 一句多中心、分号串两事、>40 字多动作 | 先拆句，再判是否还需拆段；同档并句不按超长句拆，异档不并进一句，判定见 `steps/05-sentences.md`「同档并句」 |
 
-假拆禁令：不为「段数好看」把同一中心拆成两段同义反复（相邻同义合并见`steps/04-paragraphs.md`「段间：过渡句只在话题切换处」）；不为对齐列表而去拆段或填第二中心；章引言多中心的形态契约见`steps/02-structure.md`「六段块序列」。
+假拆禁令：不为「段数好看」把同一中心拆成两段同义反复（相邻同义合并见 `steps/04-paragraphs.md`「段间：过渡句只在话题切换处」）；不为对齐列表而去拆段或填第二中心；章引言多中心的形态契约见 `steps/02-structure.md`「六段块序列」。
 
 ### 罗列短句成段禁令
 
 - 禁止把多个各自成句、互不衔接的罗列式短句机械堆进同一段：每句单看成立不等于段落成立，句号串联的清单式段落让读者在句间自行补关系。
-- 确认一个中心主题后，围绕段首中心句用衔接关系（…时、一旦、则、因此）把相关动作组织成连贯的完整句；单句长度与拆句触发仍守`steps/05-sentences.md`「句子规则」，不为连贯写超长句。同档并句不按超长句拆，异档不并进一句，判定见`steps/05-sentences.md`「同档并句」。
-- 真正并列、需要扫读的项改用列表（详见`steps/07-layout.md`「列表选择」）。
-- 判定信号：段内句子逐句可删、互不引用；句间没有承接、因果或时序词；逐句像要点罗列。改写对照见`examples/05-sentence-brevity.md`「罗列短句成段」。
+- 确认一个中心主题后，围绕段首中心句用衔接关系（…时、一旦、则、因此）把相关动作组织成连贯的完整句；单句长度与拆句触发仍守 `steps/05-sentences.md`「句子规则」，不为连贯写超长句。同档并句不按超长句拆，异档不并进一句，判定见 `steps/05-sentences.md`「同档并句」。
+- 真正并列、需要扫读的项改用列表（详见 `steps/07-layout.md`「列表选择」）。
+- 判定信号：段内句子逐句可删、互不引用；句间没有承接、因果或时序词；逐句像要点罗列。改写对照见 `examples/05-sentence-brevity.md`「罗列短句成段」。
 
 ### 凑字数禁令
 
 信息密度以读者判断所需为准，不以篇幅为准。篇幅超限时先删下面这些句式，再考虑拆页；以下句式在 `content/**` 正文一律禁止：
 
 - 统计性凑句：「文件只有 X 行」「真正执行的只有 X 行」「一共只有 X 个」这类数字统计。数字本身影响读者判断时（规模超出预期、需要据此决定读法）才允许出现，纯描述规模一律删除。
-- 导航复述段：含「先看…再看…」的句子按`steps/05-sentences.md`「句子规则」整句删除，不单指「接下来先看」；与 `##` 标题结构重复的段落同样删除，读者从标题自身即可获得导航。
-- 同义反复：同一事实在承接句、代码块 filename、树内注释、列表项中重复出现时只保留一处。相邻段落同义合并见`steps/04-paragraphs.md`「段间：过渡句只在话题切换处」。代码围栏的块后复述由`steps/03-blocks.md`「内容块前后的闭环」管辖（对照见`examples/03-block-after.md`「块后复述注释」）。同一禁令再延伸到公开接口旁白：禁止「接口清单压缩段」——把私有成员、公开成员名单、`const`、`[[nodiscard]]` 等压进同一段；定稿为场景 → 代码 → 块后只补注释未写的工程信息（对照见`examples/04-paragraph-opening.md`「接口清单压缩段」）。
+- 导航复述段：含「先看…再看…」的句子按 `steps/05-sentences.md`「句子规则」整句删除，不单指「接下来先看」；与 `##` 标题结构重复的段落同样删除，读者从标题自身即可获得导航。
+- 同义反复：同一事实在承接句、代码块 filename、树内注释、列表项中重复出现时只保留一处。相邻段落同义合并见 `steps/04-paragraphs.md`「段间：过渡句只在话题切换处」。代码围栏的块后复述由 `steps/03-blocks.md`「内容块前后的闭环」管辖（对照见 `examples/03-block-after.md`「块后复述注释」）。同一禁令再延伸到公开接口旁白：禁止「接口清单压缩段」——把私有成员、公开成员名单、`const`、`[[nodiscard]]` 等压进同一段；定稿为场景 → 代码 → 块后只补注释未写的工程信息（对照见 `examples/04-paragraph-opening.md`「接口清单压缩段」）。
 - 判断标准：一句删掉后主线闭环不受影响、且答不出「删掉它读者会做错什么」，默认删除。
 
 ### 拆分判据
@@ -66,7 +66,7 @@
 - **引言**：一句点明对象之间的关系（如「配置和构建是两件不同的事」）。
 - **展开**：每个问题一段，或用加粗引导词列表（`**配置**：…` / `**构建**：…`）；两项且能写进一句的仍可保留正文。
 - **收束**：一句写出操作后果或因果（如「改了 CMakeLists.txt 要重跑配置」）。
-- 典型禁例：把「谁做配置、谁做构建、何时重配」压进同一段；改写对照见`examples/04-paragraph-opening.md`。
+- 典型禁例：把「谁做配置、谁做构建、何时重配」压进同一段；改写对照见 `examples/04-paragraph-opening.md`。
 
 ### 段内同义堆叠禁令
 
@@ -80,8 +80,8 @@
 
 豁免与边界：
 
-- **换算短句豁免**：换算写成同一段短句各答一个动作，是递进不是堆叠（见`steps/07-layout.md`「列表选择」换算条）。
-- **简洁边界反向保护**：删辅句不得造成电报省略；动作、对象、顺序三要素仍写全（见`steps/05-sentences.md`「简洁边界」）。
+- **换算短句豁免**：换算写成同一段短句各答一个动作，是递进不是堆叠（见 `steps/07-layout.md`「列表选择」换算条）。
+- **简洁边界反向保护**：删辅句不得造成电报省略；动作、对象、顺序三要素仍写全（见 `steps/05-sentences.md`「简洁边界」）。
 - **跨章固定表述不复述判重**：「九个数据项」这类全书统一表述在各章按需出现，不受「同一事实只讲一次」限制。
 - **自测答案豁免**：答案可对照题面复述一次再展开。
 
@@ -97,7 +97,7 @@
 
 豁免（不得误杀）：列表项（含 `` `enable_testing()`：开启 CTest。``）；列举/代码/图导语（下一块是列表、围栏或图）；终端与协议字面量（如 `流程结果：甲方获胜`）；表格单元格与代码注释。
 
-与「破折号夹心改冒号引出」（见`steps/05-sentences.md`「句子规则」）的关系是**收窄**：破折号解释改冒号时，只允许改成上述两种合法场合，不允许改成散文词条式冒号。
+与「破折号夹心改冒号引出」（见 `steps/05-sentences.md`「句子规则」）的关系是**收窄**：破折号解释改冒号时，只允许改成上述两种合法场合，不允许改成散文词条式冒号。
 
 ### 拆核四步（多核混段的拆段方法）
 
@@ -106,21 +106,21 @@
 1. **拆核**：列出本段必须交代的独立核（例：长度常量的含义；使用该长度的容器；行列到下标的换算）。
 2. **判关系**：核是「属性 → 承载」递进还是并列。递进可同段用衔接推进（如长度定型 → 容器选用该长度，先长度后容器）；并列必须拆段。
 3. **一句一核推进**：每句主语明确（长度 / 数组 / 换算），不夹第二个核的细节；禁止伪标签把两核糊成词条。
-4. **衔接与次序**：段内用「因此 / 所以 / 这样」接住上句对象；换核新段时首句点名上段产物（例：先讲 `kRows`、`kCols` 给出合法范围，新段首句写「范围确定后，坐标检查才有了依据」；递进同一核的展开留在同一段，拆段判据见`steps/05-sentences.md`「句内骨架」）；若某核由后续小节专讲，本段只留一句明确桥接或整句下沉为其首句，禁止悬空预告。
+4. **衔接与次序**：段内用「因此 / 所以 / 这样」接住上句对象；换核新段时首句点名上段产物（例：先讲 `kRows`、`kCols` 给出合法范围，新段首句写「范围确定后，坐标检查才有了依据」；递进同一核的展开留在同一段，拆段判据见 `steps/05-sentences.md`「句内骨架」）；若某核由后续小节专讲，本段只留一句明确桥接或整句下沉为其首句，禁止悬空预告。
 
-拆段触发表已收录「词条式冒号 / 多核并列」信号行；改写对照见`examples/04-paragraph-cases.md`「散文伪标签冒号与多核混段」。
+拆段触发表已收录「词条式冒号 / 多核并列」信号行；改写对照见 `examples/04-paragraph-cases.md`「散文伪标签冒号与多核混段」。
 
 ### 章级：总—分—总
 
-- **总起**：无标题引言的构成见`steps/02-structure.md`「六段块序列」；引言的宾语等于本章 YAML `title` 的对象（承诺链第 2 条，见`steps/02-structure.md`「纵向承诺链」）。
-- **分述**：正文 `##` 序列沿一条主线递进展开；每个 `##` 是一个可验证结果的判定见`steps/02-structure.md`「六段块序列」，每个 `###` 的中心名词与导语宾语按`steps/02-structure.md`「纵向承诺链」第 4、5 条核对。
-- **收束**：本章回顾照应引言提出的任务；首尾照应要求回顾能对上引言的承诺，不引入新概念；「下一章」后的名字等于 `_quarto.yml` 中下一章的 YAML `title`（承诺链第 7 条，见`steps/02-structure.md`）。回顾的句数、句式与承接正文的要求以`steps/02-structure.md`为准。
-- 已有源文件的章要补齐自测与回顾。没有源文件的章的处理见`steps/02-structure.md`。
+- **总起**：无标题引言的构成见 `steps/02-structure.md`「六段块序列」；引言的宾语等于本章 YAML `title` 的对象（承诺链第 2 条，见 `steps/02-structure.md`「纵向承诺链」）。
+- **分述**：正文 `##` 序列沿一条主线递进展开；每个 `##` 是一个可验证结果的判定见 `steps/02-structure.md`「六段块序列」，每个 `###` 的中心名词与导语宾语按 `steps/02-structure.md`「纵向承诺链」第 4、5 条核对。
+- **收束**：本章回顾照应引言提出的任务；首尾照应要求回顾能对上引言的承诺，不引入新概念；「下一章」后的名字等于 `_quarto.yml` 中下一章的 YAML `title`（承诺链第 7 条，见 `steps/02-structure.md`）。回顾的句数、句式与承接正文的要求以 `steps/02-structure.md` 为准。
+- 已有源文件的章要补齐自测与回顾。没有源文件的章的处理见 `steps/02-structure.md`。
 
 ### 节内：递进式为默认，并列式处理枚举
 
-- 有先后或因果的内容用递进式展开，顺序依据见`steps/02-structure.md`「六段块序列」，段落顺序与执行顺序一致。
-- 无先后关系的要点（边界清单、原则枚举）用并列式，列表选择规则见`steps/07-layout.md`「列表选择」。
+- 有先后或因果的内容用递进式展开，顺序依据见 `steps/02-structure.md`「六段块序列」，段落顺序与执行顺序一致。
+- 无先后关系的要点（边界清单、原则枚举）用并列式，列表选择规则见 `steps/07-layout.md`「列表选择」。
 - 同一小节内不混用：一条主线递进到底；并列枚举整体作为一个环节嵌在递进中。
 
 ### 段间：过渡句只在话题切换处
@@ -128,60 +128,60 @@
 - 需要过渡的位置：段落话题或对象发生切换时（上一段讲 A 命令，下一段讲 B 命令；前一小节配置，本节运行）。同一段内句子推进、或下一段直接继续当前对象时，不加过渡。
 - 段间衔接落在下一段第一句的主语；主语复用上段的宾语或话题，话题切换时仍先接住上文再引出本段。
 - 形式：一句，放在新段段首，先接住上文（点明与上段的关系或结果），再引出本段中心。范例（示例章构建规则节首句）：「可执行目标之外，同一份构建规则还注册了本章唯一的自动化检查」——前半句接住上文的可执行目标，后半句引出新对象。
-- 边界：过渡句服务主线判断，不复述标题结构。含「先看…再看…」的导航复述句整句删除，判法见`steps/04-paragraphs.md`「凑字数禁令」；`##`/`###` 开头的承接句数见`steps/02-structure.md`「分层上限」。
+- 边界：过渡句服务主线判断，不复述标题结构。含「先看…再看…」的导航复述句整句删除，判法见 `steps/04-paragraphs.md`「凑字数禁令」；`##`/`###` 开头的承接句数见 `steps/02-structure.md`「分层上限」。
 - 相邻小节的首句同时是上一小节的承接位：写完上一小节结尾后检查下一小节首句是否接住读者，不在小节尾部再补预告句（与凑字数禁令同源）。
 - **读者正文禁写「下一节／上一节」**：`content/**` 正文不得用「下一节…」「上一节…」预告或回指小节，衔接靠新节首句接住上文；章末的「下一章」保留。本文件讨论衔接位置时引用的这两个词是规则描述用语，不是允许正文照写的句式（`verifying-content.py` 对读者 qmd 与 agent 文档判失败，紧贴引号或反引号的术语引用豁免）。
-- 相邻段落同义合并：相邻两段各自换一种说法讲同一事实时合并为一段，由后段的机制或结论接住前段的对象；合并后其余段落、列表和 Callout 不得再以第三种说法复述该事实。改写对照见`examples/04-paragraph-cases.md`。
-- 相邻两段不得各成独立说明书：第一段讲工具、第二段讲目录而彼此无衔接时，第二段段首要接住第一段的对象（工具基线 → 这些工具在编号目录上如何使用）；只删不接，两段仍然是两个条目。改写对照见`examples/02-structure-shape.md`。
-- 目录树后的正文不复述树内行尾注释：树注释已逐文件交代职责，再列一段「A 组件、B 目录与 C 目录各自带 CMakeLists.txt」是把树翻译成说明书目录。树注释的标记方式（目录 `#/`、文件 `#` 右移 4 列、字母序、个数对齐）见`steps/03-blocks.md`「情况：目录树」；本条只管树后正文。树后保留的一句读法说明直述机制（「文件名给出位置，行尾注释说明职责」），不写「X 回答 A，Y 回答 B」的问答式并列；换成工具配置、依赖方向或「不参与 / 不依赖」类边界，即使树注释没写过，也删除或下沉，不得靠「新工程信息」留下（改写对照见`examples/02-structure-shape.md`「目录式堆砌」「树后换对象收束句」）。
-- 同一禁令延伸到代码围栏：块后不复述围栏内注释、单段并列对象按对象拆段的写法，见`steps/03-blocks.md`「内容块前后的闭环」与`steps/04-paragraphs.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 是两个容易混淆的词：」式元标签开场。
+- 相邻段落同义合并：相邻两段各自换一种说法讲同一事实时合并为一段，由后段的机制或结论接住前段的对象；合并后其余段落、列表和 Callout 不得再以第三种说法复述该事实。改写对照见 `examples/04-paragraph-cases.md`。
+- 相邻两段不得各成独立说明书：第一段讲工具、第二段讲目录而彼此无衔接时，第二段段首要接住第一段的对象（工具基线 → 这些工具在编号目录上如何使用）；只删不接，两段仍然是两个条目。改写对照见 `examples/02-structure-shape.md`。
+- 目录树后的正文不复述树内行尾注释：树注释已逐文件交代职责，再列一段「A 组件、B 目录与 C 目录各自带 CMakeLists.txt」是把树翻译成说明书目录。树注释的标记方式（目录 `#/`、文件 `#` 右移 4 列、字母序、个数对齐）见 `steps/03-blocks.md`「情况：目录树」；本条只管树后正文。树后保留的一句读法说明直述机制（「文件名给出位置，行尾注释说明职责」），不写「X 回答 A，Y 回答 B」的问答式并列；换成工具配置、依赖方向或「不参与 / 不依赖」类边界，即使树注释没写过，也删除或下沉，不得靠「新工程信息」留下（改写对照见 `examples/02-structure-shape.md`「目录式堆砌」「树后换对象收束句」）。
+- 同一禁令延伸到代码围栏：块后不复述围栏内注释、单段并列对象按对象拆段的写法，见 `steps/03-blocks.md`「内容块前后的闭环」与 `steps/04-paragraphs.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 是两个容易混淆的词：」式元标签开场。
 
 ### 三层审查
 
 润色按三个层级推进；高层问题不先定，低层改写会白做：
 
 1. **篇章级**：全篇只保留一条成功路径，章节与小节顺序服务这条路径，无跳脱话题；开头交代读者做什么、完成后得到什么。
-2. **段落级**：段落与段间条文见`steps/04-paragraphs.md`，衔接见`steps/04-paragraphs.md`「段间：过渡句只在话题切换处」。
+2. **段落级**：段落与段间条文见 `steps/04-paragraphs.md`，衔接见 `steps/04-paragraphs.md`「段间：过渡句只在话题切换处」。
 3. **句子级**：逐句过「七个质量维度」与「句子级病类清单」。
 
 ### 句序与段落形态
 
 维度之外还有四条形态硬规则，读者正文（`content/**`）命中即改：
 
-- **对象先行**：句子按「对象 → 名称 → 约束 → 出处」排；禁「代码把它写成」式把源码当施事的元叙述开场，也禁「因此记作」「写成 `class`」等以源码为主语的句子。对照见`examples/01-language-scope.md`「元叙述开场与对象先行」。
+- **对象先行**：句子按「对象 → 名称 → 约束 → 出处」排；禁「代码把它写成」式把源码当施事的元叙述开场，也禁「因此记作」「写成 `class`」等以源码为主语的句子。对照见 `examples/01-language-scope.md`「元叙述开场与对象先行」。
 - **正常语序**：推荐「主语/对象 + 谓语 + 宾语 +（必要状语）」，本书工程句优先「对象 → 名称 → 约束 → 出处」。改写信号：句首「关于…」抽空主语；「代码把它写成」式元叙述倒装；长定语链把施事压到句末；英文式「被…所…」堆叠；状语（时间/处所）乱插导致主谓隔断。与「对象先行」同向，不另开 kb。
 - **连续纯散文上限**：同一小节连续 ≥3 段纯散文（中间无列表、代码块、图或表）即改「一句中心 + 列表/代码/图」；判定信号：删任一段其余仍成立、段间无承接。
-- **禁小节导航**：正文「下一节／上一节」的禁令与豁免见`steps/04-paragraphs.md`「段间：过渡句只在话题切换处」。
-- **换算句版式**：换算的写法见`steps/07-layout.md`「列表选择」。
+- **禁小节导航**：正文「下一节／上一节」的禁令与豁免见 `steps/04-paragraphs.md`「段间：过渡句只在话题切换处」。
+- **换算句版式**：换算的写法见 `steps/07-layout.md`「列表选择」。
 
-六个成分和场景表不在本文件复述，见`steps/05-sentences.md`。
+六个成分和场景表不在本文件复述，见 `steps/05-sentences.md`。
 
-代码块门槛（哪些实现值得出围栏）见`steps/03-blocks.md`「代码块门槛」。
+代码块门槛（哪些实现值得出围栏）见 `steps/03-blocks.md`「代码块门槛」。
 
 ### 段落与句子
 
-段落长度与中心句条文以本文件「段落规则」为唯一出处；单句 20/40 字与多动作拆句见`steps/05-sentences.md`「句子规则」。本文件只保留句子级病类判法（见「句子级病类清单」）。
+段落长度与中心句条文以本文件「段落规则」为唯一出处；单句 20/40 字与多动作拆句见 `steps/05-sentences.md`「句子规则」。本文件只保留句子级病类判法（见「句子级病类清单」）。
 
 ### 定段落：衔接与句段删改口诀
 
 一段一个对象、段间衔接、概念负荷的判定依据见本文件「段落规则」；对每个段落依次检查：
 
-- 删掉后影响当前任务吗？删除判据见`steps/04-paragraphs.md`「凑字数禁令」。
-- 段落是否同时承担两个以上动作？拆分判据见`steps/04-paragraphs.md`「拆分判据」。
-- 同一小节的连续同源代码围栏是否拆并，判定见`steps/03-blocks.md`（对照见`examples/03-excerpt-lead.md`「递进片段合并」）。
-- 段落是否推进了两个互不依赖的并列对象？是就按「拆核四步（多核混段的拆段方法）」处理，判定见`steps/04-paragraphs.md`「拆核四步（多核混段的拆段方法）」（对照见`examples/03-block-after.md`「单段混并列对象」）。
-- 段内是否有换说法复述同一机制的句子？是就删辅句或合并，判定见`steps/04-paragraphs.md`「段内同义堆叠禁令」。
-- 分句骨架是否成立？设计说明的角色链不合格情形见`steps/05-sentences.md`「句内骨架」，都在定句子判为不合格。
-- 散文里是否有「话题标签：解释」词条式冒号？是就改完整主谓句或真列表项，判定见`steps/04-paragraphs.md`「散文伪标签冒号禁令」。
-- 收束段是否把列表或围栏注释再讲一遍？次序与块后新信息见`steps/03-blocks.md`（对照见`examples/03-block-after.md`「块后复述注释」）。
-- 树后或块后补写的新信息主语是否换成另一个对象？删除或下沉见`steps/04-paragraphs.md`（对照见`examples/02-structure-shape.md`「树后换对象收束句」）。
-- 读者能否指出完成后要观察什么？任务可验证结果的判定见`steps/02-structure.md`「六段块序列」。
-- 正文、代码块和回顾是否重复同一句话？同义反复判定见`steps/04-paragraphs.md`「凑字数禁令」。
-- 新术语是否由当前动作自然引出？标题与论据的术语建立判定见`steps/03-blocks.md`「小节标题与正文对齐」。
-
-段落衔接、罗列短句成段与接口清单压缩段的判定见`steps/04-paragraphs.md`；句间关系的写法见`steps/05-sentences.md`「过简断裂禁令」，对照见`examples/05-sentence-brevity.md`「罗列短句成段」、`examples/04-paragraph-opening.md`「接口清单压缩段」。
+- 删掉后影响当前任务吗？删除判据见 `steps/04-paragraphs.md`「凑字数禁令」。
+- 段落是否同时承担两个以上动作？拆分判据见 `steps/04-paragraphs.md`「拆分判据」。
+- 同一小节的连续同源代码围栏是否拆并，判定见 `steps/03-blocks.md`（对照见 `examples/03-excerpt-lead.md`「递进片段合并」）。
+- 段落是否推进了两个互不依赖的并列对象？是就按「拆核四步（多核混段的拆段方法）」处理，判定见 `steps/04-paragraphs.md`「拆核四步（多核混段的拆段方法）」（对照见 `examples/03-block-after.md`「单段混并列对象」）。
+- 段内是否有换说法复述同一机制的句子？是就删辅句或合并，判定见 `steps/04-paragraphs.md`「段内同义堆叠禁令」。
+- 分句骨架是否成立？设计说明的角色链不合格情形见 `steps/05-sentences.md`「句内骨架」，都在定句子判为不合格。
+- 散文里是否有「话题标签：解释」词条式冒号？是就改完整主谓句或真列表项，判定见 `steps/04-paragraphs.md`「散文伪标签冒号禁令」。
+- 收束段是否把列表或围栏注释再讲一遍？次序与块后新信息见 `steps/03-blocks.md`（对照见 `examples/03-block-after.md`「块后复述注释」）。
+- 树后或块后补写的新信息主语是否换成另一个对象？删除或下沉见 `steps/04-paragraphs.md`（对照见 `examples/02-structure-shape.md`「树后换对象收束句」）。
+- 读者能否指出完成后要观察什么？任务可验证结果的判定见 `steps/02-structure.md`「六段块序列」。
+- 正文、代码块和回顾是否重复同一句话？同义反复判定见 `steps/04-paragraphs.md`「凑字数禁令」。
+- 新术语是否由当前动作自然引出？标题与论据的术语建立判定见 `steps/03-blocks.md`「小节标题与正文对齐」。
+
+段落衔接、罗列短句成段与接口清单压缩段的判定见 `steps/04-paragraphs.md`；句间关系的写法见 `steps/05-sentences.md`「过简断裂禁令」，对照见 `examples/05-sentence-brevity.md`「罗列短句成段」、`examples/04-paragraph-opening.md`「接口清单压缩段」。
 
 ## 情况