@chengzhao-dev/dsh-quarto-book 0.6.2 → 0.6.4

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

@@ -19,9 +19,10 @@
 
 以代码块为中段，导语讲工程语境（这段代码为什么存在、为什么此刻看它）；若有块后句，只讲注释没覆盖的新工程关系。语法细节不逐行展开。导语与块后都禁止关键字释义当开场：不写「X 是 `inline constexpr` 常量」「用 `enum class` 表达」「用有符号整型承载」「坐标字段为什么选定宽有符号」式语言课或选型旁白（除 01 设计章外工程 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`「块后复述字面值」。
 - **禁止单段夹杂多个并列对象**：一段一对象的通则见 `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`「逐条释义代替动机」。
@@ -81,6 +82,12 @@ int main() {
 
 一个三级标题下面的正文由一到两个最小模块组成。一个模块是一个整体，次序固定：标题已经给出对象；标题下一句导语；有并列取值时跟着列表，一项一个取值、一项一句；代码块、表格或图放在列表和收束段之间；没有列表时放在导语和收束段之间；收束段只写各项共同的契约；Callout 可有可没有，写了就放在收束段之后。短模块可以只有导语和代码块。示例章「操作与成败」里的 `Move` 与 `PlaceResult` 各是一个短模块，下一个短模块用自己的导语接上。第二个模块用来解释前一个时，衔接句就是第二个模块的导语。示例章「数据项坐标」用「下面的图标出这块状态面板上可用的 `(row, col)`。」接上图。讲一个函数时，先一个模块讲 `.h`，再用导语接 `.cpp`。列表写选法，围栏与源文件逐字一致，收束段不把列表再写一遍。禁止「每个状态码对应」，也禁止以 `` `类型::kName`： `` 开头的释义项。正面例子是 示例章「操作的强度」。
 
+### 节末旁注与 Callout 收尾
+
+二级标题的最后一个内容块只承载旁注时，改写成 Callout 收尾，正文不再保留同一句。旁注是读者跳过也能完成本节、回看能少走弯路的补充：可重新生成的产物、版本差异、可选替代、边界条件。本节结论、下一步动作、必经步骤与成功判据留在正文。
+
+收尾 Callout 放在本节最后一块之后、下一个标题之前；每节至多一个收尾 Callout。正文必须脱离前文也能读懂：点名对象，写出前提与结果，不复用上一段的句子；超过两段或需要列举时改用 `###` 小节。正反例见 `examples/03-qmd-elements.md`「节末旁注改为 Callout 收尾」。
+
 ### 执行位置判据
 
 故障定位第一步是确认执行位置和前置状态，给可观察判据而不是模糊要求：Shell 场景用 `pwd` 看路径结尾，工程场景用特征文件（如 `CMakeLists.txt`）存在性判断。
@@ -93,11 +100,12 @@ int main() {
 
 ### 代码与图的桥接
 
-代码块引出 `{mermaid}` 图或 `{python}` 坐标图时按固定序列组织：代码块 → 桥接句 → 图（含 `fig-cap`）→ 图后新结论。固定序列的完整写法见 `writing-quarto` 技能 `quarto/authoring.md`「代码与图的桥接」，两条硬边界：
+代码块引出 `{mermaid}` 图或 `{python}` 坐标图时按固定序列组织：代码块 → 桥接句 → 图（含 `fig-cap`）→ 图后新结论。固定序列的完整写法见 `writing-quarto` 技能 `quarto/authoring.md`「代码与图的桥接」，边界如下：
 
 - 代码块与图之间必须有桥接句，说明图要核对代码已讲清的哪条关系；中间只有空行视为堆叠（`verifying-content.py` 的 DOC-E11 只要求相邻围栏留空行，空行不等于桥接正文）。
 - 图后先给「从图带走的结论」或图外新信息，再进入下一块；小节以图收尾时，结论可并入桥接段，不在图后孤悬一句。图注已写明的信息不复述。坐标图计入盒子密度，口径见 `quarto/coords.md` 与本文件。
-- 一图一事、同主题相邻、图不承载正文未写的新信息：一张图只核对一条已讲清的关系；代码与图主题不同时收束本对象再拆 `###`，禁止「代码 A → 短句拐弯 → 图讲 B → 再贴代码 C」的同节混排（三条边界的写法见 `quarto/authoring.md`「代码与图的桥接」）。
+- 图注与图前句分工：图注写图面内容与读法，落在图下；图前只写引出关系的一句，不写“下图标出……”这类图面说明。三类图（Mermaid、坐标图、原生 HTML/SVG）的写法见 `quarto/figures.md`。
+- 一图一事、同主题相邻、图不承载正文未写的新信息：一张图只核对一条已讲清的关系；代码与图主题不同时收束本对象再拆 `###`，禁止「代码 A → 短句拐弯 → 图讲 B → 再贴代码 C」的同节混排（上述边界的写法见 `quarto/authoring.md`「代码与图的桥接」）。
 - 图前段只讲本页可见的对象，且单一主题：描述版式的句子其对象必须同页可见，引用前章画面时复述读者需要的关键事实（如行列取值 0 到 2），不指称前章画面的版式（「画面上方是列号」式会让读者翻回前章）；调用方行为等第二主题移出图前段（示例章定义坐标范围节两段并一段的改稿对照）。
 
 图不能替代结论句：桥接句与图带走的结论缺任何一处，读者只有图没有判断依据。正反对照见 `examples/03-qmd-elements.md`「代码与图桥接对照」。
@@ -218,7 +226,7 @@ int main() {
 
 ### 情况：图是 Mermaid 或坐标轴图
 
-要画流程图、时序图才打开 `quarto/mermaid.md`，坐标轴网格图打开 `quarto/coords.md`。不排图不打开。
+要画流程图、类图或时序图才打开 `quarto/mermaid.md`（类图先按内容预算删节点和成员），坐标轴网格图打开 `quarto/coords.md`，图注与原生 HTML/SVG 图打开 `quarto/figures.md`。不排图不打开。
 
 ### 情况：Callout
 
@@ -226,13 +234,17 @@ int main() {
 
 ### 情况：目录树
 
-目录树只在需要让读者认识文件清单时出现，先按磁盘事实取节点，再删掉与当前任务无关的缓存和构建产物。同一棵树里顶层目录个数、句子里点到的目录个数、列表条数三者相同。
+目录树只在读者需要认识文件清单时出现。树是地图，不是文件清单：先按磁盘事实取节点，再删掉与当前任务无关的缓存；同一棵树里顶层目录个数与紧邻列表的条数相同，正文写了目录个数时三处一致。定稿前用 `tree -a` 对照一次，树里每个节点都在磁盘上，本章要讲的节点都在树里。
+
+整棵树控制在 20 行以内（不含根）。顶层目录都保留，子层只留本章会点名的文件；同层同类文件超过三个时，只留目录行，文件名交给后文或对应章节。排列按 `tree -a` 的字母序，不按讲解顺序重排；本章不讲的文件整枝删掉；`build/` 这类生成目录默认只保留顶层并注明「配置与编译生成」，本章要说明产物落在哪个子目录时可以展开一层。目录名以 `/` 结尾，目录注释以 `#/` 开头，文件注释以 `#` 开头。两种注释不共列：目录的 `#/` 从同一列开始，文件的 `#` 比目录的 `#` 右移一列，落在 `/` 下方；两种注释的文字左端对齐，标记后只留一个空格。注释列与最长节点之间至少留四个空格。
+
+每个展示的节点都写一条注释。目录写这里装什么，用名词短语：`apps/` 旁写「终端程序」就够，再写「打印与读入」等于替 `cli.h` 说话；目录注释不加冒号、不列清单，最多 16 个显示列。文件写这个文件负责什么，用「对象 + 动作」：`board.h` 旁写「棋盘尺寸与坐标」，`main.cpp` 旁写「程序入口」；文件注释不超过 28 个显示列，只列 1 到 2 项，出现第二个「、」或「与」就删到两项。文件不能只写「头文件」「实现」「源码」「测试」「配置文件」这类类别词；目录可以用「终端程序」「单元测试」这类类别词。注释是路标，不写实现细节，也不写第二句。
 
-排列按 `tree -a` 的字母序，不按讲解顺序重排。本章不讲的文件整枝删掉。目录注释以 `#/` 开头，文件注释以 `#` 开头并比 `#/` 右移 4 列，每个展示文件都带一条行尾注释。
+一条注释只回答一个问题：这一项负责什么，或者它和谁划界；冒号后不再起第二句，也不再套第二层解释。需要两句才说得清的，第二句放树后的正文。
 
-注释只用两档，同一棵树里不混用。文件名已经说出职责时只写名词，例如 `mermaid.md` 旁写「Mermaid」。名词没说出的那一件事补一句，例如 `07-layout.md` 旁写「版式：标点、列表与加粗」。这一句只做一件事，要么职责要么边界；冒号后不再起第二句，也不再套第二层解释。第二句放树后的正文，或者拆到树外的段落。
+树内的名词不点名下层文件，也不写「见某一章」；需要指路时写在树后的正文里，链接放在该文件第一次被讲到的段落。树后一段只讲从树上读不出的关系：谁编译进谁、谁调用谁、哪些目录会重新生成，不复述注释，也不逐行翻译；超过两句的细节留给下一节。
 
-树内的名词不点名下层文件，也不写「见某一章」；需要指路时写在树后的正文里，链接放在该文件第一次被讲到的段落。目录树不是列表，也不是表格；列表形态在 `steps/07-layout.md`，表格的说明句在通用情况里。
+目录树不是列表，也不是表格；列表形态在 `steps/07-layout.md`，表格的说明句在通用情况里。
 
 ## 正反例
 

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

@@ -17,6 +17,14 @@
 - 代码块后的逐条讲解用无序列表：每项格式为「行内代码标识符 + 全角冒号 + 一句职责」（如 `` `enable_testing()`：开启 CTest。``），描述从简，全页标记方式一致；列表前保留一句引言交代工程语境，列表后需要时补一句收束或尾置 Callout。有先后顺序的排查步骤仍用有序列表；块前导语直接点名对象做什么，不用「先…再…最后…」，元计数禁令见 `steps/03-blocks.md`。
 - 删段还是拆段，先按 `steps/05-sentences.md`「一次对话」数这段有几件内容再定删或拆；判定全文见该文件「一次对话」。
 
+### 默认总分与并列槽位
+
+读者正文默认先总后分；段首先给这一段的整体，后面的句子或列表再展开部分。列表前的那一句就是“总”，列表项是“分”。分总只留一种情况：紧挨在前的代码块或图已经把部分摆在读者眼前，下一句只给这些部分一个总名。
+
+并列项的槽位固定，多项也不得对调：前槽写棋盘或对局里读者看得见的东西，后槽写代码里的类型、常量或函数。例如「行列数字写进棋盘格子坐标；每个棋盘格子保存的取值写进棋盘格子类型」。需要点出多个对象时，不先列 `kBoardRows`、`kBoardCols`、`CellPosition` 再补它们共同约定坐标；先说棋盘格子坐标由尺寸和一对行列位置组成，再分别写行数、列数和 `CellPosition`。
+
+依据：中文技术文档写作风格指南的段首主题句、OpenHarmony 文档规范的「主题句置于段首」、金字塔原理的「结论先行、同组同构」；「疑问 / 回答」只用于作者自检，不写进读者正文。
+
 #### 拆段触发表
 
 段落拆分不只按行数硬切，命中下表任一信号即拆段或改形态（列表 / 代码 / 图）：
@@ -65,7 +73,7 @@
 
 - **引言**：一句点明对象之间的关系（如「配置和构建是两件不同的事」）。
 - **展开**：每个问题一段，或用加粗引导词列表（`**配置**：…` / `**构建**：…`）；两项且能写进一句的仍可保留正文。
-- **收束**：一句写出操作后果或因果（如「改了 CMakeLists.txt 要重跑配置」）。
+- **收束**：一句写出操作后果或因果（如「改了 CMakeLists.txt 要重新运行配置」）。
 - 典型禁例：把「谁做配置、谁做构建、何时重配」压进同一段；改写对照见 `examples/04-paragraph-opening.md`。
 
 ### 段内同义堆叠禁令
@@ -117,6 +125,15 @@
 - **收束**：本章回顾照应引言提出的任务；首尾照应要求回顾能对上引言的承诺，不引入新概念；「下一章」后的名字等于 `_quarto.yml` 中下一章的 YAML `title`（承诺链第 7 条，见 `steps/02-structure.md`）。回顾的句数、句式与承接正文的要求以 `steps/02-structure.md` 为准。
 - 已有源文件的章要补齐自测与回顾。没有源文件的章的处理见 `steps/02-structure.md`。
 
+### 章节核心不漂移
+
+章引言和每个 `##` 的首句，主语必须是本章标题的对象。不要用这个对象被谁使用、能推出什么结果来替换它；那些内容属于后文专门的小节。
+
+- 不佳（标题是棋盘，首句却把格子用途列成一段）：棋盘是 3 行 3 列，共九个格子。每次落子先检查坐标；满盘、三连和赢家都从这些格子判断。
+- 改写：棋盘是 3 行 3 列，共九个格子，`Board` 保存这些格子。写入与读出的接口声明在 `board.h`，实现放在 `board.cpp`。
+
+判定信号：首句主语是「格子 / 对局 / 终端」等下游对象，而标题是「棋盘 / 对局 / 程序结构」；把首句主语换成标题对象后句子仍成立，说明原句已经漂移。01 设计章按规则讲范围，不受本条限制。
+
 ### 节内：递进式为默认，并列式处理枚举
 
 - 有先后或因果的内容用递进式展开，顺序依据见 `steps/02-structure.md`「六段块序列」，段落顺序与执行顺序一致。
@@ -133,7 +150,7 @@
 - **读者正文禁写「下一节／上一节」**：`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`「目录式堆砌」「树后换对象收束句」）。
+- 目录树后的正文不复述树内行尾注释：树注释已逐文件交代职责，再列一段「A 组件、B 目录与 C 目录各自带 CMakeLists.txt」是把树翻译成说明书目录。树注释的标记方式（目录 `#/` 与文件 `#` 分两列、文字对齐、字母序、个数对齐）见 `steps/03-blocks.md`「情况：目录树」；本条只管树后正文。树后保留的一句读法说明直述机制（「文件名给出位置，行尾注释说明职责」），不写「X 回答 A，Y 回答 B」的问答式并列；换成工具配置、依赖方向或「不参与 / 不依赖」类边界，即使树注释没写过，也删除或下沉，不得靠「新工程信息」留下（改写对照见 `examples/02-structure-shape.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 是两个容易混淆的词：」式元标签开场。

package/skills/writing-quarto/steps/06-wording.md

@@ -9,6 +9,57 @@
 
 中文技术工程文档的语气：陈述、可核对、主动语态。句子的三要素判法见 `steps/05-sentences.md`「简洁边界」；允许自然衔接词，不堆砌「必须 / 应当 / 予以」。
 
+### 读者正文禁用问答式讲解
+
+读者正文（`content/**`、README）不把类型、函数或图写成“它回答什么问题”“只回答”“回答四类问题”“回答整局走到哪一步”。这类句子把读者正文写成作者自检提纲，删掉后读者仍能拿到同样的结果。改写为返回值、判断结果或直接陈述：
+
+- 不佳：`Board` 保存九个棋盘格子。它回答四类问题：坐标是否越界、棋盘是否已满、是否连成三个以及赢家是谁。
+- 改写：`Board` 保存九个棋盘格子，写入前检查坐标；满盘、三连和赢家都从这些格子得出。
+- 不佳：`GetResult` 读取 `result_`，它回答整局走到哪一步。
+- 改写：`GetResult` 返回 `GameResult`，开局是 `kInProgress`，分出胜负或平局后给出对应结果。
+
+自测固定导语“试着自己把回答完整说出来”中的“回答”指读者自己的答复，允许保留；技能步骤里的“读者要能说出什么”是自检说明，不要求改写成读者句。其余示例必须给读者能直接读到的句子，不写“读者要能说出……”。
+
+### 绝对范围词要少用
+
+读者正文默认不写「只 / 仅 / 唯一 / 一律 / 永远 / 一定 / 必然 / 全部 / 完全」这类把范围一次说死的词。删掉后句义不变就删；需要限定范围时，写出范围本身：尺寸、条件、文件名或入口。
+
+- 不佳：`Board` 只保存九个棋盘格子，入口只把三个标准流交给 `RunMatch`。
+- 改写：`Board` 保存九个棋盘格子，入口把三个标准流交给 `RunMatch`。
+- 不佳：测试只覆盖落子成功，其余分支没有保护。
+- 改写：测试覆盖落子成功；错人落子、越界和终局还没有测试。
+
+「只读」「只写」是读写性质的固定术语，保留；`const` 成员函数首次称「只读」时，写明它不改动对象。安全、协议或验收条件确实需要排他时，写成可核对的条件（「`PlaceCell` 在目标格子非空时返回 `false`」），不靠「只」承担论证。
+
+### 表示、保存、记录，不用「承载」
+
+读者正文不把类型或字段写成「承载」某个值。「承载」是抽象能力或文档职责的说法，套到 `struct`、`enum`、字段上会让读者分不清它表示什么、运行时保存什么。
+
+按对象选动词：
+
+- 类型表达概念：`CellPosition` **表示**一对行列，`CellType` **表示**格子里的取值。
+- 对象保存数据：`Board` 的 `cells_` **保存**九个 `CellType`。
+- 文件或协议留下记录：快照 **记录**落子次数、当前玩家和结果。
+- 名称与值对应：`kX` **对应** X 标记。
+
+- 不佳：坐标由 `CellPosition` 承载，取值由 `CellType` 承载。
+- 改写：`CellPosition` 表示一对行列，`CellType` 表示格子里的取值。
+- 不佳：这份配置承载三个字段。
+- 改写：这份配置保存三个字段。
+
+### 读者正文禁无信息提问与自造关系词
+
+读者正文不向读者发问。没有任务指向的提问（「总览图为什么不列成员？」「这条边表示什么？」）只是把作者自检提纲搬进正文，删掉后读者仍能拿到同样信息；需要读者判断的内容改写为陈述句，或放进自测。
+
+关系用通行词：组成、调用、依赖、只读依赖、继承。不要给关系另造简称（「组成边」「依赖边」），也不要把「组成关系」写成一个新名词再解释。
+
+- 不佳：总览图为什么不列成员？
+- 改写：（删除；图注已说明总览的范围。）
+- 不佳：`Game` 与 `Board` 之间的组成边表示什么？
+- 改写：`Game` 持有一个 `Board` 作为组成部分。
+
+判定信号：正文句以「为什么 / 为何 / 表示什么」收尾并带问号；出现「×边」式自造关系词；把图的取舍、成员多少写成读者需要回答的问题。
+
 ### 两轴禁例与允许写法
 
 | 轴 | 禁止 | 允许 |
@@ -65,7 +116,9 @@
 - 动词选用与主动语态见「目标语气」；「由 X 完成」在这一步改成主动句，改完露出第二个核就退回定段落。
 - 「同一概念只使用一个称呼」的判定见「七个质量维度」；英文标识保持大小写。
 - 「游戏」指作品或玩法整体，「对局」指具体一场：定义「井字棋是…游戏」用「游戏」，规则、落子与结果语境用「对局」；同一页不把两者当同义词换用（对照见 `examples/06-wording-cases.md`「游戏与对局」）。
+- 项目名在同一页首次写全（如「井字棋棋盘」），后文改用对象名（「棋盘」「动态库」「对局」）；不逐段重复项目名，也不在同一页反复解释已经说过的事。
 - 无信息修饰的删除判定见「七个质量维度」；禁用词以 `scripts/verifying-content.py` 词表为准。
+- 压缩动词写全：`重建`、`重编`、`重跑` 这类两字词，读者可能读成「重新创建」；写「重新生成」「重新编译」「重新运行」，同一页后续也不回退到压缩词。
 - 连续出现三个「的」时的改写判定见「七个质量维度」第 5 条。
 - 正文提及枚举类型与成员函数时写源码完整标识符（`Result`、`Game::ApplyMove`），不设「概念简称」层；架构层名首次出现用一句可观察行为定义；讲读写路径第一句写屏幕上或调用处发生什么。下一句点名类型与函数。再下一句写边界（对照见 `examples/01-language-scope.md`「零基础可懂的读写路径与层名定义」）。
 - 枚举成员的含义写在源码行尾注释里，正文不复述成释义列表或释义段；正文只写谁调用、如何验收、与邻章关系（叙事范围见 `steps/01-task.md`「叙事范围（硬边界）」）。

package/skills/writing-quarto/steps/07-layout.md

@@ -26,7 +26,7 @@
 - 行为或规则枚举项用「**动词短语引导词**：完整句」格式：引导词命名本项的中心动作（如「**显示状态面板**」「**判定流程结果**」），冒号后保留完整中文句，写全动作、对象与结果。引导词是扫读索引，不替代句子信息，不为省字把冒号后压成电报短句（对照见 `examples/07-layout-list.md`）。
 - 解释并列名称的引导词列表放在首次使用这些名称的代码块或目录树之前：读者先经列表认识每个名称，再看结构展示；禁止把解释压到块后，读者会带着未解释的名称读块。名称本身用读者可核对的具体形态（如「项目动态库」），不用模糊统称（术语依据见 `steps/06-wording.md`）。
 - 并列成员一次列全：目录、组件等并列对象（含 `build/` 这类构建生成的目录）并入同一个引导词列表，先列全再展示目录树等结构；列表之后不用段落补列遗漏的成员（对照见 `examples/04-paragraph-opening.md`「角色总述段」）。
-- 目录树的列对齐（目录 `#/`、文件 `#` 右移 4 列、同一棵树只一档注释）见 `steps/03-blocks.md`「情况：目录树」；本文件只管列表、标点与加粗，不另写一份树规则。
+- 目录树的列对齐（目录 `#/` 在左、文件 `#` 右移一列、两种注释文字对齐、每个节点一条注释）见 `steps/03-blocks.md`「情况：目录树」；本文件只管列表、标点与加粗，不另写一份树规则。
 - 三项以上、或每项内含解释的信息优先成列表；只有两项且能写进一句的保留正文；只有一项时不设列表，写进正文（节内无代码块或列表承接时，整节收成一句）。
 - **不为凑三项拆列表**：列表项各要有一条独立信息；同一事实的碎片拆成三项、或为对齐硬补一项，都改回完整句，两项各有信息就写两项（对照见 `examples/07-layout-list.md`「凑三项拆列表」）。
 - **构造后的成员并列成列表**：同一句或同一段用顿号、逗号并列三个及以上数据成员、而且各项状态不同时，改成引导词列表；列表放在数据成员围栏**之前**，引导句不数个数、不把类名连写两次，也不写「成员写在该类里」——只把「构造之后的取值」引出来（如「`Game()` 默认构造之后，状态面板、当前用户、流程结果和操作记录是下面这样：」）。每一项恰好两句：第一句写成员是什么，第二句只写开局取值；第二句可以是「开局是空状态面板」这类状态句。枚举取值列表的位置见 `steps/03-blocks.md`「三级标题最小模块」，本文件不重写；枚举成员的含义仍留在源码行尾注释，这里列的是构造之后每个数据成员的状态，不是把枚举成员再解释一遍。依据：C++ Primer 把名字和初值分开讲，阮一峰一句一事。

package/skills/writing-quarto/steps/08-reread.md

@@ -22,6 +22,7 @@
 | 定结构 | 章引言顿号串 ≥3 个交付物 | 下沉为列表或正文 `##` | `steps/02-structure.md`「六段块序列」、`examples/02-structure-shape.md`「目录式堆砌」 |
 | 排列内容块 | 过简实现围栏（单次比较或直接 `return`） | 删围栏，改入口列表 + 失败策略列表 | `steps/03-blocks.md` |
 | 排列内容块 | 块间闭环缺失（标题下无引导、段→列表无 lead-in、代码→图只有空行、表前无关系句、Callout 复述块内） | 按块链检查清单补桥接 | `steps/03-blocks.md`「块链检查清单」、`steps/03-blocks.md` |
+| 排列内容块 | 节末旁注裸句（`##` 最后一块是一句可跳过的补充，前面是列表、表格或围栏） | 改写为独立可读的 Callout 收尾，正文删同句；超过两句改小节 | `steps/03-blocks.md`「节末旁注与 Callout 收尾」、`examples/03-qmd-elements.md`「节末旁注改为 Callout 收尾」 |
 | 定段落 | 段内同义堆叠（两句换说法讲同一机制） | 删辅句或合并；公式递进与简洁边界豁免 | `steps/04-paragraphs.md`「段内同义堆叠禁令」 |
 | 定段落 | 过简断裂（逗号、句号后分句换新主语、新事实，无回指、无承接词）；一段第 4 个主概念 | 收敛主概念后用给定信息衔接；超 3 个主概念拆段或改列表 | `steps/05-sentences.md`「过简断裂禁令」「概念负荷」 |
 | 定句子 | 处所状语后 12 字内出现「记住」「保存」或「选出」 | 判为状语配错谓语；改写见「同档并句」——位置句的谓语用「放进」，职责不并进位置句 | `steps/05-sentences.md`「同档并句」 |

package/skills/writing-quarto/steps/09-check.md

@@ -10,7 +10,7 @@
 
 项目技能列了内容检查命令时，只跑它列出的命令。没有项目技能时，在书根跑本技能 `scripts/` 下的 `verifying-content.py`、`checking-links.py` 与 `checking-prose.py`。
 
-`verifying-content.py` 查章节表、YAML 标题、标题层级、句段长度、围栏语言、Mermaid 围栏、占位文字和本地链接；`checking-prose.py` 查中文与拉丁字母、数字、行内代码之间的空格，以及中文句里的半角标点。项目专属检查只在书的 `.agents/skills/quarto-book-project/` 存在时启用。
+`verifying-content.py` 查章节表、YAML 标题、标题层级、句段长度、围栏语言、Mermaid 围栏、占位文字、目录树（行数、目录注释 16 列且无冒号/顿号、文件注释 1–2 项、标记列对齐）和本地链接；`checking-prose.py` 查中文与拉丁字母、数字、行内代码之间的空格，以及中文句里的半角标点。项目专属检查只在书的 `.agents/skills/quarto-book-project/` 存在时启用。
 
 ### 渲染与 HTML
 
@@ -22,8 +22,8 @@
 检查次数有上限：
 
 - `dry_run: true` 最多 2 次。第 1 次返回 `safe_to_render: false` 时，只改 `output-dir` 一次。第 2 次仍不安全就停住，把 `warnings` 列给用户。
-- `dry_run: false` 最多 1 次。渲染失败就停住，把 `errors` 列给用户，不自动重跑。
-- 成功时同一次返回里带 `html_report`，不再为同一份文件重跑。
+- `dry_run: false` 最多 1 次。渲染失败就停住，把 `errors` 列给用户，不自动重新运行。
+- 成功时同一次返回里带 `html_report`，不再为同一份文件重新运行。
 
 报告字段：
 

package/templates/quarto-book-project/SKILL.md

@@ -39,7 +39,7 @@ description: 记录某一本 Quarto Book 的项目级约定：书名、读者、
 - 链接检查：`<插件技能目录>/scripts/checking-links.py --root <book>`。
 - HTML 可用性：只调 `quarto_render_check`，`qmd_path` 传当前章节；`dry_run: true` 最多 2 次，`dry_run: false` 最多 1 次。
 - 不手跑 `quarto render`，也不手跑 `checking-output.py` 或 `checking-callouts.py`；这些检查由工具按书配置调用。
-- 项目专属词表：同目录 `checks.json`（`forbidden_terms`、`fragment_prefixes`、`chapter_titles`）；不写就只跑通用规则。
+- 项目专属词表：同目录 `checks.json`（`forbidden_terms`、`fragment_prefixes`、`chapter_titles`）；模板带一份空文件，复制后按项目填写，不写就只跑通用规则。
 - 项目自己的检查命令（如有）与它覆盖的 profile：
 - 命令在哪个环境执行（本机 / WSL / 容器）：
 

package/templates/quarto-book-project/checks.json

@@ -0,0 +1,5 @@
+{
+  "forbidden_terms": [],
+  "fragment_prefixes": [],
+  "chapter_titles": {}
+}