@chengzhao-dev/dsh-quarto-book 0.6.18 → 0.6.19

package/README.en.md

@@ -29,7 +29,7 @@ Both skills are discovered from the package's `skills/` directory and loaded on
 2. Open a session in the book repository. `_quarto.yml` needs a standalone `type: book` line, and the book needs at least one `.qmd` or `.md` chapter source; only then do both skill names appear.
 3. Call a skill: `writing-quarto` for prose, `designing-theme` for the theme.
 
-Replace `--profile` with the profile you actually run. The desktop app always runs the `desktop` profile, and that profile is owned by the app, so `dsh --profile desktop` is rejected; install or upgrade with `dsh plugin --profile desktop add <package>`, and use the app's Settings → Plugins → Add plugin only if the app refuses that write. To pin a version, write `npm:@chengzhao-dev/dsh-quarto-book@0.6.18`; to follow a GitHub tag, write `github:chengzhao-dev/dsh-quarto-book#v0.6.18`.
+Replace `--profile` with the profile you actually run. The desktop app always runs the `desktop` profile, and that profile is owned by the app, so `dsh --profile desktop` is rejected; install or upgrade with `dsh plugin --profile desktop add <package>`, and use the app's Settings → Plugins → Add plugin only if the app refuses that write. To pin a version, write `npm:@chengzhao-dev/dsh-quarto-book@0.6.19`; to follow a GitHub tag, write `github:chengzhao-dev/dsh-quarto-book#v0.6.19`.
 
 Upgrading from the old unscoped package `dsh-quarto-book` (removed from npm with 0.3.4, so this only affects profiles that installed it earlier): remove it from the same profile first with `dsh plugin --profile <profile> remove dsh-quarto-book`, then add the scoped package. Keeping both installed registers `writing-quarto` and `designing-theme` twice at the same rank 550.
 

package/README.md

@@ -29,7 +29,7 @@
 2. 在书仓库里打开会话。`_quarto.yml` 要有独立一行的 `type: book`，书根至少有一个 `.qmd` 或 `.md` 章节源文件；两个技能名这时才会出现。
 3. 调用技能：写正文用 `writing-quarto`，改主题用 `designing-theme`。
 
-`--profile` 换成你实际运行的那个 profile。桌面应用固定跑 `desktop` profile，且该 profile 由应用独占管理，`dsh --profile desktop` 直接启动会被拒绝；安装或升级用 `dsh plugin --profile desktop add <包>`，应用拒绝写入时再走「设置 → 插件 → 添加插件」。需要固定版本时写 `npm:@chengzhao-dev/dsh-quarto-book@0.6.18`，跟 GitHub 标签时写 `github:chengzhao-dev/dsh-quarto-book#v0.6.18`。
+`--profile` 换成你实际运行的那个 profile。桌面应用固定跑 `desktop` profile，且该 profile 由应用独占管理，`dsh --profile desktop` 直接启动会被拒绝；安装或升级用 `dsh plugin --profile desktop add <包>`，应用拒绝写入时再走「设置 → 插件 → 添加插件」。需要固定版本时写 `npm:@chengzhao-dev/dsh-quarto-book@0.6.19`，跟 GitHub 标签时写 `github:chengzhao-dev/dsh-quarto-book#v0.6.19`。
 
 从旧的无作用域包 `dsh-quarto-book` 升级（该包已随 0.3.4 从 npm 删除，只影响之前装过它的 profile）：先在同一个 profile 里 `dsh plugin --profile <profile> remove dsh-quarto-book`，再装新包。两个包同时留着会以相同的 rank 550 各注册一遍 `writing-quarto` 和 `designing-theme`。
 
@@ -50,7 +50,7 @@
 
 ### 写章节
 
-在 `type: book` 的仓库里加载 `writing-quarto`，按 `SKILL.md` 的九步执行。每一步只打开同号的一个 `steps/` 文件；判不准才读 `examples/` 里同号的案例；要排图、查渲染或全仓重构才打开 `quarto/`。
+在 `type: book` 的仓库里加载 `writing-quarto`，按 `SKILL.md` 判操作并走九步。每一步只打开同号的一个 `steps/` 文件；判不准才读 `examples/` 里同号的案例；要排图、查渲染或全仓改写才打开 `quarto/`。
 
 书仓库根目录的 `README.md` 是说明页，不是章节：只走第 5–8 步，不套第 1–4 步的任务与结构骨架，不写「常见错误」「自测问题」，不调 `quarto_render_check`。`README.en.md` 同样处理。
 
@@ -71,7 +71,7 @@ python scripts/checking-prose.py --root <book>
 python scripts/checking-names.py --root <book>
 ```
 
-`checking-prose.py` 只报中文混排里能直接判断的问题；`checking-names.py` 只在全仓重构时加跑。日常章节检查跑前三条即可。
+`checking-prose.py` 只报中文混排里能直接判断的问题；`checking-names.py` 只在全仓改写时加跑。日常章节检查跑前三条即可。
 
 渲染后的 Callout、HTML 产物与 DOM 结构约定由 `quarto_render_check` 调包内脚本完成，不用手跑 `checking-callouts.py`、`checking-output.py` 或 `checking-dom.py`；`designing-theme` 的 `scripts/checking-layout.py` 在渲染后的 HTML 上检查溢出、对比度和页面结构。`apply()` 不在加载时跑这些脚本，也不跑 `quarto render`。
 

package/lib/tools/pass-report.js

@@ -1,10 +1,10 @@
-// `quarto_pass_report`：把一次写作或主题润色的结果压成固定行数的卡片。
+// `quarto_pass_report`：把一次写作、改写、润色或主题调整的结果压成固定行数的卡片。
 //
 // 入参是闭集：模式、文件、步骤、未改项、检查状态都只能取登记过的值。
 // 卡片由工具自己拼接，返回的文本就是卡片本身，不附章节原文，也不贴改写后的句子。
 // 没改也要出卡，这样「插件没跑」和「跑了但没改」在会话里分得开。
 export const PASS_SKILLS = ['writing-quarto', 'designing-theme'];
-export const PASS_MODES = ['polish', 'rewrite', 'theme', 'skipped'];
+export const PASS_MODES = ['write', 'rewrite', 'polish', 'theme', 'skipped'];
 export const HELD_ITEMS = ['fences', 'facts', 'css', 'prose'];
 export const CHECK_NAMES = ['content', 'html', 'layout'];
 export const CHECK_STATUSES = ['pass', 'fail', 'skip'];
@@ -25,8 +25,9 @@ export const WRITING_STEPS = {
 /** 主题步骤表的名字，与 `skills/designing-theme/references/theme-spine.md` 逐字对应。 */
 export const THEME_STEPS = ['定表面', '定字体', '定尺度', '定颜色', '定组件', '通过检查'];
 const MODE_LABELS = {
-    polish: '增量润色',
-    rewrite: '全章重构',
+    write: '写作',
+    rewrite: '改写',
+    polish: '润色',
     theme: '主题',
     skipped: '未执行',
 };
@@ -247,7 +248,7 @@ const RESULT_SCHEMA = {
 export function registerPassReportTool(tools) {
     tools.register({
         name: 'quarto_pass_report',
-        description: '把一次写作或主题润色的改动压成一张回执卡，卡片即回执，不写文件。',
+        description: '把一次写作、改写、润色或主题调整的改动压成一张回执卡，卡片即回执，不写文件。',
         parameters: {
             type: 'object',
             additionalProperties: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chengzhao-dev/dsh-quarto-book",
-  "version": "0.6.18",
+  "version": "0.6.19",
   "description": "把一份 Quarto Book 写成可读、可查、可发布的中文技术书：九步章节写作、结构/链接/图表检查、统一主题与渲染验收。",
   "type": "module",
   "main": "./lib/index.js",

package/skills/designing-theme/SKILL.md

@@ -5,22 +5,33 @@ metadata:
   short-description: 维护 Quarto 图书主题
 ---
 
-# Skill: designing-theme
+# designing-theme
 
-维护本技能自带的 Quarto Book 主题资产，入口是 `assets/theme/`。这套主题属于本插件，不与其他仓库共享同一套文件；项目若另有权威副本，以项目 `_quarto.yml` 实际引用的路径为准。
+本技能维护插件自带的 Quarto Book 主题资产，入口是 `assets/theme/`。这套资产属于本插件，不与其他仓库共享同一套文件；项目若另有权威副本，以项目 `_quarto.yml` 实际引用的路径为准。
 
 ## 适用场景
 
 - 调整颜色、字体、间距、导航、Callout 或落地页样式。
 - 新增 palette 或页面组件样式。
-- **不适用**：`.qmd` 正文写法（转 `writing-quarto`）；书里项目的业务领域内容（由项目自己的技能负责）。
-- 项目带有 `.agents/skills/quarto-book-project/SKILL.md` 时，先读它的「主题与过滤器路径」，只改 `_quarto.yml` 实际引用的书内副本；没有就跳过。书内副本默认在 `theme/`，过滤器在 `filters/`。
-- 编码与行尾跟 `writing-quarto` 的 `quarto/encoding.md`：UTF-8 无 BOM、样式文件用 LF；`.bat`/`.cmd` 才用 CRLF。
+- 不适用：`.qmd` 正文写法（转 `writing-quarto`）；书里项目的业务领域内容（由项目自己的技能负责）。
+
+项目有 `.agents/skills/quarto-book-project/SKILL.md` 时，先读它的「主题与过滤器路径」，只改 `_quarto.yml` 实际引用的书内副本；没有就跳过。书内副本默认在 `theme/`，过滤器在 `filters/`。
+
+编码与行尾跟 `writing-quarto` 的 `quarto/encoding.md`：UTF-8 无 BOM、样式文件用 LF；`.bat`/`.cmd` 才用 CRLF。
 
 ## 任务路由
 
 任何主题任务先读 `references/theme-spine.md`（步骤唯一入口）。增量任务只走被改组件所在的那一步，再加第 6 步「通过检查」；从定表面到通过检查依次走完只用于新主题或用户明确要求整体调整。
 
+| 步 | 名称 | 产出 | 文件 |
+| --- | --- | --- | --- |
+| 1 | 定表面 | 这次动的是正文、代码、Callout 还是导航 | `references/theme-spine.md` |
+| 2 | 定字体 | 字体栈与字形来源 | `references/theme-spine.md` |
+| 3 | 定尺度 | 字号台阶、行长与间距 | `references/theme-spine.md` |
+| 4 | 定颜色 | 语义色、明暗分层与对比度 | `references/theme-spine.md` |
+| 5 | 定组件 | 表格、Callout、代码块与导航 | `references/theme-spine.md` |
+| 6 | 通过检查 | 布局、对比度与整本渲染 | `references/theme-spine.md` |
+
 ## 加载与结束
 
 - 只改 `_quarto.yml` 实际引用的主题文件；不打开章节正文，也不打开章节以外的实现文件。
@@ -29,12 +40,13 @@ metadata:
 - `scripts/checking-layout.py` 通过并完成一次整本渲染后，在同一轮结束 goal，不把没失败的步骤留到下一轮。
 - 不探测同 profile 的其他插件，也不把它们写成依赖；子会话按自己的 cwd 重新判定门禁。
 
-| 任务 | 读取 |
-| --- | --- |
-| 主题的分层、令牌与组件边界 | `references/theme-system.md` |
-| 色板接线与暗色分层 | `assets/theme/palettes/flexoki/meta.md` |
-| 结构尺度令牌 | `assets/theme/css/tokens.css` 头注释 |
-| 字体、栏宽与阅读表面的取舍理由 | `knowledge/reading-surface.md` |
+## 文件职责
+
+- `references/theme-spine.md`：主题步骤的唯一入口与每步的检查点。
+- `references/theme-system.md`：令牌、组件边界与分层规则。
+- `knowledge/reading-surface.md`：字体、栏宽与阅读表面的取舍理由。
+- `assets/theme/`：palette、CSS 与可被 `_quarto.yml` 直接消费的资产。
+- `scripts/`：布局测量与检查。
 
 ## P0 硬约束
 

package/skills/writing-quarto/SKILL.md

@@ -1,68 +1,81 @@
 ---
 name: writing-quarto
-description: 写、改、检查与润色 Quarto Book 章节正文时使用；不用于改主题样式与只改 .cpp。
+description: 写作、改写、润色或检查 Quarto Book 章节时使用；不用于改主题样式与只改 .cpp。
 metadata:
-  short-description: 润色中文 Quarto 图书章节
+  short-description: 写作、改写与润色中文 Quarto 章节
 ---
 
-# Skill: writing-quarto
+# writing-quarto
 
-承载 `.qmd` 写法与 Book 结构约定。正文九步：增量任务只开对应一步，全章重构走九步，只读审查只报告不改文件。判不准才开步骤点名的 `examples/` 案例，排图与查渲染开 `quarto/`；插件开发资料不属读者正文。
+本技能负责 Quarto Book 的读者正文：`content/**/*.qmd`、`index.qmd` 与 `_quarto.yml` 的章节结构。主题样式走 `designing-theme`，C++ 源码走 `developing-cpp`，书里的业务事实由项目技能提供。
 
 ## 适用场景
 
-- 新建或修改 `content/**/*.qmd` 章节、`index.qmd` 或 `_quarto.yml`；内容与链接核对走本技能 `scripts/` 下的脚本，HTML 是否可用走 `quarto_render_check` 工具。
-- **不适用**：改主题样式、颜色或字体（转 `designing-theme`）；讲解书里项目的业务领域知识（那是项目正文的职责，不是本技能）。
-- 项目带有 `.agents/skills/quarto-book-project/SKILL.md` 时，读完本技能再读它，并只按它指向的 `writing/` 文件读章节对照；没有就跳过，不要猜书名、章节名和术语。书内 `context/` 旧副本不再打开，写法以本技能为准。
-- 书仓库根目录的 `README.md` 只走第 5–8 步：它是仓库说明页，不是章节；不套第 1–4 步的任务与结构骨架，不写「常见错误」「自测问题」，不调 `quarto_render_check`。第 8 步发现问题只退回第 5、6、7 步。`README.en.md` 同样处理；`CHANGELOG.md`、`LICENSE`、`AGENTS.md` 不在写作范围。这条只在书仓库里适用。
+- 新建、改写、润色或只读审查章节正文。
+- 调整章题、二级标题、内容块顺序、段落、句子、用词与版式。
+- 核对正文里的代码围栏与源文件是否一致。
 
-## 加载与结束
+不适用：主题颜色、字体、导航与页面样式；只改 `.cpp`；书里项目的业务知识本身。
 
-- 一次激活只做一类文件：章节或主题。写章节时只打开项目技能或 `_quarto.yml` 点名的章节；围栏注释与源文件不一致时回源改围栏，不读无关实现。句子与条文、项目技能或既有正文冲突时，先列冲突位置、原句与出处，由用户选一条；不自行取舍，也不默认采用计划。
-- 项目提供作用域命令就先跑它，只读它列出的文件；渲染产物、构建目录与 Quarto 缓存不读。
-- 增量任务只开本文件、当前一步与这一步点名的一个文件；第 8 步可点名 `references/personas.md` 与 `examples/08-appendix.md` 两个，其余步骤仍只一个；同轮不把同号案例、其余步骤和条文一起打开。
-- 同一文件最多退回上一步一次；第二次仍失败就停在检查输出上，不重走整段。
-- 项目技能列出检查命令时只跑那一条；没有就跑本技能 `scripts/` 下的内容与链接检查。退出码为 0 就在同一轮结束 goal。
-- 不探测同 profile 的其他插件，也不把它们写成依赖；子会话按自己的 cwd 重新判定门禁，不把技能正文塞进子代理提示。
+项目有 `.agents/skills/quarto-book-project/SKILL.md` 时，先读本技能，再读项目技能，只按它指向的章节对照与术语表读；没有就跳过，不猜书名、章节名与术语。
+
+`README.md` 与 `README.en.md` 只走第 5–8 步：它们是说明页，不套任务与结构骨架，不写「常见错误」「自测问题」，不调 `quarto_render_check`；发现问题只退回第 5–7 步。`CHANGELOG.md`、`LICENSE`、`AGENTS.md` 不在写作范围。
 
-## 整书走法
+## 三种操作
 
-改多章或排目录时，先读 `references/book-journey.md`：先定全书主线与章节次序，再逐章走九步，最后做全书一致性回读。
+一次只选一种，`mode` 只填一个；范围（单点、整章、全书）是任务属性，不单独占一个操作。只读审查不改文件，不调渲染与回执。
 
-单章与整书共用同一套九步，不另造一套章节规则；项目有章节表时以项目表为准。技能文件体量受 `references/token-budget.md` 约束，新增整书规则只写进 `book-journey.md`。
+| 操作 | 什么时候选 | 从哪步进 | `mode` |
+| --- | --- | --- | --- |
+| 写作（起稿） | 缺任务、结构或可观察行为 | 第 1 步；新章走到第 4 步 | `write` |
+| 改写 | 事实与行为不变，块段或顺序不对 | 从被打破的步重走，可到第 9 步 | `rewrite` |
+| 润色 | 只改句子和用词 | 第 5–8 步；段像清单先走第 4 步 | `polish` |
 
-## 三种走法
+三种操作共守：不新增事实、数字、命令、结论、引文与出处；不把「可能」「通常」「在本书里」改成确定；保留否定、条件、范围、时间与归属；围栏里的代码、命令、路径、URL 与 YAML 不改。润色只删换词；改写可删可换序，但不发明事实。只读审查按九步逐条报告行号、规则出处与改法。
 
-增量任务只走对应步骤，只改不合格处。全章重构走九步：第 1–2 步定删留，第 3–4 步拆块段，第 5–7 步逐句改。只读审查不改文件，按九步逐条报告行号、规则出处与改法。
+## 加载规则
+
+- 一次激活只做一类文件：章节或主题。写章节时只打开项目技能或 `_quarto.yml` 点名的章节；围栏注释与源文件不一致时回源改围栏，不读无关实现。
+- 只开本文件、当前一步与该步点名的一个文件；第 8 步只开 `steps/08-reread.md`。同轮不把同号案例、其余步骤和条文一起打开。
+- 判不准才开步骤点名的 `examples/` 案例；`references/` 是完整条文，只在排错、整书重构或步骤明确指向时打开。
+- `quarto/` 只在排图、查渲染、写围栏或核对 qmd 语法时按需打开，不整目录读。
+- 同一文件最多退回上一步一次；第二次仍失败就停在检查输出上，不重走整段。
+- 句子与条文、项目技能或既有正文冲突时，先列冲突位置、原句与出处，由用户选一条；不自行取舍或默认采用计划。
+- 不探测同 profile 的其他插件，也不把它们写成依赖；子会话按自己的 cwd 重新判定门禁，不把技能正文塞进子代理提示。
 
-三种走法共守：不新增原文没有的事实、数字、命令、性能结论、引文和出处；不把「可能」「通常」「在本书里」改成确定说法；保留否定、条件、范围、时间和归属；围栏里的代码、命令、路径、URL 与 YAML 不改。增量润色只删除和换词；全章重构可删可换序，但不能发明事实。
+改多章或排目录时，先读 `references/book-journey.md`：先定全书主线与章节次序，再逐章判操作走对应步骤，最后做全书一致性回读。单章与整书共用同一套九步，不另造章节规则；项目有章节表时以项目表为准。
 
-## 九步
+## 九步地图
 
-九步按四个写作域分：写作 1–2，布局 3–4 与 7，润色 5–6 与 8，排版归主题技能；第 9 步是检查与渲染。跨域改动按「写作 → 布局 → 润色」的顺序推进，前一步落定再进下一步。
+操作定入口，域定层次；九步按四域分：写作 1–2，布局 3–4 与 7，润色 5–6 与 8，排版归主题。跨域按写作→布局→润色推进，前步落定再进。
 
-1. 定任务：写出读者做完能完成的那件事，再列这一章要覆盖的任务。规则在 `steps/01-task.md`。
-2. 定结构：排页面骨架、二级标题和篇幅预算，只定删留、标题与章题对齐。规则在 `steps/02-structure.md`。
-3. 排列内容块：导语、围栏、收束与 Callout 的次序，一个围栏只放正在讲的那一块。规则在 `steps/03-blocks.md`，表格写法见 `quarto/tables.md`；围栏给声明还是给定义，按 `references/fence-semantics.md` 判。
-   图注写在图下、图前只写引出关系；三类图的统一写法见 `quarto/figures.md`。
-4. 定段落：一段一个关键，下一句接住上一句的新信息；段间衔接落在话题切换处。规则在 `steps/04-paragraphs.md`。
-5. 定句子：主语选执行者，对象先行，一句一动作。规则在 `steps/05-sentences.md`。
-6. 定用词：统一术语、主动语态和语气。规则在 `steps/06-wording.md`。
-7. 定版式：标点、中英混排、列表和加粗。规则在 `steps/07-layout.md`。
-8. 回读并退回：按现象判断属于哪一步，先按 `references/priority.md` 判冲突，再退回那一步改。规则在 `steps/08-reread.md`。
-9. 检查与渲染：先核对内容与链接，再调 `quarto_render_check` 渲染并检查 HTML。规则在 `steps/09-check.md`。
+| 步 | 名称 | 产出 | 文件 |
+| --- | --- | --- | --- |
+| 1 | 定任务 | 读者做完能完成的一件事 | `steps/01-task.md` |
+| 2 | 定结构 | 页面骨架、二级标题与篇幅 | `steps/02-structure.md` |
+| 3 | 排列内容块 | 导语、围栏、收束与 Callout 的次序 | `steps/03-blocks.md` |
+| 4 | 定段落 | 一段一个关键，句间接住新信息 | `steps/04-paragraphs.md` |
+| 5 | 定句子 | 主语是执行者，一句一动作 | `steps/05-sentences.md` |
+| 6 | 定用词 | 术语、语态与语气统一 | `steps/06-wording.md` |
+| 7 | 定版式 | 标点、中英混排、列表与加粗 | `steps/07-layout.md` |
+| 8 | 回读并退回 | 按现象找到该退的步 | `steps/08-reread.md` |
+| 9 | 检查与渲染 | 内容与链接检查，HTML 可用 | `steps/09-check.md` |
 
-## 规则卡
+## 文件职责
 
-改句子、改块、改标题时，按需打开 `references/rules-cards.md` 的一张卡（C01–C30）查正例与反例，不整份读。卡是结论的紧凑副本，步骤文件仍是权威；两者冲突时以步骤为准。
+- `steps/`：每步的唯一权威；同一事实不在本文件复述。
+- `references/`：跨步骤的完整条文（优先级、规则卡、整书旅程、围栏语义、人物、预算）。
+- `examples/`：案例；只开步骤点名的一份。
+- `references/rules-cards.md`：改句子、块或标题时按需开一张卡（C01–C30），不整份读；卡是步骤的紧凑副本，冲突时以步骤为准。
+- `quarto/`：qmd 语法、表格、图、mermaid、终端、编码、渲染与作者工具。
+- `scripts/`：内容、链接、混排与结构检查。
 
 ## 完成判据
 
-- [ ] 本轮点名的文件走完它对应的步骤，改动落在正文里；不要求九步全走。
-- [ ] 本轮检查命令退出码为 0；通过后按「加载与结束」在同一轮结束 goal。
-- [ ] 内容与链接核对通过：项目技能列了检查命令时按它执行，否则跑本技能 `scripts/verifying-content.py` 与 `checking-links.py`。
+- [ ] 本轮点名的文件走完它对应的步骤；不要求九步全走。
+- [ ] 检查命令退出码为 0；项目有检查命令就按它跑，没有就跑本技能 `scripts/` 下的检查。
 - [ ] 新人能按正文独立完成任务：前置、动作、结果与失败出口齐全，术语首用有解释；清单见 `quarto/readability.md`。
 - [ ] 混排自查通过：`scripts/checking-prose.py --root <book>` 无高置信问题。
 - [ ] 调 `quarto_render_check`：`dry_run: true` 最多 2 次，确认 `safe_to_render`；`dry_run: false` 最多 1 次，确认 `html_report.usable` 为 true。不手跑 `quarto render`，也不截图 PNG。
-- [ ] 收尾调用一次 `quarto_pass_report`：`skill` 填 `writing-quarto`，`mode` 填 `polish` 或 `rewrite`，文件与步骤的改动次数、未改项、检查结论照实填。卡片就是回执，回复里不再复述；没改也传 0，当前文件不是章节时传 `executed: false`。
+- [ ] 收尾调用一次 `quarto_pass_report`：`skill` 填 `writing-quarto`，`mode` 填 `write`、`rewrite` 或 `polish`，改动次数、未改项与检查结论照实填。卡片就是回执，回复里不再复述；没改也传 0，当前文件不是章节时传 `executed: false`。
 - [ ] 只读审查：不改文件，不调 `quarto_render_check`、`quarto_pass_report`，报告写清行号、规则出处与改法。

package/skills/writing-quarto/examples/02-structure-shape.md

@@ -22,7 +22,7 @@
 
 ## 定结构：标题只留对象名
 
-条文见 `steps/02-structure.md`「标题字数」「形式规则」。两个旧标题都在旧字数上限内，仍是一句步骤说明：指示、过程动词和关系词把真正的对象挤到末尾；目录、侧栏和页内 TOC 需要的是对象名，不是把导语缩进标题。改写在定结构：先圈出目录里要扫到的对象，删掉指示、过程和数量，再检查同级句式是否一致。
+条文见 `steps/02-structure.md`「标题分层」「形式规则」。两个旧标题都在旧字数上限内，仍是一句步骤说明：指示、过程动词和关系词把真正的对象挤到末尾；目录、侧栏和页内 TOC 需要的是对象名，不是把导语缩进标题。改写在定结构：先圈出目录里要扫到的对象，删掉指示、过程和数量，再检查同级句式是否一致。
 
 **定结构（示例章「记下流程数据」下两个三级标题）：**
 

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

@@ -149,7 +149,7 @@ state.h 里 `private:` 下的 ToFlatIndex 只写函数名与参数表，函数
 
 ## 口语开场与规划套话
 
-语气的完整标准见 `steps/06-wording.md`；以下两例是重构示例项目全书时的定稿对照。
+语气的完整标准见 `steps/06-wording.md`；以下两例是改写示例项目全书时的定稿对照。
 
 开场把讲义口换成书面陈述（首章）：
 

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

@@ -70,7 +70,23 @@
 - **数据项被占用**：`PlacePiece` 返回 `false`，状态面板保持不变，调用方另选数据项就行。
 ```
 
-判定信号：同一列表内最长项冒号后字数 ≥ 最短项 × 2，或引导词相差 ≥ 4；长项的第二句删掉后主线仍闭合。章级定稿对照见 `examples/08-appendix.md`「列表项长度均衡定稿」。
+以 01 规则章的落子规则列表改稿前为对照（有序步骤同样受字数带约束）：
+
+```text
+不佳（第 3 项先写「程序检查输入」再展开三种失败，长度超过最短项两倍）：
+1. 程序显示当前棋盘，提示轮到谁落子。
+2. 玩家给出两个 0 到 2 的行列号，要落的棋盘格子必须为空。
+3. 程序检查输入。行列越界、棋盘格子已被占用或格式错误时，程序说明原因并保持棋盘不变。随后要求重新输入。
+4. 输入有效时写入棋盘格子，随后判定胜负。
+
+改写（第 3 项收成一句，四项落在同一字数带）：
+1. 程序显示当前棋盘，提示轮到谁落子。
+2. 玩家给出两个 0 到 2 的行列号，要落的棋盘格子必须为空。
+3. 越界、占用或格式错误时，程序说明原因并要求重新输入，棋盘保持不变。
+4. 输入有效时写入棋盘格子，随后判定胜负。
+```
+
+判定信号：同一列表内最长项可见字数 ≥ 最短项 × 2（有引导词时另看引导词相差 ≥ 4）；长项的第二句删掉后主线仍闭合。章级定稿对照见 `examples/08-appendix.md`「列表项长度均衡定稿」。
 
 ## 公式与换算讲解段
 

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

@@ -22,9 +22,9 @@
 - 新手必须掌握的内容和引言说明放正文。引言用连贯段落交代动机、范围和全章路线。代码块前交代本步目标、执行环境和预期变化，三级标题内部次序见「三级标题最小模块」；收束段只写共同契约、结果和少量解释；块内 `//` / `#` 注释已写明的意图不在块后同义复述（对照见 `examples/03-block-after.md`「块后复述注释」）。Callout 只承载非主线且确有独立价值的风险、版本差异或可选替代；不重复正文动作或成功判据，不用于装饰层级，也不放进引言。
 - 需要失败分支时，先用 `## 常见错误` 按症状列出 `###`，再用 `## 自测问题` 承载自测题，最后以 `## 本章回顾` 收束。不设置章末集中式资料区。
 
-## 重构与事实核对
+## 改写与事实核对
 
-重构默认在原文基础上进行：先读取原文件、相关引用和任务边界，再局部调整结构、表达和衔接。只有用户明确要求，或原结构无法安全修复时，才删除后重新生成。目录、文件名、版本号、命令输出和工程结构等可从磁盘获得的内容，必须先实际获取。无法确认时只写检查方法，不伪造事实。
+改写默认在原文基础上进行：先读取原文件、相关引用和任务边界，再局部调整结构、表达和衔接。只有用户明确要求，或原结构无法安全修复时，才删除后重新生成。目录、文件名、版本号、命令输出和工程结构等可从磁盘获得的内容，必须先实际获取。无法确认时只写检查方法，不伪造事实。
 
 局部删除或移动内容后必须回读切口，并为后文仍引用的动作保留「触发时机 → 状态变化及原因 → 可观察结果 → 下一步」的最短闭环。后文出现悬空的「然后、因此、此时、重启、再次」等承接时必须重写切口，不能只按表面冗余删除过渡句。
 
@@ -133,6 +133,6 @@ Callout 个数见 `steps/02-structure.md`，本段不写数字；`warning` 只
 
 ### 交叉引用
 
-图、表、公式或 Callout 需要按编号引用时，标签写法、前缀与书内编号规则见 `quarto/crossrefs.md`。本项目是纯 HTML 中文书，`number-sections: false`，章节标题不写 `{#sec-...}`；跨章节引用用章节标题链接，不写「第 N 章」。引用前确认目标页面存在，改标题后按「重构与事实核对」重新核对。
+图、表、公式或 Callout 需要按编号引用时，标签写法、前缀与书内编号规则见 `quarto/crossrefs.md`。本项目是纯 HTML 中文书，`number-sections: false`，章节标题不写 `{#sec-...}`；跨章节引用用章节标题链接，不写「第 N 章」。引用前确认目标页面存在，改标题后按「改写与事实核对」重新核对。
 
 需要渲染与链接依据时，读 `quarto/render.md` 与 `quarto/mermaid.md`；图注、原生 SVG 与图前句的分工读 `quarto/figures.md`。

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

@@ -1,6 +1,6 @@
 # 坐标轴网格图的生成约定
 
-坐标轴类网格图（状态面板行列、二维数组下标）用共享绘图助手生成 SVG，不用 Mermaid 硬画网格。流程图与坐标图的分工、页面围栏写法、解释器与 CI 依赖都在本文件；token 预算的排除口径见 `steps/02-structure.md`「计数口径」。
+坐标轴类网格图（状态面板行列、二维数组下标）用共享绘图助手生成 SVG，不用 Mermaid 硬画网格。流程图与坐标图的分工、页面围栏写法、解释器与 CI 依赖都在本文件；token 预算的排除口径见 `steps/02-structure.md`「分层上限」。
 
 ## 与 Mermaid 的分工
 

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

@@ -39,9 +39,7 @@
 
 反例：`Board` 只保存九个棋盘格子。落子、满盘、成线与赢家都从这些格子得出。写入前先检查坐标。声明在工程目录的 board.h。实现放在 board.cpp。
 
-改写：`Board` 从九个棋盘格子得出四类结果：坐标是否越界、棋盘是否已满、是否连成三个、赢家是谁。写入前先检查坐标；接口声明在工程目录的 board.h，实现放在 board.cpp。
-
-判定信号：同一段连续 4 个以上句号且多数句子短于 15 字；顿号串在分句之间；声明与实现各占一句，只剩位置碎片。
+改写与判定见 `steps/04-paragraphs.md`「章节核心不漂移」；本节只留这个标点反例：句号把共享主语的相邻短句切碎后，读者读到的是位置碎片，不是机制。
 
 ## 空格
 

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

@@ -1,6 +1,6 @@
-# 全仓 QMD 重构
+# 全仓 QMD 改写
 
-用于同时重构根入口、part 入口和全部 `content/**/*.qmd` 的任务。它补充单章写作规则，不替代章节骨架和领域路由。
+用于同时改写根入口、part 入口和全部 `content/**/*.qmd` 的任务。它补充单章写作规则，不替代章节骨架和领域路由。
 
 ## 范围
 
@@ -20,6 +20,6 @@
 
 ## 收尾
 
-全仓重构后，核对导航与路由表、标题层级、章节链接、源码摘录、命令和输出。先运行增量验证定位问题，再对所有 QMD 执行全量 `verifying-content.py`，最后在仓库根目录渲染 Book。按章推进时，每一章的出口是 `verifying-content.py --root <书根> --paths <该章>`；全部章节通过之后才 `render`。涉及知识库时同步索引、健康检查和评测；涉及代码时用实际构建、CTest 或示例验证核对文档。
+全仓改写后，核对导航与路由表、标题层级、章节链接、源码摘录、命令和输出。先运行增量验证定位问题，再对所有 QMD 执行全量 `verifying-content.py`，最后在仓库根目录渲染 Book。按章推进时，每一章的出口是 `verifying-content.py --root <书根> --paths <该章>`；全部章节通过之后才 `render`。涉及知识库时同步索引、健康检查和评测；涉及代码时用实际构建、CTest 或示例验证核对文档。
 
 ## 本项目边界

package/skills/writing-quarto/references/book-journey.md

@@ -1,6 +1,6 @@
 # 整本书的写作次序
 
-单章润色看一章；整书重构先看这本书要带读者完成什么，再决定章节次序。本文件只定整书层的判断，单章规则仍在 `steps/`。
+单章润色看一章；整书改写先看这本书要带读者完成什么，再决定章节次序。本文件只定整书层的判断，单章规则仍在 `steps/`。
 
 ## 先定一条主线
 
@@ -23,26 +23,26 @@
 - **总览章**写整体形状：交代对象在全局里的位置、彼此关系与阅读路线，可以点名后章对象，但不展开它的数据与函数。
 - **对象章**只写本章对象：数据成员、构造后的状态、公开接口与实现选择。后章才展开的类型名、个数标题、块后归属段不写；「留在某类型」「由某类得出」「不放进本章」这类归属句整句删除。
 - 对象章内的互斥结果写成无序列表，每项「情形：结果」，列表后停止；标题点名这一节的实体，不数条目（`八条线` 拆成 `线坐标表`、`成线判断`）。
-- 总览章与对象章的分界见项目章节表；本书 `01-rules.qmd`、`02-mapping-layout.qmd`、`viewing-program.qmd` 与两份 index 是总览，`03` 起各章是对象章。
+- 总览章与对象章的分界见项目章节表；项目没有章节表时，规则、结构与导航类章用总览写法，讲具体类型或函数的章用对象写法。
 - 整书遍同时统一陈述范围：部分页使用项目名与「这一部分」，不把单个样例抬成全书；只有书首页概括全书。页首导语不复述目录与章节卡片，卡片入口只写章节标题与一句交付结果。
 
-## 以井字棋书为例
+## 阶段示例
 
-| 阶段 | 章节 | 交给下一章的结果 |
-| --- | --- | --- |
-| 规则 | 对局规则 | 一局怎样算结束 |
-| 结构 | 工程结构、程序结构 | 文件与类的整体形状 |
-| 数据 | 棋盘、对局 | 格子、坐标、落子后的状态 |
-| 决策 | 电脑落子 | 电脑怎样选一格 |
-| 交互 | 终端程序、程序入口 | 人怎样下一局 |
-| 质量 | 调试、测试、构建与运行 | 改动后怎样确认没坏 |
-| 收束 | 局面快照 | 一局怎样保存与还原 |
+| 阶段 | 交给下一章的结果 |
+| --- | --- |
+| 规则 | 一局怎样算结束 |
+| 结构 | 文件与类的整体形状 |
+| 数据 | 对象、坐标与操作后的状态 |
+| 决策 | 程序怎样选择下一步 |
+| 交互 | 人怎样完成一次操作 |
+| 质量 | 改动后怎样确认没坏 |
+| 收束 | 怎样保存与还原一次过程 |
 
-这张表只是示例。项目有自己的章节表时，以 `.agents/skills/quarto-book-project/writing/chapter-map.md` 为准；没有就按上面的阶段顺序推，不猜项目事实。
+这张表只示例阶段顺序。项目有自己的章节表时，以 `.agents/skills/quarto-book-project/writing/chapter-map.md` 为准；没有就按上面的阶段顺序推，不猜项目事实。
 
 ## 插件层怎么配合
 
 - 整书规划先读本文件与项目章节表，再逐章加载 `steps/`；不要一次读完九步。
-- 单章判不准时才开 `examples/`；排图、查渲染或全仓重构才开 `quarto/`。
+- 单章判不准时才开 `examples/`；排图、查渲染或全仓改写才开 `quarto/`。
 - 全仓检查用 `scripts/`，渲染验收用 `quarto_render_check`；两件事都放在最后一遍，不在骨架遍执行。
 - 文件体量受 `references/token-budget.md` 约束；新增整书规则只写进本文件，不复制到各步。

package/skills/writing-quarto/references/personas.md

@@ -12,4 +12,4 @@
 
 ## 路由
 
-`03-board`、`04-game`、`05-ai` 用「C++ 文档」，其余章用「中文技术写作」。
+有代码摘录、以类型或函数为主体的章用「C++ 文档」；规则、流程与导航页用「中文技术写作」。具体章型看项目章节表；没有章节表时按本章是否交付可编译对象判断。

package/skills/writing-quarto/references/rules-cards.md

@@ -53,7 +53,7 @@
 - 步骤：`steps/02-structure.md`
 
 **C10 章节按五步走。** 现象 → 最小例子 → 机制 → 边界 → 自测。
-- 正：`03-board.qmd` 依次讲空棋盘、落子、越界、判胜、自测。
+- 正：章文件依次讲空棋盘、落子、越界、判胜、自测。
 - 反：先给完整类声明，再逐行解释。
 - 步骤：`steps/02-structure.md`
 
@@ -63,8 +63,8 @@
 - 步骤：`steps/03-blocks.md`
 
 **C12 一节一个关键。** 一章只解决一个问题，多出来的挪到下一章。
-- 正：03 章只讲棋盘；游戏流程留给 04 章。
-- 反：03 章顺手把 `Game` 的状态机也讲了。
+- 正：讲棋盘的章只讲棋盘；游戏流程留给下一章。
+- 反：讲棋盘的章顺手把 `Game` 的状态机也讲了。
 - 步骤：`steps/02-structure.md`
 
 **C13 章首导语 60–146 字。** 一段说清这章解决什么、读者读完能做什么。

package/skills/writing-quarto/references/token-budget.md

@@ -18,11 +18,11 @@
 | `assets/**/meta.md` | 2000 |
 | 全部技能 Markdown 合计 | 140000 |
 
-单次激活上限：`SKILL.md` + 1 个步骤 + 1 个被点名文件（案例、条文或脚本路径）。**九步同走**只用于新章、新阶段或用户明确要求全章重构；同轮不把同号案例与条文一起打开。
+单次激活上限：`SKILL.md` + 1 个步骤 + 1 个被点名文件（案例、条文或脚本路径）。**九步同走**只用于新章、整章改写或用户明确要求全章处理；同轮不把同号案例与条文一起打开。
 
 ## 怎么用
 
 - 新增规则先判断属于哪一层，再写进已有文件；同一判定只成文一处，其他位置写引用。
 - 文件将超限时，先删重复、合并同源条目，再考虑拆成同目录的新文件；拆文件后同步入口和 `scripts/checking-skill-links.mjs`。
-- 增量任务只加载 `SKILL.md`、当前一步与该步点名的一个文件；不要为了省 token 把整本书的规则塞进 `SKILL.md`。
+- 单点修改只加载 `SKILL.md`、当前一步与该步点名的一个文件；不要为了省 token 把整本书的规则塞进 `SKILL.md`。
 - 预算不是目标：没必要的条文直接删，不靠缩写把句子压成暗语。