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

package/skills/writing-quarto/examples/02-structure-shape.md

@@ -81,22 +81,36 @@
 
 判定信号：引言一句话里用顿号或「并」串起三个以上交付物；树后段落逐项复述树内行尾注释。清单删掉后读者仍能说出成功判据，清单就该下沉到小节。
 
-## 树注释点名文件与问答式读法句
+## 目录行替子文件说话
 
-示例章改稿前的两个反例：树注释点名下层实现文件，与同棵树的职责注释不同层级；树后读法句用问答式并列把前半句再讲一遍，像写给工具的格式规格，不像给读者的解说（规则见 `steps/03-blocks.md`  与 `steps/01-task.md`）：
+示例章改稿前，目录行把子文件的职责也写进来，读者会以为「打印与读入」是目录本身的任务；目录只说明这里装什么，文件才写职责（规则见 `steps/03-blocks.md`「情况：目录树」）：
 
 ```text
-不佳（树注释列举实现文件名）：
-├── apps/          #/ 终端程序
-│   ├── include/cli.h  # 打印状态面板与读入坐标
-│   └── src/       #/ cli.cpp 与 main.cpp
-
-改写（src/ 写“X 实现”，与规则库一侧的「规则库实现」平行；文件分工留给讲实现的章节）：
-├── apps/          #/ 终端程序
-│   ├── include/cli.h  # 打印状态面板与读入坐标
-│   └── src/       #/ 终端程序实现
+不佳（目录替子文件说话，同棵树的层级也不一致）：
+├── apps/          #/ 终端程序：打印与读入
+│   ├── include/   #/ 终端程序的对外接口
+│   │   └── cli.h  # 终端交互
+├── cmake/         #/ 构建用的 CMake 脚本
+└── tictactoe/     #/ 动态库：棋盘与对局
+    ├── include/   #/ 动态库对外接口
+    └── src/       #/ 动态库实现：随库一起编译
 ```
 
+```text
+改写（目录只写装什么，文件写职责）：
+├── apps/            #/ 终端程序
+│   ├── include/     #/ 终端程序接口
+│   │   └── cli.h     # 终端交互
+├── cmake/           #/ 构建脚本
+└── tictactoe/       #/ 动态库
+    ├── include/     #/ 动态库接口
+    └── src/         #/ 动态库的实现
+```
+
+判定信号：目录注释出现冒号、顿号清单或替子文件写任务（「打印与读入」「棋盘与对局」），就是越界；目录只用名词短语（不超过 16 个显示列），文件注释才承担对象与动作（不超过 28 列、只列 1–2 项）。
+
+## 树后读法句问答式并列
+
 ```text
 不佳（树后读法句问答式并列）：
 目录树在同一行里写出文件位置和职责，文件名回答“文件在哪里”，行尾注释回答“它负责什么”。
@@ -105,7 +119,7 @@
 目录树在同一行里写出文件位置和职责：文件名给出位置，行尾注释说明职责。
 ```
 
-判定信号：同棵树里某行注释是文件名列举而非职责短语；树后句子前半句先概括，后半句再用「X 回答 A，Y 回答 B」拆开重讲。
+判定信号：树后句子前半句先概括，后半句再用「X 回答 A，Y 回答 B」拆开重讲。
 
 ## 树后换对象收束句
 
@@ -183,3 +197,31 @@
 ```
 
 判定信号：引言含「并列部分」「并列区域」等描述文本自身结构的元词，删去后读者仍知道看什么。拦截面见 `writing-quarto` 技能 `scripts/verifying-content.py` 的 FORBIDDEN_PATTERNS。
+
+## 标题口语化与章题脱节
+
+条文见 `steps/02-structure.md`「形式规则」「纵向承诺链」第 9 条。标题先看目录里要扫到的对象：人称、劝诱和时间从句都是导语的事；章题再看正文的主对象，title 承诺 A 而多数任务节在讲 B 时，改 title 或重排结构，不靠导语补丁。示例书首章改稿前后的对照：
+
+```text
+不佳（人称 + 劝诱；时间从句起头）：
+## 自己走一局
+## 输入之后的回应
+
+改写（对象或「动词 + 具体宾语」；时间关系下放导语）：
+## 对局演示
+## 落子规则
+```
+
+```text
+不佳（title 对局规则，正文主对象是程序回应）：
+标题：对局规则
+引言：程序对每一次输入作出回应……
+任务节：输入之后的回应、自己走一局
+
+改写（title 的对象在引言、任务节和回顾三处兑现）：
+标题：对局规则
+引言：井字棋是两名玩家轮流落子的对局……
+任务节：落子规则、胜负判定、对局演示
+```
+
+判定信号：标题带「自己」「跟我」「试试」或「…之后」「…之前」；把 title 与各 `##` 的中心名词并排，多数 `##` 的中心名词不是 title 的对象。

package/skills/writing-quarto/examples/03-block-after.md

@@ -106,3 +106,17 @@ $ORIGIN 表示可执行文件所在目录，查找位置随文件移动。
 不佳：本章配置和运行的对象就是引言中的最小工程目录……代码块标题使用短文件名……避免标题栏被深层路径挤满：
 改写：最小工程目录如下，树内注释标出各文件职责。src/main.cpp 与 CMakeLists.txt 是配置与运行的两个关键文件。
 ```
+
+## 块后复述字面值
+
+围栏已经把常量和字段摆出来，块后再翻译一遍，读者得不到新信息：
+
+```text
+不佳（围栏已写 kBoardRows = 3、kBoardCols = 3、row 与 col；块后逐项复述）：
+棋盘格子坐标由尺寸和一对行列位置组成。这块棋盘有 3 行 3 列，每个位置用一对行列数字定位。代码里，kBoardRows 和 kBoardCols 都取 3，CellPosition 的 row 与 col 保存这对数字。
+
+改写（块前只写坐标约定，块后不翻译围栏）：
+棋盘坐标由行数和列数确定，行向下、列向右，左上角是 (0, 0)。一对行列写成 (row, col)，先写行后写列；行、列的取值都在 0 到 2 之间。尺寸和坐标定义在 board.h 里：
+```
+
+判定信号：块后连续出现围栏内的常量名、字段名或数字，句子只是把 `X = 3` 读成「`X` 取 3」；删掉块后句，读者仍能从围栏和导语得到同一事实。

package/skills/writing-quarto/examples/03-qmd-elements.md

@@ -210,3 +210,19 @@ CTest（CMake 自带的测试运行工具）…　随后跟上术语卡又把同
 ```
 
 判定信号：术语卡的定义句与行内括号逐字同义（升级无收益）；Callout 内出现删掉后读者无法走通主线的必经动作。
+
+## 节末旁注改为 Callout 收尾
+
+不佳（`##` 最后一块是裸句，读者分不清它是结论还是旁注）：
+
+六个目录各管一件事（列表略）。`build/` 里没有源码，删掉或换一个目录后重新配置、编译就会按源码重新生成。
+
+改写（末句独立成 Callout，正文不再保留）：
+
+列表略。
+
+::: {.callout-note title="构建目录不含源码"}
+构建目录 `build/` 里只有生成物，没有源码。整个目录可以删掉，也可以换一个路径；下一次配置和编译会按源码重新生成。
+:::
+
+判定信号：`##` 最后一块是一句可跳过的补充，前面是列表、表格或围栏；Callout 能独立读出对象与条件，且不与正文任何一句逐字相同。末句是本节结论、下一章入口或读者必须照做的步骤时，不升级。

package/skills/writing-quarto/examples/04-paragraph-cases.md

@@ -85,3 +85,17 @@
 ```
 
 判定信号：读者复述不出这段要记住什么；删掉整段后导语与围栏仍闭合；段内另一件内容在后文小节已有专讲。
+
+## 章节核心漂移
+
+标题是棋盘，章首却把格子的用途列成一段，主语从 `Board` 滑到「格子」：
+
+```text
+不佳（标题是棋盘，首句却在数格子能推出哪些判断）：
+棋盘是 3 行 3 列，共九个格子。每次落子先检查坐标；满盘、三连和赢家都从这些格子判断。
+
+改写（首句主语回到 Board 的保存职责，判断留给后文小节）：
+棋盘是 3 行 3 列，共九个格子，Board 保存这些格子，并提供写入与读出的接口。
+```
+
+判定信号：章首或 `##` 首句的主语是下游对象（格子、对局、终端），而不是标题对象；把主语换成标题对象后句子仍成立，说明原句已经漂移。

package/skills/writing-quarto/examples/04-paragraph-opening.md

@@ -44,7 +44,7 @@ Game::GetResult 这三个成员。Game::ReadCellState 与 Game::GetResult 声明
 
 ```text
 不佳（一段压三问）：
-配置由 CMake 完成：读取 CMakeLists.txt，在 build/ 下生成构建计划。构建由 Ninja 完成：按计划把源码编译成可执行文件。所以改了 CMakeLists.txt 要重跑配置，而只改 main.cpp 时重新构建就够了。
+配置由 CMake 完成：读取 CMakeLists.txt，在 build/ 下生成构建计划。构建由 Ninja 完成：按计划把源码编译成可执行文件。所以改了 CMakeLists.txt 要重新运行配置，而只改 main.cpp 时重新构建就够了。
 
 改写（引言 → 引导词列表 → 收束）：
 配置和构建是两件不同的事，由不同工具完成。
@@ -52,7 +52,7 @@ Game::GetResult 这三个成员。Game::ReadCellState 与 Game::GetResult 声明
 - **配置**：由 CMake 完成，读取 CMakeLists.txt，在 build/ 下生成构建计划。
 - **构建**：由 Ninja 完成，按计划把源码编译成可执行文件。
 
-改了 CMakeLists.txt 要重跑配置；只改 main.cpp 时重新构建即可。
+改了 CMakeLists.txt 要重新运行配置；只改 main.cpp 时重新构建即可。
 ```
 
 ## 问答对象错位

package/skills/writing-quarto/examples/05-sentence-frame.md

@@ -41,7 +41,7 @@
 
 ```text
 不佳（「各说一层」把 PlaceResult 与 Result 的分工配进一句，删掉任一配对另一照常成立）：
-操作结果和流程结果各说一层：`PlaceResult` 回答这一次操作写进状态面板没有，`Result` 回答整局流程进行到了哪一步。
+操作结果和流程结果各说一层：`PlaceResult` 表示这一次操作有没有写进状态面板，`Result` 表示整局流程走到哪一步。
 
 改写（两个类型已在前文各配导语和围栏，分工不再复述，直接进入下一块）：
 （整段删除。下一块改为一句桥接：这些类型由 `Game` 的四个数据成员使用，都声明在 `state.h` 的 `private:` 下。）
@@ -107,15 +107,15 @@
 
 ## 定句子：两次说话拆成一次对话
 
-条文见 `steps/05-sentences.md`「一次对话」。总述叠了几件内容：有没有写进状态面板、整局走到哪、它们是两个问题、用两个枚举分开答，下一句又改口「接着看」「第一个枚举」。改写发生在定句子：每件内容一次对话，紧挨自己的围栏。
+条文见 `steps/05-sentences.md`「一次对话」。总述叠了几件内容：有没有写进状态面板、整局走到哪、它们是两个问题、用两个枚举分开表示，下一句又改口「接着看」「第一个枚举」。改写发生在定句子：每件内容一次对话，紧挨自己的围栏。
 
 **定句子（示例章两个枚举的总述）：**
 
 ```text
 不佳（几件内容叠进一次说话，读者要拿开头的问题去猜「第一个」是哪个；「走向」又与开头的「进行到了哪一步」对不上）：
-至于操作有没有写进状态面板、整局进行到了哪一步，是两个不同的问题，`Game` 用两个枚举分开回答。接着看操作可能写入状态面板、也可能被拒绝的处理结果，用第一个枚举 `PlaceResult` 表示：
+至于操作有没有写进状态面板、整局进行到了哪一步，是两个不同的问题，`Game` 用两个枚举分别表示。接着看操作可能写入状态面板、也可能被拒绝的处理结果，用第一个枚举 `PlaceResult` 表示：
 
-第二个枚举回答流程整体的走向，用 `Result` 表示：
+第二个枚举表示流程整体的走向，用 `Result` 表示：
 
 改写（每件内容一次对话，说法从开头保持到围栏，中间不编号）：
 这次操作有没有写进状态面板，用 `PlaceResult` 表示：

package/skills/writing-quarto/examples/05-sentence-reference.md

@@ -129,3 +129,17 @@
 ```
 
 判定信号：处所状语「在……头文件或源文件……里」后 12 字内出现「记住」「保存」或「选出」，判为状语配错谓语；同对象相邻两句被句号切开且异档混排同判。改写时位置句的谓语用「放进」，职责留前一句。
+
+## 主语不落到下游产物
+
+条文见 `steps/05-sentences.md`「主语选执行者或话题对象」。以章首旧稿为对照。
+
+```text
+不佳（「确定」的动作是程序在做，主语却是产物「回应」）：
+终端画面里的回应确定一局井字棋要做什么。
+
+改写（程序作主语，回应退回宾语）：
+程序每一轮都显示当前棋盘，并提示轮到谁落子。
+```
+
+判定信号：主语是「回应」「输入」「输出」「画面」「结果」「数据」，谓语却是「确定」「决定」「完成」这类程序的动作；改写时把执行者提到主语，产物退回宾语。

package/skills/writing-quarto/examples/06-wording-cases.md

@@ -8,6 +8,20 @@
 
 一个概念全书只用一个词，统一术语与替换规则见 `steps/06-wording.md`。对照案例：示例章引言的「实现切片」改「阶段」后统称又停用，最终直接写具体目录路径。
 
+## 游戏与对局
+
+条文见 `steps/06-wording.md`「定用词：术语要稳」。「游戏」指作品或玩法整体，「对局」指具体一场；定义句用「游戏」，规则、落子与结果语境用「对局」，同一页不互换。
+
+```text
+不佳（定义句把作品整体说成一场对局）：
+井字棋是两名玩家轮流落子的对局：先手用 X，后手用 O。
+
+改写（作品用「游戏」，具体一场才用「对局」）：
+井字棋是两名玩家轮流落子的游戏：先手用 X，后手用 O。本章演示一局对局。
+```
+
+判定信号：定义「X 是…」时用「对局」；同一段里「游戏」与「对局」互换指同一对象。
+
 ## 术语标签对照句
 
 「ToFlatIndex 的声明」这种贴标签写法要改成什么：改成直接写位置事实。正文不给代码实体贴「是定义／是声明」标签，也不成对展开两者的区分——那是教 C++ 术语，不推进读者对状态面板工程的理解。位置与实现直接写具体事实（「换算写在 state.cpp」「常量在头文件里给出值」），「定义在 x.h」式位置动词不受限；声明引入名字、定义提供实体的辨析降为编辑与评审的内部口径，见 `steps/06-wording.md`「定用词：术语要稳」。以 示例章用数组存放九个数据项节改稿前为对照：
@@ -72,6 +86,7 @@ state.h 里 `private:` 下的 ToFlatIndex 只写函数名与参数表，函数
 | 错误被返回 | API 返回错误 |
 | 刻意保持最小 / 刻意…… | 直接陈述程序做了什么、不包含什么 |
 | 只可能来自 A，不可能来自 B | 写成可核对的排查范围：工程不含 B → 失败时先查 A |
+| 只保存 / 只把 / 只返回 / 只有（范围断言） | 直接写动作与对象；需要限定范围时写出尺寸、条件、文件名或入口。「只读」「只写」作固定术语保留 |
 | 由 N 段命令定义：A、B 和 C | 直接点名对象：这段规则定义可执行目标 app，规定产物目录、源文件和 C++20。 |
 | 规则库 | 项目动态库（读者正文与代码注释、CMake 注释统一此定名） |
 | 即胜着 / 更好的着 / 随机着法 | 马上能赢的一步 / 对当前用户更有利的一步 / 随机操作 |
@@ -163,3 +178,25 @@ CMakeLists.txt 把编译和测试串起来：先 cmake --build build，再跑 ct
 ```
 
 判定信号：删掉「下面我们来看」「至关重要」「无缝」「赋能」后，读者取走的信息不变；同一动作在一段里换了三个说法；正文出现对读者的招呼或「如有疑问请联系」。
+
+## 无信息提问与自造关系词
+
+正文不向读者发问，也不把关系另造成一个新名词：
+
+```text
+不佳（读者被问一个与当前任务无关的问题）：
+总览图为什么不列成员？
+
+改写（删除；图注已经说明总览的范围）：
+（删除）
+```
+
+```text
+不佳（把组成关系说成「组成边」，再让读者解释它）：
+Game 与 Board 之间的组成边表示什么？
+
+改写（用通行关系词直接陈述）：
+Game 持有一个 Board 作为组成部分。
+```
+
+判定信号：正文句以「为什么 / 为何 / 表示什么」收尾并带问号；出现「×边」式自造关系词；把图的取舍或成员多少写成读者需要回答的问题。

package/skills/writing-quarto/examples/{03-layout-list.md → 07-layout-list.md}

@@ -108,6 +108,20 @@ $$
 
 判定信号：`return` 行之外另排 `$$` 或行内数学模式；换算句没点名载体（「一个下标」「这个下标」「这次代入」互相指代，或导语用「这个下标」而全句未写出是 `cells_` 的数组下标）；一句里同时出现跳过整行、列偏移、代入数字与得数；公式项列表；导语用反引号扛公式本体；代入段里列号与「第 N 列」混用（列号从 0 起算，「第 2 列」会让人从 1 数起）；图已经标出的下标区间在图前再列一遍。「换算只发生在 `Board` 内部」这类局部实现事实本身合法（见 `language-scope.md` 的「流程交流不绑定媒介与行为刚性表述」的判定信号），多处复述或混进图导览段才违规。换算句式规则见 `steps/07-layout.md`「列表选择」换算条。
 
+## 标点分配：连续短句各用句号
+
+条文见 `quarto/prose.md`「标点分配」。五句各用句号，把共享主语的动作、并列成分和位置说明切成电报句；改成一句总说加冒号列举，声明与实现并成一句。
+
+```text
+不佳（五句各用句号，顿号串在分句之间）：
+`Board` 只保存九个棋盘格子。落子、满盘、成线与赢家都从这些格子得出。写入前先检查坐标。声明在工程目录的 board.h。实现放在 board.cpp。
+
+改写（共享主语并成总说，四类结果用冒号列举，声明与实现并成一句）：
+`Board` 从九个棋盘格子得出四类结果：坐标是否越界、棋盘是否已满、是否连成三个、赢家是谁。写入前先检查坐标；接口声明在工程目录的 board.h，实现放在 board.cpp。
+```
+
+判定信号：同一段连续 4 个以上句号，且多数句子短于 15 字；顿号用在分句之间；「声明在…的…」把位置拆成两句。
+
 ## 未定义名字的调用链
 
 以 示例章改稿前为对照。章引言用后文才定义的名字串起一条必须看懂的调用链，读者在第一个分句就遇到三个没讲过的名字（步骤：排列内容块；规则见 `steps/03-blocks.md`「内容块前后的闭环」）：

package/skills/writing-quarto/examples/08-appendix.md

@@ -1,10 +1,10 @@
 # 中文写作的章级定稿对照（附录）
 
-本文件是低频章级对照附录，不进检索索引与评测；仅人审或用户点名时读。规则与通用对照见 `examples/06-wording-cases.md`。
+本文件是第 8 步的低频章级对照附录：信号表判不准，或用户点名时才读；不进检索索引与评测。规则与通用对照见 `examples/06-wording-cases.md`。
 
 ## 操作节删除离题辩白
 
-以 示例章运行一键脚本节为对照。脚本节标题是「怎么跑、看到什么」，嵌在块后的「幂等 / 跳过 / 配置漂移」长论与标题无关，新人缺语境；删除后主线（执行脚本 → 核对输出）仍闭合，「必须重跑配置」已由「修改 CMakeLists 后行为没变」排查节与脚本注释覆盖：
+以 示例章运行一键脚本节为对照。脚本节标题是「怎么跑、看到什么」，嵌在块后的「幂等 / 跳过 / 配置漂移」长论与标题无关，新人缺语境；删除后主线（执行脚本 → 核对输出）仍闭合，「必须重新运行配置」已由「修改 CMakeLists 后行为没变」排查节与脚本注释覆盖：
 
 ```text
 不佳（操作节内的工程取舍长论）：

package/skills/writing-quarto/quarto/authoring.md

@@ -2,13 +2,13 @@
 
 ## 文件关系先于单页润色
 
-多个页面一起修改时，先确定入口、索引和正文的职责。根首页只回答「这是什么、从哪一部分开始」，part 落地页只安排顺序，正文负责一个可完成的任务。前置页面不提前展开后续命令，正文不重复落地页给出的路线。
+多个页面一起修改时，先确定入口、索引和正文的职责。根首页只说明「这是什么、从哪一部分开始」，part 落地页只安排顺序，正文负责一个可完成的任务。前置页面不提前展开后续命令，正文不重复落地页给出的路线。
 
 包含实际源码和构建结构的章节，应在第一次展示源码前加入目录树，展示前核对真实磁盘。目录树细则见 `steps/03-blocks.md`。
 
 ## 页面增长与拆页
 
-教学页达到 `steps/02-structure.md` 的 token 上限（整章 5000 token）后，按读者任务拆页或上调本书阈值，不做「上篇/中篇/下篇」式机械切分。每页只改变一个主要工程变量或回答一个可验证问题。每个新页面都登记到 `_quarto.yml` 与所属 part 的落地页，并拥有独立的代码路径。
+教学页达到 `steps/02-structure.md` 的 token 上限（整章 5000 token）后，按读者任务拆页或上调本书阈值，不做「上篇/中篇/下篇」式机械切分。每页只改变一个主要工程变量或解决一个可验证问题。每个新页面都登记到 `_quarto.yml` 与所属 part 的落地页，并拥有独立的代码路径。
 
 超限先判断内容是否必要：凑字数句删除，必要讲解保留并按读者任务拆页。长代码不得以内联围栏绕过预算；先下沉为项目源码（例如 `src/` 或 `src/`，以项目实际目录为准），再在页面中摘录关键片段。
 
@@ -94,7 +94,7 @@ README 遵循 GitHub Markdown。根目录 `README.md` 是在线阅读链接的
 | 深入机制 | `important` | 读者可跳过但不影响成功 |
 | 严重且不可逆 | `caution` | 数据丢失、需要停手确认 |
 
-带标题的 Callout 使用 `::: {.callout-note title="中文标题"}`，标题由块属性提供，块内不再写 `##` 标题。Callout 放在它所补充的段落或小节内容的最后面，前后各留一个空行；术语卡是唯一就近放置的例外，紧跟术语参与的那段解释之后。必经步骤不进 callout。结果型 Callout 的边界见 `steps/03-blocks.md`。
+带标题的 Callout 使用 `::: {.callout-note title="中文标题"}`，标题由块属性提供，块内不再写 `##` 标题。Callout 放在它所补充的段落或小节内容的最后面，前后各留一个空行；术语卡是唯一就近放置的例外，紧跟术语参与的那段解释之后。必经步骤不进 callout。结果型 Callout 的边界见 `steps/03-blocks.md`。节末旁注的升级与位置见 `steps/03-blocks.md`「节末旁注与 Callout 收尾」；正文与 Callout 不复述同一句。
 
 参数解释默认使用短无序列表。Callout 不承载必经命令或构建命令，也不把唯一成功判据写成脱离正文的脚注。
 
@@ -102,7 +102,7 @@ README 遵循 GitHub Markdown。根目录 `README.md` 是在线阅读链接的
 
 何时升级为 Callout、何时留行内括号，只会遇到两种情形：
 
-- **升级**：说明需要的文字超过一句同位短语，且确有读者会回看的价值——术语卡（业界叫法 + 通过条件，就近放置）或尾置补充（正文与围栏注释之外确有独立价值的一点，如风险、版本差异、可选替代）。
+- **升级**：说明需要的文字超过一句同位短语，且确有读者会回看的价值——术语卡（业界叫法 + 通过条件，就近放置）或尾置补充（正文与围栏注释之外确有独立价值的一点，如风险、版本差异、可选替代）。节末旁注按尾置补充处理，位置与改写要求见 `steps/03-blocks.md`「节末旁注与 Callout 收尾」。
 - **不升级**：一句同位短语能说清的（如「CTest（CMake 自带的测试运行工具）」）一律留行内括号；升级后卡片里没有正文未写的新信息时，删卡片。
 
 Callout 个数见 `steps/02-structure.md`，本段不写数字；`warning` 只进「常见错误」节里对应的环境差异条目。必经步骤与成功判据永不进 Callout。位置与类型选择的细则见 `steps/03-blocks.md`「元素边界」。

package/skills/writing-quarto/quarto/basics.md

@@ -36,9 +36,9 @@ format: html
 ## 常用命令
 
 ```bash
-quarto render 文档.qmd            # 渲染单个文档
-quarto preview 文档.qmd           # 本地预览（实时刷新）
-quarto render                     # 渲染当前项目全部内容
+quarto render 文档.qmd      # 渲染单个文档
+quarto preview 文档.qmd     # 本地预览（实时刷新）
+quarto render               # 渲染当前项目全部内容
 ```
 
 `quarto render` 必须在仓库根目录执行，在其他目录执行会静默不渲染。书里若有 `{python}` 可执行单元，先按项目约定设置 `QUARTO_PYTHON`，再运行 `quarto render`；不要依赖系统 PATH 里的 `python3`（Windows 上可能是 Store 占位符）。
@@ -49,17 +49,17 @@ quarto render                     # 渲染当前项目全部内容
 
 ```text
 book/
-├── _quarto.yml                           # 书配置：chapters、appendices 与输出
-├── index.qmd                             # 根首页：只导航到各 part 落地页
-├── content                               #/ 正文与附录
-│   ├── <part>                            #/ 一个部分
-│   │   ├── index.qmd                     # part 落地页：本部分章节卡片
-│   │   ├── 01-intro.qmd
-│   │   └── 02-topic.qmd
-│   └── appendix                          #/ 附录
-│       └── references.qmd
-├── theme                                 #/ 书内主题副本
-└── filters                               #/ 书内过滤器
+├── _quarto.yml                # 章序与输出配置
+├── index.qmd                  # 首页：导航到各 part
+├── content/                  #/ 正文与附录
+│   ├── <part>/               #/ 一个部分
+│   │   ├── index.qmd          # part 落地页：本部分章节卡片
+│   │   ├── 01-intro.qmd       # 第一章的正文
+│   │   └── 02-topic.qmd       # 第二章的正文
+│   └── appendix/             #/ 附录
+│       └── references.qmd     # 参考文献与术语出处
+├── theme/                    #/ 书内主题副本
+└── filters/                  #/ 书内过滤器
 ```
 
 Quarto Book 的核心配置在书根 `_quarto.yml`：
@@ -78,7 +78,7 @@ book:
       chapters:
         - content/<part>/01-intro.qmd
         - content/<part>/02-topic.qmd
-    - content/<part>/99-bibliography.qmd   # 书目页：#refs 留在 chapters
+    - content/<part>/99-bibliography.qmd     # 书目页：#refs 留在 chapters
   appendices:
     - content/appendix/references.qmd
 ```
@@ -109,7 +109,7 @@ title: "章节标题"
 
 开篇说明写正文普通段落（1-3 句）；章节与 part 落地页不写 `description`，定位信息只保留在开篇说明。
 
-## 第一个小节
+     # # 第一个小节
 正文。
 ```
 
@@ -117,7 +117,7 @@ title: "章节标题"
 - **标题层级**：`##` 表示阅读阶段、范围或一个可验收任务，`###` 表示该阶段中可独立完成或观察的子任务。正文最多到 `###`，禁止 `####` 及更深标题。
 - `###` 只用于源码阅读、验证、可选分支、排错症状等拥有独立动作或观察结果的内容。只有一两句话的解释并入相邻段落，不为目录对称强行拆分。
 - 根首页、part 落地页的卡片标题可以保留 `###`，那是导航组件的视觉层级，不改变正文最多三级的约束。
-- 归并或改名标题前先检索 `@sec-` 与 `#anchor`，避免破坏交叉引用。标题字数与形式的建议值见 `steps/02-structure.md`。
+- 归并或改名标题前先检索 `@sec-` 与 `#anchor`，避免破坏交叉引用。标题字数与形式见 `steps/02-structure.md`「标题分层」与「形式规则」，章题与正文的对齐见同文件「纵向承诺链」第 9 条。
 
 ## 输出结构
 

package/skills/writing-quarto/quarto/mermaid.md

@@ -15,17 +15,53 @@ Quarto 只执行 ` ```{mermaid} ` 属性围栏；plain 的 ` ```mermaid ` 围栏
 每个 `{mermaid}` 块的第一行写：
 
 ```text
-%%{init: {"fontFamily": "LXGW Bright Medium, system-ui, sans-serif"}}%%
+%%{init: {"fontFamily": "LXGW Bright Medium, system-ui, sans-serif", "class": {"hideEmptyMembersBox": true}}}%%
 ```
 
 mermaid 用 init 指令中的字体测量标签宽度，页面 CSS 按 `--ui-font` 渲染文字；两者使用同一字体栈，标签测量与最终渲染一致，避免文字溢出或留白。`mermaid.css` 的排版守卫依赖这一约定。
 
+`class.hideEmptyMembersBox` 只影响类图：没有成员的类只画类名和注解，不画空成员栏。接口、派生类和函数节点都靠它收紧；`verifying-content.py` 要求每个类图块首出现这一项。
+
+## 类图：先定内容预算
+
+正文栏宽随视口变化：默认 1280 宽的 Edge 窗口下约 644 px，1440 宽下约 804 px。类图按自然宽度绘制，预算按最窄的 644 px 定，目标宽度不超过 600 px。把图缩到栏宽会让 15 px 的字降到读不清，横向滚动又会把图切成几段；两种结果都不合格。类图先按下面的预算删内容，再考虑拆图：
+
+| 项 | 上限 | 说明 |
+| --- | --- | --- |
+| 类型节点 | 6 个 | 包括空类、接口、枚举与函数节点 |
+| 成员行合计 | 14 行 | `<<enum>>` 这类注解不计 |
+| 单个类的成员行 | 5 行 | 只留本章连边或正文要用的成员 |
+| 单行成员显示列 | 40 列 | 汉字按 2 列计；参数省略类型名 |
+| 估算宽度 | 600 px | 渲染后按 `svg` 的 `max-width` 核对；超过就删内容或改方向 |
+| 方向 | 有成员用 `TB`，无成员可用 `LR` | 基类在上，派生类在下 |
+
+超预算时先删节点和成员，再按前后半拆图；不缩字号、不缩图、不等横向滚动兜底。
+
+总览图只画类型和边，不列成员：成员会把每个类框撑宽，让关系退到视口外。成员放进分块明细或对应章节，总览只画“谁和谁相连”。
+
+## 类图成员写法
+
+- 成员行用 `+`/`-` 标出可见性，类型写在名字前，参数只保留名字：`+bool CompletesLine(position, cell_type)`；
+- 一行只写一个成员，不把多个方法压进同一行；
+- 只列本章用到的成员；完整声明留在代码块和章节正文里，图内不补空成员，也不在图后写“其余成员见某章”；
+- 空类、接口和派生类只写类名与 `<<interface>>` 一类注解，不补空成员占位；
+- 关系边标签只写动词或名词短语，不写方法签名清单。
+
+## 流程图与类图的方向
+
+- 分层结构用 `TB`；单向推进链节点数 ≥ 5 时默认 `TB` 单列，一屏过高时拆成两张图，禁止长 `LR` 挤爆视口；节点数 ≤ 4 的短链可用 `LR`；
+- 类图有成员时用 `TB`，基类在上、派生类在下；无成员的纯类型关系图才用 `LR`；
+- 单图节点不超过 6 个，一图一事不变，超出优先拆图而不是压缩标签。
+
 ## 节点与边标签写法
 
 - 节点标签一律放在双引号内，例如 `A["标签文字"]`，不依赖裸文本解析；
 - 节点标签只画抽象层名，不把职责明细塞进节点括号；逐项职责用图后列表交代；
 - 标签中不使用全角冒号与直角引号「」承载分隔语义；并列用顿号，补充说明用全角括号；
-- 边标签写在 `-- 文字 -->` 中，保持简短中文；
-- 图表方向以窄屏可读为底线：分层结构用 `TB`；单向推进链节点数 ≥ 5 时默认 `TB` 单列，一屏过高时拆成两张图（如按前后半各一张），禁止长 `LR` 挤爆视口；节点数 ≤ 4 的短链可用 `LR`；
-- 单图节点建议 ≤ 6，一图一事不变，超出优先拆图而不是压缩标签。类图方向用 TB：基类在上，派生类在下。
-- 图后不设 `>` 引用块图注：图注内容并入图后列表的引言句或正文句，图表之后直接跟职责列表，不让图独立承载全部信息。
+- 边标签写在 `-- 文字 -->` 中，保持简短中文。
+
+## 图注
+
+每个 `{mermaid}` 图块在围栏开头、init 之前写一行 `%%| fig-cap: "程序结构总览。实线箭头表示调用或依赖，……"`。`fig-cap` 只写图意和读图约定，不手写“图 1：”这类编号；Quarto 按 `lang: zh` 自动在正文中排成“图 1：”。图注紧跟图块开头、落在图下。线型、箭头方向、读图范围这类说明只写进该图的图注，图后正文不再复述；图后只补图外的新信息或从图带走的结论，不点名被省略的成员，也不写“其余成员见某章”。`fig-cap` 是 Quarto 对 Mermaid 的单元选项语法，`%%|` 必须直接写在围栏开头、init 之前（Quarto 只解析块首选项；写在 init 之后会被当成 Mermaid 注释原样渲染），不能改成 `#|` 或图后引用块。
+
+图注文字概括图意，不与图后正文逐句重复；需要交叉引用时同时写 `label: fig-...`，正文用 `@fig-...` 引用。

package/skills/writing-quarto/quarto/prose.md

@@ -19,6 +19,29 @@
 - 书名号用 `《》`，内层用 `〈〉`。
 - 冒号只用于引出列表、代码、图或结论；词条式冒号按 `steps/04-paragraphs.md`「散文伪标签冒号禁令」改写。
 
+### 标点分配
+
+句号结束一个句子，不用来分隔并列成分。一个自然段通常 3 到 6 句；连续 4 句以上、每句都短于 15 字时，先按下面分工合并，再回读：
+
+| 符号 | 用在 | 不用在 |
+| --- | --- | --- |
+| 顿号 `、` | 并列的词或短语（行、列与对角线） | 分句之间 |
+| 逗号 `，` | 分句之间、状语与主句之间、两项并列 | 三项以上并列词语 |
+| 分号 `；` | 并列分句，且分句内部已有逗号 | 单个短句末尾 |
+| 冒号 `：` | 总说之后引出列举、说明、代码或结论 | 一句之内第二次；伪标签 |
+| 句号 `。` | 句子结束 | 标题、图题、列表项内部 |
+
+- 相邻两句共享主语或动作时并成一句，用逗号或分号连接；主语或动作换了才保留句号。
+- 列举三项以上用顿号；列举项本身含逗号或分句时，各项之间用分号，末项用「和」或句号。
+- 冒号前必须是总说或提示语；冒号后的内容离开前文能读成完整一句。
+- 同一列表的末项标点统一：都用句号，或都不带句号。
+
+反例：`Board` 只保存九个棋盘格子。落子、满盘、成线与赢家都从这些格子得出。写入前先检查坐标。声明在工程目录的 board.h。实现放在 board.cpp。
+
+改写：`Board` 从九个棋盘格子得出四类结果：坐标是否越界、棋盘是否已满、是否连成三个、赢家是谁。写入前先检查坐标；接口声明在工程目录的 board.h，实现放在 board.cpp。
+
+判定信号：同一段连续 4 个以上句号且多数句子短于 15 字；顿号串在分句之间；声明与实现各占一句，只剩位置碎片。
+
 ## 空格
 
 - 中文与拉丁字母、数字之间加一个半角空格：`使用 Quarto 渲染`、`共 9 格`。
@@ -62,9 +85,9 @@
 
 润色要的「灵性」不靠形容词，靠三件事：主语是具体对象，动词是具体动作，读完能看见结果。
 
-- 删掉章节行程，直接给对象和它回答的问题。
+- 删掉章节行程，直接给对象和它产生的结果。
   - 原句：这一章介绍棋盘类的设计，首先看成员，然后看落子，最后看胜负判定。
-  - 改写：棋盘只保存九个格子。落子、满盘、成线与赢家都由它回答。
+  - 改写：棋盘只保存九个格子。落子、满盘、成线与赢家都从这些格子得出。
 - 把「进行校验」「负责计算」换成调用方看得见的动作与返回值。
   - 原句：程序会对输入进行校验，如果坐标不合法就会返回错误。
   - 改写：坐标越界、格子被占用或对局已结束时，`TryPlace` 返回 `kRejected`，棋盘不变。

package/skills/writing-quarto/quarto/terminal.md

@@ -75,7 +75,7 @@
 3. 如何恢复：能否重新生成，或恢复需要哪些前置。
 4. 替代方案：先给出可逆写法，把不可逆写法放在确认新状态正常之后。
 
-`rm -rf` 只有在没有安全替代、且恢复路径明确时才写，并放在 warning callout 或独立段落里，不与成功路径混排。删除 `build/` 属于可重建产物，恢复方式是重跑配置。
+`rm -rf` 只有在没有安全替代、且恢复路径明确时才写，并放在 warning callout 或独立段落里，不与成功路径混排。删除 `build/` 属于可重新生成的产物，恢复方式是重新运行配置。
 
 ## 常见错误条目形态与三步诊断流