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

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

@@ -9,6 +9,11 @@
 
 中文标点、中西文边界空格、引号、数字与英文术语的细则见 `quarto/prose.md`；本步不重复附表。判定顺序：先改标点与空格，再改列表与加粗，最后回读。
 
+- 中文用全角标点；并列英文用顿号；中文与英文/数字之间留半角空格。
+- 句号密度与顿号、逗号、分号、冒号的分工见 `quarto/prose.md`「标点分配」；同一段连续四个以上短句各用句号时，先合并再回读。
+- 破折号夹解释的句子级判法见 `steps/05-sentences.md`（冒号合法场合见 `steps/04-paragraphs.md`「散文伪标签冒号禁令」）。
+- `true` / `false` / `nullptr` 等 C++ 关键字用行内代码原样书写，不写中文译名。
+
 ### 列表选择
 
 目录列表后能用段落补一个遗漏的目录吗：不能，并列成员一次列全。列表选择规则：
@@ -18,12 +23,12 @@
 - 列表项结构平行：起首用同类的词（都是名词短语，或都是动词短语），长度相近。
 - **列表字数带**：同一列表各项保持视觉齐长，避免扫读节奏断裂。计量：引导词汉字数、冒号后汉字数（行内代码按标识符计）。失衡判定：冒号后最长 ≥ 最短 × 2，或引导词相差 ≥ 4。改写顺序：删长项多余中心 → 拆多中心 → 过短项按简洁边界补全 → 停止。豁免：出错原因/正确做法；有序步骤；着陆页卡片。列表齐长服从句段主规则，假拆禁令见 `steps/04-paragraphs.md`。
 - 列表项起首用加粗引导词标记中心语，读者扫读时先看到分类再决定是否细读；关键词取同类词（如「显示状态面板」「读入坐标」），并按对象的发生顺序排列，读者扫读即得顺序与内容。
-- 行为或规则枚举项用「**动词短语引导词**：完整句」格式：引导词命名本项的中心动作（如「**显示状态面板**」「**判定流程结果**」），冒号后保留完整中文句，写全动作、对象与结果。引导词是扫读索引，不替代句子信息，不为省字把冒号后压成电报短句（对照见 `examples/03-layout-list.md`）。
+- 行为或规则枚举项用「**动词短语引导词**：完整句」格式：引导词命名本项的中心动作（如「**显示状态面板**」「**判定流程结果**」），冒号后保留完整中文句，写全动作、对象与结果。引导词是扫读索引，不替代句子信息，不为省字把冒号后压成电报短句（对照见 `examples/07-layout-list.md`）。
 - 解释并列名称的引导词列表放在首次使用这些名称的代码块或目录树之前：读者先经列表认识每个名称，再看结构展示；禁止把解释压到块后，读者会带着未解释的名称读块。名称本身用读者可核对的具体形态（如「项目动态库」），不用模糊统称（术语依据见 `steps/06-wording.md`）。
 - 并列成员一次列全：目录、组件等并列对象（含 `build/` 这类构建生成的目录）并入同一个引导词列表，先列全再展示目录树等结构；列表之后不用段落补列遗漏的成员（对照见 `examples/04-paragraph-opening.md`「角色总述段」）。
-- 目录树的列对齐（目录 `#/`、文件 `#` 右移 4 列、同一棵树只一档注释）见 `steps/03-blocks.md`「情况：目录树」；本文件只管列表、标点与加粗，不另写一份树规则。
+- 目录树的列对齐（目录 `#/` 在左、文件 `#` 右移一列、两种注释文字对齐、每个节点一条注释）见 `steps/03-blocks.md`「情况：目录树」；本文件只管列表、标点与加粗，不另写一份树规则。
 - 三项以上、或每项内含解释的信息优先成列表；只有两项且能写进一句的保留正文；只有一项时不设列表，写进正文（节内无代码块或列表承接时，整节收成一句）。
-- **不为凑三项拆列表**：列表项各要有一条独立信息；同一事实的碎片拆成三项、或为对齐硬补一项，都改回完整句，两项各有信息就写两项（对照见 `examples/03-layout-list.md`「凑三项拆列表」）。
+- **不为凑三项拆列表**：列表项各要有一条独立信息；同一事实的碎片拆成三项、或为对齐硬补一项，都改回完整句，两项各有信息就写两项（对照见 `examples/07-layout-list.md`「凑三项拆列表」）。
 - **构造后的成员并列成列表**：同一句或同一段用顿号、逗号并列三个及以上数据成员、而且各项状态不同时，改成引导词列表；列表放在数据成员围栏**之前**，引导句不数个数、不把类名连写两次，也不写「成员写在该类里」——只把「构造之后的取值」引出来（如「`Game()` 默认构造之后，状态面板、当前用户、流程结果和操作记录是下面这样：」）。每一项恰好两句：第一句写成员是什么，第二句只写开局取值；第二句可以是「开局是空状态面板」这类状态句。枚举取值列表的位置见 `steps/03-blocks.md`「三级标题最小模块」，本文件不重写；枚举成员的含义仍留在源码行尾注释，这里列的是构造之后每个数据成员的状态，不是把枚举成员再解释一遍。依据：C++ Primer 把名字和初值分开讲，阮一峰一句一事。
 - **成员围栏前不列类型**：禁止「`board_` 用 `Board`，`current_owner_` 用 `Player`」这种把类型再列一遍的句子——类型已经在围栏里。列表前的导语只点名要展开的维度，不把列表项里的取值先写一遍。
 - **`private:` 不作正文话题**：围栏里可以保留源码的 ` private:`，因为片段必须和头文件逐字一致；「存放在 `private:` 下」「都在 `private:` 下」一类把访问说明符当话题的句子删掉，换成该 `##` 标题里的对象。
@@ -40,26 +45,20 @@
 - 同一页加粗不成片：一段正文内至多一两处加粗，连续多句加粗等于没有重点。
 - 标题不加粗（层级已由 `##`/`###` 表达）；行内代码与加粗不叠加在同一对象上。
 
-### 标点与中英混排
-
-- 中文用全角标点；并列英文用顿号；中文与英文/数字之间留半角空格。
-- 破折号夹解释的句子级判法见 `steps/05-sentences.md`（冒号合法场合见 `steps/04-paragraphs.md`「散文伪标签冒号禁令」）。
-- `true` / `false` / `nullptr` 等 C++ 关键字用行内代码原样书写，不写中文译名。
-
 ### 外部规范对照
 
 - 阮一峰《中文技术文档的写作规范》：句长、中英混排空格、标点全角；标题不跳级、同级不孤立。
-- Google developer documentation style guide：一段一意、先给最重要信息；任务级标题用动词。
+- Google developer documentation style guide：一段一意、先给最重要信息；任务级标题用「动词 + 具体宾语」。
 - 华为《中文技术文档写作风格指南》：标题层级与句式；段落长度条文统一指向 `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`。
 
 具体元素写法见 `quarto/authoring.md`，终端步骤见 `quarto/terminal.md`。
@@ -76,4 +75,4 @@
 
 ## 正反例
 
-第 7 步不单设例子文件。列表的对照在 `examples/03-layout-list.md`，标点和加粗的短对照就是本文件通用情况里的条目。
+同号案例见 `examples/07-layout-list.md`；标点和加粗的短对照就是本文件通用情况里的条目。

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

@@ -12,14 +12,17 @@
 | 步骤 | 信号 | 判定 | 依据 |
 | --- | --- | --- | --- |
 | 定任务 | 正文「下一节／上一节」 | 删，改新节首句承接（章末「下一章」保留） | `steps/01-task.md` |
-| 定结构 | agent 免责腔（「服务于讲解」「片段不保证」「不等于文件内顺序」、台账口吻声明） | 读者正文整句删除；同源保证交给 verify，规则留 `.agents` | `steps/02-structure.md`「页面骨架」 |
+| 定结构 | agent 免责腔（「服务于讲解」「片段不保证」「不等于文件内顺序」、台账口吻声明） | 读者正文整句删除；同源保证交给 verify，规则留 `.agents` | `steps/02-structure.md`「六段块序列」 |
 | 定句子 | 自测题干出现「这个／那个／这些／那些／哪个／哪些／哪一句／哪一层／哪一行／哪一块」（「什么」允许） | 题干写出被问的对象与候选，用「是多少、会不会、A 还是 B」问 | `steps/05-sentences.md`「代词不能代替未写出的对象」、`examples/05-sentence-reference.md`「定结构与定句子：代词不能代替未写出的对象」 |
 | 定段落 | 同节 ≥3 连纯散文（中间无列表/代码/图/表） | 按「句序与段落形态」改一句中心并拆出列表、代码或图 | `steps/04-paragraphs.md`「句序与段落形态」 |
 | 定结构 | 章引言两个散文段并立、单句孤儿段（首个 `##` 前 ≥2 个非列表散文块） | 并为单段或改「一段 + 列表」 | `steps/02-structure.md` |
+| 定结构 | 标题口语化：第一人称、劝诱，或「输入之后」「看完之后」类时间从句起头 | 改成「限定语 + 对象」或「动词 + 具体宾语」，时间与人称下放导语 | `steps/02-structure.md`「形式规则」 |
+| 定结构 | 章题脱节：title 对象与多数任务节中心名词不同 | 并排看引言首句、各 `##` 中心名词、回顾能力句；改 title 或重排结构，不写导语补丁 | `steps/02-structure.md`「纵向承诺链」第 9 条 |
 | 定段落 | 一段内两个独立中心 | 按「拆核四步」拆段或改列表 | `steps/04-paragraphs.md`「拆核四步（多核混段的拆段方法）」、`examples/04-paragraph-cases.md`「自然段多中心未拆」 |
-| 定结构 | 章引言顿号串 ≥3 个交付物 | 下沉为列表或正文 `##` | `steps/02-structure.md`「页面骨架」、`examples/02-structure-shape.md`「目录式堆砌」 |
+| 定结构 | 章引言顿号串 ≥3 个交付物 | 下沉为列表或正文 `##` | `steps/02-structure.md`「六段块序列」、`examples/02-structure-shape.md`「目录式堆砌」 |
 | 排列内容块 | 过简实现围栏（单次比较或直接 `return`） | 删围栏，改入口列表 + 失败策略列表 | `steps/03-blocks.md` |
 | 排列内容块 | 块间闭环缺失（标题下无引导、段→列表无 lead-in、代码→图只有空行、表前无关系句、Callout 复述块内） | 按块链检查清单补桥接 | `steps/03-blocks.md`「块链检查清单」、`steps/03-blocks.md` |
+| 排列内容块 | 节末旁注裸句（`##` 最后一块是一句可跳过的补充，前面是列表、表格或围栏） | 改写为独立可读的 Callout 收尾，正文删同句；超过两句改小节 | `steps/03-blocks.md`「节末旁注与 Callout 收尾」、`examples/03-qmd-elements.md`「节末旁注改为 Callout 收尾」 |
 | 定段落 | 段内同义堆叠（两句换说法讲同一机制） | 删辅句或合并；公式递进与简洁边界豁免 | `steps/04-paragraphs.md`「段内同义堆叠禁令」 |
 | 定段落 | 过简断裂（逗号、句号后分句换新主语、新事实，无回指、无承接词）；一段第 4 个主概念 | 收敛主概念后用给定信息衔接；超 3 个主概念拆段或改列表 | `steps/05-sentences.md`「过简断裂禁令」「概念负荷」 |
 | 定句子 | 处所状语后 12 字内出现「记住」「保存」或「选出」 | 判为状语配错谓语；改写见「同档并句」——位置句的谓语用「放进」，职责不并进位置句 | `steps/05-sentences.md`「同档并句」 |
@@ -43,14 +46,14 @@
 | 定段落 | 散文伪标签冒号（话题 + `：` 词条式冒号）；多核混段 | 词条式冒号改完整主谓句或真列表项；多核混段按拆核四步改写 | `steps/04-paragraphs.md`「散文伪标签冒号禁令」「拆核四步（多核混段的拆段方法）」 |
 | 定版式 | 成员函数声明间无空行、qmd 围栏坍缩 | 补空 1 行；围栏保留源码空白 | `steps/03-blocks.md`「类与多函数摘录的垂直空白」 |
 | 定版式 | 行尾超 100 列 | 超宽整条回退上一行 | `steps/03-blocks.md` |
-| 定版式 | 列表项字数失衡（冒号后最长 ≥ 最短 ×2，或引导词相差 ≥4） | 删长项多余中心 → 拆多中心 → 过短项按简洁边界补全 | `steps/07-layout.md`「列表选择」、`examples/03-layout-list.md`「列表字数带失衡」 |
+| 定版式 | 列表项字数失衡（冒号后最长 ≥ 最短 ×2，或引导词相差 ≥4） | 删长项多余中心 → 拆多中心 → 过短项按简洁边界补全 | `steps/07-layout.md`「列表选择」、`examples/07-layout-list.md`「列表字数带失衡」 |
 | 定版式 | 凑三项拆列表：列表项只是同一事实的碎片，各自没有独立信息 | 改回完整句；两项各有信息就写两项 | `steps/07-layout.md`「列表选择」 |
 | 定句子 | 句号后下一句以「它」开头且下一个字不是「们」 | 话题没换就不写「它」，主语空缺或写回原类型名 | `steps/05-sentences.md`「同档并句」 |
 | 定句子 | 反引号结束后紧跟「减」加数字 | 标识符的加减乘除写进同一对反引号，运算符用源码符号 | `steps/05-sentences.md`「关系写成能核对的运算」 |
 | 定段落 | 列表前的导语写出列表项里的取值 | 导语只点名要展开的维度，不提前写取值 | `steps/07-layout.md`「列表选择」 |
 | 定句子 | 简单函数注释写出「不抛异常」而声明没有 `noexcept` | 可能抛出则不写「不抛异常」，声明也不加 `noexcept` | `steps/03-blocks.md`「代码块门槛」 |
 | 定用词 | 空泛套话（「深入探讨」「至关重要」「无缝」「赋能」）不指具体对象；同义循环换词；客服腔；编辑过程残留 | 改写成可核对的对象或删除；工程术语（反馈里的「闭环」）保留 | `steps/06-wording.md`「情况：空泛套话与编辑残留」 |
-| 回读并退回 | 与改前文本对照：新增原文没有的事实、遗漏读者需要的信息、把限定说成确定 | 恢复原文或按现象退回对应步 | `steps/08-reread.md`「情况：对照改前文本」 |
+| 回读并退回 | 与改前文本对照：新增原文没有的事实、遗漏读者需要的信息、把限定说成确定 | 恢复原文或按现象退回对应步 |本文件「情况：对照改前文本」 |
 
 机械项：`verifying-content.py` 扫读者 qmd 与 agents 的 `下一节`/`上一节`、`代码把它写成`、`第二道…防线`、围栏外正文的 `由…完成` 与 `由…确定／体现／界定／表达`；读者正文的 agent 免责腔硬拦，章节页引言两个散文段、段落下限由 `verifying-content.py` 判失败；段内连续分句引入新行内代码标识且无回指的过简断裂信号由 `verifying-content.py` 记 WARN（不追清零）。句子模块切分由 `verifying-content.py` 对扫描范围内的 qmd 全量执行，只印切分计数与失败行，失败收三类高精度信号（类型接线句、「接着看／第 N 个枚举」改口、全称被下一句否定）；段中心写不出与对话件数不做正则，留给步骤与案例。
 

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

@@ -10,7 +10,7 @@
 
 项目技能列了内容检查命令时，只跑它列出的命令。没有项目技能时，在书根跑本技能 `scripts/` 下的 `verifying-content.py`、`checking-links.py` 与 `checking-prose.py`。
 
-`verifying-content.py` 查章节表、YAML 标题、标题层级、句段长度、围栏语言、Mermaid 围栏、占位文字和本地链接；`checking-prose.py` 查中文与拉丁字母、数字、行内代码之间的空格，以及中文句里的半角标点。项目专属检查只在书的 `.agents/skills/quarto-book-project/` 存在时启用。
+`verifying-content.py` 查章节表、YAML 标题、标题层级、句段长度、围栏语言、Mermaid 围栏、占位文字、目录树（行数、目录注释 16 列且无冒号/顿号、文件注释 1–2 项、标记列对齐）和本地链接；`checking-prose.py` 查中文与拉丁字母、数字、行内代码之间的空格，以及中文句里的半角标点。项目专属检查只在书的 `.agents/skills/quarto-book-project/` 存在时启用。
 
 ### 渲染与 HTML
 
@@ -22,8 +22,8 @@
 检查次数有上限：
 
 - `dry_run: true` 最多 2 次。第 1 次返回 `safe_to_render: false` 时，只改 `output-dir` 一次。第 2 次仍不安全就停住，把 `warnings` 列给用户。
-- `dry_run: false` 最多 1 次。渲染失败就停住，把 `errors` 列给用户，不自动重跑。
-- 成功时同一次返回里带 `html_report`，不再为同一份文件重跑。
+- `dry_run: false` 最多 1 次。渲染失败就停住，把 `errors` 列给用户，不自动重新运行。
+- 成功时同一次返回里带 `html_report`，不再为同一份文件重新运行。
 
 报告字段：
 

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

@@ -39,7 +39,7 @@ description: 记录某一本 Quarto Book 的项目级约定：书名、读者、
 - 链接检查：`<插件技能目录>/scripts/checking-links.py --root <book>`。
 - HTML 可用性：只调 `quarto_render_check`，`qmd_path` 传当前章节；`dry_run: true` 最多 2 次，`dry_run: false` 最多 1 次。
 - 不手跑 `quarto render`，也不手跑 `checking-output.py` 或 `checking-callouts.py`；这些检查由工具按书配置调用。
-- 项目专属词表：同目录 `checks.json`（`forbidden_terms`、`fragment_prefixes`、`chapter_titles`）；不写就只跑通用规则。
+- 项目专属词表：同目录 `checks.json`（`forbidden_terms`、`fragment_prefixes`、`chapter_titles`）；模板带一份空文件，复制后按项目填写，不写就只跑通用规则。
 - 项目自己的检查命令（如有）与它覆盖的 profile：
 - 命令在哪个环境执行（本机 / WSL / 容器）：
 

package/templates/quarto-book-project/checks.json

@@ -0,0 +1,5 @@
+{
+  "forbidden_terms": [],
+  "fragment_prefixes": [],
+  "chapter_titles": {}
+}

package/templates/quarto-book-project/writing/chapter-map.md

@@ -17,6 +17,9 @@ YAML `title` 与二级标题。类章与能力章的定义、一章一个关键
   不写英文类名，除非关键对象本身只有一个英文名。
 - 二级标题是这一章关键的部分，顺序与「关键」一列对应；成员函数可以做三级标题，
   不能做章标题。
+- 本表是章题契约：`title`、`关键`、二级标题三列与正文同轮同步；改 title 或任务节
+  时同轮改本表，表与正文不一致按章题脱节处理。项目有检查脚本时，让它逐章核对
+  `title` 与 `##` 顺序。
 - 固定收尾 `常见错误`、`自测问题`、`本章回顾` 不改名，不升成关键。
 - 类型章的文件名镜像关键类；改文件名时同轮同步 `_quarto.yml`、本表、`title`、
   已有链接与内容检查脚本里的章关键键，不留旧名孤儿。