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

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

@@ -4,7 +4,7 @@
 
 ## 定结构与定句子：代词不能代替未写出的对象
 
-条文见`steps/05-sentences.md`「代词不能代替未写出的对象」；题干禁令在定结构改（对照见`steps/02-structure.md`「六段块序列」），节首前指在定句子改。两个对照都拿整篇 qmd 验：题干合上书单独可读，节首对象名同句可核。
+条文见 `steps/05-sentences.md`「代词不能代替未写出的对象」；题干禁令在定结构改（对照见 `steps/02-structure.md`「六段块序列」），节首前指在定句子改。两个对照都拿整篇 qmd 验：题干合上书单独可读，节首对象名同句可核。
 
 **定结构（示例章第 5 题，题干代词没有说出对象）：**
 
@@ -40,7 +40,7 @@
 
 ## 定句子：数量词对着下一块点名
 
-条文见`steps/05-sentences.md`「一次对话」。三个对照都来自数量词与紧挨名单对不上的旧稿：成员与类型的接线句、`kPlaced` 的两种结局、`StateTest` 的场景数。
+条文见 `steps/05-sentences.md`「一次对话」。三个对照都来自数量词与紧挨名单对不上的旧稿：成员与类型的接线句、`kPlaced` 的两种结局、`StateTest` 的场景数。
 
 **成员与类型（示例章「流程成员」节首）：**
 
@@ -49,7 +49,7 @@
 这些类型由 `Game` 的四个数据成员使用，都声明在 `state.h` 的 `private:` 下，初始状态写在声明处：
 
 改写（数量词对准成员，类型跟着各成员点名，`PlaceResult` 明确不是成员）：
-四个数据成员都在 `state.h` 的 `private:` 下，`board_` 用 `Board`，`current_player_` 用 `Player`，`result_` 用 `Result`，`history_` 按顺序保存 `Move`：
+四个数据成员都在 `state.h` 的 `private:` 下，`board_` 用 `Board`，`current_owner_` 用 `Player`，`outcome_` 用 `Result`，`move_log_` 按顺序保存 `Move`：
 ```
 
 **`kPlaced`（示例章「尝试操作」块后）：**
@@ -85,7 +85,7 @@
 
 ## 主语跳变与并列搭配不当
 
-并列成分里顿号套顿号怎么改：降层级，一级并列只用顿号。句子级语法判为不合格的总纲见`steps/06-wording.md`；本案例收并列施事失配、受事与施事混排、顿号层级嵌套三类。以 示例章本章回顾、示例章章引言与 示例章测试场景句改稿前为对照：
+并列成分里顿号套顿号怎么改：降层级，一级并列只用顿号。句子级语法判为不合格的总纲见 `steps/06-wording.md`；本案例收并列施事失配、受事与施事混排、顿号层级嵌套三类。以 示例章本章回顾、示例章章引言与 示例章测试场景句改稿前为对照：
 
 ```text
 不佳（并列三项共用「说明」，后两项主语从「数据项」跳到省略的施事）：
@@ -115,7 +115,7 @@
 
 ## 处所状语配错谓语
 
-以 示例章章首改稿前为对照。四句章首把职责与位置并列甩开；并句时若把「在头文件和源文件里」留在「记住」上，状语就配错了谓语——记住的是元素，不是头文件。三档并法见`steps/05-sentences.md`「同档并句」：
+以 示例章章首改稿前为对照。四句章首把职责与位置并列甩开；并句时若把「在头文件和源文件里」留在「记住」上，状语就配错了谓语——记住的是元素，不是头文件。三档并法见 `steps/05-sentences.md`「同档并句」：
 
 ```text
 不佳（四句章首：职责、承接、机制、位置被句号甩成并列）：

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

@@ -4,13 +4,13 @@
 
 ## 术语节奏
 
-首次出现时就近放术语 callout（规则见`steps/02-structure.md`），后续固定一种称呼。普通概念不加行内代码；命令、路径、文件名、关键字、API 和配置键使用行内代码。同一对象在同一页保持一种标记方式，链接标签内不嵌套行内代码。
+首次出现时就近放术语 callout（规则见 `steps/02-structure.md`），后续固定一种称呼。普通概念不加行内代码；命令、路径、文件名、关键字、API 和配置键使用行内代码。同一对象在同一页保持一种标记方式，链接标签内不嵌套行内代码。
 
-一个概念全书只用一个词，统一术语与替换规则见`steps/06-wording.md`。对照案例：示例章引言的「实现切片」改「阶段」后统称又停用，最终直接写具体目录路径。
+一个概念全书只用一个词，统一术语与替换规则见 `steps/06-wording.md`。对照案例：示例章引言的「实现切片」改「阶段」后统称又停用，最终直接写具体目录路径。
 
 ## 术语标签对照句
 
-「ToFlatIndex 的声明」这种贴标签写法要改成什么：改成直接写位置事实。正文不给代码实体贴「是定义／是声明」标签，也不成对展开两者的区分——那是教 C++ 术语，不推进读者对状态面板工程的理解。位置与实现直接写具体事实（「换算写在 state.cpp」「常量在头文件里给出值」），「定义在 x.h」式位置动词不受限；声明引入名字、定义提供实体的辨析降为编辑与评审的内部口径，见`steps/06-wording.md`「定用词：术语要稳」。以 示例章用数组存放九个数据项节改稿前为对照：
+「ToFlatIndex 的声明」这种贴标签写法要改成什么：改成直接写位置事实。正文不给代码实体贴「是定义／是声明」标签，也不成对展开两者的区分——那是教 C++ 术语，不推进读者对状态面板工程的理解。位置与实现直接写具体事实（「换算写在 state.cpp」「常量在头文件里给出值」），「定义在 x.h」式位置动词不受限；声明引入名字、定义提供实体的辨析降为编辑与评审的内部口径，见 `steps/06-wording.md`「定用词：术语要稳」。以 示例章用数组存放九个数据项节改稿前为对照：
 
 ```text
 不佳（块后给 `private:` 下的两行分别贴定义、声明标签，再总结「声明集中在头文件」）：
@@ -26,12 +26,12 @@
 
 ```text
 不佳（同为完整枚举，一处称定义、两处称声明）：
-Game::Place 每次操作都返回一个处理结果，定义在 state.h 里：……
+Game::ApplyMove 每次操作都返回一个处理结果，定义在 state.h 里：……
 先手是 X。流程用户用枚举表示，声明在 state.h 里：……
 流程结果有四种取值，声明在 state.h 里：……
 
 改写（位置动词只说「定义在 state.h 里」；函数体位置直接写「写在 state.cpp」，不贴声明标签）：
-Game::Place 每次操作都返回一个处理结果，用枚举 PlaceResult 表示，定义在 state.h 里：……
+Game::ApplyMove 每次操作都返回一个处理结果，用枚举 PlaceResult 表示，定义在 state.h 里：……
 先手是 X。流程用户用枚举 Player 表示，定义在 state.h 里：……
 流程结果有四种取值，用枚举 Result 表示，定义在 state.h 里：……
 state.h 里 `private:` 下的 ToFlatIndex 只写函数名与参数表，函数体写在 state.cpp。
@@ -128,13 +128,13 @@ state.h 里 `private:` 下的 ToFlatIndex 只写函数名与参数表，函数
 改写：这段程序对外可见的结果只有两处：标准输出中的 Hello, World!，以及 main 返回的 0。
 ```
 
-判定信号：句子的主语是「本章 / 这本书 / 写作策略」而不是工程对象；内容在告诉读者「接下来不讲什么、什么时候才讲」。禁用词见`steps/06-wording.md`。
+判定信号：句子的主语是「本章 / 这本书 / 写作策略」而不是工程对象；内容在告诉读者「接下来不讲什么、什么时候才讲」。禁用词见 `steps/06-wording.md`。
 
 不整词禁用「可能」：规划边界可写「按需评估」；技术命题「不可能改变结果」改为肯定表述（如「跳过不改变搜索结果的分支」）。
 
 ## 口语开场与规划套话
 
-语气的完整标准见`steps/06-wording.md`；以下两例是重构示例项目全书时的定稿对照。
+语气的完整标准见 `steps/06-wording.md`；以下两例是重构示例项目全书时的定稿对照。
 
 开场把讲义口换成书面陈述（首章）：
 
@@ -152,7 +152,7 @@ state.h 里 `private:` 下的 ToFlatIndex 只写函数名与参数表，函数
 
 ## 空泛套话与编辑残留
 
-以操作节导语改稿前为对照（规则见`steps/06-wording.md`「情况：空泛套话与编辑残留」）：
+以操作节导语改稿前为对照（规则见 `steps/06-wording.md`「情况：空泛套话与编辑残留」）：
 
 ```text
 不佳（套话、编辑腔与客服腔各一处）：

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

@@ -1,6 +1,6 @@
 # 中文写作的章级定稿对照（附录）
 
-本文件是低频章级对照附录，不进检索索引与评测；仅人审或用户点名时读。规则与通用对照见`examples/06-wording-cases.md`。
+本文件是低频章级对照附录，不进检索索引与评测；仅人审或用户点名时读。规则与通用对照见 `examples/06-wording-cases.md`。
 
 ## 操作节删除离题辩白
 
@@ -22,7 +22,7 @@
 
 ## 密集引言拆分
 
-多个独立概念压进一段时拆开，但拆的形态由引言规范收敛（规则见`steps/02-structure.md`）：任务概览并入承接句，正文小节承担展开，预览列表不再使用。以 示例章引言为对照：
+多个独立概念压进一段时拆开，但拆的形态由引言规范收敛（规则见 `steps/02-structure.md`）：任务概览并入承接句，正文小节承担展开，预览列表不再使用。以 示例章引言为对照：
 
 ```text
 不佳（旧形态，一段七概念 + 预览列表）：首章界定了……本章开始第一个实现切片：……最小链路完整走通——CMake 配置 → 编译 → CTest 测试 → 运行程序。链路一旦打通……
@@ -61,7 +61,7 @@
 
 ## 下一章预告归位定稿
 
-以 示例章「读写数据项」收尾为对照。改稿前收尾第二句写「`Game` 在下一章决定轮到谁操作、何时获胜和何时平局」，与章末本章回顾的预告重复（规则见`steps/05-sentences.md`「句子规则」）。改写后收尾只留「调用方只给出坐标和要写入的状态，数组和下标换算都留在 `Board` 私有段。`Board` 到此完成数据项的全部读写」，下一章预告由本章回顾独自承担。
+以 示例章「读写数据项」收尾为对照。改稿前收尾第二句写「`Game` 在下一章决定轮到谁操作、何时获胜和何时平局」，与章末本章回顾的预告重复（规则见 `steps/05-sentences.md`「句子规则」）。改写后收尾只留「调用方只给出坐标和要写入的状态，数组和下标换算都留在 `Board` 私有段。`Board` 到此完成数据项的全部读写」，下一章预告由本章回顾独自承担。
 
 示例章引言同类：改稿前引言末句写「终端输入输出留到构建、测试并运行终端流程（`09-running-build.qmd`）」，整句删除——引言只写本章要交出的对象，后章预告由本章回顾独自承担。
 
@@ -69,6 +69,6 @@
 
 ## 同类归位定稿
 
-以 示例章判定节与四章常见错误小节为对照，一次归位四类：结果映射列表不混测试覆盖——示例章「得出胜负与平局」前两项是 `Result` 映射，第三项 `StateTest` 覆盖范围移成图后单句，原「这一次面在 `StateTest` 里记为 甲方获胜」与图注重复，一并替换；常见错误小节只有导语句加单项列表时整节折成一句（规则见`steps/07-layout.md`「列表选择」，多处）；列表项里不混另一类观察——决策章难度列表第 3 项第二句「双方都用它从空状态面板下完，结果是平局」与 `EngineTest` 句重复，删去后三项回到纯难度定义；裸文件名首次点名挂 blob 链接——相关章的 `state.h` 与两处 `running-build.sh`（对照见`examples/06-wording-cases.md`「口语开场与规划套话」）。
+以 示例章判定节与四章常见错误小节为对照，一次归位四类：结果映射列表不混测试覆盖——示例章「得出胜负与平局」前两项是 `Result` 映射，第三项 `StateTest` 覆盖范围移成图后单句，原「这一次面在 `StateTest` 里记为 甲方获胜」与图注重复，一并替换；常见错误小节只有导语句加单项列表时整节折成一句（规则见 `steps/07-layout.md`「列表选择」，多处）；列表项里不混另一类观察——决策章难度列表第 3 项第二句「双方都用它从空状态面板下完，结果是平局」与 `EngineTest` 句重复，删去后三项回到纯难度定义；裸文件名首次点名挂 blob 链接——相关章的 `state.h` 与两处 `running-build.sh`（对照见 `examples/06-wording-cases.md`「口语开场与规划套话」）。
 
 判定信号：结果映射列表里出现测试覆盖项；### 小节正文只有导语加一个列表项；列表项的第二句是别处已有的观察；正文反引号源文件名同句无链接。

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

@@ -2,7 +2,7 @@
 
 本文件是 Quarto Book 项目结构、YAML front matter、章节标题约定的**规范唯一出处**。其他文件提到这些约定时一律引用本文件，不重复陈述。`format: html` 的选项语义与失效边界归 `quarto/render.md`，本文件不复制。
 
-> 速查：`.qmd` = YAML front matter + Markdown 正文 · `title:` 与 `# H1` 二选一 · `index.qmd` 必须存在 · Book 输出 `_book/` · `part:` 分组章节
+> 速查：`.qmd` = YAML front matter + Markdown 正文 · `title:` 与 `# H1` 二选一 · `index.qmd` 必须存在 · Book 输出 `_book/` · `part:` 分组章节 · `appendices:` 收附录
 
 Quarto 接受 `.qmd`、`.md`、`.ipynb`、`.Rmd` 四种章节源文件；Book 的章节以 `.qmd` 为主，本技能只按 `.qmd` 与 `.md` 讲正文写法，其他类型按 Quarto 官方文档处理。
 
@@ -45,6 +45,23 @@ quarto render                     # 渲染当前项目全部内容
 
 ## Quarto Book 项目
 
+书根只放配置、入口和主题资产，正文按部分收进 `content/`。常见布局如下：
+
+```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 Book 的核心配置在书根 `_quarto.yml`：
 
 ```yaml
@@ -61,11 +78,16 @@ book:
       chapters:
         - content/<part>/01-intro.qmd
         - content/<part>/02-topic.qmd
+    - content/<part>/99-bibliography.qmd   # 书目页：#refs 留在 chapters
+  appendices:
+    - content/appendix/references.qmd
 ```
 
-- **`index.qmd` 必须存在**，作为 Book 首页/入口。
+- **`index.qmd` 必须存在**，作为 Book 首页/入口；根首页只承担这一层导航。
 - **`part:` 指向该部分的落地页**（如 `content/<part>/index.qmd`），产生分组标题；新增部分时先建落地页，再加 part。
 - 章节可放子目录，在 `chapters` 写相对路径；`_quarto.yml` 的章节顺序与落地页的阅读顺序保持一致。
+- **`appendices:` 只放附录页**，排在 `chapters` 之后；附录标题默认由 Quarto 加前缀，想改中文名在 `crossref.appendix-title` 设「附录」。
+- 用 `#refs` 生成的书目页留在 `chapters`，不要放进 `appendices`，否则书目会被当成附录。
 - 渲染：`quarto render`，Book 默认输出到 `_book/`。
 
 ### 根首页与 part 落地页的链接边界

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

@@ -0,0 +1,43 @@
+# 注释：qmd、YAML、SCSS 与 CSS
+
+> 速查：qmd 不写声明注释 · YAML 的 `#` 只写为什么 · SCSS 区域标记不可删 · 纯 CSS 只用 `/* */` · 不写 `///` 与 `@param`
+
+本文件只管 Quarto 书里各类文件的注释写法。C++、CMake、shell 与 Python 的注释归项目自己的 C++ 流程，本技能不复述；正文与代码围栏的关系见 `steps/03-blocks.md`「内容块前后的闭环」。
+
+## qmd 正文
+
+- `.qmd` 不设文件头声明注释，也不写函数、参数或返回值注释。章节的任务、边界和读者对象由导语与二级标题承担，注释不重复。
+- 正文里不保留被注释掉的旧段落、旧链接或旧围栏。要留历史就交给 Git，不在源文件里堆注释。
+- 代码围栏逐字摘自源文件，围栏里的注释属于源文件；正文不解释这些注释，只补注释没写到的工程关系。
+
+## YAML
+
+- `#` 只写「为什么这样取值」，不把键名翻译成中文，也不复述默认值。
+- 能由 `_quarto.yml` 的键本身说清的，不写注释；同一取值只在一处解释，其他文件引用该处。
+- front matter 里不写分隔线式注释（`# --- 标题 ---`）；标题就是 YAML 的 `title:`。
+- 注释紧贴被说明的键，放在上一行；不放在行尾挤占宽度。
+
+## SCSS
+
+- Quarto 的三段区域标记必须原样保留，不能删除、改写或合并：
+
+  ```scss
+  /*-- scss:defaults --*/
+  /*-- scss:rules --*/
+  /*-- scss:mixins --*/
+  ```
+
+  区域标记是 Quarto 注入变量的边界，删掉后变量会落到错误的作用域。
+- 变量分组用 `//` 单行注释；跨行说明用 `/* */`。
+- 不写「这段设置颜色」式复述；注释只写取值理由或与另一处令牌的同步关系。
+
+## CSS
+
+- 纯 CSS 只接受 `/* */`；`//` 不是合法 CSS 注释，会被当成选择器或声明而报错。
+- 不在 CSS 里写 `///` 文档注释、`@param`、`@return` 或 Doxygen 标签；这些是源码声明注释的写法，主题资产不用。
+- 注释只解释「这条规则为什么存在」或「和哪个令牌联动」，不逐条翻译属性。
+- 被禁用的规则用注释说明原因后直接删掉，不保留大段注释掉的旧样式。
+
+## 编码与行尾
+
+所有文本文件按 `quarto/encoding.md` 保存为 UTF-8 无 BOM、LF；`.bat` 与 `.cmd` 例外，用 CRLF。

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

@@ -1,10 +1,10 @@
 # 坐标轴网格图的生成约定
 
-坐标轴类网格图（状态面板行列、二维数组下标）用共享绘图助手生成 SVG，不用 Mermaid 硬画网格。流程图与坐标图的分工、页面围栏写法、解释器与 CI 依赖都在本文件；token 预算的排除口径见`steps/02-structure.md`「计数口径」。
+坐标轴类网格图（状态面板行列、二维数组下标）用共享绘图助手生成 SVG，不用 Mermaid 硬画网格。流程图与坐标图的分工、页面围栏写法、解释器与 CI 依赖都在本文件；token 预算的排除口径见 `steps/02-structure.md`「计数口径」。
 
 ## 与 Mermaid 的分工
 
-- 默认图是 `{mermaid}` flowchart，表达调用链、分层与数据流（口径见`quarto/mermaid.md`）。
+- 默认图是 `{mermaid}` flowchart，表达调用链、分层与数据流（口径见 `quarto/mermaid.md`）。
 - 坐标轴类网格图只走 `rendering-coords.py` 加 `{python}` 可执行单元；Mermaid 的节点文本排版不适合网格，禁止用它拼状态面板。
 - Agent 作图边界：默认只生成 Mermaid 流程图；坐标图仅当用户明确指定时生成，且只改助手调用参数，不内联第二套 SVG 逻辑。
 
@@ -17,9 +17,9 @@
 
 ## 上游代码与图的桥接
 
-坐标图不孤立出现：引出图的代码块与图之间必须有桥接句，说明图核对代码的哪部分契约（如「下面的图标出每个数据项的 (row, col)，与 `IsValid` 接受的范围一致」）；图后先给从图带走的结论，再进入下一块；小节以图收尾时，从图带走的结论可并入桥接段（如 示例章先给 `row` 为 `3` 或 `col` 为 `-1` 这类反例再上图），不在图后孤悬一句。代码块与图之间只有空行视为堆叠，固定序列见 `writing-quarto` 技能 `quarto/authoring.md`「代码与图的桥接」与`steps/03-blocks.md`。
+坐标图不孤立出现：引出图的代码块与图之间必须有桥接句，说明图核对代码的哪部分契约（如「下面的图标出每个数据项的 (row, col)，与 `IsValid` 接受的范围一致」）；图后先给从图带走的结论，再进入下一块；小节以图收尾时，从图带走的结论可并入桥接段（如 示例章先给 `row` 为 `3` 或 `col` 为 `-1` 这类反例再上图），不在图后孤悬一句。代码块与图之间只有空行视为堆叠，固定序列见 `writing-quarto` 技能 `quarto/authoring.md`「代码与图的桥接」与 `steps/03-blocks.md`。
 
-坐标图单元计入盒子密度（口径见`steps/03-blocks.md`）：同一 `###` 内坐标图与代码块相邻出现时，桥接句就是盒子之间的承接正文；`verifying-content.py` 对两围栏之间无正文给出 WARN 提示，人审与对照案例仍是主检查。
+坐标图单元计入盒子密度（口径见 `steps/03-blocks.md`）：同一 `###` 内坐标图与代码块相邻出现时，桥接句就是盒子之间的承接正文；`verifying-content.py` 对两围栏之间无正文给出 WARN 提示，人审与对照案例仍是主检查。
 
 ## 助手 API 与主题适配
 

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

@@ -0,0 +1,35 @@
+# 文件编码与行尾
+
+> 速查：UTF-8 无 BOM · 文本文件 LF · `.bat`/`.cmd` CRLF · 机器规则以根 `.gitattributes` 与 `.editorconfig` 为准 · 不反向转码
+
+## 默认值
+
+书里的 `.qmd`、`.yml`、`.yaml`、`.scss`、`.css`、`.md`、`.lua`、`.py`、`.mjs` 一律满足三条：
+
+- UTF-8 无 BOM。
+- 行尾 LF。
+- 文件末尾保留一个换行。
+
+`.bat` 与 `.cmd` 用 CRLF；`.sh` 必须是 LF，否则在 Linux、WSL 与 CI 里会报 `bad interpreter`。
+
+二进制文件（图片、字体、PDF）不按文本规则处理，也不要让 Git 做行尾转换。
+
+## 权威与工具
+
+- 仓库根的 `.gitattributes` 管提交与检出时的行尾，`.editorconfig` 管编辑器写入时的编码、行尾与空白。两份文件冲突时以 `.gitattributes` 为准，并同轮修正 `.editorconfig`。
+- 新建文件前先看根 `.editorconfig` 是否已覆盖该扩展名；没有就用编辑器显式设成 UTF-8、LF。
+- 提交前跑 `git diff --check`，它会拦下行尾空白与冲突标记；行尾本身由 `.gitattributes` 保证。
+- 不要用 `git add --renormalize .` 批量改行尾：它会把无关文件一起带进提交。只改本次动到的文件。
+- 不用 PowerShell 5.1 的 `Out-File`、`Set-Content -Encoding utf8` 写中文文件，它们会加 BOM；用编辑器或 Python 显式写 `encoding="utf-8", newline="\n"`。
+
+## 症状与处置
+
+| 症状 | 先查 | 处置 |
+|---|---|---|
+| 中文变乱码特征串 | 文件是否被按错误编码重读 | 从 Git 可读版本恢复后重做修改，不对已乱码文本反向转码 |
+| 文件头出现 `\ufeff` | 编辑器是否加了 BOM | 用无 BOM 方式重写整个文件 |
+| 每行末尾多出 `^M` | 是否在 Windows 上按 CRLF 保存 | 统一转回 LF；`.bat`/`.cmd` 保持 CRLF |
+| `bash: ...: /usr/bin/env: bad interpreter` | `.sh` 是否为 CRLF | 转成 LF 后重新提交 |
+| `git diff` 整文件重写 | 行尾或 BOM 被批量改动 | 先恢复，再只改目标段落 |
+
+渲染侧的中文乱码排查见 `quarto/render.md`「5. 中文乱码/编码」。

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

@@ -2,7 +2,7 @@
 
 本文件记录 `content/**/*.qmd` 中 Mermaid 图表的渲染层约定；是否使用图表的门槛见 `writing-quarto` 技能的 P0 硬约束，主题侧取色与排版守卫见 `designing-theme` 技能的 `../designing-theme/assets/theme/css/mermaid.css`。
 
-Mermaid 只承担流程图、分层图与调用链；坐标轴类网格图（状态面板行列、二维下标）走 `rendering-coords.py` 加 `{python}` 可执行单元，分工与写法见`quarto/coords.md`，禁止用 Mermaid 硬画网格。
+Mermaid 只承担流程图、分层图与调用链；坐标轴类网格图（状态面板行列、二维下标）走 `rendering-coords.py` 加 `{python}` 可执行单元，分工与写法见 `quarto/coords.md`，禁止用 Mermaid 硬画网格。
 
 ## 只使用 {mermaid} 围栏
 

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

@@ -0,0 +1,86 @@
+# 中英混排与中文润色
+
+> 速查：中文句用中文标点 · 英文句子内部保留英文标点 · 中西文之间一个半角空格 · 数字与单位之间一个空格 · 行内代码只标记要逐字识别的对象
+
+本文件是标点、空格、引号、数字和英文术语写法的唯一出处；句子结构与用词仍归 `steps/05-sentences.md` 与 `steps/06-wording.md`，版式列表与加粗归 `steps/07-layout.md`。标点依据 GB/T 15834—2011 与 W3C CLREQ，空格与润色取舍是本仓约定。
+
+## 一条主轴
+
+先保住事实、数字、条件、范围和归属，再改句子，最后才动标点。润色不是重写：原句已经自然准确就不改（叶圣陶「可改可不改则不改」）；要改就改到读者能更快拿到动作与结果，不靠形容词抬高语气。
+
+## 标点
+
+- 中文句子用全角标点：`，` `。` `；` `：` `？` `！` `、` `……` `——`。
+- 完整英文句子、英文引文、代码、命令、URL 与文件路径内部保留半角标点，不改写。
+- 中文句子里不混入半角 `,` `.` `;` `:` `?` `!`；版本号、时间、比例、坐标和代码例外。
+- 中文引号先双后单：`“……”`，内层 `‘……’`；英文引文用英文引号；代码字符串保留源码引号。
+- 中文内容的括号用全角 `（）`；API、代码、英文缩写内部用半角 `()`；不中英括号混用。
+- 破折号用 `——`，省略号用 `……`；不写 `--`、`...`。
+- 书名号用 `《》`，内层用 `〈〉`。
+- 冒号只用于引出列表、代码、图或结论；词条式冒号按 `steps/04-paragraphs.md`「散文伪标签冒号禁令」改写。
+
+## 空格
+
+- 中文与拉丁字母、数字之间加一个半角空格：`使用 Quarto 渲染`、`共 9 格`。
+- 中文与行内代码之间加一个半角空格；代码与中文标点之间不留空格：`调用 \`ApplyMove\`，返回 \`kRejected\`。`
+- 中文标点前后不加空格；行首、行尾不留空格。
+- 数字与单位之间加一个半角空格：`10 GB`、`3 s`；百分号紧贴数字：`20%`。
+- 英文缩写与中文之间同样加空格：`使用 API 时`。
+- 不为凑空格拆行，也不手写 ` ` 或不换行空格字符。
+
+## 引号与术语
+
+- 术语首次出现写「中文译名（English original）」，后文统一用中文或原文，全书只选一种。
+- API、类型、函数、参数、命令、路径和取值一律用行内代码，不翻译、不改大小写。
+- 英文句子独立成句时，句末用英文标点；中文句子里夹一个英文词时，句末仍用中文标点。
+- 不用全角拉丁字母或数字；不用中文引号包代码；不在术语中间插入空格。
+
+## 数字、单位与范围
+
+- 数据用阿拉伯数字；概数与成语用汉字（`三四个`、`九宫格`）。
+- 范围用 `～` 或「到」：`10～20`；不用半角连字符连接中文数字范围。
+- 版本号、坐标、代码里的数字保持源码形式，不补空格、不换全角。
+- 单位符号与数字之间加空格；角度、百分比按行业习惯，同一本书内保持一致。
+
+## 去套话
+
+- 删「进行／作出＋名词」「值得注意的是」「不难发现」「综上所述」「首先、其次、最后」的堆叠。
+- 少用「被」和长「的」链；一句一个动作，主语尽量是领域对象，不用「我们」代替读者。
+- 不写「本文将介绍」「下面我们来看」；直接给读者要做的动作和看得见的结果。
+- 同一事实只留一处：标题、段首、块后不互相复述。
+- 英文术语不堆叠；能用中文说清就不夹英文，必须夹时首次给原文。
+
+## 让句子有信息量
+
+润色要的「灵性」不靠形容词，靠三件事：主语是具体对象，动词是具体动作，读完能看见结果。
+
+- 删掉章节行程，直接给对象和它回答的问题。
+  - 原句：这一章介绍棋盘类的设计，首先看成员，然后看落子，最后看胜负判定。
+  - 改写：棋盘只保存九个格子。落子、满盘、成线与赢家都由它回答。
+- 把「进行校验」「负责计算」换成调用方看得见的动作与返回值。
+  - 原句：程序会对输入进行校验，如果坐标不合法就会返回错误。
+  - 改写：坐标越界、格子被占用或对局已结束时，`TryPlace` 返回 `kRejected`，棋盘不变。
+- 主语落在领域对象上，不落在「我们」「本章」。
+  - 原句：这个函数负责计算当前局面下电脑应该落子的位置。
+  - 改写：`Choose` 收下当前对局，交出一个 `Move`。
+- 一段里留一句短句（20 字以内）；连续三句长度相近就拆开或合并，让节奏有起伏。
+- 比喻只在能缩短解释时用一次，不叠加形容词。
+
+## 检查表
+
+- 中文句里是否混入半角标点；英文句子里是否被改成全角。
+- 中西文边界是否正好一个半角空格；中文标点前后是否多了空格。
+- 引号、括号、书名号是否成对；代码与标点之间是否留了多余空格。
+- 一句是否只做一件事；40 字以上是否该拆；删掉修饰词后信息是否不变。
+- 段首是否用「这一章」「接下来」「首先」代替了具体对象。
+- 是否出现「进行」「负责」「完成」加名词的空心动作，能换成具体动词吗。
+- 段内是否至少有一句 20 字以内的短句。
+- 首次出现的英文术语是否给了中文，后文是否统一。
+
+## 依据
+
+- W3C《中文排版需求》（CLREQ）：https://www.w3.org/TR/clreq/
+- GB/T 15834—2011《标点符号用法》
+- 中文文案排版指北：https://github.com/sparanoid/chinese-copywriting-guidelines
+- 中文技术文档的写作规范：https://github.com/ruanyf/document-style-guide
+- 叶圣陶《评改两篇作文》、朱光潜《谈文学》的修改观

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

@@ -4,7 +4,7 @@
 
 > 速查：外观选项集中在根目录配置的格式块下 · 目录收至三级标题放右侧 · 本书不用行号、代码块不折叠。自测答案使用 `.answer` 并渲染为原生 details
 
-选项语义、作用域层级与生效边界的唯一出处是本文件与`steps/02-structure.md`（宽度与节奏）；本文件只留本书的取值和写作口径：
+选项语义、作用域层级与生效边界的唯一出处是本文件与 `steps/02-structure.md`（宽度与节奏）；本文件只留本书的取值和写作口径：
 
 ### 本书的现行取值
 
@@ -28,12 +28,12 @@
 1. 改 `format: html:` 任何取值都属于主题级改动，会触发整本渲染，先确认代价再走 `quarto render`。
 2. 新增或删减主题样式表（`.agents/skills/designing-theme/assets/theme/css/**` 或书内 `theme/css/**`）时，同步修改配置里的样式表清单，否则新样式不参与渲染。
 3. 页面视觉问题（提示符配色、文件名条、术语色）改 `.agents/skills/designing-theme/assets/theme/**` 或书内 `theme/**` 与设计令牌，不在文档里内联样式，也不改高亮配置。主题系统详见 `../designing-theme/references/theme-system.md`。
-4. 流程图使用 `{mermaid}` 属性围栏，配色由主题样式控制。配置里不指定图表主题名；围栏与 init 指令细则见`quarto/mermaid.md`。
+4. 流程图使用 `{mermaid}` 属性围栏，配色由主题样式控制。配置里不指定图表主题名；围栏与 init 指令细则见 `quarto/mermaid.md`。
 5. 拿不准选项名、默认值或嵌套层级时查官方参考页，不凭记忆写 YAML（入口见本文件 #8）。
 
 ### 验证
 
-渲染后确认：目录深度与位置符合预期、明暗两套高亮都可读。渲染产物结构由 `checking-output.py` 与 `checking-callouts.py`自动核对；页面宽度与视觉依据见`steps/02-structure.md`。主题或目录看起来没生效时先硬刷新排除缓存，再核对选项嵌套层级。
+渲染后确认：目录深度与位置符合预期、明暗两套高亮都可读。渲染产物结构由 `checking-output.py` 与 `checking-callouts.py` 自动核对；页面宽度与视觉依据见 `steps/02-structure.md`。主题或目录看起来没生效时先硬刷新排除缓存，再核对选项嵌套层级。
 
 ## 渲染与发布排查索引
 
@@ -67,6 +67,7 @@
 - **症状**：中文变成乱码特征串，或文件带 BOM、行尾变 CRLF。
 - **处置**：改 `.qmd` 或规范文档后先跑 `verifying-content.py`。失败时从 Git 可读版本恢复再重做修改，**不要**对已乱码文本反向转码。用 `verifying-content.py` 复查结构，并在编辑器里确认 UTF-8 无 BOM。
 - **注意**：PowerShell 5.1 的 `Out-File`/`Set-Content -Encoding utf8` 会附带 BOM，需显式无 BOM 或改用 Python 写入。
+- 编码与行尾的完整规则见 `quarto/encoding.md`；本文件只处理渲染后的症状。
 
 ### 6. 渲染失败排查顺序
 
@@ -113,17 +114,17 @@
 ### 13. `{{< include >}}` 引用代码文件未加属性围栏 → 乱码式排版、目录被污染
 
 - **症状**：渲染出的脚本失去高亮与等宽底色，`#` 注释行变成大号标题，含 `*`、`_` 的行变成斜体或粗体，右侧目录多出假标题。
-- **处置**：`{{< include >}}` 整体放进 `{.cpp filename="main.cpp"}` 形式的属性围栏，按扩展名选语言并把 `filename` 写成真实文件名短名，**没有一个例外**。规则见 `quarto/authoring.md`「代码与媒体」；include 的使用边界见`quarto/render.md`。
+- **处置**：`{{< include >}}` 整体放进 `{.cpp filename="main.cpp"}` 形式的属性围栏，按扩展名选语言并把 `filename` 写成真实文件名短名，**没有一个例外**。规则见 `quarto/authoring.md`「代码与媒体」；include 的使用边界见 `quarto/render.md`。
 
 本文件记录本书 `content/**/*.qmd` 的渲染层约定，供 Agent 编写和评审章节时使用；写作层骨架与元素规则见 `steps/` 下的步骤文件。
 
 ## include 短代码必须包在围栏代码块内
 
-展示源码默认**内联摘录片段**（片段规则见`steps/03-blocks.md`，生效）；include 是可选手段，仅用于确实需要完整展示且很短的文件。仍在使用 include 时，必须包在围栏代码块内。
+展示源码默认**内联摘录片段**（片段规则见 `steps/03-blocks.md`，生效）；include 是可选手段，仅用于确实需要完整展示且很短的文件。仍在使用 include 时，必须包在围栏代码块内。
 
 `{{< include <文件> >}}` 裸用（不包代码块）时，Quarto 把文件内容当作 Markdown 正文渲染——换行丢失、`#===` 横幅被解析为 Markdown 标记，最终在 HTML 中变成一串 `<p>` 段落，代码结构完全破坏。
 
-正确写法是包在带语言标注的围栏代码块内（[官方文档](https://quarto.org/docs/authoring/includes.html)给出了同样模式）：
+正确写法是包在带语言标注的围栏代码块内（[官方文档](https://quarto.org/docs/authoring/includes.html) 给出了同样模式）：
 
 ````markdown
 ```python
@@ -140,26 +141,26 @@
 
 qmd 指向仓库内路径的链接仍**一律使用 GitHub 绝对链接**，不使用相对路径链接；锚文本与外链按下列规则执行。
 
-- 章节互引：用章节 title 作链接文字，`.qmd` 相对路径（规则见`steps/06-wording.md`）；
+- 章节互引：用章节 title 作链接文字，`.qmd` 相对路径（规则见 `steps/06-wording.md`）；
 - 仓库内目录：`https://github.com/your-org/your-book/tree/main/<路径>`，锚文本用简短中文描述（如「最小工程目录」）；
 - 仓库内文件：`https://github.com/your-org/your-book/blob/main/<路径>`，锚文本用中文描述或专名文件名（如「构建规则 CMakeLists.txt」「main.cpp」）；
-- 锚文本不写路径结构：`src/` 这类层级不进锚文本；完整路径只出现在 GitHub URL、目录树和确需精确指路的行文里，不进代码块 filename（filename 一律短名，见`steps/03-blocks.md`）；
+- 锚文本不写路径结构：`src/` 这类层级不进锚文本；完整路径只出现在 GitHub URL、目录树和确需精确指路的行文里，不进代码块 filename（filename 一律短名，见 `steps/03-blocks.md`）；
 - 行文叙述少用行内代码路径指代目录：正文指向仓库内目录或文件时，首次出现处用中文锚文本的 GitHub 链接，此后用中文短指称；行内代码路径只保留在目录树与目录映射表格，正文里的实现目录用 GitHub 链接（模板见 `quarto/authoring.md`）；
 - 外部官方文档非必要不链接：命令与概念默认用行内代码加正文一句话讲清；引用第三方内容注明出处与章末参考资料清单是外链的合法位置；
 - 全路径在行文首次出现后改用中文短指称（工程目录、一键脚本、构建规则），不重复全路径；
 - 跨仓锚文本禁止「写法依据见 / 依据见 / 机制见 / 选型见 / 承诺见 / 用法见 / 陷阱见」式；默认不挂链，可选尾置用「若要系统阅读…」；细则见 `writing-quarto` 技能 `steps/01-task.md`「叙事范围（硬边界）」；
 - 新增链接后渲染检查 HTML：锚文本与 URL 对应、无相对路径仓库链接混入（章节互引除外）；
-- 正文与代码块 filename 标注不引用 `.agents/` 内部路径：读者所需的解释就地写清，仓库内路径一律链 GitHub；内部知识路径的读者/作者分离依据见`steps/03-blocks.md`「内容块前后的闭环」；
+- 正文与代码块 filename 标注不引用 `.agents/` 内部路径：读者所需的解释就地写清，仓库内路径一律链 GitHub；内部知识路径的读者/作者分离依据见 `steps/03-blocks.md`「内容块前后的闭环」；
 - 页面级 GitHub 入口只有「查看源码」：`_quarto.yml` 的 `book.repo-actions` 钉为 `[source]`，不开放编辑与议题按钮（取舍见 `quarto/render.md`）。
 
 ## 章节结构约定的归属
 
 章节骨架（无标题引言、任务序列、常见错误、自测问题、本章回顾）、标题字数与教学元素写法统一由 `steps/` 下的步骤文件维护，按下表查阅：
 
-- 见`steps/02-structure.md`：六段骨架、引言职责边界、H2/H3 门槛、术语策略；
-- 见`steps/02-structure.md`：title 与二三级标题的标题字数（动词短语、无冒号）与纵向承诺链；
-- 见`steps/03-blocks.md`：代码块 filename 标注、盒子密度、Callout、目录树、多命令块；
-- 见`examples/06-wording-cases.md`：措辞替换与术语节奏；句段对照见 `examples/05-sentence-frame.md`；
-- 见`steps/02-structure.md`：小节主线收束与信息分层。
+- 见 `steps/02-structure.md`：六段骨架、引言职责边界、H2/H3 门槛、术语策略；
+- 见 `steps/02-structure.md`：title 与二三级标题的标题字数（动词短语、无冒号）与纵向承诺链；
+- 见 `steps/03-blocks.md`：代码块 filename 标注、盒子密度、Callout、目录树、多命令块；
+- 见 `examples/06-wording-cases.md`：措辞替换与术语节奏；句段对照见 `examples/05-sentence-frame.md`；
+- 见 `steps/02-structure.md`：小节主线收束与信息分层。
 
 本文件只维护 include 包裹与链接使用两条渲染层约定。

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

@@ -15,7 +15,7 @@
 
 后续命令依赖前一条命令的输出时，正文必须说明从输出中复制什么、如何用它完成占位符替换，以及什么时候执行下一条命令。不能只写「记下名称后再安装」，否则新手需要自行判断取值对象和替换位置。
 
-恢复后的可观察状态本身需要拆解说明，并且其后没有必经动作时，可以用结果型 Callout 承接精确判据和说明列表。正文仍要先保留检查动作。结果型 Callout 的边界见`steps/03-blocks.md`。
+恢复后的可观察状态本身需要拆解说明，并且其后没有必经动作时，可以用结果型 Callout 承接精确判据和说明列表。正文仍要先保留检查动作。结果型 Callout 的边界见 `steps/03-blocks.md`。
 
 ## 代码块前的标点
 
@@ -37,7 +37,7 @@
 
 命令块只放能直接复制执行的命令，以及紧贴在命令上方的原生注释。不加 `$ ` 或 `PS>` 提示符，不在命令行末尾追加注释。每个代码块在首条命令上方写一条总注释，说明整块要做什么。只有单个依赖或用途不明显、容易误用时，才在该命令上方补一行子注释。输出放在紧随其后的 `text` 块中，命令块与输出块之间只留一个空行。
 
-代码块注释一行只承担一个职责。总注释和子注释都用短句，不用中文冒号或分号串联多个动作。片段内注释硬限（每处 ≤2 行、单行 ≤100 列，与源文件 `ColumnLimit` 同一口径）见`steps/03-blocks.md`。代码块中不使用 Markdown 强调符号。
+代码块注释一行只承担一个职责。总注释和子注释都用短句，不用中文冒号或分号串联多个动作。片段内注释硬限（每处 ≤2 行、单行 ≤100 列，与源文件 `ColumnLimit` 同一口径）见 `steps/03-blocks.md`。代码块中不使用 Markdown 强调符号。
 
 标点规则只作用于正文、标题、表格和列表，行内代码与代码块内部照抄真实语法。把多条命令串进一句话，读者无法判断该复制哪一行，应当拆成独立的代码块或独立句子。留在同一块内的多条命令职责不同时，逐条写子注释说明各自用途；读者只需执行其中一条时，拆成独立代码块，并在正文写明先执行哪条、什么情况下改用另一条。多命令块后的逐条讲解用无序列表（格式见 `steps/07-layout.md`「列表选择」）。
 
@@ -81,7 +81,7 @@
 
 常见错误放在本章回顾之前，`## 常见错误` 负责导航。每个故障用一个描述现象的 `###`，标题后的第一句同时说明触发条件与可观察现象。条目按故障性质分两种形态：
 
-- **误用型条目**（接口或状态的用法错误，如传错枚举值、想绕开封装）：默认一段成文，一句话写全「触发条件与现象：原因与正确做法」，验证信息并入现象句或做法句，不设加粗步骤；原因与做法各需一句完整交代时（如原因牵涉私有段的设计动机），改用症状句导语加两项引导词列表——首句只写触发条件与现象，列表项为「**出错的原因**」「**正确的做法**」，格式见 `steps/07-layout.md`「列表选择」（示例章绕过下标换算条目为对照）；列表可作为节导语的合法收尾，三级导语预算只约束症状句。篇幅按`steps/02-structure.md` 的预算执行。
+- **误用型条目**（接口或状态的用法错误，如传错枚举值、想绕开封装）：默认一段成文，一句话写全「触发条件与现象：原因与正确做法」，验证信息并入现象句或做法句，不设加粗步骤；原因与做法各需一句完整交代时（如原因牵涉私有段的设计动机），改用症状句导语加两项引导词列表——首句只写触发条件与现象，列表项为「**出错的原因**」「**正确的做法**」，格式见 `steps/07-layout.md`「列表选择」（示例章绕过下标换算条目为对照）；列表可作为节导语的合法收尾，三级导语预算只约束症状句。篇幅按 `steps/02-structure.md` 的预算执行。
 - **排查型故障**（环境或运行时问题，需要动手定位，如流状态、动态库加载失败）：正文只保留「定位 → 修复 → 验证」三个有序步骤。
 
 排查型三步中，定位步骤只放收敛问题所需的最小检查，先确认执行位置与前置状态，再检查故障本身。确认执行位置用一条可观察的判据，例如用 `pwd` 确认当前目录以阶段目录结尾，或用 `ls CMakeLists.txt` 确认当前位于工程根目录。修复步骤必须复用定位得到的具体对象，并提供回到成功路径的动作。验证步骤给出一个可观察结果。修复动作必须与定位得到的故障对象一致：清理目标产物不能替代清除 CMake 配置缓存，排查缓存或工具链问题时也不顺带更换构建类型。

package/skills/writing-quarto/scripts/checking-dom.py

@@ -28,7 +28,8 @@
   C7 代码块视觉契约：普通文本代码块与语言代码块必须共用代码背景、边框、
       字体和布局令牌，避免两套代码块样式分叉。
   C8 代码来源标题：QMD 代码块必须由 .code-with-filename 包裹，且主题必须提供
-      标题背景、文字和间距令牌。标题条不能退化为普通代码块。
+      标题背景、文字和间距令牌。标题条不能退化为普通代码块。自定义组件里的
+      <pre>（没有 <code> 子节点）不算代码来源块。
   C9 可折叠答案：产物中的 details.answer-disclosure 存在时，必须默认收起，
       摘要必须等于“查看答案”，且答案区不得混入标题层级；没有答案块时为 N/A。
 
@@ -443,6 +444,10 @@ def check_contracts(book_dir, htmls, css_pairs, root=None, require_favicon=True)
                 continue
             if node.classes & {"mermaid", "mermaid-js"}:
                 continue
+            # Pandoc 生成的源码块一定带 <code> 子节点；交互组件里的终端输出
+            # 直接把文本放进 <pre>，不是代码来源块，不该按 C8 判定。
+            if not any(child.tag == "code" for child in walk(node)):
+                continue
             untitled.append(str(path.relative_to(book_dir)))
     title_tokens = all(token in source_css_text for token in (
         "--code-title-bg", "--code-title-fg", "--code-title-font-size", "--code-title-padding",

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

@@ -91,11 +91,15 @@ def parse_frontmatter_title(front: str) -> str:
 def parse_chapters(quarto_yml: Path) -> list[str]:
     """Return chapter hrefs in declaration order.
 
-    Supports the two forms Quarto Book uses:
+    Supports the forms Quarto Book uses:
       chapters:
         - index.qmd
         - href: content/part/01-intro.qmd
-    It deliberately does not parse part titles as chapters.
+        - part: content/part/index.qmd
+          chapters:
+            - content/part/01-intro.qmd
+    `part:` 带标题时只是分组标题，不带 .qmd 后缀，因此不会被当成章节；带文件时，
+    该文件是分组落地页，也要接受内容检查。嵌套的 `chapters:` 键本身不是章节。
     """
     if not quarto_yml.is_file():
         return []
@@ -114,7 +118,12 @@ def parse_chapters(quarto_yml: Path) -> list[str]:
         if not stripped.startswith("-"):
             continue
         item = stripped[1:].strip()
-        href = re.sub(r"^href:\s*", "", item).strip().strip("'\"")
+        key, sep, value = item.partition(":")
+        if sep and re.fullmatch(r"[a-z_]+", key.strip()):
+            # 只接受会落到页面的键：href 与 part 的文件形式。
+            href = value.strip().strip("'\"") if key.strip() in {"href", "part"} else ""
+        else:
+            href = item.strip("'\"")
         if href.endswith(".qmd"):
             chapters.append(href)
     return chapters

package/skills/writing-quarto/steps/01-task.md

@@ -47,13 +47,13 @@
 
 ### 定任务：先让新人完成任务
 
-- 开篇场景的写法见`steps/02-structure.md`「六段块序列」。
-- 每页一条成功路径与后置内容的判定见`steps/06-wording.md`；主线闭合见`steps/02-structure.md`。
-- 标准术语的首次解释与术语卡落点见`steps/02-structure.md`（写法见 `quarto/authoring.md`）；缩写先写全称。
+- 开篇场景的写法见 `steps/02-structure.md`「六段块序列」。
+- 每页一条成功路径与后置内容的判定见 `steps/06-wording.md`；主线闭合见 `steps/02-structure.md`。
+- 标准术语的首次解释与术语卡落点见 `steps/02-structure.md`（写法见 `quarto/authoring.md`）；缩写先写全称。
 - 不假设读者知道工具名、命令参数、目录布局或错误输出代表的含义。
-- 目录式堆砌禁令与清单下沉判据见`steps/02-structure.md`。
-- 标题与引言的单事承诺、承诺用词与 title 变更同步见`steps/02-structure.md`。
-- 语言课禁令、否定式预告、不写「下一节」都在这一步判：它们决定本章能不能出现某句，不是措辞问题（细则见`steps/05-sentences.md`「句子规则」、本文件「叙事范围」）。
+- 目录式堆砌禁令与清单下沉判据见 `steps/02-structure.md`。
+- 标题与引言的单事承诺、承诺用词与 title 变更同步见 `steps/02-structure.md`。
+- 语言课禁令、否定式预告、不写「下一节」都在这一步判：它们决定本章能不能出现某句，不是措辞问题（细则见 `steps/05-sentences.md`「句子规则」、本文件「叙事范围」）。
 
 ## 情况