@chengzhao-dev/dsh-quarto-book 0.6.1 → 0.6.3

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

@@ -5,28 +5,6 @@
 
 ## 通用情况
 
-### 页面骨架
-
-正文按下面顺序组织：
-
-```text
-无标题引言 → 任务序列（2-4 个 ##）→ ## 常见错误 → ## 自测问题 → ## 本章回顾
-```
-
-- 无标题引言写成连贯读者文（形态契约见 `steps/02-structure.md`）：首选单个自然段（承接上一章的结果，用章节标题链接；正面陈述本章要解决的问题；可选在段末用一句话点名主源文件并挂链接），必要时「一段 + 列表」；禁止两个散文自然段并立、单句孤儿段和结尾导航段，摘录免责句永不进入读者正文，不放 Callout。
-- `##` 承担一个可验证阶段，数量按独立任务和依赖关系决定；2–4 个是常见预算而非标题配额，`###` 只用于有独立动作或结果的子任务。`##` 下有多于一段的主线内容时必须拆成合理的 `###`，禁止「长导语 + 大段代码 + 过短 `###`」的失衡结构。
-- 章目标与回顾分工：引言或紧随引言的目标节只陈述本章可交付、可见的产物，不提前堆「属于哪章、哪章再讲」的回顾式边界；「本章做到哪、后续章接什么」只写在 `## 本章回顾`，过程中的 `### 本章实现边界` 一类过程节标题一律不设。
-- 每个任务按「做什么 → 执行什么 → 看到什么 → 简短说明」推进。
-- 常见错误按症状分 `###`，标题后第一句写触发条件与可观察现象，随后给原因与正确做法；误用型条目一段成文，原因与做法需要分开完整交代时用症状句导语加原因/做法引导词列表，排查型故障展开「定位 → 修复 → 验证」三步，形态分野见 `quarto/terminal.md`。入门章节只保留最可能遇到的 2-3 项。中间实现章的常见错误承接开发过程中真实出现过的报错记录。
-- 自测问题用带 `.answer` 的有序问题检查本章已经写明的一件可观察结果；题面只描述自洽局面、一道题只问一件可观察结果，其余规则（含拒绝题的正例写法）见 `steps/02-structure.md`「六段块序列」；只有本章写了原因、而且情景已经说全时，才用「为什么」问句。每章按本章可验证的结果决定题数，没有这种结果时不添加，写法见 `quarto/authoring.md`。答案首句直接针对问题所问的对象作答，补充细节放在首句之后，不先岔到相邻对象（对照见 `examples/05-sentence-reference.md`）。
-- 本章回顾确认读者获得的能力并说明下一章可使用的状态；句数、句式与承接正文的要求以 `steps/02-structure.md` 为准，不重复页面目录。
-
-页面骨架的块级顺序与引言构成以 `steps/02-structure.md` 为准。篇幅以该文件的 token 预算为准，由 `scripts/verifying-content.py` 强制。
-
-### 收尾
-
-最后说明下一章可以继续使用什么状态。需要领域依据时查 `SKILL.md`，再读对应文件；不在本文件复制知识正文。
-
 ### 六段块序列
 
 ```text
@@ -40,7 +18,7 @@
 **章际衔接（定结构检查项）**：第 N 章的引言、任务节与自测题只用第 1..N-1 章已建立的名字与概念；本章新术语在首次真正使用处就近落术语卡或行内括号；术语卡的升级判据见 `writing-quarto` 技能 `quarto/authoring.md`「Callout 升级判据」，写法见 `steps/03-blocks.md`。某概念接不上前章已建立的名字时，把它下沉回首次使用它的章建立，不在本章临时补课。
 
 - **无标题引言**：第一个 `##` 之前，写成**连贯读者文**回答读者三问——从哪来（承接上一章已成立的结果）、这一章做什么（本章要解决的问题与读者将获得的能力，正面陈述；范围能并则并，不写否定式后章预告）、代码在哪（可选：若本章有主源文件，用**同段末句**自然语言点名并挂全章 blob 链接，不另起「代码写在…里」独立段）。第一句写出谁在什么情况下做本章这件事，类章同时写出类名；类型怎么实现放到后面的句子。不另开背景节。**形态硬限（用户决定）**：首选**恰好 1 个自然段**（通常 2–4 句）；必要时允许 **1 个自然段 + 1 个列表**（列表前引导句写在同一段末，或段落后紧跟列表；列表不算第二散文段）；**禁止**出现两个散文自然段并立，更禁止 ≥3 段、单句孤儿段、结尾导航段。列表仅用于并列范围/对象，任务细节下沉正文 `##`，不用顿号串交付物冒充散文。**摘录免责句永不写进读者正文**：「本章摘录源码服务于讲解」「片段不保证与源文件逐字一致」「不等于文件内顺序」类作者旁白一律删除（旧「示例位置句开口子」已废止），同源保证交给 `verifying-content.py`；摘录免责只保留在 技能的权威文件与检查脚本里。不放 Callout，不写后续章节内容，不用「后面的 X」式前向指称引入后续章节才建立的结构件（如「实现放在后面的编号目录里」）。引言容纳多个独立概念时**并段或改列表**，禁止拆成两个散文段；拆分判据见 `steps/04-paragraphs.md`「拆分判据」。内容量硬限：token 预算见本文件「分层上限」；范围边界能并入承接段时不成列表。承接中引用其他章节一律用章节标题链接，不用「第 N 章」；本章回顾的下一章预告不写链接，直述预告一句（页面导航已有前进按钮），两者均见 `steps/06-wording.md`。任务概览默认并入承接句，正文小节就是任务的展开；预览列表仅当任务没有对应正文小节时使用（示例章四项工作列表已按此删除）。原 front matter `description` 的定位信息并入引言承接句，信息只保留引言一处、不同义两存；章节 qmd 不写 `description`（字段出处见 basics.md）。着陆页 `index` 按 landing 规则组织，不硬套本契约。
-- **任务序列**：每节一个可验证结果。判定标准是任务结束时存在一个读者能自己复述的检查动作；只有「读完了解释」的内容并入相邻任务。概念 → 最小示例 → 操作 → 验证 → 边界，先让读者看到行为再解释规则。各章的任务节以该章标题里的对象为准，不把每一章都写成「目录、设计、构建、测试」四节。设计范围以这一章能在 `src/` 里核对的源文件收束。内容量硬限：任务级 `##` 通常不超过 4 个；`##` 与 `###` 开头的承接句数见本文件「分层上限」，写完直接进入代码、命令或列表；超出即为凑字数信号，禁令见 `steps/04-paragraphs.md`「凑字数禁令」。有 `###` 子节时，二级标题（`##`）的引言须承接上文；恰好 2 个子节时一句点一个，3 个或 4 个时不再逐个点名，点名交给三级标题的句式见本文件「标题分层」，点名用读者已认识的词，不点后文才定义的类型名；一句之内禁止把两个子节对象配成「由 X 定位，并保存 Y」「分别交给」式的两组对应（对照见 `examples/05-sentence-frame.md`「拉链句」）。交付清单或纯边界说明不单独设 `##`，并入引言或相邻工程总览节；同一头文件中连续的值类型优先按一个可验证结果归并到同一任务节。任务节内的讲述顺序按「类型 → 简单函数 → 更难的函数」排列，最难的组装放在最后，并满足先定义后调用：读者要跟着读懂的行内代码标识符，其行为必须已经出现过——上一章、上文，或同一小节里紧挨着的声明和一句行为——上一章已建立的名字视为已知；未定义名字的调用链、节首概览与编号步骤整段删除。`##` 导语只用白话，不点后文才定义的函数名。章内顺序的章内顺序的依据见 `SKILL.md`「九步」的定结构一条，本文件不复述。
+- **任务序列**：每节一个可验证结果。判定标准是任务结束时存在一个读者能自己复述的检查动作；只有「读完了解释」的内容并入相邻任务。概念 → 最小示例 → 操作 → 验证 → 边界，先让读者看到行为再解释规则；单次操作按「做什么 → 执行什么 → 看到什么 → 简短说明」推进。各章的任务节以该章标题里的对象为准，不把每一章都写成「目录、设计、构建、测试」四节。设计范围以这一章能在 `src/` 里核对的源文件收束。内容量硬限：任务级 `##` 通常不超过 4 个；`##` 与 `###` 开头的承接句数见本文件「分层上限」，写完直接进入代码、命令或列表；超出即为凑字数信号，禁令见 `steps/04-paragraphs.md`「凑字数禁令」。有 `###` 子节时，二级标题（`##`）的引言须承接上文；恰好 2 个子节时一句点一个，3 个或 4 个时不再逐个点名，点名交给三级标题的句式见本文件「标题分层」，点名用读者已认识的词，不点后文才定义的类型名；一句之内禁止把两个子节对象配成「由 X 定位，并保存 Y」「分别交给」式的两组对应（对照见 `examples/05-sentence-frame.md`「拉链句」）。交付清单或纯边界说明不单独设 `##`，并入引言或相邻工程总览节；同一头文件中连续的值类型优先按一个可验证结果归并到同一任务节。任务节内的讲述顺序按「类型 → 简单函数 → 更难的函数」排列，最难的组装放在最后，并满足先定义后调用：读者要跟着读懂的行内代码标识符，其行为必须已经出现过——上一章、上文，或同一小节里紧挨着的声明和一句行为——上一章已建立的名字视为已知；未定义名字的调用链、节首概览与编号步骤整段删除。`##` 导语只用白话，不点后文才定义的函数名。章内顺序的依据见 `SKILL.md`「九步」的定结构一条，本文件不复述。
 - **常见错误**：服务失败后回来的读者。每个症状一个 `###`，标题后第一句写触发条件和可观察现象。误用型条目一段成文写原因与正确做法；原因与做法各需一句完整交代时（如原因牵涉私有段的设计动机），用症状句导语加「出错的原因／正确的做法」引导词列表，列表可作为节导语的合法收尾，导语预算只约束症状句；排查型故障展开定位 → 修复 → 验证三步。形态分野与细则是 `writing-quarto` 技能 `quarto/terminal.md`「常见错误条目形态与三步诊断流」。入门章节只保留最可能遇到的 2-3 项，不是完整 FAQ。
 - **自测问题**：服务刚跑通主线、需要确认理解的读者。每章 0-7 道题，题目问本章已经写明的一件可观察结果（会怎样、是哪一个、从几开始），没有这种结果就不设题；只有本章写了原因、而且情景已经说全时，才用「为什么」。题面用本章已经用过的词说全，不用本章未定义的概念，不问「为什么不做成另一种」；题干是合上书的一问，只看本题题干、不看答案与上一题；题干代词的判法见 `steps/05-sentences.md`「代词不能代替未写出的对象」，允许「什么」——它在要一个名字或一句文字，不是指上文没出现的东西；题面里每个细节都要改变答案，答案不受细节影响时不单点某一种情形。题面只描述一个自洽局面，每个事实都要能同时成立，禁止把互相矛盾的局面写成题干（同一句里先说轮到甲方、又说这一步的用户是 O，读者听到的是程序自相矛盾，不是一次非法调用）——「轮到谁」和「这一步的用户」若是同一个对象，只写一次。要考拒绝，用正文已经用过的那条规则问可观察结果（正例：「空状态面板开局，轮到甲方。没轮到的一方来操作时，状态面板会改变吗？」，答案首句「不会。操作的用户不是当前用户，`Place` 返回 `kRejected`，状态面板和轮次都保持原样。」）；不为了出题制造正文没走过的矛盾局面。一道题只问一件可观察结果，不把两个观察捆进同一题（如「状态面板是空的吗」与「轮到谁」并列），拆开或删去一个。固定导语「不要展开答案，试着自己把回答完整说出来，写完之后展开对照；说不出来的部分，回到对应小节对照正文。」；答案写在 `::: {.answer}` 围栏 div 内，由 `scripts/answering-disclosure.lua` 渲染为默认收起的原生 `<details>`；答案只使用本章已讲过的概念。题目同样必须能由本章正文回答：答案依据须是正文已写明的内容，正文没讲的概念不设题；若问题值得问，先在正文补上依据再设题。答案先答所问：首句直接回答题面，一到两句，不补题面之外的对比、延伸或重复题面（对照与归属由正文承载）。问答中的文件、路径与标识符指称统一用行内代码，不挂链接（`verifying-content.py` 对自测节链接记 WARN）；所属目录在答案前文已确立时，路径可省去重复的顶层前缀（如先写 `example/`，后文写 `include/state.h`）。
 - **本章回顾**：服务已经成功的读者。1-2 句段落（不是 bullet 列表）：「你已经能 <能力>」中的能力必须对应本章任务节交出的结果，可复用任务节关键词，不写正文没有的抽象总称（如「按输入、输出和终局」）；「下一章 <预告>」不写链接，直述预告一句（页面导航已有前进按钮），预告不引入下一章才建立的术语。回顾的每个说法都要能在正文找到出处，禁止空泛能力句或只写预告；正文任务节变化时同步改写回顾。
@@ -111,6 +89,10 @@
 - 一律**不加冒号、破折号、括号补充说明**；并列结构可用顿号或逗号连接（如「区分声明、初始化与赋值」）。
 - 不堆「教程」「详解」「学习」「验证：」等泛化或解释性后缀；标题让读者预先知道这一页/节要完成什么，而不是只知道宽泛主题。
 - 标题不用「看懂、读懂、弄清」类口语领会词，也不预设读者的领悟结果；标题写读者要在目录里找的对象，陈述本页交付的内容（用户决定：`看懂一次完整流程` 改 `流程规则`；自动化由 `writing-quarto` 技能 `scripts/verifying-content.py` 词表承担）。
+- 标题不用人称、劝诱和口语动词：不写「自己走一局」「跟我做」「动手试试」这类第一人称或劝诱式；标题只留对象名或「动词 + 具体宾语」（`对局演示`、`启动对局`），不把读者本人写进标题。`scripts/verifying-content.py` 检查人称与标题里的行内代码。
+- 标题不以时间或过程从句起头：不把「输入之后」「看完之后」「下一步」压成 `输入之后的回应` 这类标题；从句还原成对象或短任务（`程序回应`、`查看回应`），时间关系留给导语。
+- 同一章的任务级 `##` 用同一种句式：类章与流程章统一收成「限定语 + 对象」名词短语（`终局判定`、`落子入口`、`棋盘还原`），同章混用「动词 + 宾语」与名词短语判为不合格；动作交给正文。
+- 标题不用视图隐喻和英文类名：`程序全图` 改 `程序结构`，`Ai 落子` 改 `电脑落子`；标题写读者在侧栏里查找的中文对象，类名留给正文与代码。
 - 标题禁元叙述与抽象空心题：不写「本节说明…」「本章规划…」类讲章节安排的标题，也不写读不出动作对象的空心名词短语（「确认依赖方向」类），一律改成「动作 + 对象」或读者已认识的对象。
 - title 留下读者在侧栏里要找的对象：概念、数据、结果用名词；只有这一页的交付就是读者要执行的一个动作时，才用「动词 + 一个宾语」。修饰性定语留给正文，否则「示例项目」「工程」等限定在 title 与二三级标题里连续重复（用户决定：各章 title 收尾为对象名，如流程规则、工程目录、数据存储、一次操作、构建与运行、操作策略、局面快照）。
 - title 不用「并」串联两个动作、不用把字句；两个动作各有任务节承载时择主撰写对象，动作细节留给导语和任务节。
@@ -119,7 +101,7 @@
 - 二级、三级标题用两组词：要么「限定语 + 对象」（数据项坐标、操作后的结果），要么「动词 + 具体宾语」（检查是否三连、放入一枚元素）；同一个二级标题下的三级标题只用其中一种，数字见「标题字数」。指示（这一步、这次）、过程动词（记下、收进、用到）、方式（用数组、先…再…）、把字句与数量词（三种、四个、九个）不进标题，下放到导语或正文。组词是否带限定语由改标题时逐条对照，不新增正则。导语仍按现规则：恰好两个三级时一句点一个，三个或四个时不逐个点名。
 - 三级标题可以保留本章对象的完整名称（如「数据项坐标」），不拆成「行与列」「空格与标记」。
 - 固定收尾节名固定复用，见本文件。
-- 过程节不承载回顾职责：`### 本章实现边界` 一类「本章做到哪、哪章再讲」的标题一律不设，边界话并入 `## 本章回顾`；开篇的目标节只陈述本章可交付产物（如 `确认本章产物`），标题与回顾分工见本文件「页面骨架」。
+- 过程节不承载回顾职责：`### 本章实现边界` 一类「本章做到哪、哪章再讲」的标题一律不设，边界话并入 `## 本章回顾`；开篇的目标节只陈述本章可交付产物（如 `确认本章产物`），标题与回顾分工见本文件「六段块序列」。
 - 英文文件名承担稳定路径职责，多词形态见本文件；中文 title 承担理解职责，两者不必逐字翻译。
 - 例外：part 落地页（`_quarto.yml` 中 part 引用的 index.qmd）title 即 part 名（如「示例项目」），不受 2-6 汉字硬限；副题信息只放落地页引言，章节与落地页 qmd 一律不写 `description`（front matter 出处见 basics.md），后续其他 part 同样处理。
 
@@ -133,7 +115,7 @@
 
 ### 纵向承诺链
 
-写章第 2 步（定结构）逐条对照，不新开第 10 步。检查顺序固定为下面 8 条；每条的要求都是「下一层必须兑现上一层对象」：
+写章第 2 步（定结构）逐条对照，不新开第 10 步。检查顺序固定为下面 9 条；每条的要求都是「下一层必须兑现上一层对象」：
 
 1. part 落地页那一句引言的范围等于该部分全部章的 YAML `title` 集合。根首页卡片不把示例项目收成其中几章。
 2. 章引言里「这一章做什么」那一句的宾语等于 YAML `title` 的对象。引言点名的源文件必须是本章摘录实际来自的文件。
@@ -143,6 +125,7 @@
 6. `##` 下没有 `###` 是允许的，条件是这一节只有一个函数或一个结果。禁止为了「有下级」补出一个孤立 `###`。
 7. 「本章回顾」里「下一章」后面的名字等于 `_quarto.yml` 中下一章的 YAML `title`，不写链接。回顾里的能力用本章 title 的对象。最后一章不写「下一章」。任务节不解释下一章才建立的术语。
 8. 有 `class` 的章的任务节顺序，见本文件「有 class 的章的任务节」。任务章的 `###` 顺序与 `src/run-build.sh` 的步骤顺序一致。目录章里「有几个目录」的句子与该节目录树的项数一致，口径见本文件。
+9. 章题一致：YAML `title` 的对象与本章的主对象相同。把引言第一句、各任务级 `##` 的中心名词、`## 本章回顾` 的能力句并排看；三处指向的对象与 title 不同，说明正文写成了另一章，先改 title 或重排任务节，不写导语把 title 拉回来。标题写 `对局规则`、正文多数节却在讲程序回应的，按章题脱节处理；`输入之后的回应` 这类时间从句标题是同一处的信号。项目技能有章节表时，同轮同步表的 `title` 与 `##` 顺序；表与正文不一致按章题脱节处理。
 
 ### 命名检查
 
@@ -191,7 +174,7 @@
 - `verifying-content.py` 第 3 查按上表逐文件、逐节、逐代码块、逐正文段落核对，超限即整体失败；限额调整只改该脚本的常量与本表，两处必须同步。
 - 根目录 `index.qmd` 与 `content/<game>/index.qmd`（YAML 含 `body-classes: index-page`）是着陆页：短引言与卡片网格不是章节引言，只核对整章总量与代码块限额；着陆页不套用标题与骨架限制，见本文件「六段块序列」。
 - 任务级 `##` 数量、固定收尾不计入、`###` 的使用条件与首章「常见错误」豁免的结构判断，见本文件「六段块序列」；数量口径以上表为准。
-- 结构性规则（引言构成、`###` 数量）同时受 `steps/02-structure.md`「六段块序列」约束；本表提供量化兜底。
+- 结构性规则（引言构成、`###` 数量）同时受本文件「六段块序列」约束；本表提供量化兜底。
 - 接近上限不是目标：预算是上限，内容仍按凑字数禁令与密度规则精简（见 `steps/04-paragraphs.md`「凑字数禁令」）。
 
 ### 页面宽度与垂直节奏

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`「逐条释义代替动机」。
@@ -75,12 +76,18 @@ int main() {
 
 ### 类与多函数摘录的垂直空白
 
-摘录 `class` 或多函数片段时**保留**源码中函数之间的空行，禁止为省行数坍缩成函数注释贴着下一声明；省略部分成员时，被保留的相邻函数之间仍空 1 行；同一 access 段内最后一组数据成员与函数之间空 1 行，数据成员组内不空行（规则与矩阵见 `steps/03-blocks.md`「类与多函数摘录的垂直空白」）。与「逐字摘录」冲突时以源码空白为准：教学缩略可删成员，不可删「函数间距」惯例。
+摘录 `class` 或多函数片段时**保留**源码中函数之间的空行，禁止为省行数坍缩成函数注释贴着下一声明；省略部分成员时，被保留的相邻函数之间仍空 1 行；同一 access 段内最后一组数据成员与函数之间空 1 行，数据成员组内不空行。与「逐字摘录」冲突时以源码空白为准：教学缩略可删成员，不可删「函数间距」惯例。
 
 ### 三级标题最小模块
 
 一个三级标题下面的正文由一到两个最小模块组成。一个模块是一个整体，次序固定：标题已经给出对象；标题下一句导语；有并列取值时跟着列表，一项一个取值、一项一句；代码块、表格或图放在列表和收束段之间；没有列表时放在导语和收束段之间；收束段只写各项共同的契约；Callout 可有可没有，写了就放在收束段之后。短模块可以只有导语和代码块。示例章「操作与成败」里的 `Move` 与 `PlaceResult` 各是一个短模块，下一个短模块用自己的导语接上。第二个模块用来解释前一个时，衔接句就是第二个模块的导语。示例章「数据项坐标」用「下面的图标出这块状态面板上可用的 `(row, col)`。」接上图。讲一个函数时，先一个模块讲 `.h`，再用导语接 `.cpp`。列表写选法，围栏与源文件逐字一致，收束段不把列表再写一遍。禁止「每个状态码对应」，也禁止以 `` `类型::kName`： `` 开头的释义项。正面例子是 示例章「操作的强度」。
 
+### 节末旁注与 Callout 收尾
+
+二级标题的最后一个内容块只承载旁注时，改写成 Callout 收尾，正文不再保留同一句。旁注是读者跳过也能完成本节、回看能少走弯路的补充：可重新生成的产物、版本差异、可选替代、边界条件。本节结论、下一步动作、必经步骤与成功判据留在正文。
+
+收尾 Callout 放在本节最后一块之后、下一个标题之前；每节至多一个收尾 Callout。正文必须脱离前文也能读懂：点名对象，写出前提与结果，不复用上一段的句子；超过两段或需要列举时改用 `###` 小节。正反例见 `examples/03-qmd-elements.md`「节末旁注改为 Callout 收尾」。
+
 ### 执行位置判据
 
 故障定位第一步是确认执行位置和前置状态，给可观察判据而不是模糊要求：Shell 场景用 `pwd` 看路径结尾，工程场景用特征文件（如 `CMakeLists.txt`）存在性判断。
@@ -96,7 +103,7 @@ 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` 与本文件。
 - 一图一事、同主题相邻、图不承载正文未写的新信息：一张图只核对一条已讲清的关系；代码与图主题不同时收束本对象再拆 `###`，禁止「代码 A → 短句拐弯 → 图讲 B → 再贴代码 C」的同节混排（三条边界的写法见 `quarto/authoring.md`「代码与图的桥接」）。
 - 图前段只讲本页可见的对象，且单一主题：描述版式的句子其对象必须同页可见，引用前章画面时复述读者需要的关键事实（如行列取值 0 到 2），不指称前章画面的版式（「画面上方是列号」式会让读者翻回前章）；调用方行为等第二主题移出图前段（示例章定义坐标范围节两段并一段的改稿对照）。
 
@@ -116,7 +123,7 @@ int main() {
 
 ### 盒子密度
 
-盒子指代码块、表格、提示框、引用块、图表容器。密度阈值与权衡的唯一出处见 `steps/03-blocks.md`，本条不重写数字。
+盒子指代码块、表格、提示框、引用块、图表容器。密度阈值与权衡的唯一出处见本文件，本条不重写数字。
 
 ### 标题导语
 
@@ -137,20 +144,20 @@ int main() {
 
 | 边界 | 规则摘要 | 权威 |
 | --- | --- | --- |
-| 标题 → 正文 | 标题下至少一句引导；禁止 `##` 后立刻 `###` 叠标题 | `steps/02-structure.md` 与 `steps/03-blocks.md` |
+| 标题 → 正文 | 标题下至少一句引导；禁止 `##` 后立刻 `###` 叠标题 | `steps/02-structure.md` 与本文件 |
 | 段 → 列表 | lead-in 含主谓、点名列表将展开的维度；完整句可用句号，明确「如下」时用冒号；列表项平行且字数带 | `steps/07-layout.md`「列表选择」 |
-| 段 → 代码 | 一句完整导语（对象标识符 + 谁调用/做什么）→ 围栏；禁块前半句 + 块后补半句；函数或枚举围栏前固定两句：第一句接住上一句的对象，第二句使用紧随围栏里 `///` 第一句的动词和对象，位置写成「定义在 `文件` 里」，不用「声明在」 | `steps/03-blocks.md`「内容块前后的闭环」 |
-| 代码 → 图 | 代码 → 桥接句 → 图 → 图后结论；空行 ≠ 桥接 | `steps/03-blocks.md`「代码与图的桥接」 |
-| 段 → 表 | 关系句引出 → 表 → 表后结论句 | `steps/03-blocks.md`「短表与宽表」 |
-| 任意块 → Callout | Callout 只承载可跳过提示，不复述块内已写信息，不承载唯一成功判据 | `steps/03-blocks.md`「元素边界」 |
+| 段 → 代码 | 一句完整导语（对象标识符 + 谁调用/做什么）→ 围栏；禁块前半句 + 块后补半句；函数或枚举围栏前固定两句：第一句接住上一句的对象，第二句使用紧随围栏里 `///` 第一句的动词和对象，位置写成「定义在 `文件` 里」，不用「声明在」 |本文件「内容块前后的闭环」 |
+| 代码 → 图 | 代码 → 桥接句 → 图 → 图后结论；空行 ≠ 桥接 |本文件「代码与图的桥接」 |
+| 段 → 表 | 关系句引出 → 表 → 表后结论句 |本文件「短表与宽表」 |
+| 任意块 → Callout | Callout 只承载可跳过提示，不复述块内已写信息，不承载唯一成功判据 |本文件「元素边界」 |
 | 节尾 → 下节 | 下节首句接住上节对象；禁正文「下一节/上一节」；章末「下一章」仅在回顾 | `steps/04-paragraphs.md`「段间：过渡句只在话题切换处」、`steps/02-structure.md` |
 | 章际 → 本章 | 第 N 章引言、任务节与自测题只用 1..N-1 章已建立的名字；新术语首次出现处就近落术语卡或行内括号 | `steps/02-structure.md`「六段块序列」 |
 
 ### 豁免与边界
 
-- 块级前后闭环（三级标题最小模块）见 `steps/03-blocks.md`；本文件管段落与小节之间的衔接，不重复块内规则。
+- 块级前后闭环（三级标题最小模块）见本文件；本文件管段落与小节之间的衔接，不重复块内规则。
 - 多命令代码块后的逐条讲解，见 `steps/04-paragraphs.md`「段落规则」。
-- 小节承接正文权重与盒子密度见 `steps/03-blocks.md`。
+- 小节承接正文权重与盒子密度见本文件。
 - 散文冒号豁免清单与表格单元格、协议字面量的豁免见 `steps/04-paragraphs.md`「散文伪标签冒号禁令」；代码注释的冒号句式不属本技能。
 
 ### 机械检查
@@ -188,17 +195,17 @@ int main() {
 
 ### 盒子与正文的比例
 
-盒子按最小模块计：一个模块一块代码、表或图；同一三级标题两个模块时可以有两块，中间必须有衔接句。Callout 不算这块主内容。盒子指代码块、表格、提示框、引用块、图表容器，含 `{mermaid}` 图与 `{python}` 坐标图单元。它们底色与边框一致、左右内缩相同，连续出现时读者分不清内容边界，只能靠滚动位置感知，页面从「读一段做一步」退化成「抄一屏」。因此一条主线动作配一段自己的承接正文，相邻盒子最多一处，其余被正文隔开。每两个盒子之间至少有一段交代判断依据的话；代码块与图之间的固定桥接序列见 `steps/03-blocks.md`。
+盒子按最小模块计：一个模块一块代码、表或图；同一三级标题两个模块时可以有两块，中间必须有衔接句。Callout 不算这块主内容。盒子指代码块、表格、提示框、引用块、图表容器，含 `{mermaid}` 图与 `{python}` 坐标图单元。它们底色与边框一致、左右内缩相同，连续出现时读者分不清内容边界，只能靠滚动位置感知，页面从「读一段做一步」退化成「抄一屏」。因此一条主线动作配一段自己的承接正文，相邻盒子最多一处，其余被正文隔开。每两个盒子之间至少有一段交代判断依据的话；代码块与图之间的固定桥接序列见本文件。
 
 修法是补承接正文，而不是删盒子。盒子承担可复制性，正文承担判断依据，两者不可互换，代码块删到只剩命令不会自动产生判断依据。
 
-代码块前后的文字重量也应服务同一个任务闭环。代码块前至少说明读者要完成什么、在哪里执行以及执行后会发生什么；代码块后只说明下一步、可观察结果或一个必要的新人解释。若提示符、参数含义等补充信息不影响主线执行，可在主线结果确认后放进一个短 Callout；Callout 只解释新信息，承载边界见 `steps/03-blocks.md`「元素边界」。
+代码块前后的文字重量也应服务同一个任务闭环。代码块前至少说明读者要完成什么、在哪里执行以及执行后会发生什么；代码块后只说明下一步、可观察结果或一个必要的新人解释。若提示符、参数含义等补充信息不影响主线执行，可在主线结果确认后放进一个短 Callout；Callout 只解释新信息，承载边界见本文件「元素边界」。
 
 密度比例不设硬阈值。盒子多少、正文长短同时取决于视口宽度、字体度量和 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` 与本文件。
 
 这种分层与页面整体的六段块序列并不冲突：它只收束任务段内部的阅读路径，不重新定义引言、任务序列、排查、自测和回顾的页面职责。
 
@@ -218,7 +225,7 @@ int main() {
 
 ### 情况：图是 Mermaid 或坐标轴图
 
-要画流程图、时序图才打开 `quarto/mermaid.md`，坐标轴网格图打开 `quarto/coords.md`。不排图不打开。
+要画流程图、类图或时序图才打开 `quarto/mermaid.md`（类图先按内容预算删节点和成员），坐标轴网格图打开 `quarto/coords.md`。不排图不打开。
 
 ### 情况：Callout
 
@@ -226,14 +233,18 @@ 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`，表格的说明句在通用情况里。
 
 ## 正反例
 
-通用情况判得准就不打开。判不准时打开同号案例：`examples/03-block-after.md`、`examples/03-excerpt-lead.md`、`examples/03-layout-list.md`、`examples/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

@@ -17,13 +17,21 @@
 - 代码块后的逐条讲解用无序列表：每项格式为「行内代码标识符 + 全角冒号 + 一句职责」（如 `` `enable_testing()`：开启 CTest。``），描述从简，全页标记方式一致；列表前保留一句引言交代工程语境，列表后需要时补一句收束或尾置 Callout。有先后顺序的排查步骤仍用有序列表；块前导语直接点名对象做什么，不用「先…再…最后…」，元计数禁令见 `steps/03-blocks.md`。
 - 删段还是拆段，先按 `steps/05-sentences.md`「一次对话」数这段有几件内容再定删或拆；判定全文见该文件「一次对话」。
 
+### 默认总分与并列槽位
+
+读者正文默认先总后分；段首先给这一段的整体，后面的句子或列表再展开部分。列表前的那一句就是“总”，列表项是“分”。分总只留一种情况：紧挨在前的代码块或图已经把部分摆在读者眼前，下一句只给这些部分一个总名。
+
+并列项的槽位固定，多项也不得对调：前槽写棋盘或对局里读者看得见的东西，后槽写代码里的类型、常量或函数。例如「行列数字写进棋盘格子坐标；每个棋盘格子保存的取值写进棋盘格子类型」。需要点出多个对象时，不先列 `kBoardRows`、`kBoardCols`、`CellPosition` 再补它们共同约定坐标；先说棋盘格子坐标由尺寸和一对行列位置组成，再分别写行数、列数和 `CellPosition`。
+
+依据：中文技术文档写作风格指南的段首主题句、OpenHarmony 文档规范的「主题句置于段首」、金字塔原理的「结论先行、同组同构」；「疑问 / 回答」只用于作者自检，不写进读者正文。
+
 #### 拆段触发表
 
 段落拆分不只按行数硬切，命中下表任一信号即拆段或改形态（列表 / 代码 / 图）：
 
 | 信号 | 动作 |
 | --- | --- |
-| 段内出现第二个互不依赖的对象或主题 | 新起段；新段首句接住上段对象（衔接见 `steps/04-paragraphs.md`「段间：过渡句只在话题切换处」） |
+| 段内出现第二个互不依赖的对象或主题 | 新起段；新段首句接住上段对象（衔接见本文件「段间：过渡句只在话题切换处」） |
 | 段内出现「话题标签：解释」词条式冒号，或两个以上互不依赖的中心并列推进 | 按「拆核四步（多核混段的拆段方法）」判关系：递进同段衔接推进，并列拆段；词条式冒号改完整主谓句（见「散文伪标签冒号禁令」） |
 | 一段同时承担「承接上一章」+「本章交付物清单」+「源文件位置」+「摘录声明」 | 章引言不拆段，形态硬限与摘录声明删除见 `steps/02-structure.md`；其他段落按职责拆段，交付物多项且需扫读 → 列表（目录式堆砌对照见 `examples/02-structure-shape.md`） |
 | 超过约 4 行舒适带、或逼近 7 行 / 篇幅 token 上限 | 先找逻辑边界拆，禁止为凑行数在句中腰斩 |
@@ -33,7 +41,7 @@
 | 一段出现第 4 个互不依赖的主概念 | 拆段或改列表见 `steps/05-sentences.md`「概念负荷」 |
 | 一句多中心、分号串两事、>40 字多动作 | 先拆句，再判是否还需拆段；同档并句不按超长句拆，异档不并进一句，判定见 `steps/05-sentences.md`「同档并句」 |
 
-假拆禁令：不为「段数好看」把同一中心拆成两段同义反复（相邻同义合并见 `steps/04-paragraphs.md`「段间：过渡句只在话题切换处」）；不为对齐列表而去拆段或填第二中心；章引言多中心的形态契约见 `steps/02-structure.md`「六段块序列」。
+假拆禁令：不为「段数好看」把同一中心拆成两段同义反复（相邻同义合并见本文件「段间：过渡句只在话题切换处」）；不为对齐列表而去拆段或填第二中心；章引言多中心的形态契约见 `steps/02-structure.md`「六段块序列」。
 
 ### 罗列短句成段禁令
 
@@ -48,7 +56,7 @@
 
 - 统计性凑句：「文件只有 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`「接口清单压缩段」）。
+- 同义反复：同一事实在承接句、代码块 filename、树内注释、列表项中重复出现时只保留一处。相邻段落同义合并见本文件「段间：过渡句只在话题切换处」。代码围栏的块后复述由 `steps/03-blocks.md`「内容块前后的闭环」管辖（对照见 `examples/03-block-after.md`「块后复述注释」）。同一禁令再延伸到公开接口旁白：禁止「接口清单压缩段」——把私有成员、公开成员名单、`const`、`[[nodiscard]]` 等压进同一段；定稿为场景 → 代码 → 块后只补注释未写的工程信息（对照见 `examples/04-paragraph-opening.md`「接口清单压缩段」）。
 - 判断标准：一句删掉后主线闭环不受影响、且答不出「删掉它读者会做错什么」，默认删除。
 
 ### 拆分判据
@@ -65,7 +73,7 @@
 
 - **引言**：一句点明对象之间的关系（如「配置和构建是两件不同的事」）。
 - **展开**：每个问题一段，或用加粗引导词列表（`**配置**：…` / `**构建**：…`）；两项且能写进一句的仍可保留正文。
-- **收束**：一句写出操作后果或因果（如「改了 CMakeLists.txt 要重跑配置」）。
+- **收束**：一句写出操作后果或因果（如「改了 CMakeLists.txt 要重新运行配置」）。
 - 典型禁例：把「谁做配置、谁做构建、何时重配」压进同一段；改写对照见 `examples/04-paragraph-opening.md`。
 
 ### 段内同义堆叠禁令
@@ -112,11 +120,20 @@
 
 ### 章级：总—分—总
 
-- **总起**：无标题引言的构成见 `steps/02-structure.md`「六段块序列」；引言的宾语等于本章 YAML `title` 的对象（承诺链第 2 条，见 `steps/02-structure.md`「纵向承诺链」）。
+- **总起**：无标题引言的构成见 `steps/02-structure.md`「六段块序列」；引言的宾语等于本章 YAML `title` 的对象（承诺链第 2 条，见 `steps/02-structure.md`「纵向承诺链」）；主语取本章对象或执行动作的一方，见 `steps/05-sentences.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`。
 
+### 章节核心不漂移
+
+章引言和每个 `##` 的首句，主语必须是本章标题的对象。不要用这个对象被谁使用、能推出什么结果来替换它；那些内容属于后文专门的小节。
+
+- 不佳（标题是棋盘，首句却把格子用途列成一段）：棋盘是 3 行 3 列，共九个格子。每次落子先检查坐标；满盘、三连和赢家都从这些格子判断。
+- 改写：棋盘是 3 行 3 列，共九个格子，`Board` 保存这些格子。写入与读出的接口声明在 `board.h`，实现放在 `board.cpp`。
+
+判定信号：首句主语是「格子 / 对局 / 终端」等下游对象，而标题是「棋盘 / 对局 / 程序结构」；把首句主语换成标题对象后句子仍成立，说明原句已经漂移。01 设计章按规则讲范围，不受本条限制。
+
 ### 节内：递进式为默认，并列式处理枚举
 
 - 有先后或因果的内容用递进式展开，顺序依据见 `steps/02-structure.md`「六段块序列」，段落顺序与执行顺序一致。
@@ -128,13 +145,13 @@
 - 需要过渡的位置：段落话题或对象发生切换时（上一段讲 A 命令，下一段讲 B 命令；前一小节配置，本节运行）。同一段内句子推进、或下一段直接继续当前对象时，不加过渡。
 - 段间衔接落在下一段第一句的主语；主语复用上段的宾语或话题，话题切换时仍先接住上文再引出本段。
 - 形式：一句，放在新段段首，先接住上文（点明与上段的关系或结果），再引出本段中心。范例（示例章构建规则节首句）：「可执行目标之外，同一份构建规则还注册了本章唯一的自动化检查」——前半句接住上文的可执行目标，后半句引出新对象。
-- 边界：过渡句服务主线判断，不复述标题结构。含「先看…再看…」的导航复述句整句删除，判法见 `steps/04-paragraphs.md`「凑字数禁令」；`##`/`###` 开头的承接句数见 `steps/02-structure.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`「块后复述注释」「单段混并列对象」）。
+- 目录树后的正文不复述树内行尾注释：树注释已逐文件交代职责，再列一段「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 是两个容易混淆的词：」式元标签开场。
 
@@ -143,7 +160,7 @@
 润色按三个层级推进；高层问题不先定，低层改写会白做：
 
 1. **篇章级**：全篇只保留一条成功路径，章节与小节顺序服务这条路径，无跳脱话题；开头交代读者做什么、完成后得到什么。
-2. **段落级**：段落与段间条文见 `steps/04-paragraphs.md`，衔接见 `steps/04-paragraphs.md`「段间：过渡句只在话题切换处」。
+2. **段落级**：段落与段间条文见本文件「段落规则」与「段间：过渡句只在话题切换处」。
 3. **句子级**：逐句过「七个质量维度」与「句子级病类清单」。
 
 ### 句序与段落形态
@@ -153,7 +170,7 @@
 - **对象先行**：句子按「对象 → 名称 → 约束 → 出处」排；禁「代码把它写成」式把源码当施事的元叙述开场，也禁「因此记作」「写成 `class`」等以源码为主语的句子。对照见 `examples/01-language-scope.md`「元叙述开场与对象先行」。
 - **正常语序**：推荐「主语/对象 + 谓语 + 宾语 +（必要状语）」，本书工程句优先「对象 → 名称 → 约束 → 出处」。改写信号：句首「关于…」抽空主语；「代码把它写成」式元叙述倒装；长定语链把施事压到句末；英文式「被…所…」堆叠；状语（时间/处所）乱插导致主谓隔断。与「对象先行」同向，不另开 kb。
 - **连续纯散文上限**：同一小节连续 ≥3 段纯散文（中间无列表、代码块、图或表）即改「一句中心 + 列表/代码/图」；判定信号：删任一段其余仍成立、段间无承接。
-- **禁小节导航**：正文「下一节／上一节」的禁令与豁免见 `steps/04-paragraphs.md`「段间：过渡句只在话题切换处」。
+- **禁小节导航**：正文「下一节／上一节」的禁令与豁免见本文件「段间：过渡句只在话题切换处」。
 - **换算句版式**：换算的写法见 `steps/07-layout.md`「列表选择」。
 
 六个成分和场景表不在本文件复述，见 `steps/05-sentences.md`。
@@ -168,20 +185,20 @@
 
 一段一个对象、段间衔接、概念负荷的判定依据见本文件「段落规则」；对每个段落依次检查：
 
-- 删掉后影响当前任务吗？删除判据见 `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`「段内同义堆叠禁令」。
+- 段落是否推进了两个互不依赖的并列对象？是就按「拆核四步（多核混段的拆段方法）」处理，判定见本文件「拆核四步（多核混段的拆段方法）」（对照见 `examples/03-block-after.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`「树后换对象收束句」）。
+- 树后或块后补写的新信息主语是否换成另一个对象？删除或下沉见本文件（对照见 `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/05-sentences.md`「过简断裂禁令」，对照见 `examples/05-sentence-brevity.md`「罗列短句成段」、`examples/04-paragraph-opening.md`「接口清单压缩段」。
 
 ## 情况
 

package/skills/writing-quarto/steps/05-sentences.md

@@ -13,7 +13,7 @@
 - **节首句**不得用代词把后文才展开的内容提前捆成一包：节首以「这些／这个／这一步」作话题、同句又没有列出对象名，即失败。「这一章」「下一章」「这一节」指书的单位，是固定说法，不在此禁令内。
 - **已经逐个写出名字之后的回指**仍然合法：如前文小节已写出 `Player`、`Move`、`PlaceResult`、`Result`，后文「这些类型由 `Game` 的四个数据成员使用」保留。
 
-条文与自动检查见 `writing-quarto` 技能 `scripts/verifying-content.py` 的整篇题干/节首检查；步骤挂点：定结构改自测题，定句子改节首与句内代词；对照见 `steps/05-sentences.md`「代词不能代替未写出的对象」。换算句里的「下标」不算已经写出的对象；点名规则见 `steps/07-layout.md`「列表选择」换算条。
+条文与自动检查见 `writing-quarto` 技能 `scripts/verifying-content.py` 的整篇题干/节首检查；步骤挂点：定结构改自测题，定句子改节首与句内代词；对照见本文件「代词不能代替未写出的对象」。换算句里的「下标」不算已经写出的对象；点名规则见 `steps/07-layout.md`「列表选择」换算条。
 
 ### 一次对话
 
@@ -79,6 +79,16 @@
 
 依据：黄伯荣、廖序东《现代汉语》把主谓句分成动词谓语句、形容词谓语句、名词谓语句、主谓谓语句，常用句式另有把字句、被字句、连谓句、兼语句、双宾句、存现句；朱德熙《语法讲义》把主语看成已知话题；陈平把零形回指定义为上文已出现的事物可以不写出那个词。
 
+### 主语选执行者或话题对象
+
+章首引言、节导语与段首句的主语，取本章或本节要交代的对象，或执行动作的一方：程序、井字棋、对局、棋盘、玩家、`Board`。主语不取这些对象产生的下游产物——回应、输入、输出、画面、结果、数据。
+
+- 主语落成产物时，动作的发出者被挤进定语，读者读到句末才知道谁在做事。例如「终端画面里的回应确定一局井字棋要做什么」，主语是「回应」，「确定」的却是程序。
+- 改法：执行者或本章对象先作主语，产物退回宾语。上例改为「程序每一轮都显示当前棋盘，并提示轮到谁落子」。
+- 判定信号：圈出主语，问它会不会自己做这个动作。不会，就是主次颠倒；把主语换成执行者或本章对象。
+- 产物是本节主题时可以作主语，例如快照字段、终端输出的格式；此时不把执行者降格为「由 X 完成」式被动（见 `steps/06-wording.md`「目标语气」）。
+- 依据：Google 开发者文档风格指南与 Microsoft 风格指南都要求尽量用主动语态，让执行动作的一方作主语；朱德熙《语法讲义》把主语看作已知话题，章首的话题是本章对象。改写对照见 `examples/05-sentence-reference.md`「主语不落到下游产物」。
+
 ### 过简断裂禁令
 
 逗号、句号把一句话切开后，下一分句必须满足 **given-new** 之一，否则为过简断裂：
@@ -145,7 +155,7 @@
 
 函数围栏前的概述句，其动词与对象必须与围栏里的函数名和参数一致：围栏里是 `ApplyMove`，概述句就用「应用」和「一步操作」，不改写成同义词（如「落子」）。位置写成「定义在 `文件` 里」，不用「声明在」。源码注释怎么写由项目 C++ 流程负责，本技能只对齐正文与围栏。
 
-散文一句不换对象；判定全文见 `steps/05-sentences.md`。
+散文一句不换对象；判定全文见本文件。
 反例：「已落 X：先手在这一格落下 X。」——右侧换成「先手」和落下动作。
 正例：「先手：使用 X 元素。」
 
@@ -171,7 +181,7 @@
 
 反例：「已落 X：先手在这一格落下 X。」——冒号右侧换成「先手」和落下动作，不再说左侧的格子状态。改写见术语表「数据项类型」的三句；正例三句不在这里贴，见同节。
 
-一句里的对象仍只有一个；六个成分的槽位见 `steps/05-sentences.md`。
+一句里的对象仍只有一个；六个成分的槽位见本文件。
 
 ### 句子级病类清单
 
@@ -184,22 +194,22 @@
 5. **指代不明**：先行词不唯一或不在最近，换专名。
 6. **紧缩并称释义**：把用途压成「一读一写」式并称、或省主语从句（「报告是否下满」），名字与动作的对应要读者自补，改写为显式映射（判定信号见「逐条释义代替动机」）。
 7. **欧化措辞**：「进行／作出＋名词」改回动词；滥「的」滥「被」压缩；名词化主语段内一致时（如「读取直接抛出」的操作名）可留，否则补施事。
-8. **破折号夹心与分号堆叠**：破折号夹解释的句子级判法见 `steps/05-sentences.md`；冒号后用分号续第二个解释即拆（对照见「破折号夹心句」「冒号后堆叠分号解释」）。改冒号时只允许两种合法场合（完整句引出列表/围栏/图；列表项引导词后），散文词条式冒号的判定见 `steps/04-paragraphs.md`「散文伪标签冒号禁令」。
+8. **破折号夹心与分号堆叠**：破折号夹解释的句子级判法见本文件；冒号后用分号续第二个解释即拆（对照见「破折号夹心句」「冒号后堆叠分号解释」）。改冒号时只允许两种合法场合（完整句引出列表/围栏/图；列表项引导词后），散文词条式冒号的判定见 `steps/04-paragraphs.md`「散文伪标签冒号禁令」。
 
 ### 定句子：句子要短
 
-设计说明的分句角色链（事实 → 约束 → 因此选择）见 `steps/05-sentences.md`「句内骨架」；句序与段落形态判定见 `steps/04-paragraphs.md`「句序与段落形态」。
+设计说明的分句角色链（事实 → 约束 → 因此选择）见本文件「句内骨架」；句序与段落形态判定见 `steps/04-paragraphs.md`「句序与段落形态」。
 
-- 先按 `steps/05-sentences.md`「六个成分」给每句分类，再改字；改完回到定段落，核对中心句和一段一对象。
-- 单句长度与拆句的判定见 `steps/05-sentences.md`「句子规则」。
-- 多中心句按中心拆成两句，判定见 `steps/05-sentences.md`「句内骨架」。
-- 拉链句判定口诀与三条改写见 `steps/05-sentences.md`「拉链句」；步骤链、同物两处不按拉链改写，对照见 `examples/05-sentence-frame.md`「拉链句」。
-- 结构助词「的」的去留判定与口诀见 `steps/05-sentences.md`「结构助词「的」」；两个名词粘成一个叫法仍带「的」，或三个以上名词、动词定语省了「的」，就按这条改。
-- 相邻句子的因果、时序关系要写在句面上，判定见 `steps/05-sentences.md`「句内骨架」。
-- 写完数量词和「这些」，对着下一块点名的判定见 `steps/05-sentences.md`「一次对话」，对照见 `examples/05-sentence-reference.md`「定句子：数量词对着下一块点名」。
-- 换算按 `steps/07-layout.md`「列表选择」换算条写成同一段短句；对照见 `examples/03-layout-list.md`「公式与换算讲解段」。
+- 先按本文件「六个成分」给每句分类，再改字；改完回到定段落，核对中心句和一段一对象。
+- 单句长度与拆句的判定见本文件「句子规则」。
+- 多中心句按中心拆成两句，判定见本文件「句内骨架」。
+- 拉链句判定口诀与三条改写见本文件「拉链句」；步骤链、同物两处不按拉链改写，对照见 `examples/05-sentence-frame.md`「拉链句」。
+- 结构助词「的」的去留判定与口诀见本文件「结构助词「的」」；两个名词粘成一个叫法仍带「的」，或三个以上名词、动词定语省了「的」，就按这条改。
+- 相邻句子的因果、时序关系要写在句面上，判定见本文件「句内骨架」。
+- 写完数量词和「这些」，对着下一块点名的判定见本文件「一次对话」，对照见 `examples/05-sentence-reference.md`「定句子：数量词对着下一块点名」。
+- 换算按 `steps/07-layout.md`「列表选择」换算条写成同一段短句；对照见 `examples/07-layout-list.md`「公式与换算讲解段」。
 - 元叙述开场与对象先行的判定见 `steps/04-paragraphs.md`「句序与段落形态」，对照见 `examples/01-language-scope.md`「元叙述开场与对象先行」。
-- 假对比（「这不仅是 X，更是 Y」）、起跑式铺垫（「在开始之前」「首先我们来看」）与句尾意义拔高的判定和删法见 `steps/05-sentences.md`「情况：假对比、起跑式铺垫与意义拔高」，对照见 `examples/05-sentence-frame.md`「假对比、起跑式铺垫与意义拔高」。
+- 假对比（「这不仅是 X，更是 Y」）、起跑式铺垫（「在开始之前」「首先我们来看」）与句尾意义拔高的判定和删法见本文件「情况：假对比、起跑式铺垫与意义拔高」，对照见 `examples/05-sentence-frame.md`「假对比、起跑式铺垫与意义拔高」。
 
 ## 情况
 

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

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