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

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

@@ -4,7 +4,7 @@
 
 ## 压缩黑话与过短句
 
-读者正文写可观察对象与完整主谓句，不写压缩隐喻和缺成分的省略句；禁用词见`steps/06-wording.md`，正向语气标准见`steps/06-wording.md`。判定口诀：读者能从句子里指出磁盘上的文件、屏幕上的输出或可执行的动作，这句才合格。
+读者正文写可观察对象与完整主谓句，不写压缩隐喻和缺成分的省略句；禁用词见 `steps/06-wording.md`，正向语气标准见 `steps/06-wording.md`。判定口诀：读者能从句子里指出磁盘上的文件、屏幕上的输出或可执行的动作，这句才合格。
 
 ```text
 不佳（压缩隐喻当主语，读者对不上现实对象）：
@@ -46,7 +46,7 @@ AI 才有稳定的地基。本章设计终端双人闭环与分层验收。
 
 ## 过简断裂段
 
-以 示例章「查看流程接口」节导语改稿前为对照。与「罗列短句成段」的分工：那条打句号清单，本条打逗号切断与过简两句各丢一个事实——每截单看都合法，段却不成篇，读者要自己补「因为／所以／其中」（规则见`steps/05-sentences.md`「过简断裂禁令」与「概念负荷」）：
+以 示例章「查看流程接口」节导语改稿前为对照。与「罗列短句成段」的分工：那条打句号清单，本条打逗号切断与过简两句各丢一个事实——每截单看都合法，段却不成篇，读者要自己补「因为／所以／其中」（规则见 `steps/05-sentences.md`「过简断裂禁令」与「概念负荷」）：
 
 ```text
 不佳（四截并列：对象 → 文件位置 → 入口个数 → 私有存储，截截换新主语、新事实）：
@@ -66,11 +66,11 @@ ai.h 不打印状态面板，也不读取键盘。`Ai::Choose` 读当前流程
 
 判定信号：逗号、句号后的分句引入新主语或新的行内代码标识，且无回指词、无承接词；删掉该分句后上下文照样成立，说明它只是被并列甩出的另一截。改写时收敛主概念，用给定信息衔接次要展开；时序句「进入目录，执行入口」合法（后一分句接住前一分句的动作）。
 
-ai.h 那组的改写只解决过简断裂；定稿进一步把「不打印、不读取」的否定边界让给常见错误节，正文只写「`ai.h` 声明操作的公共接口：`Ai::Choose` 读当前流程，返回当前用户的一次合法 `Move`。」（否定式预告见`steps/05-sentences.md`「句子规则」）。
+ai.h 那组的改写只解决过简断裂；定稿进一步把「不打印、不读取」的否定边界让给常见错误节，正文只写「`ai.h` 声明操作的公共接口：`Ai::Choose` 读当前流程，返回当前用户的一次合法 `Move`。」（否定式预告见 `steps/05-sentences.md`「句子规则」）。
 
 ## 罗列短句成段
 
-以 首章「观察一次流程」改稿前为对照。三个短句各自成立、句间无衔接，读起来像清单；分号还把显示状态面板与拒绝非法输入两件事串进一句（规则见`steps/04-paragraphs.md`「罗列短句成段禁令」）：
+以 首章「观察一次流程」改稿前为对照。三个短句各自成立、句间无衔接，读起来像清单；分号还把显示状态面板与拒绝非法输入两件事串进一句（规则见 `steps/04-paragraphs.md`「罗列短句成段禁令」）：
 
 ```text
 不佳（三个独立短句堆成一段，句间无衔接；分号串两个中心）：
@@ -84,7 +84,7 @@ ai.h 那组的改写只解决过简断裂；定稿进一步把「不打印、不
 
 ## 过简实现围栏
 
-值得出围栏的是类型布局、多步或非显然控制流、与图核对的公式实现；单次比较或直接 `return` 的平凡实现不出围栏（门槛见`steps/03-blocks.md`）。以 示例章检查坐标后读写节改稿前为对照：
+值得出围栏的是类型布局、多步或非显然控制流、与图核对的公式实现；单次比较或直接 `return` 的平凡实现不出围栏（门槛见 `steps/03-blocks.md`）。以 示例章检查坐标后读写节改稿前为对照：
 
 ```text
 不佳（为证明「源码有此函数」贴出一次比较的平凡实现）：

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

@@ -13,7 +13,7 @@
 
 ## 句内骨架：先依据后选择
 
-以 示例章「用数组存放九个数据项」的块后段为对照。旧改写只去掉词条式冒号和同义堆叠，分句骨架仍不合格：第一句先给代码决定，第二句才补依据；「是示例项目规则的一部分」只贴类别；「正好装下」把上一句再说一遍；「由 `ToFlatIndex` 完成」提前交接下一小节专讲的对象（规则见`steps/05-sentences.md`「句内骨架」）：
+以 示例章「用数组存放九个数据项」的块后段为对照。旧改写只去掉词条式冒号和同义堆叠，分句骨架仍不合格：第一句先给代码决定，第二句才补依据；「是示例项目规则的一部分」只贴类别；「正好装下」把上一句再说一遍；「由 `ToFlatIndex` 完成」提前交接下一小节专讲的对象（规则见 `steps/05-sentences.md`「句内骨架」）：
 
 ```text
 不佳（先决定后补依据，类别句不改下一步，复述句与交接句多余）：
@@ -29,7 +29,7 @@
 
 ## 拉链句
 
-一句话把两组对象两两配对，删掉任一配对、剩下的仍能单独成立，原句就是拉链句：读者要按顺序把左组一一配到右组，且两个配对共用同一个判据（判定与三条改写见`steps/05-sentences.md`「拉链句」；步骤链、同物两处与回顾不按拉链判）。以 示例章章首改稿前与 示例章改稿前为对照：
+一句话把两组对象两两配对，删掉任一配对、剩下的仍能单独成立，原句就是拉链句：读者要按顺序把左组一一配到右组，且两个配对共用同一个判据（判定与三条改写见 `steps/05-sentences.md`「拉链句」；步骤链、同物两处与回顾不按拉链判）。以 示例章章首改稿前与 示例章改稿前为对照：
 
 ```text
 不佳（一句两组配对：「数据项在哪、上面是什么」分别交给两个类型；还提前点了后文才定义的类型名，并用「写进代码时」元叙述）：
@@ -83,7 +83,7 @@
 
 ## 结构助词「的」
 
-两条判定见`steps/05-sentences.md`「结构助词「的」」；正反对照只收这一组。两个名词粘合后仍是一个叫法时去掉「的」；术语表已定名的按定名走：
+两条判定见 `steps/05-sentences.md`「结构助词「的」」；正反对照只收这一组。两个名词粘合后仍是一个叫法时去掉「的」；术语表已定名的按定名走：
 
 ```text
 不佳（「状态面板的格子的总数」两个「的」，内层先粘合成「数据项」）：
@@ -103,11 +103,11 @@
 已经写入的状态面板
 ```
 
-「的的」字面仍由 verifying-content.py 拦截，不新增「A的B的C」正则。
+「的的」字面仍由 verifying-content.py 拦截，不新增 `A的B的C` 这类正则。
 
 ## 定句子：两次说话拆成一次对话
 
-条文见`steps/05-sentences.md`「一次对话」。总述叠了几件内容：有没有写进状态面板、整局走到哪、它们是两个问题、用两个枚举分开答，下一句又改口「接着看」「第一个枚举」。改写发生在定句子：每件内容一次对话，紧挨自己的围栏。
+条文见 `steps/05-sentences.md`「一次对话」。总述叠了几件内容：有没有写进状态面板、整局走到哪、它们是两个问题、用两个枚举分开答，下一句又改口「接着看」「第一个枚举」。改写发生在定句子：每件内容一次对话，紧挨自己的围栏。
 
 **定句子（示例章两个枚举的总述）：**
 
@@ -129,7 +129,7 @@
 
 ## 假对比、起跑式铺垫与意义拔高
 
-以一段常量位置说明改稿前为对照（规则见`steps/05-sentences.md`「情况：假对比、起跑式铺垫与意义拔高」）：
+以一段常量位置说明改稿前为对照（规则见 `steps/05-sentences.md`「情况：假对比、起跑式铺垫与意义拔高」）：
 
 ```text
 不佳（起跑式铺垫、假对比、句尾拔高各一处）：

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,95 @@
+# 中英混排与中文润色
+
+> 速查：中文句用中文标点 · 英文句子内部保留英文标点 · 中西文之间一个半角空格 · 数字与单位之间一个空格 · 行内代码只标记要逐字识别的对象
+
+本文件是标点、空格、引号、数字和英文术语写法的唯一出处；句子结构与用词仍归 `steps/05-sentences.md` 与 `steps/06-wording.md`，版式列表与加粗归 `steps/07-layout.md`，新人可读性与任务完整性归 `quarto/readability.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`；不用半角连字符连接中文数字范围。
+- 版本号、坐标、代码里的数字保持源码形式，不补空格、不换全角。
+- 单位符号与数字之间加空格；角度、百分比按行业习惯，同一本书内保持一致。
+
+## 条件与步骤
+
+- 条件写在动作前：「若要删除整个文档，先点 Delete」，不写「点 Delete，若你想删除整个文档」。
+- 这条只约束操作步骤；解释分支结果时仍先写可观察结果，再补条件。
+- 一步一个动作，动作后紧跟结果或验收方式；不要把三个动作塞进一句。
+- 步骤只写读者此刻要做的事，设计取舍另起一段放在动作完成后。
+
+## 去套话
+
+- 删「进行／作出＋名词」「值得注意的是」「不难发现」「综上所述」「首先、其次、最后」的堆叠。
+- 少用「被」和长「的」链；一句一个动作，主语尽量是领域对象，不用「我们」代替读者。
+- 不写「本文将介绍」「下面我们来看」；直接给读者要做的动作和看得见的结果。
+- 同一事实只留一处：标题、段首、块后不互相复述。
+- 英文术语不堆叠；能用中文说清就不夹英文，必须夹时首次给原文。
+
+## 让句子有信息量
+
+润色要的「灵性」不靠形容词，靠三件事：主语是具体对象，动词是具体动作，读完能看见结果。
+
+- 删掉章节行程，直接给对象和它回答的问题。
+  - 原句：这一章介绍棋盘类的设计，首先看成员，然后看落子，最后看胜负判定。
+  - 改写：棋盘只保存九个格子。落子、满盘、成线与赢家都由它回答。
+- 把「进行校验」「负责计算」换成调用方看得见的动作与返回值。
+  - 原句：程序会对输入进行校验，如果坐标不合法就会返回错误。
+  - 改写：坐标越界、格子被占用或对局已结束时，`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/readability.md

@@ -0,0 +1,55 @@
+# 新人可读性与任务完整性
+
+> 速查：读者能独立做完 = 前置 + 动作 + 结果 + 失败出口；术语首次出现给定义，条件写在动作前。
+
+本文件补句子规则之外的两件事：新人能不能独立完成任务，术语有没有解释。句子、段落与版式仍归 `steps/05-sentences.md`、`steps/04-paragraphs.md` 与 `steps/07-layout.md`；本文件不重复它们的规则。
+
+## 读者三问
+
+每个任务节要让读者回答三个问题：我在哪里、我要做什么、做完看到什么。
+
+- **前置**：开始前需要哪一章的结果、哪个文件、哪个环境或哪条命令。缺一项就补一句。
+- **动作**：一个步骤一个动作，动词开头，对象明确。
+- **结果**：命令输出、文件变化、界面变化、返回值或测试结果，至少有一项可观察。
+- **失败出口**：出错时看哪条信息、回到哪一节、下一步试什么。
+
+只写「运行脚本」而不写运行后看到什么，读者无法判断自己是否成功。
+
+## 术语
+
+术语的写法（首次「中文（English）」、一句可观察解释、缩写先全称、后文统一）以 `quarto/prose.md`「引号与术语」为准。本节只管解释放在哪里：
+
+- 解释放在首次真正使用的位置，不放章首清单，也不留给下一章补课。
+- 能换成日常词就不造术语；不为「显得专业」引入新词。
+- 判定句：把术语换成「这个东西」，句子是否仍然成立？不成立说明解释不够。
+
+## 步骤完整
+
+- 动作之后紧跟结果或验收方式，结果不要等到节末才出现。
+- 失败路径写触发条件、可观察现象与恢复动作，不写空泛的「注意报错」。
+- 操作节不插入与当前动作无关的设计辩论；取舍另起一段放在动作完成后。
+- 条件与动作的先后见 `quarto/prose.md`「条件与步骤」。
+
+## 完整性清单
+
+- [ ] 读者知道开始前需要什么：环境、文件、上一章产物。
+- [ ] 每个任务有可观察的完成标志，不只写「运行一下」。
+- [ ] 新术语首用有解释，缩写有全称。
+- [ ] 条件在动作前，一句只做一个动作。
+- [ ] 失败时知道看什么、回到哪一节。
+- [ ] 没有「以后会讲」但当前就必须使用的名字。
+- [ ] 删掉本段后读者仍能完成任务的内容已经删除。
+- [ ] 读者不需要作者的补充说明，就能把这一节独立走完。
+
+## 混排自查
+
+`python <skill>/scripts/checking-prose.py --root <book>` 检查中文与拉丁字母、数字、行内代码之间的空格，以及中文句里的半角标点。脚本只报高置信项，不替代人工回读。
+
+## 依据
+
+- Google developer documentation style guide：https://developers.google.com/style/highlights
+- Google Jargon：https://developers.google.com/style/jargon
+- Google sentence structure（条件先于指令）：https://developers.google.com/style/sentence-structure
+- Diátaxis 质量模型：https://diataxis.fr/quality/
+- Digital.gov Plain language：https://digital.gov/guides/plain-language/principles
+- 中文技术文档写作风格指南：https://zh-style-guide.readthedocs.io/