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

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

@@ -5,25 +5,29 @@
 
 ## 通用情况
 
+### 标点与中英混排
+
+中文标点、中西文边界空格、引号、数字与英文术语的细则见 `quarto/prose.md`；本步不重复附表。判定顺序：先改标点与空格，再改列表与加粗，最后回读。
+
 ### 列表选择
 
 目录列表后能用段落补一个遗漏的目录吗：不能，并列成员一次列全。列表选择规则：
 
-- **无序列表**：并列概念、范围边界、要点枚举——各项之间没有先后或因果；代码块后的逐条讲解格式见`steps/04-paragraphs.md`「段落规则」。
+- **无序列表**：并列概念、范围边界、要点枚举——各项之间没有先后或因果；代码块后的逐条讲解格式见 `steps/04-paragraphs.md`「段落规则」。
 - **有序列表**：有先后顺序的步骤或链路——执行顺序本身就是信息（如配置 → 编译 → 测试 → 运行）。
 - 列表项结构平行：起首用同类的词（都是名词短语，或都是动词短语），长度相近。
-- **列表字数带**：同一列表各项保持视觉齐长，避免扫读节奏断裂。计量：引导词汉字数、冒号后汉字数（行内代码按标识符计）。失衡判定：冒号后最长 ≥ 最短 × 2，或引导词相差 ≥ 4。改写顺序：删长项多余中心 → 拆多中心 → 过短项按简洁边界补全 → 停止。豁免：出错原因/正确做法；有序步骤；着陆页卡片。列表齐长服从句段主规则，假拆禁令见`steps/04-paragraphs.md`。
+- **列表字数带**：同一列表各项保持视觉齐长，避免扫读节奏断裂。计量：引导词汉字数、冒号后汉字数（行内代码按标识符计）。失衡判定：冒号后最长 ≥ 最短 × 2，或引导词相差 ≥ 4。改写顺序：删长项多余中心 → 拆多中心 → 过短项按简洁边界补全 → 停止。豁免：出错原因/正确做法；有序步骤；着陆页卡片。列表齐长服从句段主规则，假拆禁令见 `steps/04-paragraphs.md`。
 - 列表项起首用加粗引导词标记中心语，读者扫读时先看到分类再决定是否细读；关键词取同类词（如「显示状态面板」「读入坐标」），并按对象的发生顺序排列，读者扫读即得顺序与内容。
-- 行为或规则枚举项用「**动词短语引导词**：完整句」格式：引导词命名本项的中心动作（如「**显示状态面板**」「**判定流程结果**」），冒号后保留完整中文句，写全动作、对象与结果。引导词是扫读索引，不替代句子信息，不为省字把冒号后压成电报短句（对照见`examples/03-layout-list.md`）。
-- 解释并列名称的引导词列表放在首次使用这些名称的代码块或目录树之前：读者先经列表认识每个名称，再看结构展示；禁止把解释压到块后，读者会带着未解释的名称读块。名称本身用读者可核对的具体形态（如「项目动态库」），不用模糊统称（术语依据见`steps/06-wording.md`）。
-- 并列成员一次列全：目录、组件等并列对象（含 `build/` 这类构建生成的目录）并入同一个引导词列表，先列全再展示目录树等结构；列表之后不用段落补列遗漏的成员（对照见`examples/04-paragraph-opening.md`「角色总述段」）。
-- 目录树的列对齐（目录 `#/`、文件 `#` 右移 4 列、同一棵树只一档注释）见`steps/03-blocks.md`「情况：目录树」；本文件只管列表、标点与加粗，不另写一份树规则。
+- 行为或规则枚举项用「**动词短语引导词**：完整句」格式：引导词命名本项的中心动作（如「**显示状态面板**」「**判定流程结果**」），冒号后保留完整中文句，写全动作、对象与结果。引导词是扫读索引，不替代句子信息，不为省字把冒号后压成电报短句（对照见 `examples/03-layout-list.md`）。
+- 解释并列名称的引导词列表放在首次使用这些名称的代码块或目录树之前：读者先经列表认识每个名称，再看结构展示；禁止把解释压到块后，读者会带着未解释的名称读块。名称本身用读者可核对的具体形态（如「项目动态库」），不用模糊统称（术语依据见 `steps/06-wording.md`）。
+- 并列成员一次列全：目录、组件等并列对象（含 `build/` 这类构建生成的目录）并入同一个引导词列表，先列全再展示目录树等结构；列表之后不用段落补列遗漏的成员（对照见 `examples/04-paragraph-opening.md`「角色总述段」）。
+- 目录树的列对齐（目录 `#/`、文件 `#` 右移 4 列、同一棵树只一档注释）见 `steps/03-blocks.md`「情况：目录树」；本文件只管列表、标点与加粗，不另写一份树规则。
 - 三项以上、或每项内含解释的信息优先成列表；只有两项且能写进一句的保留正文；只有一项时不设列表，写进正文（节内无代码块或列表承接时，整节收成一句）。
-- **不为凑三项拆列表**：列表项各要有一条独立信息；同一事实的碎片拆成三项、或为对齐硬补一项，都改回完整句，两项各有信息就写两项（对照见`examples/03-layout-list.md`「凑三项拆列表」）。
-- **构造后的成员并列成列表**：同一句或同一段用顿号、逗号并列三个及以上数据成员、而且各项状态不同时，改成引导词列表；列表放在数据成员围栏**之前**，引导句不数个数、不把类名连写两次，也不写「成员写在该类里」——只把「构造之后的取值」引出来（如「`Game()` 默认构造之后，状态面板、当前用户、流程结果和操作记录是下面这样：」）。每一项恰好两句：第一句写成员是什么，第二句只写开局取值；第二句可以是「开局是空状态面板」这类状态句。枚举取值列表的位置见`steps/03-blocks.md`「三级标题最小模块」，本文件不重写；枚举成员的含义仍留在源码行尾注释，这里列的是构造之后每个数据成员的状态，不是把枚举成员再解释一遍。依据：C++ Primer 把名字和初值分开讲，阮一峰一句一事。
-- **成员围栏前不列类型**：禁止「`board_` 用 `Board`，`current_player_` 用 `Player`」这种把类型再列一遍的句子——类型已经在围栏里。列表前的导语只点名要展开的维度，不把列表项里的取值先写一遍。
+- **不为凑三项拆列表**：列表项各要有一条独立信息；同一事实的碎片拆成三项、或为对齐硬补一项，都改回完整句，两项各有信息就写两项（对照见 `examples/03-layout-list.md`「凑三项拆列表」）。
+- **构造后的成员并列成列表**：同一句或同一段用顿号、逗号并列三个及以上数据成员、而且各项状态不同时，改成引导词列表；列表放在数据成员围栏**之前**，引导句不数个数、不把类名连写两次，也不写「成员写在该类里」——只把「构造之后的取值」引出来（如「`Game()` 默认构造之后，状态面板、当前用户、流程结果和操作记录是下面这样：」）。每一项恰好两句：第一句写成员是什么，第二句只写开局取值；第二句可以是「开局是空状态面板」这类状态句。枚举取值列表的位置见 `steps/03-blocks.md`「三级标题最小模块」，本文件不重写；枚举成员的含义仍留在源码行尾注释，这里列的是构造之后每个数据成员的状态，不是把枚举成员再解释一遍。依据：C++ Primer 把名字和初值分开讲，阮一峰一句一事。
+- **成员围栏前不列类型**：禁止「`board_` 用 `Board`，`current_owner_` 用 `Player`」这种把类型再列一遍的句子——类型已经在围栏里。列表前的导语只点名要展开的维度，不把列表项里的取值先写一遍。
 - **`private:` 不作正文话题**：围栏里可以保留源码的 ` private:`，因为片段必须和头文件逐字一致；「存放在 `private:` 下」「都在 `private:` 下」一类把访问说明符当话题的句子删掉，换成该 `##` 标题里的对象。
-- **列表后直接进围栏**：成员取值列表的每一项先写这个成员是什么，再写开局状态；状态是枚举值时写出含义，不单写 `Player::kFirst` 或 `Result::kInProgress`。列表之后直接进数据成员围栏，围栏后不再放取值列表或同义复述段；成员的先后顺序、关联的结果类型等话题留到使用它们的函数小节再讲，不在成员节预告。围栏前的成员列表与随后成员注释的用词接近、围栏后不复述，见`steps/05-sentences.md`。
+- **列表后直接进围栏**：成员取值列表的每一项先写这个成员是什么，再写开局状态；状态是枚举值时写出含义，不单写 `Player::kFirst` 或 `Result::kInProgress`。列表之后直接进数据成员围栏，围栏后不再放取值列表或同义复述段；成员的先后顺序、关联的结果类型等话题留到使用它们的函数小节再讲，不在成员节预告。围栏前的成员列表与随后成员注释的用词接近、围栏后不复述，见 `steps/05-sentences.md`。
 - **换算条（行列到下标的换算怎么写）**：
   - **点名**：第一次就写出是哪一种数。`cells_` 的数组下标、行号 `row`、列号 `col` 各用自己的名字。禁止「一个下标」「这个下标」「这次代入」互相指代。
   - **次序**：放在代码围栏和图之间的**同一段**，一句一个动作，后句接住前句的得数。第 0 行写出具体下标；下一句写第 `row` 行的起点；再一句写 `col` 从 0 加在这个起点上；然后一句只给出 `(1, 2)` 的三个数；最后一句只写算式和得数。禁止把跳过整行、列偏移、代入数字和得数写进同一句。
@@ -39,24 +43,24 @@
 ### 标点与中英混排
 
 - 中文用全角标点；并列英文用顿号；中文与英文/数字之间留半角空格。
-- 破折号夹解释的句子级判法见`steps/05-sentences.md`（冒号合法场合见`steps/04-paragraphs.md`「散文伪标签冒号禁令」）。
+- 破折号夹解释的句子级判法见 `steps/05-sentences.md`（冒号合法场合见 `steps/04-paragraphs.md`「散文伪标签冒号禁令」）。
 - `true` / `false` / `nullptr` 等 C++ 关键字用行内代码原样书写，不写中文译名。
 
 ### 外部规范对照
 
 - 阮一峰《中文技术文档的写作规范》：句长、中英混排空格、标点全角；标题不跳级、同级不孤立。
 - Google developer documentation style guide：一段一意、先给最重要信息；任务级标题用动词。
-- 华为《中文技术文档写作风格指南》：标题层级与句式；段落长度条文统一指向`steps/04-paragraphs.md`。
+- 华为《中文技术文档写作风格指南》：标题层级与句式；段落长度条文统一指向 `steps/04-paragraphs.md`。
 - GB/T 15834—2011《标点符号用法》：顿号层级与标点用法。
 - 阿里 f2e-spec writing：中英混排与标点。
 
 ### 定版式：格式要降噪
 
-- 行内代码与平台名词的版式判定见`steps/02-structure.md`。
-- 可复制命令使用指定语言的代码围栏；命令与输出分开的判定见`steps/02-structure.md`。
-- 标题与导航不用行内代码的判定见`steps/02-structure.md`；中英文之间的空格见`steps/06-wording.md`。
-- 列表用于并列或顺序关系，选择判定见`steps/07-layout.md`「列表选择」。表格只用于需要对多个属性进行比较的内容：同一主题的属性合并成一张表，不按小节拆成多张薄表；只有一两列信息或右侧大量留白时改用句子或列表。列表是版式选择，不是新的一段说明。
-- Callout 只承载可跳过提示的判定见`steps/03-blocks.md`。
+- 行内代码与平台名词的版式判定见 `steps/02-structure.md`。
+- 可复制命令使用指定语言的代码围栏；命令与输出分开的判定见 `steps/02-structure.md`。
+- 标题与导航不用行内代码的判定见 `steps/02-structure.md`；中英文之间的空格见 `steps/06-wording.md`。
+- 列表用于并列或顺序关系，选择判定见 `steps/07-layout.md`「列表选择」。表格只用于需要对多个属性进行比较的内容：同一主题的属性合并成一张表，不按小节拆成多张薄表；只有一两列信息或右侧大量留白时改用句子或列表。列表是版式选择，不是新的一段说明。
+- Callout 只承载可跳过提示的判定见 `steps/03-blocks.md`。
 
 具体元素写法见 `quarto/authoring.md`，终端步骤见 `quarto/terminal.md`。
 

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

@@ -7,7 +7,7 @@
 
 ### 信号表（句段与注释，按步骤命中即改）
 
-同一张表扫 `content/**` 与 `.agents/**`；载体差异按`steps/06-wording.md` 的「不同文件的语气」表（压缩语气豁免不适用于读者正文）。高精度项由 `verifying-content.py` 固化，其余靠人工过表；「步骤」列对齐 `SKILL.md` 的写作步骤：
+同一张表扫 `content/**` 与 `.agents/**`；载体差异按 `steps/06-wording.md` 的「不同文件的语气」表（压缩语气豁免不适用于读者正文）。高精度项由 `verifying-content.py` 固化，其余靠人工过表；「步骤」列对齐 `SKILL.md` 的写作步骤：
 
 | 步骤 | 信号 | 判定 | 依据 |
 | --- | --- | --- | --- |
@@ -34,17 +34,13 @@
 | 定句子 | 假对比「这不仅是 X，更是 Y」两半并不都提供信息；起跑式铺垫（「在开始之前」「首先我们来看」）；句尾把一次操作拔高成意义 | 删宣布与拔高；两半都有信息时保留对比 | `steps/05-sentences.md`「情况：假对比、起跑式铺垫与意义拔高」 |
 | 定句子 | 两个名词粘成一个叫法仍带「的」，或三个以上名词、动词定语省了「的」 | 按「结构助词「的」」判定去留与口诀改写 | `steps/05-sentences.md`「结构助词「的」」 |
 | 定句子 | 没点名载体（「一个下标」「这个下标」「这次代入」），或一句里同时有跳过整行、列偏移和得数，或公式项列表 | 按列表选择换算条写成同一段短句 | `steps/07-layout.md`「列表选择」 |
-| 定句子 | `Get*` 概述纯名词句（`/// 当前流程结果。`） | 改「获取…」，动词与函数名前缀硬对齐 | `steps/03-blocks.md` |
+| 定句子 | `Get*` 概述纯名词句（`/// 当前流程结果。`） | 改「获取…」，动词与函数名前缀硬对齐；只对齐围栏里的声明，不改源码注释 | `steps/03-blocks.md` |
 | 定句子 | 分支解释把条件压在句首（拒绝、终局句读到句末才知道结果） | 主句先写可观察结果，条件跟在后面或另起一句 | `steps/05-sentences.md`「句子规则」 |
-| 定版式 | 配置与脚本注释混用句式形状（裸完整句与话题句并存） | 按文件定一种形状：键值配置与构建脚本用「话题：一句完整说明。」，`.gitignore` 等点文件用名词短语 | `steps/05-sentences.md`「情况：围栏里的注释」 |
-| 定句子 | 「第二道…防线」类实现注 | 删 | `steps/03-blocks.md` |
 | 定句子 | 行尾把格子状态、先手或后手、操作动作写进同一句 | 换成术语表「数据项类型」里的三句，与头文件逐字一致 | `steps/05-sentences.md`、`steps/06-wording.md` |
-| 定句子 | 注释把下一行的形参比较（「检查 position 是否…」）或坐标写死、各查几次再写一遍 | 函数体只是一次比较或 `all_of` 时不写，只写代码看不出的例外；扫描注释只写检查哪一组线 | `steps/05-sentences.md`「函数概述跟注释」 |
-| 定句子 | 成员或函数细节只剩「按…存放 / 排列 / 记录」而没有领域对象 | 先补本体（如 `history_` 行尾补「本局操作记录。」），列宽不够再删动作半句；这条只改源码注释，不进入 qmd | `steps/05-sentences.md`「函数概述跟注释」 |
 | 定句子 | 一句里的量被「确定、体现、界定、表达」盖住（时间义「已经确定」合格） | 改写成相等、乘除加减、上下界或成员记法；「由 A 得到 B」「将 A 转换为 B」的换算注释不在此改 | `steps/05-sentences.md`「关系写成能核对的运算」 |
 | 定段落 | 散文伪标签冒号（话题 + `：` 词条式冒号）；多核混段 | 词条式冒号改完整主谓句或真列表项；多核混段按拆核四步改写 | `steps/04-paragraphs.md`「散文伪标签冒号禁令」「拆核四步（多核混段的拆段方法）」 |
 | 定版式 | 成员函数声明间无空行、qmd 围栏坍缩 | 补空 1 行；围栏保留源码空白 | `steps/03-blocks.md`「类与多函数摘录的垂直空白」 |
-| 定版式 | 注释位置混用（同一意图忽上忽下）、行尾超 100 列 | 按位置矩阵；超宽整条回退上一行 | `steps/03-blocks.md` |
+| 定版式 | 行尾超 100 列 | 超宽整条回退上一行 | `steps/03-blocks.md` |
 | 定版式 | 列表项字数失衡（冒号后最长 ≥ 最短 ×2，或引导词相差 ≥4） | 删长项多余中心 → 拆多中心 → 过短项按简洁边界补全 | `steps/07-layout.md`「列表选择」、`examples/03-layout-list.md`「列表字数带失衡」 |
 | 定版式 | 凑三项拆列表：列表项只是同一事实的碎片，各自没有独立信息 | 改回完整句；两项各有信息就写两项 | `steps/07-layout.md`「列表选择」 |
 | 定句子 | 句号后下一句以「它」开头且下一个字不是「们」 | 话题没换就不写「它」，主语空缺或写回原类型名 | `steps/05-sentences.md`「同档并句」 |
@@ -58,7 +54,7 @@
 
 ### 润色流程：沿着步骤走
 
-润色任务沿 `SKILL.md` 的写作步骤执行，从定任务走到通过检查，跳步视为未完成；判定标准见`steps/06-wording.md`。两种走法共用 1–9：**增量润色**保持最小改动，只改判为不合格的句子，不做风格重塑；**全章重构**按 `SKILL.md`「两种走法」走——章级（1–2）先定删留不动句子，节级（3–4）只拆块和段，句级（5–7）逐句拆开再写回去，该层全部重组，不走最小改动。执行时遵守定段落节的既有判定：分句骨架在定句子判为不合格，不在定段落里顺手改句子。
+润色任务沿 `SKILL.md` 的写作步骤执行，从定任务走到通过检查，跳步视为未完成；判定标准见 `steps/06-wording.md`。两种走法共用 1–9：**增量润色**保持最小改动，只改判为不合格的句子，不做风格重塑；**全章重构**按 `SKILL.md`「两种走法」走——章级（1–2）先定删留不动句子，节级（3–4）只拆块和段，句级（5–7）逐句拆开再写回去，该层全部重组，不走最小改动。执行时遵守定段落节的既有判定：分句骨架在定句子判为不合格，不在定段落里顺手改句子。
 
 **先切模块，再套规则。** 任何一步动笔前先把文本切成单位，围栏、YAML 与链接 URL 跳过（脚本按同一口径统计，计数见 `verifying-content.py` 输出）：
 
@@ -68,19 +64,19 @@
 - **句子**：段内按「。！？」切开。只做一句一中心、拉链、句内骨架、和下一句是否互相否定。
 - **列表项**：`-` 或有序编号。只做一项一中心、平行、字数带。不把列表项当散文拉链改。
 - **表格单元格**：管道表。一表一事；格里写事实，不写第二篇散文。
-- **块**：导语、围栏、块后、Callout。围栏不是句子；块后新信息的判定见`steps/03-blocks.md`。
+- **块**：导语、围栏、块后、Callout。围栏不是句子；块后新信息的判定见 `steps/03-blocks.md`。
 
-「一次对话」不与这些单位并列成切分单位：脚本切得出标题、空行、句号、列表和表格，切不出「一次说话」。它只留在`steps/05-sentences.md`「一次对话」的判定里——定段落先问这段有几件内容，再决定删、拆或切成几次说话；定句子才改措辞。
+「一次对话」不与这些单位并列成切分单位：脚本切得出标题、空行、句号、列表和表格，切不出「一次说话」。它只留在 `steps/05-sentences.md`「一次对话」的判定里——定段落先问这段有几件内容，再决定删、拆或切成几次说话；定句子才改措辞。
 
 1. **普查建账**：`git ls-files` 按扩展名分类，列出全部含中文自然语言的文件（跳过机器生成物与二进制）。台账写 `temp/`（不入库），逐文件记「审读状态／修改数／备注」；任务结束前每行落到「已审」，无问题也记「未发现」。覆盖率由 `verifying-content.py` 的「中文体检」项背书：台账文件总数与脚本输出的载体组计数对不上即为漏审。
 2. **沿步骤逐篇走**：从定任务到通过检查，每步只改该步判为不合格的句子；后一步发现前一步没做完，退回那一步，不在当前步补结构。某句只在定用词失败，就不重写它的结构；某段在定句子失败，先改骨架，再让定用词看一遍。已合格的句子不重润。
-3. **改写**：最小改动，只改判为不合格的句子，不做风格重塑。改写不破检查：qmd 导语 token 与句数、段落篇幅、禁用词由 `verifying-content.py` 把关；中文文件保持 UTF-8 无 BOM、LF。代码围栏与源码注释同源：改源码注释前先 grep 各 qmd 围栏，被逐字引用的两侧同改；同源复制文件改一处同步其余并 diff 比对。改动触及知识库案例引用句时先 grep 案例文件再同步。
-4. **验收同步**：按改动域跑校验（qmd → `verifying-content.py` + `checking-links.py`；有项目技能时按它列出的命令，跨域收尾跑它的全量 profile）。检查次数与停手见`steps/09-check.md`「完成判据」。
+3. **改写**：最小改动，只改判为不合格的句子，不做风格重塑。改写不破检查：qmd 导语 token 与句数、段落篇幅、禁用词由 `verifying-content.py` 把关；中文文件保持 UTF-8 无 BOM、LF。代码围栏逐字摘自源文件，本步骤不改围栏；同源复制文件改一处同步其余并 diff 比对。改动触及知识库案例引用句时先 grep 案例文件再同步。
+4. **验收同步**：按改动域跑校验（qmd → `verifying-content.py` + `checking-links.py`；有项目技能时按它列出的命令，跨域收尾跑它的全量 profile）。检查次数与停手见 `steps/09-check.md`「完成判据」。
 
 ### 完成前核对
 
 - [ ] 信号表逐行扫过，FAIL 清零；WARN 记台账不追清。
-- [ ] 章节骨架与 `steps/02-structure.md` 一致；引言形态守`steps/02-structure.md`。
+- [ ] 章节骨架与 `steps/02-structure.md` 一致；引言形态守 `steps/02-structure.md`。
 - [ ] 与改前文本对照过：没有新增原文没有的事实、遗漏读者需要的信息，或把限定说成确定；判法见本文件「情况：对照改前文本」。
 - [ ] `verifying-content.py` 与 `checking-links.py` 通过，证据在 `temp/`。
 

package/templates/quarto-book-project/SKILL.md

@@ -22,7 +22,7 @@ description: 记录某一本 Quarto Book 的项目级约定：书名、读者、
 
 - 章节顺序的唯一来源：根 `_quarto.yml` 的 `book.chapters`。
 - 每章的类章或能力章、关键对象、`title` 与二级标题：`writing/chapter-map.md`。
-- 目录布局：`content/<part>/<NN-chapter>.qmd`。
+- 目录布局：正文按部分放在 `content/<part>/`，章节写成 `content/<part>/<NN-chapter>.qmd`；附录放在 `content/appendix/`，由根 `_quarto.yml` 的 `appendices` 引用。
 - 改文件名时同轮同步 `_quarto.yml`、章节对照、`title` 和已有链接。
 
 ## 术语表