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

package/README.en.md

@@ -29,7 +29,7 @@ Both skills are discovered from the package's `skills/` directory and loaded on
 2. Open a session in the book repository. `_quarto.yml` needs a standalone `type: book` line, and the book needs at least one `.qmd` or `.md` chapter source; only then do both skill names appear.
 3. Call a skill: `writing-quarto` for prose, `designing-theme` for the theme.
 
-Replace `--profile` with the profile you actually run. The desktop app always runs the `desktop` profile, and that profile is owned by the app, so `dsh --profile desktop` is rejected; install or upgrade with `dsh plugin --profile desktop add <package>`, and use the app's Settings → Plugins → Add plugin only if the app refuses that write. To pin a version, write `npm:@chengzhao-dev/dsh-quarto-book@0.6.17`; to follow a GitHub tag, write `github:chengzhao-dev/dsh-quarto-book#v0.6.17`.
+Replace `--profile` with the profile you actually run. The desktop app always runs the `desktop` profile, and that profile is owned by the app, so `dsh --profile desktop` is rejected; install or upgrade with `dsh plugin --profile desktop add <package>`, and use the app's Settings → Plugins → Add plugin only if the app refuses that write. To pin a version, write `npm:@chengzhao-dev/dsh-quarto-book@0.6.18`; to follow a GitHub tag, write `github:chengzhao-dev/dsh-quarto-book#v0.6.18`.
 
 Upgrading from the old unscoped package `dsh-quarto-book` (removed from npm with 0.3.4, so this only affects profiles that installed it earlier): remove it from the same profile first with `dsh plugin --profile <profile> remove dsh-quarto-book`, then add the scoped package. Keeping both installed registers `writing-quarto` and `designing-theme` twice at the same rank 550.
 

package/README.md

@@ -29,7 +29,7 @@
 2. 在书仓库里打开会话。`_quarto.yml` 要有独立一行的 `type: book`，书根至少有一个 `.qmd` 或 `.md` 章节源文件；两个技能名这时才会出现。
 3. 调用技能：写正文用 `writing-quarto`，改主题用 `designing-theme`。
 
-`--profile` 换成你实际运行的那个 profile。桌面应用固定跑 `desktop` profile，且该 profile 由应用独占管理，`dsh --profile desktop` 直接启动会被拒绝；安装或升级用 `dsh plugin --profile desktop add <包>`，应用拒绝写入时再走「设置 → 插件 → 添加插件」。需要固定版本时写 `npm:@chengzhao-dev/dsh-quarto-book@0.6.17`，跟 GitHub 标签时写 `github:chengzhao-dev/dsh-quarto-book#v0.6.17`。
+`--profile` 换成你实际运行的那个 profile。桌面应用固定跑 `desktop` profile，且该 profile 由应用独占管理，`dsh --profile desktop` 直接启动会被拒绝；安装或升级用 `dsh plugin --profile desktop add <包>`，应用拒绝写入时再走「设置 → 插件 → 添加插件」。需要固定版本时写 `npm:@chengzhao-dev/dsh-quarto-book@0.6.18`，跟 GitHub 标签时写 `github:chengzhao-dev/dsh-quarto-book#v0.6.18`。
 
 从旧的无作用域包 `dsh-quarto-book` 升级（该包已随 0.3.4 从 npm 删除，只影响之前装过它的 profile）：先在同一个 profile 里 `dsh plugin --profile <profile> remove dsh-quarto-book`，再装新包。两个包同时留着会以相同的 rank 550 各注册一遍 `writing-quarto` 和 `designing-theme`。
 

package/lib/tools/pass-report.js

@@ -247,7 +247,7 @@ const RESULT_SCHEMA = {
 export function registerPassReportTool(tools) {
     tools.register({
         name: 'quarto_pass_report',
-        description: '一次写作或主题润色收尾时调用一次，生成短回执卡；卡片即回执，不在回复里重复。参数是闭集：skill、mode、files（每条带 path 与 edits）、steps（各步 edits 合计等于 files 合计）、held、checks、skip_reason。没改动时传空 files、steps 与 0；不适用时 executed:false、mode:skipped，并写 skip_reason。',
+        description: '把一次写作或主题润色的改动压成一张回执卡，卡片即回执，不写文件。',
         parameters: {
             type: 'object',
             additionalProperties: false,

package/lib/tools/render-check.js

@@ -744,7 +744,7 @@ function refusedResult(warning) {
 export function registerRenderCheckTool(tools) {
     tools.register({
         name: 'quarto_render_check',
-        description: '只在 Quarto Book 项目中使用：检查渲染输出目录，按需运行一次 quarto render，并检查 HTML 可用性。先传 dry_run:true；不安全时最多改一次 output-dir 再查。dry_run:false 只调用一次，成功才返回 html_report。非书项目直接拒绝，不启动渲染。',
+        description: '检查 Quarto Book 的渲染输出目录、最多运行一次 quarto render 并返回 HTML 可用性报告，非书项目直接拒绝。',
         parameters: {
             type: 'object',
             additionalProperties: false,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chengzhao-dev/dsh-quarto-book",
-  "version": "0.6.17",
-  "description": "把一份 Quarto Book 写成可读、可查、可发布的中文技术书：九步章节写作、结构/链接/图表检查、统一主题与渲染验收。 · Write, check, and publish a Chinese Quarto Book: nine-step chapter writing, structure/link/figure checks, a consistent theme, and render acceptance.",
+  "version": "0.6.18",
+  "description": "把一份 Quarto Book 写成可读、可查、可发布的中文技术书：九步章节写作、结构/链接/图表检查、统一主题与渲染验收。",
   "type": "module",
   "main": "./lib/index.js",
   "exports": {

package/skills/designing-theme/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: designing-theme
-description: 维护 Quarto Book 阅读主题：颜色、字体、字号、行距、表格与 Callout 样式、导航；不用于章节正文
+description: 维护 Quarto Book 阅读主题时使用：颜色、字体、字号、行距、表格与 Callout 样式、导航；不用于章节正文。
 metadata:
   short-description: 维护 Quarto 图书主题
 ---

package/skills/writing-quarto/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: writing-quarto
-description: 写作、布局、排版与润色 Quarto Book 章节：任务与结构、内容块与表格、段落与句子、中英混排与术语、改 qmd 代码围栏与块后解说、检查与渲染；不用于改主题样式与只改 .cpp。
+description: 写、改、检查与润色 Quarto Book 章节正文时使用；不用于改主题样式与只改 .cpp。
 metadata:
   short-description: 润色中文 Quarto 图书章节
 ---
@@ -13,21 +13,21 @@ metadata:
 
 - 新建或修改 `content/**/*.qmd` 章节、`index.qmd` 或 `_quarto.yml`；内容与链接核对走本技能 `scripts/` 下的脚本，HTML 是否可用走 `quarto_render_check` 工具。
 - **不适用**：改主题样式、颜色或字体（转 `designing-theme`）；讲解书里项目的业务领域知识（那是项目正文的职责，不是本技能）。
-- 项目带有 `.agents/skills/quarto-book-project/SKILL.md` 时，读完本技能再读它，并只按它指向的 `writing/` 文件读章节对照；没有就跳过，不要凭猜测补书名、章节名和术语。书内 `context/` 下的旧通用副本不再打开，写法以本技能为准。
-- 书仓库根目录的 `README.md` 只走第 5–8 步：它是仓库说明页，不是章节；不套第 1–4 步的任务与结构骨架，不写「常见错误」「自测问题」，不调 `quarto_render_check`。第 8 步发现问题只退回第 5、6、7 步。`README.en.md` 同样处理；`CHANGELOG.md`、`LICENSE`、`AGENTS.md` 不在写作范围。这条只在书仓库里适用（技能本身由 Book 门禁触发）。
+- 项目带有 `.agents/skills/quarto-book-project/SKILL.md` 时，读完本技能再读它，并只按它指向的 `writing/` 文件读章节对照；没有就跳过，不要猜书名、章节名和术语。书内 `context/` 旧副本不再打开，写法以本技能为准。
+- 书仓库根目录的 `README.md` 只走第 5–8 步：它是仓库说明页，不是章节；不套第 1–4 步的任务与结构骨架，不写「常见错误」「自测问题」，不调 `quarto_render_check`。第 8 步发现问题只退回第 5、6、7 步。`README.en.md` 同样处理；`CHANGELOG.md`、`LICENSE`、`AGENTS.md` 不在写作范围。这条只在书仓库里适用。
 
 ## 加载与结束
 
-- 一次激活只做一类文件：章节或主题。写章节时只打开项目技能或 `_quarto.yml` 点名的章节；围栏保持原样，不为逐字核对去读实现文件。
+- 一次激活只做一类文件：章节或主题。写章节时只打开项目技能或 `_quarto.yml` 点名的章节；围栏注释与源文件不一致时回源改围栏，不读无关实现。句子与条文、项目技能或既有正文冲突时，先列冲突位置、原句与出处，由用户选一条；不自行取舍，也不默认采用计划。
 - 项目提供作用域命令就先跑它，只读它列出的文件；渲染产物、构建目录与 Quarto 缓存不读。
-- 增量任务只开本文件、当前一步与这一步点名的一个文件；同轮不把同号案例、其余步骤和条文一起打开。
+- 增量任务只开本文件、当前一步与这一步点名的一个文件；第 8 步可点名 `references/personas.md` 与 `examples/08-appendix.md` 两个，其余步骤仍只一个；同轮不把同号案例、其余步骤和条文一起打开。
 - 同一文件最多退回上一步一次；第二次仍失败就停在检查输出上，不重走整段。
-- 项目技能列出检查命令时只跑那一条；没有就跑本技能 `scripts/` 下的内容与链接检查。退出码为 0 就在同一轮结束 goal，不把没失败的步骤留到下一轮。
+- 项目技能列出检查命令时只跑那一条；没有就跑本技能 `scripts/` 下的内容与链接检查。退出码为 0 就在同一轮结束 goal。
 - 不探测同 profile 的其他插件，也不把它们写成依赖；子会话按自己的 cwd 重新判定门禁，不把技能正文塞进子代理提示。
 
 ## 整书走法
 
-改多章或排目录时，先读 `references/book-journey.md`：先定全书主线与章节次序，再逐章走九步，最后做全书一致性回读。只润色一章时不读它。
+改多章或排目录时，先读 `references/book-journey.md`：先定全书主线与章节次序，再逐章走九步，最后做全书一致性回读。
 
 单章与整书共用同一套九步，不另造一套章节规则；项目有章节表时以项目表为准。技能文件体量受 `references/token-budget.md` 约束，新增整书规则只写进 `book-journey.md`。
 

package/skills/writing-quarto/examples/03-excerpt-lead.md

@@ -174,3 +174,22 @@ constexpr bool IsInRange(Position position) {
 ```
 
 判定信号：章引言（第一个 `##` 之前）出现两个及以上 `.qmd` 链接；除承接上一章的那一个之外，其余都在正文有对应的「首次真正用到」的句子可以迁入。`verifying-content.py` 对引言多余章节链接直接报错。
+
+## 声明注释摘一半
+
+围栏只留概述行，把 `@param`、`@return` 与空 `///` 行删掉。
+
+```text
+不佳（围栏只剩第一行）：
+/// 检查两个坐标是否相同。
+[[nodiscard]] constexpr bool operator==(CellPosition lhs, CellPosition rhs) noexcept {
+
+改写（整段照抄）：
+/// 检查两个坐标是否相同。
+///
+/// @param lhs 左操作数。
+/// @return 相同返回 true。
+[[nodiscard]] constexpr bool operator==(CellPosition lhs, CellPosition rhs) noexcept {
+```
+
+围栏注释是源文件的前缀。条文见 `steps/03-blocks.md`「摘录与源文件注释」。

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

@@ -148,19 +148,10 @@
 
 ## 接口、调用场合与实现细节的次序
 
-以示例章的只读接口节为对照。表格已经列出 `Get`、`IsEmpty`、`IsFull` 的返回与边界，下一段却用「读格子、判空格、判满盘」代替函数名，紧接着又插 `Get` 的实现；读者还没看完三个接口的调用场合，就被带到单个函数的越界细节。
+以示例章的只读接口节为对照。声明围栏里给了 `Get`、`IsEmpty`、`IsFull` 三个查询，接着却把 `Get` 的实现拆到下一个 `###`；读者刚看完三个接口的返回与边界，又被带回越界细节。
 
 ```text
-不佳（函数名被中文动作替代，用法和实现夹在一起）：
-`Get`、`IsEmpty`、`IsFull` 都只读面板。读格子、判空格、判满盘是三件不同的事。
-`Get` 的边界判断与 `std::array::at` 相同，越界时抛 `std::out_of_range`。异常消息先写来源，再写失败条件与实际值。
-`Get` 和 `IsEmpty` 都先检查坐标。调用方按场合选择：
-- 终端逐行调用 `Get`。
-- 测试用 `Get` 核对空格、已有值与越界坐标。
-```
-
-```text
-改写（先三个接口与调用场合，再单列 Get 的越界处理）：
+不佳（声明与实现被小节拆开，标题盖住同类查询）：
 `Get`、`IsEmpty`、`IsFull` 都只读面板，区别在返回什么、越界怎么处理：
 | 接口 | 返回 | 边界 |
 ...
@@ -170,11 +161,24 @@
 - `IsFull` 用来判断是否满盘。
 
 ### Get 的越界处理
-
 `Get` 越界时抛 `std::out_of_range`。相关异常如下：
 ```
 
-判定信号：同一段先用函数名、再用「读格子/判空格」一套中文动作；表格后没有先把三个接口的用法讲完，就插进某一个函数的实现；实现句还带着「与 `std::array::at` 相同」这类比较。处理：函数名作名词，返回、边界、调用场合先成组讲完；单个函数的实现另起小节，只留读者需要知道的异常与必要代码，实现比较和通用异常组织法删掉。
+```text
+改写（Get 的声明与实现同节，另外两个查询单独成节）：
+`IsEmpty` 与 `IsFull` 都只读面板，区别在返回什么、边界怎么处理：
+| 接口 | 返回 | 边界 |
+| `IsEmpty` | 空面板格子为 `true` | 越界或已有棋子时返回 `false` |
+| `IsFull` | 九个格子都有棋子时为 `true` | 不判断谁获胜 |
+调用方按场合选择：
+- 判断单个格子是否为空时调用 `IsEmpty`。
+- `IsFull` 用来判断是否满盘。
+
+### Get 的读取与越界
+`Get` 合法坐标返回格子类型，越界时抛 `std::out_of_range`。声明和实现都放在这一节。
+```
+
+判定信号：同一段先用函数名、再用「读格子/判空格」一套中文动作；声明围栏在一个 `###`、实现却被拆到另一个 `###`；标题用「只读接口」盖住同章其他只读函数。处理：函数名作名词，返回、边界、调用场合按查询分组；一个函数的声明和实现留在同一个 `###`；`###` 点名这一节实际讲解的操作或对象，不用总称；通用异常组织法删掉。
 
 ## GetWinner 的三段删前样本
 

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

@@ -9,6 +9,7 @@
 - `.qmd` 不设文件头声明注释，也不写函数、参数或返回值注释。章节的任务、边界和读者对象由导语与二级标题承担，注释不重复。
 - 正文里不保留被注释掉的旧段落、旧链接或旧围栏。要留历史就交给 Git，不在源文件里堆注释。
 - 代码围栏逐字摘自源文件，围栏里的注释属于源文件；正文不解释这些注释，只补注释没写到的工程关系。
+- 源文件的 `@file`、`@brief` 文件头不进读者正文。
 
 ## YAML
 

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

@@ -34,6 +34,7 @@
 - 相邻两句共享主语或动作时并成一句，用逗号或分号连接；主语或动作换了才保留句号。
 - 列举三项以上用顿号；列举项本身含逗号或分句时，各项之间用分号，末项用「和」或句号。
 - 冒号前必须是总说或提示语；冒号后的内容离开前文能读成完整一句。
+- 前半是一个动作、后半说明这个动作失败时怎样，用全角冒号引出说明，不用分号把说明当成并列分句。
 - 同一列表的末项标点统一：都用句号，或都不带句号。
 
 反例：`Board` 只保存九个棋盘格子。落子、满盘、成线与赢家都从这些格子得出。写入前先检查坐标。声明在工程目录的 board.h。实现放在 board.cpp。

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

@@ -54,6 +54,8 @@
 
 终端画面、构建日志和机器协议分开展示，不把它们混成一个成功判据。终局示例先交代触发场景，再展示真实输出；代码块后的正文只解释读者需要观察的稳定部分。机器协议示例要说明消费对象、稳定字段及其与人类文本的关系，不能用“输出类似如下”代替实际验收依据。
 
+章节里的可交互演示只保留渲染后页面上能操作的 HTML，不嵌终端转录，也不解释当前构建还不会打印；终端的实测输出只写在专门讲终端的那一章。
+
 ## 成功判据三件套
 
 输出不稳定或篇幅过长的命令，不展示完整输出，改给可核对的判据。三条按可得性写，不必凑齐：

package/skills/writing-quarto/references/fence-semantics.md

@@ -7,16 +7,16 @@
 | 素材 | 围栏里是什么 | 正文可以讲什么 |
 | --- | --- | --- |
 | 声明围栏 | `.h` 里的签名、成员、类定义 | 契约：参数、返回值、异常、边界、副作用、与其它接口的分工 |
-| 定义围栏 | `.cpp`（或头文件里的函数体）里的实现 | 机制：用了哪个函数、什么表达式、是否复制、扫描顺序、为什么这样写 |
+| 定义围栏 | `.cpp`（或头文件里的函数体）里的实现 | 机制：用了哪个函数、什么表达式、是否复制、按什么次序 |
 
-判据只有一句：**删掉定义文件，这句话还成立吗？** 成立是契约，不成立是实现。
+判据只有一句：**删掉定义文件，这句话还成立吗？** 成立是契约，不成立是实现。正文不要求比较没采用的写法。
 
 ## 三种合法配对
 
 | 配对 | 围栏 | 正文 | 用在 |
 | --- | --- | --- | --- |
 | 契约型 | 声明 | 契约文字 | 定义平凡：单行 `return`、一跳转发、两行赋值 |
-| 机制型 | 声明 + 定义 | 实现文字 | 定义非平凡，需要讲分支、算法或取舍 |
+| 机制型 | 声明 + 定义 | 实现文字 | 定义非平凡，需要讲分支、算法或步骤 |
 | 纯定义型 | 定义 | 实现文字 | 定义就在头文件（`constexpr`、模板），或声明已在本章前文出现过 |
 
 补充一条**组合转发例外**：同一小节里几个一跳转发的定义可以合并成一个短围栏，正文讲它们如何组合；合并后仍遵守「正文只讲围栏里看得到的代码」。
@@ -32,9 +32,9 @@
 ## 平凡定义的判定
 
 - 平凡：单次比较、单个 `return`、两行赋值、纯委托（`return Other();`）、只做一次边界检查后返回。
-- 不平凡：含循环或分支组合、更新状态、与别的类型协作、需要解释「为什么不用另一种写法」。
+- 不平凡：含循环或分支组合、更新状态、与别的类型协作、需要讲清做了什么、按什么次序。
 
-平凡判例：`IsInRange` 的 `return row >= 0 && row < kRows && col >= 0 && col < kCols;`、`IsFull` 的 `none_of` 一行。
+平凡判例：`IsInRange` 的边界比较、`IsFull` 的 `none_of` 一行。
 
 ## 正反例（棋盘章的真实片段）
 
@@ -71,5 +71,5 @@ GameResult Game::JudgeAfterPlace(const Board& board, Player player) {
 ## 与其它规则的关系
 
 - **代码块门槛**（`steps/03-blocks.md`）：平凡实现不出围栏；本文件给的是「已经决定要讲」时该怎么配围栏。
-- **正文与注释分工**：契约与边界写进 `///`，正文不转述；实现文字只补围栏里没有的上下文（为什么这样组合、和谁配合）。
+- **正文与注释分工**：契约与边界写进 `///`，正文不转述；实现文字只补围栏里没有的上下文（怎么组合、和谁配合）。
 - **检查器**：`scripts/verifying-content.py` 按 `###` 小节扫描，只有 `.h` 围栏而正文出现实现词时报 `decl-without-def`；「常见错误」「自测问题」「本章回顾」与表格行豁免。

package/skills/writing-quarto/references/personas.md

@@ -0,0 +1,15 @@
+# 回读人格
+
+第 8 步回读按章型选一副眼光；规则仍由各步骤与条文负责，这里只指向。
+
+## C++ 文档
+
+本书主专业。围栏与源码一致，不把章节写成语言课，函数声明和实现留在同一个 `###`。块后写表达式做了什么，不写作者动机。细则见 `steps/02-structure.md`、`steps/06-wording.md`、`references/fence-semantics.md`。
+
+## 中文技术写作
+
+一段说完一件事。禁止「意图很直接」「这样写是为了」「不用猜」这类向读者解释作者为什么没选另一种写法的句子。已有禁令以 `steps/06-wording.md` 为准。
+
+## 路由
+
+`03-board`、`04-game`、`05-ai` 用「C++ 文档」，其余章用「中文技术写作」。

package/skills/writing-quarto/scripts/testing-content.py

@@ -122,7 +122,7 @@ title: 入门
 下面是一张只画类型和边的类图，读者可以对照箭头理解类型之间的依赖。
 
 ::: {.class-diagram}
-```{mermaid}
+```{mermaid role="img" aria-label="类型 A 依赖类型 B"}
 %%| fig-cap: "类型 A 依赖类型 B。实线箭头从使用者指向被使用者。"
 %%{init: {"fontFamily": "LXGW Bright Medium, system-ui, sans-serif", "class": {"hideEmptyMembersBox": true}}}%%
 classDiagram
@@ -178,12 +178,17 @@ def main() -> int:
         needle: str,
         project: bool = False,
         checks_json: str | None = None,
+        files: dict[str, str] | None = None,
     ) -> None:
         nonlocal passed_cases
         passed_cases += 1
         with tempfile.TemporaryDirectory() as raw:
             root = Path(raw)
             make_book(root, chapter)
+            for relative, content in (files or {}).items():
+                target = root / relative
+                target.parent.mkdir(parents=True, exist_ok=True)
+                target.write_text(content, encoding="utf-8")
             if project:
                 skill_dir = root / ".agents" / "skills" / "quarto-book-project"
                 skill_dir.mkdir(parents=True)
@@ -293,6 +298,18 @@ def main() -> int:
         "---\ntitle: 入门\n---\n\n## 目标\n\n```mermaid\ngraph LR\n```\n",
         1, "plain mermaid",
     )
+    expect(
+        "mermaid 围栏带前导点",
+        "---\ntitle: 入门\n---\n\n## 目标\n\n"
+        '```{.mermaid role="img" aria-label="流程"}\ngraph LR\n```\n',
+        1, "不会载入图表脚本",
+    )
+    expect(
+        "mermaid 围栏正确写法",
+        "---\ntitle: 入门\n---\n\n## 目标\n\n"
+        '```{mermaid role="img" aria-label="流程"}\ngraph LR\n```\n',
+        0, "OK",
+    )
     expect(
         "未声明围栏",
         "---\ntitle: 入门\n---\n\n## 目标\n\n```\nprint(1)\n```\n",
@@ -316,6 +333,67 @@ def main() -> int:
         0, "OK",
     )
 
+    excerpt_url = "https://github.com/your-org/your-book/blob/main/games/board.h"
+    excerpt_source = (
+        "/// 判断两个坐标是否相同。\n"
+        "///\n"
+        "/// @param lhs 左操作数。\n"
+        "/// @return 相同返回 true。\n"
+        "bool Same(int lhs, int rhs);\n"
+    )
+    excerpt_chapter = VALID_CHAPTER + (
+        f"\n声明见 [board.h]({excerpt_url})。\n\n"
+    )
+    expect(
+        "正文讲解文件头",
+        VALID_CHAPTER + "\n每个源文件开头都有一段 Doxygen 文件头。\n",
+        1, "文件级",
+    )
+    expect(
+        "围栏摘录 @file",
+        excerpt_chapter
+        + "```{.cpp filename=\"board.h\"}\n/// @file board.h\n/// @brief 棋盘。\n```\n",
+        1, "文件级",
+    )
+    expect(
+        "围栏注释截断",
+        excerpt_chapter
+        + "```{.cpp filename=\"board.h\"}\n"
+        "/// 判断两个坐标是否相同。\n"
+        "bool Same(int lhs, int rhs);\n"
+        "```\n",
+        1, "只摘了",
+        files={"games/board.h": excerpt_source},
+    )
+    expect(
+        "围栏注释整段一致",
+        excerpt_chapter
+        + "```{.cpp filename=\"board.h\"}\n"
+        + excerpt_source
+        + "```\n",
+        0, "OK",
+        files={"games/board.h": excerpt_source},
+    )
+    expect(
+        "围栏整段不摘注释",
+        excerpt_chapter
+        + "```{.cpp filename=\"board.h\"}\n"
+        "bool Same(int lhs, int rhs);\n"
+        "```\n",
+        0, "OK",
+        files={"games/board.h": excerpt_source},
+    )
+    expect(
+        "输出围栏不比对注释",
+        VALID_CHAPTER
+        + "\n```text filename=\"运行效果\"\n"
+        "/// 判断两个坐标是否相同。\n"
+        "bool Same(int lhs, int rhs);\n"
+        "```\n",
+        0, "OK",
+        files={"games/board.h": excerpt_source},
+    )
+
     expect("目录树合格", TREE_CHAPTER, 0, "OK")
     expect("原生 SVG 缺图注", HTML_FIGURE_BAD, 1, "figcaption")
     expect("原生 SVG 图注合格", HTML_FIGURE_GOOD, 0, "OK")
@@ -379,7 +457,10 @@ def main() -> int:
     expect("类图图注写在 init 之后", wrong_order, 1, "init 之前")
     expect(
         "类图缺少页面容器",
-        MERMAID_CHAPTER.replace("::: {.class-diagram}\n```{mermaid}", "```{mermaid}").replace(
+        MERMAID_CHAPTER.replace(
+            '::: {.class-diagram}\n```{mermaid role="img" aria-label="类型 A 依赖类型 B"}',
+            '```{mermaid role="img" aria-label="类型 A 依赖类型 B"}',
+        ).replace(
             "```\n:::", "```"
         ),
         1, ".class-diagram",

package/skills/writing-quarto/scripts/verifying-content.py

@@ -78,6 +78,12 @@ TEST_RE = re.compile(r"测试|断言|用例|gtest|CTest")
 # 围栏与正文的配对：声明围栏只配契约文字。正文出现实现词而小节里没有定义围栏时
 # 报 decl-without-def，规则与正反例见 references/fence-semantics.md。
 FENCE_FILENAME_RE = re.compile(r'filename="([^"]+)"')
+# 读者正文不摘文件级 Doxygen 头；成员注释的 @param、@return 不受这条限制。
+EXCERPT_HEADER_RE = re.compile(r"@file\b|@brief\b|Doxygen\s*文件头")
+REF_DEFINITION_RE = re.compile(r"^\s*\[([^\]]+)\]:\s*(\S+)\s*$")
+REF_USE_RE = re.compile(r"\]\[([^\]]+)\]")
+BLOB_URL_RE = re.compile(r"^https://github\.com/[^/]+/[^/]+/blob/[^/]+/(.+)$")
+DOC_COMMENT_RE = re.compile(r"^\s*///")
 IMPL_MARKER_RE = re.compile(r"复用|委托给|扫描|遍历|对每个|短路|表达式|状态位|缓存|不再单独|递归")
 FENCE_SKIP_SECTION_RE = re.compile(r"常见错误|自测|回顾|练习|小结")
 DECL_SUFFIXES = (".h", ".hpp", ".hh", ".hxx")
@@ -653,6 +659,159 @@ def check_fence_semantics(path: Path, lines: list[str]) -> list[Issue]:
     return issues
 
 
+def normalize_code(text: str) -> str:
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def collect_excerpt_links(lines: list[str]) -> list[tuple[int, str]]:
+    """Return GitHub blob links in reading order, including reference-style uses."""
+    definitions: dict[str, str] = {}
+    for raw in lines:
+        definition = REF_DEFINITION_RE.match(raw)
+        if definition:
+            definitions.setdefault(definition.group(1), definition.group(2))
+    links: list[tuple[int, str]] = []
+    for number, raw in enumerate(lines, start=1):
+        for match in LINK_RE.finditer(raw):
+            links.append((number, match.group(1).strip()))
+        for match in REF_USE_RE.finditer(raw):
+            target = definitions.get(match.group(1))
+            if target:
+                links.append((number, target))
+    links.sort()
+    return links
+
+
+def excerpt_fence_blocks(lines: list[str]) -> list[tuple[int, str, list[tuple[int, str]]]]:
+    """Return (opening line, filename, body) for every fence with a filename."""
+    blocks: list[tuple[int, str, list[tuple[int, str]]]] = []
+    in_fence = False
+    start = 0
+    filename = ""
+    body: list[tuple[int, str]] = []
+    for number, raw in enumerate(lines, start=1):
+        fence = FENCE_RE.match(raw)
+        if fence:
+            if not in_fence:
+                in_fence = True
+                start = number
+                opening = FENCE_FILENAME_RE.search(raw)
+                filename = opening.group(1) if opening else ""
+                body = []
+            else:
+                in_fence = False
+                if filename:
+                    blocks.append((start, filename, body))
+                filename = ""
+                body = []
+            continue
+        if in_fence:
+            body.append((number, raw))
+    return blocks
+
+
+def source_doc_above(source: list[str], index: int) -> list[str]:
+    """Collect the contiguous `///` block that sits directly above index."""
+    block: list[str] = []
+    cursor = index - 1
+    while cursor >= 0:
+        raw = source[cursor]
+        if not DOC_COMMENT_RE.match(raw) or raw.lstrip().startswith("///<"):
+            break
+        block.append(raw)
+        cursor -= 1
+    block.reverse()
+    return block
+
+
+def check_excerpts(path: Path, root: Path, lines: list[str]) -> list[Issue]:
+    """Reader text carries no file headers; kept doc comments match the source."""
+    issues: list[Issue] = []
+    for number, raw in enumerate(lines, start=1):
+        if EXCERPT_HEADER_RE.search(raw):
+            issues.append(Issue(
+                path, number,
+                "读者正文不摘文件级 Doxygen 头（@file、@brief、文件范围段）；"
+                "删掉这段，围栏从它之后开始",
+            ))
+
+    links = collect_excerpt_links(lines)
+    for start, filename, body in excerpt_fence_blocks(lines):
+        candidates = [
+            (number, target)
+            for number, target in links
+            if number < start and target.rsplit("/", 1)[-1] == filename
+        ]
+        if not candidates:
+            continue
+        target = candidates[-1][1]
+        blob = BLOB_URL_RE.match(target)
+        if not blob:
+            continue
+        relative = blob.group(1)
+        source_path = (root / relative).resolve()
+        if root not in source_path.parents or not source_path.is_file():
+            continue
+        source = read_text(source_path).splitlines()
+
+        pending: list[tuple[int, str]] = []
+        pending_start = start
+        for number, raw in body:
+            stripped = raw.strip()
+            if DOC_COMMENT_RE.match(raw) and not stripped.startswith("///<"):
+                if not pending:
+                    pending_start = number
+                pending.append((number, raw))
+                continue
+            if not pending:
+                continue
+            if not stripped:
+                pending = []
+                continue
+            declaration = normalize_code(raw)
+            fence_block = [item.strip() for _, item in pending]
+            pending = []
+            if not declaration or declaration.startswith(("#", "}", "{", "...")):
+                continue
+            matches = [
+                index for index, item in enumerate(source)
+                if normalize_code(item) == declaration
+            ]
+            if not matches:
+                continue
+            # 同一行声明可能在多个类里重复（如各实现类的 override）；任一处注释
+            # 与围栏整段一致即通过，避免把第一个同名声明当成唯一出处。
+            source_blocks = [
+                [item.strip() for item in source_doc_above(source, index)]
+                for index in matches
+            ]
+            if any(block == fence_block for block in source_blocks):
+                continue
+            if not fence_block:
+                continue
+            prefixes = [
+                block for block in source_blocks
+                if len(block) > len(fence_block) and block[: len(fence_block)] == fence_block
+            ]
+            if prefixes:
+                issues.append(Issue(
+                    path, pending_start,
+                    f"围栏只摘了 {filename} 注释的前 {len(fence_block)} 行；"
+                    "整段补上 @param、@return 与空 /// 行，或整段不摘",
+                ))
+            elif all(not block for block in source_blocks):
+                issues.append(Issue(
+                    path, pending_start,
+                    f"围栏带有注释，但 {filename} 对应声明上方没有 /// 注释；整段删掉",
+                ))
+            else:
+                issues.append(Issue(
+                    path, pending_start,
+                    f"围栏注释与 {filename} 对应声明上方的不一致；整段照抄或整段不摘",
+                ))
+    return issues
+
+
 def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> list[Issue]:
     issues: list[Issue] = []
     text = read_text(path)
@@ -712,7 +871,12 @@ def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> li
                 elif fence_lang.startswith("{"):
                     inner = fence_lang.strip("{}").strip()
                     fence_is_html = inner == "=html"
-                    if inner and not inner.startswith((".", "=")) and "mermaid" not in inner:
+                    if inner.startswith(".") and "mermaid" in inner:
+                        issues.append(Issue(
+                            path, number,
+                            "Mermaid 围栏写成 `{.mermaid}`，Quarto 不会载入图表脚本，图会退化成代码块；改成 `{mermaid ...}`",
+                        ))
+                    elif inner and not inner.startswith((".", "=")) and "mermaid" not in inner:
                         # ```{python} style attribute fences are valid.
                         pass
             else:
@@ -780,6 +944,7 @@ def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> li
         issues.append(Issue(path, fence_start, "代码围栏未闭合"))
 
     issues.extend(check_fence_semantics(path, lines))
+    issues.extend(check_excerpts(path, root, lines))
 
     for block in fence_blocks:
         issues.extend(check_tree_block(path, block))

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

@@ -37,14 +37,14 @@
 
 链接预算：引言只挂承接上一章的那 1 个章节链接和本章主源文件的 blob 链接；其余章节链接下沉到正文真正用到它的句子。同一段不堆多个章节链接——每个链接都是读者离开当前页的一次机会。
 
-摘录免责句（「本章摘录源码服务于讲解」「片段不保证与源码逐字一致」）不写进读者正文，同源保证交给 `verifying-content.py`。
+摘录免责句不写进读者正文，同源保证交给 `verifying-content.py`。
 
 ### 任务序列
 
 - 每节一个可验证结果：任务结束时存在读者能自己复述的检查动作；只有「读完了解释」的内容并入相邻任务。
 - 节内顺序：概念 → 最小示例 → 操作 → 验证 → 边界；先让读者看到行为，再解释规则。单次操作按「做什么 → 执行什么 → 看到什么 → 简短说明」推进。
 - 任务节以该章标题里的对象为准，不把每章都写成「目录、设计、构建、测试」。
-- 交付清单或纯边界说明不单独设 `##`，并入引言或相邻总览节；同一头文件中连续的值类型优先并成一个可验证结果。
+- 交付清单或边界说明不单独设 `##`，并入引言或相邻总览；连续值类型并成一个结果。
 - 任务节内按「类型 → 简单函数 → 更难的函数」排列，最难的组装放在最后，满足先定义后调用：读者要读懂的行内标识符，其行为必须已在上文或紧邻声明中出现；未定义名字的调用链、节首概览与编号步骤整段删除。
 - `##` 导语只用白话，不点后文才定义的函数名；有 `###` 时导语承接上文。
 
@@ -53,7 +53,7 @@
 有 `class` 定义的章，任务级 `##` 按下面次序排；没有下一种内容就停，不为凑数加节：
 
 1. 类型：本章用到的值类型（枚举与结构体），一节一个可验证结果，可下分三级标题。
-2. 成员变量：单独一节；读取成员的函数用三级标题。只判断下标区间的检查也用三级标题放在这一节，不单独占二级标题。类说明、构造函数与数据成员拼进同一个围栏，不拆成两个围栏。
+2. 成员变量：单独一节；读取成员的函数用三级标题。只判断下标区间的检查也用三级标题放在这一节，不单独占二级标题。类说明、构造函数与数据成员拼进同一个围栏。每个函数的声明和实现留在同一个 `###`；标题点名本节对象，不用「只读接口」这类总称。
 3. 最重要的函数：这个类最重要的一个函数及配套函数。
 4. 其余重要函数：还有一组就再加一节，没有就停。
 
@@ -217,6 +217,7 @@ YAML `title` 2–6 个汉字；`##` 与 `###` 2–10 个汉字，「常见错误
 - 类章按「类型 → 成员变量 → 最重要函数 → 其余函数」排任务节；没有 `class` 的章按「类型 → 使用这些类型的函数」排。
 - 只有一项交付、没有可独立复现失败症状的工程章，可省「常见错误」，其余固定收尾保留。
 - 着陆页与根首页不套六段骨架，只核对整章预算、标题层级与卡片承诺。
+- 已有的 `.feature-grid` 内 `.landing-card` 不得删除，也不得改成普通列表；卡片数量和链接与项目章节表一致，缺了按章节表补回。
 - 全章重构或跨章搬迁时，先按「章节骨架」定删留，再进入标题与句子步骤。
 
 ## 正反例

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

@@ -15,7 +15,7 @@
 
 同一 `##`/`###` 内 ≥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`）。对照见 `examples/03-excerpt-lead.md`「多代码块一句导语」。
 
 以代码块为中段，导语讲工程语境（这段代码为什么存在、为什么此刻看它）；若有块后句，只讲注释没覆盖的新工程关系。语法细节不逐行展开。导语与块后都禁止关键字释义当开场：不写「X 是 `inline constexpr` 常量」「用 `enum class` 表达」「用有符号整型承载」「坐标字段为什么选定宽有符号」式语言课或选型旁白（除 01 设计章外工程 qmd 禁选型外链），改写对照见 `examples/01-language-scope.md`「语言课旁白与工程旁白」。
 
@@ -52,18 +52,24 @@ 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` 判失败）。悬空的裸链接行既不像正文也不像说明，读者扫读时只剩一个锚点。
-- **本章主源文件可重复挂链接，其他仓库路径每章至多一条**：章引言用可跳转链接（内联 `[]()` 或同页引用式 `[label][id]`）挂本章主源文件（如 `board.h`、`board.cpp`），正文再点名这些文件时复用同一 GitHub 链接，读者不用回翻章首。不在章引言挂链接的其他仓库文件，正文用行内代码，不包链接；跨章指称用章节标题链接。同一章摘录另一阶段目录的同名文件时，在切换处再挂一条不同 URL（对照见 `examples/03-excerpt-lead.md`「摘录链接密度」；`verifying-content.py` 只对非章引言主源文件的同章重复 URL 判失败）。本条挂在写作步骤的定版式。
-- 片段内注释硬限：每处实现注释（`//` 或 `#`）不超过 3 行（与源文件注释规范的 1–3 行同一口径）、单行不超过 100 列（与源文件 `ColumnLimit: 100` 同一口径；正文散文的 40 字限不套到代码注释），只写这段代码做什么；CMake/Shell 等命令型片段每条命令保留一行意图注释。Doxygen `///` 声明块（概述、空 `///` 与细节）是声明骨架的一部分，摘录随源保留，不受此限。命名惯例、官方建议、未来演化等规范说理一律不进代码块；术语卡和可跳过的操作提醒可以进 callout，注释怎么写、行尾先写什么、`///` 与 `@` 标签怎么分工只留在 `.agents`，面向作者的进知识文件。
-- 首讲某段源码的章节不省略源码既有的职责注释：注释是读者读到的第一层讲解；「注释与空行可以省略」只服务后续章节复现已见代码。源码缺注释时交给项目 C++ 流程补齐，本技能不替源码补注释。
+- **本章主源文件可重复挂链接，其他仓库路径每章至多一条**：章引言用可跳转链接（内联 `[]()` 或同页引用式 `[label][id]`）挂本章主源文件（如 `board.h`、`board.cpp`），正文再点名这些文件时复用同一 GitHub 链接，读者不用回翻章首。不在章引言挂链接的其他仓库文件，正文用行内代码，不包链接；跨章指称用章节标题链接。同一章摘录另一阶段目录的同名文件时，在切换处再挂一条不同 URL（`verifying-content.py` 只对非章引言主源文件的同章重复 URL 判失败）。
+- 片段内注释硬限：每处实现注释（`//` 或 `#`）不超过 3 行（与源文件注释规范的 1–3 行同一口径）、单行不超过 100 列（与源文件 `ColumnLimit: 100` 同一口径；正文散文的 40 字限不套到代码注释），只写这段代码做什么；CMake/Shell 等命令型片段每条命令保留一行意图注释。Doxygen `///` 声明块随源保留，不受此限。命名惯例、官方建议等说理不进代码块；术语卡与操作提醒可以进 callout。注释写法与 `///`、`@` 标签分工只留在 `.agents`，面向作者的进知识文件。
+- 首讲某段源码的章节不省略源码既有的职责注释：注释是读者读到的第一层讲解；「整段省略」只服务后续章节复现已见代码。源码缺注释交给项目 C++ 流程。
 - 讲解段只解释片段中实际出现的代码；片段没有展示的内容要么补进片段、要么进 callout，不在正文列表里讲代码外面的东西。
 - include 短代码降级为可选手段：仅用于确实需要完整展示且很短的文件，并仍须包在带语言标注的围栏代码块内（包裹规则见 `quarto/render.md`）。
 - 手动命令块标注执行位置，如 `filename="WSL Ubuntu（仓库根目录）"`。
 - 输出效果类代码块（运行效果、预期输出）filename 只写场景名（如「运行效果」）；终端样式、颜色等展示细节写进正文，不进 filename。输出摘录用单独一行 `...` 表示省略的工具输出，与源码片段的省略是两回事。
 
+### 摘录与源文件注释
+
+- 读者正文不摘文件级 Doxygen 头：`/// @file`、`/// @brief` 与文件范围段都不进正文，围栏从其后开始。
+- 围栏保留的声明带 `///` 注释时，整段必须与源文件该声明上方一致，`@param`、`@return` 与空 `///` 行一并保留；整段不摘可以，只摘概述行不行。
+- 润色或回读发现围栏与源文件不一致，打开该源文件把围栏改一致；只读对应声明。
+
 ### 代码块门槛
 
 不是每段代码都值得出围栏。**值得出围栏**：类型布局（常量、枚举、结构体、类的声明）、多步或非显然的控制流、需要与图核对的公式实现，且块前有工程动机导语。

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

@@ -20,6 +20,10 @@
 
 自测固定导语“试着自己把回答完整说出来”中的“回答”指读者自己的答复，允许保留；技能步骤里的“读者要能说出什么”是自检说明，不要求改写成读者句。其余示例必须给读者能直接读到的句子，不写“读者要能说出……”。
 
+### 读者正文不解释作者的选择
+
+读者正文不写作者为什么没选另一种写法。「意图很直接」「这样写是为了」「不用猜」都属这类句子。块后只写表达式做了什么、按什么次序。
+
 ### 绝对范围词要少用
 
 读者正文默认不写「只 / 仅 / 唯一 / 一律 / 永远 / 一定 / 必然 / 全部 / 完全」这类把范围一次说死的词。删掉后句义不变就删；需要限定范围时，写出范围本身：尺寸、条件、文件名或入口。
@@ -112,26 +116,24 @@
 
 每个维度给可操作判定信号，命中即改写：
 
-1. **中心明确**：判定见 `steps/04-paragraphs.md`「段落规则」（对照见 `examples/03-block-after.md`「单段混并列对象」）。
+1. **中心明确**：判定见 `steps/04-paragraphs.md`「段落规则」。
 2. **简洁**：把候选词句删掉，信息不变即删——无信息修饰（「非常」「其实」「完全」「简单来说」）、同义反复、重复交代的同一事实。
 3. **连贯**：段间衔接的判法见 `steps/04-paragraphs.md`「段间：过渡句只在话题切换处」；句序违背时序或因果即调整；连接词表达的关系与上下文不符即改。句间衔接遵守 given-new 与设计句骨架，判定见 `steps/05-sentences.md`。
 4. **可读性**：单句 20/40 字与拆句见 `steps/05-sentences.md`「句子规则」；复合句拆成简单句或并列句；三项以上并列写成列表，不写伪连贯长句；换算豁免见 `steps/07-layout.md`「列表选择」。同档并句的长度见 `steps/05-sentences.md`「同档并句」。
 5. **不拗口**：命中即重写——三重定语链；一句里连续三个「的」；名词化堆叠（「进行 X 的实现」「对 X 作出更新」）；双介词嵌套（「在…中通过…对…」）。
 6. **指代明确**：「这 N 个」「它们」「其」的先行词必须唯一且紧邻；承前省略的判法见 `steps/05-sentences.md`「六个成分」。
-7. **不冗余**：同一事实只讲一次与固定表述豁免的判定见 `steps/04-paragraphs.md`「段内同义堆叠禁令」（对照见 `examples/04-paragraph-cases.md`「相邻段落同义合并」）；同一对象同页统一称呼。
+7. **不冗余**：同一事实只讲一次与固定表述豁免的判定见 `steps/04-paragraphs.md`「段内同义堆叠禁令」；同一对象同页统一称呼。
 
 ### 定用词：术语要稳
 
 - 动词选用与主动语态见「目标语气」；「由 X 完成」在这一步改成主动句，改完露出第二个核就退回定段落。
-- 「同一概念只使用一个称呼」的判定见「七个质量维度」；英文标识保持大小写。
+- 英文标识保持大小写。
 - 「游戏」指作品或玩法整体，「对局」指具体一场：定义「井字棋是…游戏」用「游戏」，规则、落子与结果语境用「对局」；同一页不把两者当同义词换用（对照见 `examples/06-wording-cases.md`「游戏与对局」）。
-- 项目名在同一页首次写全（如「井字棋棋盘」），后文改用对象名（「棋盘」「动态库」「对局」）；不逐段重复项目名，也不在同一页反复解释已经说过的事。
-- 无信息修饰的删除判定见「七个质量维度」；禁用词以 `scripts/verifying-content.py` 词表为准。
-- 压缩动词写全：`重建`、`重编`、`重跑` 这类两字词，读者可能读成「重新创建」；写「重新生成」「重新编译」「重新运行」，同一页后续也不回退到压缩词。
-- 连续出现三个「的」时的改写判定见「七个质量维度」第 5 条。
+- 项目名在同一页首次写全（如「井字棋棋盘」），后文改用对象名（「棋盘」「动态库」「对局」）；不逐段重复项目名，也不反复解释同一件事。
+- 压缩动词写全：`重建`、`重编`、`重跑` 这类两字词，读者可能读成「重新创建」；写「重新生成」「重新编译」「重新运行」，同页不回退到压缩词。
 - 正文提及枚举类型与成员函数时写源码完整标识符（`Result`、`Game::ApplyMove`），不设「概念简称」层；架构层名首次出现用一句可观察行为定义；讲读写路径第一句写屏幕上或调用处发生什么。下一句点名类型与函数。再下一句写边界（对照见 `examples/01-language-scope.md`「零基础可懂的读写路径与层名定义」）。
 - 枚举成员的含义写在源码行尾注释里，正文不复述成释义列表或释义段；正文只写谁调用、如何验收、与邻章关系（叙事范围见 `steps/01-task.md`「叙事范围（硬边界）」）。
-- C++ 概念点名按「定用词：术语要稳」的词表；读者侧禁用行见 `scripts/verifying-content.py`；语气判定与口语腔、公文腔的正向标准见「两轴禁例与允许写法」。
+- C++ 概念点名按本步词表；读者侧禁用行见 `scripts/verifying-content.py`；口语腔、公文腔标准见「两轴禁例与允许写法」。
 
 ## 情况
 
@@ -145,7 +147,7 @@
 
 ### 情况：空泛套话与编辑残留
 
-- **空泛套话**只在不指向具体对象时才算病：「深入探讨」「至关重要」「无缝」「赋能」「全方位」删掉后读者取走的信息不变就删；确实在点名一个对象时保留并写出那个对象（「无缝接入现有构建」指不新增构建命令，就写「不新增构建命令」）。
+- **空泛套话**只在不指向具体对象时才算病：「深入探讨」「至关重要」「无缝」「赋能」「全方位」删掉后信息不变就删；确实点名对象时保留并写出那个对象（「无缝接入现有构建」写「不新增构建命令」）。
 - **同义循环换词**：同一段里「实现」「落地」「完成」轮换指同一动作，读者会以为换了东西；统一成一个词。
 - **客服腔**：「如果您有任何疑问，欢迎随时联系」只留操作与结果。
 - **编辑过程残留**：「下面我们来看」「综上所述」「本节将」把写作动作写进正文，删；「本节」只在确需导航时留一次。

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

@@ -21,6 +21,7 @@
 - **无序列表**：并列概念、范围边界、要点枚举——各项之间没有先后或因果；代码块后的逐条讲解格式见 `steps/04-paragraphs.md`「段落规则」。
 - **有序列表**：有先后顺序的步骤或链路——执行顺序本身就是信息（如配置 → 编译 → 测试 → 运行）。
 - **规则和条件不编号**：并列的许可、禁止、判定条件写自然段或分句；只有读者需要按顺序执行动作时才用编号。把「越界 / 占用 / 格式错误」写成 1、2、3，会让读者以为要按顺序检查。一段同时有规则和流程时，规则先成段，流程另起有序列表。
+- 例外：终局判定的「获胜」「平局」这类并列结果，每条都有名称和可独立核对的条件时，可以用编号列表，让读者逐条对照。
 - 列表项结构平行：起首用同类的词（都是名词短语，或都是动词短语），长度相近。
 - **列表字数带**：同一列表各项保持视觉齐长，避免扫读节奏断裂。计量：引导词汉字数、冒号后汉字数（行内代码按标识符计）。失衡判定：冒号后最长 ≥ 最短 × 2，或引导词相差 ≥ 4。改写顺序：删长项多余中心 → 拆多中心 → 过短项按简洁边界补全 → 停止。豁免：出错原因/正确做法；有序步骤；着陆页卡片。列表齐长服从句段主规则，假拆禁令见 `steps/04-paragraphs.md`。
 - 列表项起首用加粗引导词标记中心语，读者扫读时先看到分类再决定是否细读；关键词取同类词（如「显示状态面板」「读入坐标」），并按对象的发生顺序排列，读者扫读即得顺序与内容。

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

@@ -60,11 +60,11 @@
 | 定用词 | 空泛套话（「深入探讨」「至关重要」「无缝」「赋能」）不指具体对象；同义循环换词；客服腔；编辑过程残留 | 改写成可核对的对象或删除；工程术语（反馈里的「闭环」）保留 | `steps/06-wording.md`「情况：空泛套话与编辑残留」 |
 | 回读并退回 | 与改前文本对照：新增原文没有的事实、遗漏读者需要的信息、把限定说成确定 | 恢复原文或按现象退回对应步 |本文件「情况：对照改前文本」 |
 
-机械项：`verifying-content.py` 扫读者 qmd 与 agents 的 `下一节`/`上一节`、`代码把它写成`、`第二道…防线`、围栏外正文的 `由…完成` 与 `由…确定／体现／界定／表达`；读者正文的 agent 免责腔硬拦，章节页引言两个散文段、段落下限由 `verifying-content.py` 判失败；段内连续分句引入新行内代码标识且无回指的过简断裂信号由 `verifying-content.py` 记 WARN（不追清零）。句子模块切分由 `verifying-content.py` 对扫描范围内的 qmd 全量执行，只印切分计数与失败行，失败收三类高精度信号（类型接线句、「接着看／第 N 个枚举」改口、全称被下一句否定）；段中心写不出与对话件数不做正则，留给步骤与案例。
+机械项：`verifying-content.py` 扫读者 qmd 与 agents 的 `下一节`/`上一节`、`代码把它写成`、围栏外正文的 `由…完成` 与 `由…确定／体现／界定／表达`；agent 免责腔、章节页引言两个散文段与段落下限硬拦；过简断裂记 WARN，不追清零。句子切分全量执行，只印计数与失败行，失败收类型接线句、「接着看／第 N 个枚举」改口、全称被下一句否定三类；段中心与对话件数留给步骤与案例。
 
 ### 润色流程：沿着步骤走
 
-润色任务沿 `SKILL.md` 的路由执行：增量任务只走与改动对应的步骤；新章、新阶段或用户明确要求全章重构才从定任务走到通过检查。判定标准见 `steps/06-wording.md`。书根 `README.md` 与 `README.en.md` 是仓库说明页，按 `SKILL.md` 的例外只走第 5–8 步，这个例外优先于本步的跳步判定。三种走法共用同一套九步：**增量润色**保持最小改动，只改判为不合格的句子，不做风格重塑；**全章重构**按 `SKILL.md`「三种走法」走——章级（1–2）先定删留不动句子，节级（3–4）只拆块和段，句级（5–7）逐句拆开再写回去，该层全部重组，不走最小改动；**只读审查**按同一套九步核对，逐条报告，不改文件。执行时遵守定段落节的既有判定：分句骨架在定句子判为不合格，不在定段落里顺手改句子。
+润色任务沿 `SKILL.md` 的路由执行：增量任务只走与改动对应的步骤；新章、新阶段或用户明确要求全章重构才从定任务走到通过检查。判定标准见 `steps/06-wording.md`。书根 `README.md` 与 `README.en.md` 是仓库说明页，按 `SKILL.md` 的例外只走第 5–8 步，这个例外优先于本步的跳步判定。三种走法见 `SKILL.md`「三种走法」，差别按那里执行。执行时遵守定段落节的既有判定：分句骨架在定句子判为不合格，不在定段落里顺手改句子。
 
 同一处同时命中多条规则时，先按 `references/priority.md` 排级：事实与读者任务 > 结构 > 清晰 > 一致 > 风格。高层没有解决，不先做低层润色；低层改动碰到高层事实，停手退回。
 
@@ -82,7 +82,7 @@
 
 1. **确定范围**：用户点名的文件，或本轮已改动的文件；项目提供作用域命令时先跑它，只读它列出的文件。全库中文普查只在用户明确要求审完全部中文文件时做，它自己就是那个 goal 的结束条件，不嵌进单章润色。
 2. **沿步骤走本次文件**：每个文件只走它对应的步骤，每步只改该步判为不合格的句子；后一步发现前一步没做完，退回那一步一次，不在当前步补结构。某句只在定用词失败，就不重写它的结构；某段在定句子失败，先改骨架，再让定用词看一遍。已合格的句子不重润。
-3. **改写**：最小改动，只改判为不合格的句子，不做风格重塑。改写不破检查：qmd 导语 token 与句数、段落篇幅、禁用词由 `verifying-content.py` 把关；中文文件保持 UTF-8 无 BOM、LF。代码围栏逐字摘自源文件，本步骤不改围栏；同源复制文件改一处同步其余并 diff 比对。改动触及知识库案例引用句时先 grep 案例文件再同步。
+3. **改写**：最小改动，只改判为不合格的句子，不做风格重塑。改写不破检查：qmd 导语 token 与句数、段落篇幅、禁用词由 `verifying-content.py` 把关；中文文件保持 UTF-8 无 BOM、LF。代码围栏逐字摘自源文件；注释与源文件不一致时回源改围栏（`steps/03-blocks.md`「摘录与源文件注释」）；同源复制文件改一处同步其余并 diff 比对。改动触及知识库案例引用句时先 grep 案例文件再同步。
 4. **验收同步**：按改动域跑校验（qmd → `verifying-content.py` + `checking-links.py`；有项目技能时只跑它列出的那一条命令，不跑全量 profile）。检查次数与停手见 `steps/09-check.md`「完成判据」。
 
 ### 完成前核对
@@ -116,6 +116,6 @@
 
 ## 正反例
 
-通用情况判得准就不打开。判不准时打开 `examples/08-appendix.md`。
+回读先开 `references/personas.md`，按章型过一份人格；通用情况判得准就不打开 `examples/08-appendix.md`，判不准时再打开。第 8 步点名这两个文件，合计最多两个。
 
 定稿前对照 `references/rules-cards.md` 的 C05、C06、C25、C26：删复述句与元叙述，补三句回顾，自测题只用本章内容。

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

@@ -24,6 +24,7 @@
 - `dry_run: true` 最多 2 次。第 1 次返回 `safe_to_render: false` 时，只改 `output-dir` 一次。第 2 次仍不安全就停住，把 `warnings` 列给用户。
 - `dry_run: false` 最多 1 次。渲染失败就停住，把 `errors` 列给用户，不自动重新运行。
 - 成功时同一次返回里带 `html_report`，不再为同一份文件重新运行。
+- 同一轮改多章时，每章只跑项目的章节检查；全部章改完后 `quarto_render_check` 只跑一轮，`dry_run: true` 最多 2 次，`dry_run: false` 1 次，`quarto_pass_report` 只收尾一次。
 
 报告字段：