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

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

@@ -43,7 +43,7 @@ set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
 
 ## 块后悬空指代
 
-块后第一次提到代码块里的常量怎么写：点名标识符，不用「这 N 个 X」。块后段落首次提及围栏里的实体时点名标识符；先行词只出现在代码围栏里、不在任何句中时，「这 N 个 X」「它们」式省称没有可依的先行词，计数指代还容易盖错范围。条文见`steps/03-blocks.md`「内容块前后的闭环」。以 示例章定义坐标范围节改稿前为对照：
+块后第一次提到代码块里的常量怎么写：点名标识符，不用「这 N 个 X」。块后段落首次提及围栏里的实体时点名标识符；先行词只出现在代码围栏里、不在任何句中时，「这 N 个 X」「它们」式省称没有可依的先行词，计数指代还容易盖错范围。条文见 `steps/03-blocks.md`「内容块前后的闭环」。以 示例章定义坐标范围节改稿前为对照：
 
 ```text
 不佳（「这三个常量」开场，先行词只在上方围栏里；三个常量里只有 kRows、kCols 约束行列取值，kCellCount 给的是总数）：
@@ -59,7 +59,7 @@ set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
 
 ## 块后并列事实段拆引导词列表
 
-以 首章查看终局输出节改稿前为对照。块后一段串起三个以上并列区域的事实（版式、显示规则、结果行），句句完整却仍是多中心段，各项对应输出的哪一部分全靠读者自补；三项以上优先成列表（规则见`steps/07-layout.md`「列表选择」）：
+以 首章查看终局输出节改稿前为对照。块后一段串起三个以上并列区域的事实（版式、显示规则、结果行），句句完整却仍是多中心段，各项对应输出的哪一部分全靠读者自补；三项以上优先成列表（规则见 `steps/07-layout.md`「列表选择」）：
 
 ```text
 不佳（块后一段四句各讲一个区域，顺序与对应关系全靠读者自补）：

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

@@ -25,7 +25,7 @@
 
 ## 摘录导语只报出处
 
-导语点名读者要在块内观察的代码标识符，再给出处；只报出处的句子让读者把「行列坐标」这类中文概念对不上围栏里的名字。条文见`steps/03-blocks.md`「内容块前后的闭环」。以 示例章定义坐标范围节改稿前为对照：
+导语点名读者要在块内观察的代码标识符，再给出处；只报出处的句子让读者把「行列坐标」这类中文概念对不上围栏里的名字。条文见 `steps/03-blocks.md`「内容块前后的闭环」。以 示例章定义坐标范围节改稿前为对照：
 
 ```text
 不佳（导语只报出处，句中没有任何块内标识符）：
@@ -51,7 +51,7 @@
 
 ## 逐条释义代替动机
 
-块后把成员逐个介绍一遍怎么改：删掉逐条释义，换成边界设计加动机。讲解性正文（摘录导语与块后项目解释）要给出设计动机，不是把成员清单散文化重写；`X` 做A、`Y` 做B 式的连续释义只回答「是什么」，删掉后读者照样不知道为什么这样设计。条文见`steps/03-blocks.md`「内容块前后的闭环」。以 示例章检查坐标后读写节改稿前为对照：
+块后把成员逐个介绍一遍怎么改：删掉逐条释义，换成边界设计加动机。讲解性正文（摘录导语与块后项目解释）要给出设计动机，不是把成员清单散文化重写；`X` 做 A、`Y` 做 B 式的连续释义只回答「是什么」，删掉后读者照样不知道为什么这样设计。条文见 `steps/03-blocks.md`「内容块前后的闭环」。以 示例章检查坐标后读写节改稿前为对照：
 
 ```text
 不佳（四个成员逐条释义，句子骨架只是行尾注释的排列）：
@@ -138,11 +138,11 @@ constexpr bool IsInRange(Position position) {
 ```
 ````
 
-判定信号：导语点名了后块才出现的符号，或同一常量的讲解被拆成块前半句加块后半句。类型定义与其使用函数分成两块不是违规；禁的是整份头文件或整条调用链贴进同一个围栏。拆块豁免清单见`steps/03-blocks.md`「内容块前后的闭环」。
+判定信号：导语点名了后块才出现的符号，或同一常量的讲解被拆成块前半句加块后半句。类型定义与其使用函数分成两块不是违规；禁的是整份头文件或整条调用链贴进同一个围栏。拆块豁免清单见 `steps/03-blocks.md`「内容块前后的闭环」。
 
 ## 函数导语与成员列表的 示例章对照
 
-以 示例章改稿前三句为对照，规则见`steps/03-blocks.md`「内容块前后的闭环」、`steps/07-layout.md`「列表选择」、`scripts/verifying-content.py`「禁用与替换」（座位）：
+以 示例章改稿前三句为对照，规则见 `steps/03-blocks.md`「内容块前后的闭环」、`steps/07-layout.md`「列表选择」、`scripts/verifying-content.py`「禁用与替换」（座位）：
 
 ```text
 不佳（「另一座位」用了座位术语，且第二句未沿用 PlayerToOpponent 注释的说法）：
@@ -156,12 +156,12 @@ constexpr bool IsInRange(Position position) {
 不佳（引导句先数个数再把类名连写两次，列表项不是「是什么 + 开局取值」两句）：
 `Game` 有四个数据成员，`Game()` 默认构造之后是下面这样：
 - **状态面板**：`board_` 是空状态面板。
-- **轮次**：`current_player_` 是当前轮到的用户，开局是先手，使用 X 元素。
+- **轮次**：`current_owner_` 是当前轮到的用户，开局是先手，使用 X 元素。
 
 改写（引导句不数个数；每项恰好两句，第一句是什么，第二句只写开局取值）：
 `Game()` 默认构造之后，状态面板、当前用户、流程结果和操作记录是下面这样：
 - `board_` 是这一次的状态面板。开局是空状态面板。
-- `current_player_` 是当前轮到的用户。开局轮到先手。
+- `current_owner_` 是当前轮到的用户。开局轮到先手。
 ```
 
 ```text

package/skills/writing-quarto/examples/03-layout-list.md

@@ -4,7 +4,7 @@
 
 ## 定版式：构造后的成员并列成列表
 
-条文见`steps/07-layout.md`「列表选择」。四个数据成员的初始状态被写进同一句，读者要自己拆开「状态面板为空，轮到甲方，结果进行中，历史也为空」；改成引导词列表后，各项共享的访问规则留在列表后的一句，不拆进每一项。同一页教怎么写注释的 callout 一并删除：注释怎么写、行尾先写什么、`///` 与 `@` 标签怎么分工只留在 `.agents`（条文见`steps/03-blocks.md`）。
+条文见 `steps/07-layout.md`「列表选择」。四个数据成员的初始状态被写进同一句，读者要自己拆开「状态面板为空，轮到甲方，结果进行中，历史也为空」；改成引导词列表后，各项共享的访问规则留在列表后的一句，不拆进每一项。同一页教怎么写注释的 callout 一并删除：注释怎么写、行尾先写什么、`///` 与 `@` 标签怎么分工只留在 `.agents`（条文见 `steps/03-blocks.md`）。
 
 **定版式（示例章 `Game()` 构造后的块后段与 callout）：**
 
@@ -13,25 +13,25 @@
 `Game()` 默认构造后，状态面板为空，轮到甲方 操作，流程结果为进行中，历史也为空。状态面板、轮次、结果和历史都收在对象内部，外界只能通过读取函数查看，改动只发生在尝试操作的函数里。历史按操作先后排列，查询历史就能回放一次流程。
 
 ::: {.callout-note title="成员注释先写保存的对象"}
-行尾注释先写成员保存的对象，`history_` 就写“本局操作记录”。至于按什么顺序排列，属于第二句信息，由正文交代，不要让只写顺序的说明代替对象名。
+行尾注释先写成员保存的对象，`move_log_` 就写“本局操作记录”。至于按什么顺序排列，属于第二句信息，由正文交代，不要让只写顺序的说明代替对象名。
 :::
 
 改写（导语一句 + 列表四项 + 共享规则与历史顺序各留一句；callout 整段删除）：
 `Game()` 默认构造之后，四个数据成员是下面这样：
 
 - **状态面板**：`board_` 是空状态面板。
-- **轮次**：`current_player_` 为 `Player::kFirst`。
-- **结果**：`result_` 为 `Result::kInProgress`。
-- **历史**：`history_` 还没有操作。
+- **轮次**：`current_owner_` 为 `Player::kFirst`。
+- **结果**：`outcome_` 为 `Result::kInProgress`。
+- **历史**：`move_log_` 还没有操作。
 
-四项都在对象内部，读取函数可以查看，只有尝试操作的函数会改它们。`history_` 按操作先后排列，查询它就能回放这一次。
+四项都在对象内部，读取函数可以查看，只有尝试操作的函数会改它们。`move_log_` 按操作先后排列，查询它就能回放这一次。
 ````
 
 判定信号：一句里顿号、逗号并列三个以上数据成员且各项状态不同；callout 在教行尾先写什么、第二句交给谁，而不是告诉读者状态面板上发生了什么。
 
 ## 枚举成员释义列表
 
-工程章正文禁止枚举成员释义表或释义段；成员含义由源码行尾注释承载（写法见`steps/06-wording.md`「定用词：术语要稳」），正文只写谁调用、如何验收、与邻章关系。以 示例章终局与操作的状态码节改稿前为对照：
+工程章正文禁止枚举成员释义表或释义段；成员含义由源码行尾注释承载（写法见 `steps/06-wording.md`「定用词：术语要稳」），正文只写谁调用、如何验收、与邻章关系。以 示例章终局与操作的状态码节改稿前为对照：
 
 ```text
 不佳（枚举成员释义段，逐个成员复述源码注释）：
@@ -54,11 +54,11 @@
 三种强度都只改变选择的方式，棋规本身不变。
 ```
 
-判定信号：列表项格式是 `` `类型::成员`：含义 ``，且含义与枚举行尾注释或类型注释同义；正文删掉整个列表后，调用关系与验收路径仍完整。正文不复述注释的总规则见`examples/03-block-after.md`「块后复述注释」。
+判定信号：列表项格式是 `` `类型::成员`：含义 ``，且含义与枚举行尾注释或类型注释同义；正文删掉整个列表后，调用关系与验收路径仍完整。正文不复述注释的总规则见 `examples/03-block-after.md`「块后复述注释」。
 
 ## 列表字数带失衡
 
-同列各项字数相差两倍以上或引导词相差 4 字以上时，扫读节奏断裂（计量口径见`steps/07-layout.md`「列表选择」）。以 示例章失败策略列表改稿前为对照：
+同列各项字数相差两倍以上或引导词相差 4 字以上时，扫读节奏断裂（计量口径见 `steps/07-layout.md`「列表选择」）。以 示例章失败策略列表改稿前为对照：
 
 ```text
 不佳（引导词长度差 6 字，长项夹带流程频次旁白）：
@@ -70,7 +70,7 @@
 - **数据项被占用**：`PlacePiece` 返回 `false`，状态面板保持不变，调用方另选数据项就行。
 ```
 
-判定信号：同一列表内最长项冒号后字数 ≥ 最短项 × 2，或引导词相差 ≥ 4；长项的第二句删掉后主线仍闭合。章级定稿对照见`examples/08-appendix.md`「列表项长度均衡定稿」。
+判定信号：同一列表内最长项冒号后字数 ≥ 最短项 × 2，或引导词相差 ≥ 4；长项的第二句删掉后主线仍闭合。章级定稿对照见 `examples/08-appendix.md`「列表项长度均衡定稿」。
 
 ## 公式与换算讲解段
 
@@ -106,19 +106,19 @@ $$
 下面的图按行标出 `cells_` 的数组下标，加粗的是下标 5。
 ```
 
-判定信号：`return` 行之外另排 `$$` 或行内数学模式；换算句没点名载体（「一个下标」「这个下标」「这次代入」互相指代，或导语用「这个下标」而全句未写出是 `cells_` 的数组下标）；一句里同时出现跳过整行、列偏移、代入数字与得数；公式项列表；导语用反引号扛公式本体；代入段里列号与「第 N 列」混用（列号从 0 起算，「第 2 列」会让人从 1 数起）；图已经标出的下标区间在图前再列一遍。「换算只发生在 `Board` 内部」这类局部实现事实本身合法（见 `language-scope.md` 的「流程交流不绑定媒介与行为刚性表述」的判定信号），多处复述或混进图导览段才违规。换算句式规则见`steps/07-layout.md`「列表选择」换算条。
+判定信号：`return` 行之外另排 `$$` 或行内数学模式；换算句没点名载体（「一个下标」「这个下标」「这次代入」互相指代，或导语用「这个下标」而全句未写出是 `cells_` 的数组下标）；一句里同时出现跳过整行、列偏移、代入数字与得数；公式项列表；导语用反引号扛公式本体；代入段里列号与「第 N 列」混用（列号从 0 起算，「第 2 列」会让人从 1 数起）；图已经标出的下标区间在图前再列一遍。「换算只发生在 `Board` 内部」这类局部实现事实本身合法（见 `language-scope.md` 的「流程交流不绑定媒介与行为刚性表述」的判定信号），多处复述或混进图导览段才违规。换算句式规则见 `steps/07-layout.md`「列表选择」换算条。
 
 ## 未定义名字的调用链
 
-以 示例章改稿前为对照。章引言用后文才定义的名字串起一条必须看懂的调用链，读者在第一个分句就遇到三个没讲过的名字（步骤：排列内容块；规则见`steps/03-blocks.md`「内容块前后的闭环」）：
+以 示例章改稿前为对照。章引言用后文才定义的名字串起一条必须看懂的调用链，读者在第一个分句就遇到三个没讲过的名字（步骤：排列内容块；规则见 `steps/03-blocks.md`「内容块前后的闭环」）：
 
 ```text
 不佳（编号步骤用后文才定义的名字串起调用链）：
 从操作到查询结果的调用链如下：
 
-1. `Game::Place` 校验这次操作，通过后经 `Board::PlacePiece` 把元素写入状态面板。
+1. `Game::ApplyMove` 校验这次操作，通过后经 `Board::WriteCell` 把元素写入状态面板。
 2. 元素写入后，`JudgeAfterPlace` 在新状态面板上判定 `Result`，其中 `HasPlayerLine` 检查是否三连。
-3. 对外的 `GetResult` 读取成员 `result_`，返回最近一次判定的流程结果。
+3. 对外的 `GetResult` 读取成员 `outcome_`，返回最近一次判定的流程结果。
 
 改写（整段删除，不改写后留在原位；各名字在后面的小节按依赖顺序登场）：
 （删除三条编号步骤。讲述按「类型 → 数据 → 简单函数 → 判定 → 组装」排列，最后的小节只摘 Place，被调函数都已在前文出现。）
@@ -152,7 +152,7 @@ enable_testing() 开启 CTest……。add_test 用 NAME 和 COMMAND……。set_
 
 ## 凑三项拆列表
 
-以一段启动说明改稿前为对照（规则见`steps/07-layout.md`「列表选择」）：
+以一段启动说明改稿前为对照（规则见 `steps/07-layout.md`「列表选择」）：
 
 ```text
 不佳（同一件事拆成三项，第三项只为凑足数量）：

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

@@ -1,6 +1,6 @@
 # Quarto 元素写法正反对照
 
-元素细则（filename 标注、闭环、盒子密度、Callout）见`steps/03-blocks.md`；本文件保存元素写法的正反对照，检索单元是「正确 + 不佳 + 改写」。
+元素细则（filename 标注、闭环、盒子密度、Callout）见 `steps/03-blocks.md`；本文件保存元素写法的正反对照，检索单元是「正确 + 不佳 + 改写」。
 
 ## 代码块导语元计数对照
 
@@ -76,7 +76,7 @@ constexpr bool IsInRange(Position position) { … }
 终端程序打印的三行对应图中每个数据项的 CellState::kEmpty。
 ````
 
-判定信号：图后句删掉任一分句中心仍成立；图注或桥接句已写明的信息在图后再讲一遍。图后正文只给图注讲不完的新结论，图后对照与句段侧的冒号分号堆叠见`examples/04-paragraph-opening.md`「冒号后堆叠分号解释」。
+判定信号：图后句删掉任一分句中心仍成立；图注或桥接句已写明的信息在图后再讲一遍。图后正文只给图注讲不完的新结论，图后对照与句段侧的冒号分号堆叠见 `examples/04-paragraph-opening.md`「冒号后堆叠分号解释」。
 
 ## 块后解释先于图对照
 
@@ -116,7 +116,7 @@ struct Move { … };
 
 ## 摘录导语只报出处
 
-代码块导语要点名块内的什么：点名读者要在块内观察的代码标识符，再给出处；只报出处的句子让读者把「行列坐标」这类中文概念对不上围栏里的名字。条文见`steps/03-blocks.md`「内容块前后的闭环」。以 示例章定义坐标范围节改稿前为对照：
+代码块导语要点名块内的什么：点名读者要在块内观察的代码标识符，再给出处；只报出处的句子让读者把「行列坐标」这类中文概念对不上围栏里的名字。条文见 `steps/03-blocks.md`「内容块前后的闭环」。以 示例章定义坐标范围节改稿前为对照：
 
 ```text
 不佳（导语只报出处，句中没有任何块内标识符）：
@@ -131,7 +131,7 @@ struct Move { … };
 
 ## 递进片段拆围栏对照
 
-同源围栏的合并已收窄：只有紧邻常量与其直接使用行才放在同一个围栏；类型定义和后一步使用它的函数是两步，分成两块，每块各配一句完整导语。判定与豁免见`steps/03-blocks.md`「内容块前后的闭环」；句段对照见`examples/03-excerpt-lead.md`「递进片段合并」。
+同源围栏的合并已收窄：只有紧邻常量与其直接使用行才放在同一个围栏；类型定义和后一步使用它的函数是两步，分成两块，每块各配一句完整导语。判定与豁免见 `steps/03-blocks.md`「内容块前后的闭环」；句段对照见 `examples/03-excerpt-lead.md`「递进片段合并」。
 
 ````text
 不佳（拆成三个同源围栏，各配半句导语，首句点名了后块符号）：

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

@@ -4,7 +4,7 @@
 
 ## 自然段多中心未拆
 
-以 示例章无标题引言改稿前为对照。一段同时承担承接上一章、交付物清单、源文件位置与摘录声明四件事，第二句还用顿号串四个交付物。章引言的形态契约（`steps/02-structure.md`）已改为「单段 ± 列表」：多中心时并段或改列表，禁止拆成两个散文段（拆段触发表见`steps/04-paragraphs.md`「段落规则」）：
+以 示例章无标题引言改稿前为对照。一段同时承担承接上一章、交付物清单、源文件位置与摘录声明四件事，第二句还用顿号串四个交付物。章引言的形态契约（`steps/02-structure.md`）已改为「单段 ± 列表」：多中心时并段或改列表，禁止拆成两个散文段（拆段触发表见 `steps/04-paragraphs.md`「段落规则」）：
 
 ```text
 不佳（一段四职责，顿号串四个交付物；拆成三个散文段同样违规）：
@@ -18,7 +18,7 @@
 
 ## 段内同义堆叠
 
-以 示例章「用数组存放九个数据项」的块后段改稿前为对照。中心句之后连续两句都在换说法解释同一个事实（长度在编译期确定），没有引入新机制，属于段内同义堆叠；相邻的同义合并规则管跨段落，这里管同一段内部（规则见`steps/04-paragraphs.md`「段内同义堆叠禁令」）：
+以 示例章「用数组存放九个数据项」的块后段改稿前为对照。中心句之后连续两句都在换说法解释同一个事实（长度在编译期确定），没有引入新机制，属于段内同义堆叠；相邻的同义合并规则管跨段落，这里管同一段内部（规则见 `steps/04-paragraphs.md`「段内同义堆叠禁令」）：
 
 ```text
 不佳（中心句后两句换说法复述「数量不变」，第三句又突然换主题）：
@@ -54,7 +54,7 @@
 
 ## 散文伪标签冒号与多核混段
 
-以 示例章数组存储节的块后段为对照。同一句里叠了两层问题：冒号前是「话题标签」，读感像词条；前半讲长度、后半讲容器，两个中心挤进一段（规则与拆核四步见`steps/04-paragraphs.md`「散文伪标签冒号禁令」「拆核四步」）：
+以 示例章数组存储节的块后段为对照。同一句里叠了两层问题：冒号前是「话题标签」，读感像词条；前半讲长度、后半讲容器，两个中心挤进一段（规则与拆核四步见 `steps/04-paragraphs.md`「散文伪标签冒号禁令」「拆核四步」）：
 
 ```text
 不佳（散文里「话题标签：解释」词条式冒号；长度与容器两个中心混在一段）：
@@ -72,7 +72,7 @@
 
 ## 定段落：类型接线段整段删除
 
-块后的类型接线句怎么判：块后没有新信息就整段删除。条文见`steps/05-sentences.md`「一次对话」。这段在定段落判为不合格：块后没有新信息，整段删除，不走拉链的三条改写。对照保留 `Move` 的导语与围栏注释，轮到谁由后文 `Game::Place` 一节承担。
+块后的类型接线句怎么判：块后没有新信息就整段删除。条文见 `steps/05-sentences.md`「一次对话」。这段在定段落判为不合格：块后没有新信息，整段删除，不走拉链的三条改写。对照保留 `Move` 的导语与围栏注释，轮到谁由后文 `Game::ApplyMove` 一节承担。
 
 **定段落（示例章 `Move` 块后，类型接线与轮到谁叠进一段）：**
 
@@ -80,7 +80,7 @@
 不佳（前两个逗号分句各自是「成员叫法 + 使用 + 某一章的类型」，后句换讲轮次；「全部信息」又被下一句的「两个不同的问题」否定）：
 `Move` 的位置直接使用上一章的 `Position`，用户字段使用本节的 `Player`，一个结构体装下一次操作的全部信息。先手和后手交替操作，一次操作由当时轮到的用户提交。
 
-改写（整段删除，不另写替身句：导语已写「一次操作要带上目标位置和操作的用户」，围栏注释已写 position 是操作的行列坐标、player 是执行操作的用户；交替操作留在 `Game::Place` 一节）：
+改写（整段删除，不另写替身句：导语已写「一次操作要带上目标位置和操作的用户」，围栏注释已写 position 是操作的行列坐标、player 是执行操作的用户；交替操作留在 `Game::ApplyMove` 一节）：
 （删除）
 ```
 

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

@@ -8,8 +8,8 @@
 
 ````text
 不佳（一块后把私有性、三个成员、const、[[nodiscard]] 串成一段）：
-成员 cells_ 保持私有，调用者能读写的只有 Game::GetCellState、Game::Place、
-Game::GetResult 这三个成员。Game::GetCellState 与 Game::GetResult 声明为 const，
+成员 cells_ 保持私有，调用者能读写的只有 Game::ReadCellState、Game::ApplyMove、
+Game::GetResult 这三个成员。Game::ReadCellState 与 Game::GetResult 声明为 const，
 读取动作不改变状态面板。三个接口都标注 [[nodiscard]]：查询结果与操作结果都不该被调用方无视。
 
 改写（块前场景已点名与划界；代码展示声明；块后删除复述，语言属性不进旁白）：
@@ -67,7 +67,7 @@ Game::GetResult 这三个成员。Game::GetCellState 与 Game::GetResult 声明
 先看项目动态库目录 `example/`。数据项的定义在 `include/state.h`，实现放在 `src/state.cpp`。
 ```
 
-判定信号：把问题和答案首句各缩成一个对象名词，两者不一致即错位；补细节不等于换对象；问答中的文件、路径与标识符指称挂了链接也命中（统一行内代码，`verifying-content.py` 对自测节链接记 WARN，规则见`steps/02-structure.md`）。
+判定信号：把问题和答案首句各缩成一个对象名词，两者不一致即错位；补细节不等于换对象；问答中的文件、路径与标识符指称挂了链接也命中（统一行内代码，`verifying-content.py` 对自测节链接记 WARN，规则见 `steps/02-structure.md`）。
 
 ## 冒号后堆叠分号解释
 

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。