@chengzhao-dev/dsh-quarto-book 0.6.7 → 0.6.9

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.7`; to follow a GitHub tag, write `github:chengzhao-dev/dsh-quarto-book#v0.6.7`.
+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.9`; to follow a GitHub tag, write `github:chengzhao-dev/dsh-quarto-book#v0.6.9`.
 
 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.7`，跟 GitHub 标签时写 `github:chengzhao-dev/dsh-quarto-book#v0.6.7`。
+`--profile` 换成你实际运行的那个 profile。桌面应用固定跑 `desktop` profile，且该 profile 由应用独占管理，`dsh --profile desktop` 直接启动会被拒绝；安装或升级用 `dsh plugin --profile desktop add <包>`，应用拒绝写入时再走「设置 → 插件 → 添加插件」。需要固定版本时写 `npm:@chengzhao-dev/dsh-quarto-book@0.6.9`，跟 GitHub 标签时写 `github:chengzhao-dev/dsh-quarto-book#v0.6.9`。
 
 从旧的无作用域包 `dsh-quarto-book` 升级（该包已随 0.3.4 从 npm 删除，只影响之前装过它的 profile）：先在同一个 profile 里 `dsh plugin --profile <profile> remove dsh-quarto-book`，再装新包。两个包同时留着会以相同的 rank 550 各注册一遍 `writing-quarto` 和 `designing-theme`。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chengzhao-dev/dsh-quarto-book",
-  "version": "0.6.7",
+  "version": "0.6.9",
   "description": "把一份 Quarto Book 写成可读、可查、可发布的中文技术书：九步章节写作、结构/链接/图表检查、统一主题与渲染验收。 · Write, check, and publish a Chinese Quarto Book: nine-step chapter writing, structure/link/figure checks, a consistent theme, and render acceptance.",
   "type": "module",
   "main": "./lib/index.js",

package/skills/designing-theme/SKILL.md

@@ -19,7 +19,15 @@ metadata:
 
 ## 任务路由
 
-任何主题任务先读 `references/theme-spine.md`（步骤唯一入口），再按其中每一步登记的文件与 `##` 行进。
+任何主题任务先读 `references/theme-spine.md`（步骤唯一入口）。增量任务只走被改组件所在的那一步，再加第 6 步「通过检查」；从定表面到通过检查依次走完只用于新主题或用户明确要求整体调整。
+
+## 加载与结束
+
+- 只改 `_quarto.yml` 实际引用的主题文件；不打开章节正文，也不打开章节以外的实现文件。
+- 一次激活只开本文件、`theme-spine.md`、被改组件对应的那一节与那一份 CSS；同轮不把其余组件 CSS 和知识文件一起打开。
+- 同一文件最多退回上一步一次；第二次仍失败就停在检查输出上，不重走整段。
+- `scripts/checking-layout.py` 通过并完成一次整本渲染后，在同一轮结束 goal，不把没失败的步骤留到下一轮。
+- 不探测同 profile 的其他插件，也不把它们写成依赖；子会话按自己的 cwd 重新判定门禁。
 
 | 任务 | 读取 |
 | --- | --- |

package/skills/designing-theme/assets/theme/css/content.css

@@ -11,9 +11,12 @@
      width: 100% 让表与代码块占满同一正文栏。横向滚动交给 .table-responsive。 */
   display: table;
   table-layout: fixed;
+  /* 与代码块同宽：占满正文栏、边框算在宽度内、左右不留外边距。 */
   width: 100%;
   max-width: 100%;
+  box-sizing: border-box;
   margin-block: 1.35rem 1.5rem;
+  margin-inline: 0;
   border: none;
   border-radius: 0;
   font-variant-numeric: tabular-nums;
@@ -31,23 +34,24 @@
   width: max-content;
   min-width: 100%;
 }
-.table > :not(caption) > * > * {
-  padding: 0.625rem 1rem;
+#quarto-document-content .table > :not(caption) > * > * {
+  /* 左右 1.25rem 让首列离开表的左缘，上下 0.7rem 保持行距；四边对称。 */
+  padding: 0.7rem 1.25rem;
   /* 多行单元格从顶部起排，同一行里短格子不被拉到垂直居中。 */
   vertical-align: top;
   /* 长 API 名与长句允许在格内折行，避免把整张表撑出内容列。 */
   overflow-wrap: break-word;
   border-bottom: 0;
 }
-.table thead th {
+#quarto-document-content .table thead th {
   /* 表头用加粗与一道极浅底色标出层级；不套 .compact-table，列宽仍随内容。 */
   background-color: color-mix(in srgb, var(--table-border) 24%, transparent);
   font-weight: 700;
   /* 表头比表体小 1px（17px → 15px），层级靠字重、字号与底色，不靠更粗的线。 */
   font-size: 0.9375rem;
   line-height: 1.6;
-  /* 表头是短标签，水平与垂直都居中；表体长句保持左对齐、顶对齐。 */
-  text-align: center;
+  /* 表头跟随该列：默认左对齐，数字列由 Pandoc 的行内 text-align 右对齐。 */
+  text-align: left;
   vertical-align: middle;
   border-top: 1px solid var(--table-border);
   border-bottom: 1px solid var(--table-border);
@@ -56,17 +60,12 @@
   border-bottom: 1px solid var(--table-border);
 }
 
-/* 短对照表保持全宽左对齐（与正文同宽，不居中收窄）；左对齐便于中文术语扫读。
+/* 短对照表保持全宽（与正文同宽，不居中收窄）；对齐与内边距已由 .table 统一。
    宽表由 .table 默认规则负责，不要给多列/长单元格表套本类。 */
 .compact-table {
   width: 100%;
   overflow-x: auto;
 }
-.compact-table .table th,
-.compact-table .table td {
-  text-align: left;
-  padding-inline: 1.25rem;
-}
 
 /* 表题：Pandoc 输出 <caption>，Bootstrap 默认把它放表下（caption-side: bottom），
    这里统一提到表上、左对齐，与图注一样小一号。 */

package/skills/designing-theme/references/theme-spine.md

@@ -4,7 +4,7 @@
 
 ## 主题步骤
 
-从定表面到通过检查依次走完；后一步发现前一步没做完，退回那一步，不在当前步补。每一步只打开登记的那一个文件和那一个 `##`。
+增量任务只走被改组件所在的那一步，再加第 6 步通过检查；从定表面到通过检查依次走完只用于新主题或用户明确要求整体调整。后一步发现前一步没做完，退回那一步一次；同一文件第二次仍失败就停在检查输出上。每一步只打开登记的那一个文件和那一个 `##`。
 
 | 步骤 | 动作与产出 | 登记的文件与一节 |
 | --- | --- | --- |

package/skills/designing-theme/references/theme-system.md

@@ -81,7 +81,7 @@
 - **章节翻页**：一条顶线 + 左右两个文字链接，不用边框卡片；箭头用 `<` / `>`，hover 才转 `--accent`，下一页右对齐。箭头用字符而不用 SVG 是量过的：Bright 的 `<` `>` 墨迹中心在 0.23em，与同行西文同一轴，没有面包屑 `>` 那种偏高，换 SVG 反而要另配基线。
 - **章节线**：标题不画线。全书只有一种横线——通栏 1px `--card-border` 发丝线，只出现在顶栏底边、引用块上下边、表格 booktabs、首页目录每行顶线、翻页顶线、页脚顶线、答案折叠线；`h2::after` 的 2.25rem 短发丝线已删除（连同首页 `.feature-grid` 例外），章节节奏只靠 H2 的 `margin-top: 3.25rem` 与字号台阶。约定改动时同步本节与 `css/base.css`。
 - **引用块**：上下各一条 1px `--card-border` 横线、正文色、无底色、无左右竖条；与 Callout 的 2px 左色条区分开（后者是类型标记，不是分隔线）。
-- **表格**：`display: table` + `table-layout: fixed` 吃 `tbl-colwidths`，`width: 100%` 让表与代码块占满同一正文栏；表头水平与垂直居中，表体左对齐、顶对齐，四边 padding 一致、首列不贴边。`display: block` 不行：外层块占 100%，里面的匿名表按内容收缩，表会变窄。宽表由 Quarto `.responsive` 类包成 `.table-responsive` 外层滚动容器；包内表改回 `table-layout: auto` + `width: max-content`，否则 fixed + 100% 永远不会溢出、滚动条是死的。不需要 JS 量列宽。表题走 `caption-side: top`、左对齐、14px `--text-secondary`；`table-striped` 压平成与普通行同底。
+- **表格**：`display: table` + `table-layout: fixed` 吃 `tbl-colwidths`；`width: 100%` + `box-sizing: border-box` + `margin-inline: 0` 让表外框与代码块外框同宽、左右边缘对齐；单元格 `padding: 0.7rem 1.25rem`，首列因此离开表的左缘。表头与表体同一列对齐：文本列左对齐，数字列右对齐，表头跟随该列；垂直方向表体格子顶对齐（`vertical-align: top`），表头文字在格内居中（`vertical-align: middle`）。`display: block` 不行：外层块占 100%，里面的匿名表按内容收缩，表会变窄。宽表由 Quarto `.responsive` 类包成 `.table-responsive` 外层滚动容器；包内表改回 `table-layout: auto` + `width: max-content`，否则 fixed + 100% 永远不会溢出、滚动条是死的。不需要 JS 量列宽。表题走 `caption-side: top`、左对齐、14px `--text-secondary`；`table-striped` 压平成与普通行同底。
 - **脚注**：区块顶部一条 1px `--card-border`、`margin-top: 3rem`、14px / lh 1.7、`--text-secondary`；回跳箭头随正文链接色。
 - **任务列表**：`input[type=checkbox]` 用 `accent-color: var(--action-color)`，不用系统蓝。
 - **图片**：正文图与坐标图圆角一律 `--radius-sm`（3px），不用 6px 大圆角；图注选择器同时覆盖 `figure figcaption`、`.quarto-float-caption`、`.figure-caption`（`lang: zh` 后 Quarto 生成「图 3.1: …」，`lang` 必须写在 `_quarto.yml`，否则图/表题回落英文 Figure/Table）。

package/skills/writing-quarto/SKILL.md

@@ -7,7 +7,7 @@ metadata:
 
 # Skill: writing-quarto
 
-承载 `.qmd` 章节的写法流程与 Book 结构约定。正文只有九步：每一步只打开 `steps/` 里同号的一个文件；判不准才打开 `examples/` 里同号的案例；要排图、查渲染或全仓重构才打开 `quarto/`。不读插件包内的 `docs/`，也不读书里的旧通用副本。
+承载 `.qmd` 章节的写法流程与 Book 结构约定。正文只有九步：增量任务只打开与这次改动对应的一个 `steps/` 文件；九步同走只用于新章、新阶段，或用户明确要求全章重构。判不准才打开步骤点名的那一个 `examples/` 案例；要排图、查渲染才打开 `quarto/`。不读插件包内的 `docs/`，也不读书里的旧通用副本。
 
 ## 适用场景
 
@@ -16,6 +16,15 @@ metadata:
 - 项目带有 `.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` 不在写作范围。这条只在书仓库里适用（技能本身由 Book 门禁触发）。
 
+## 加载与结束
+
+- 一次激活只做一类文件：章节或主题。写章节时只打开项目技能或 `_quarto.yml` 点名的章节；围栏保持原样，不为逐字核对去读实现文件。
+- 项目提供作用域命令就先跑它，只读它列出的文件；渲染产物、构建目录与 Quarto 缓存不读。
+- 增量任务只开本文件、当前一步与这一步点名的一个文件；同轮不把同号案例、其余步骤和条文一起打开。
+- 同一文件最多退回上一步一次；第二次仍失败就停在检查输出上，不重走整段。
+- 项目技能列出检查命令时只跑那一条；没有就跑本技能 `scripts/` 下的内容与链接检查。退出码为 0 就在同一轮结束 goal，不把没失败的步骤留到下一轮。
+- 不探测同 profile 的其他插件，也不把它们写成依赖；子会话按自己的 cwd 重新判定门禁，不把技能正文塞进子代理提示。
+
 ## 整书走法
 
 改多章或排目录时，先读 `references/book-journey.md`：先定全书主线与章节次序，再逐章走九步，最后做全书一致性回读。只润色一章时不读它。
@@ -24,11 +33,11 @@ metadata:
 
 ## 两种走法
 
-增量润色沿九步走，只改判为不合格的地方，其余保持原样。全章重构仍是这九步，但第 1–2 步先定删留、不动句子，第 3–4 步只拆块和段，第 5–7 步才逐句改。
+增量任务只走与改动对应的步骤，只改判为不合格的地方，其余保持原样；九步同走只用于新章、新阶段或用户明确要求全章重构。全章重构仍是这九步，但第 1–2 步先定删留、不动句子，第 3–4 步只拆块和段，第 5–7 步才逐句改。
 
 两条走法共守同一组不变量，写在这里，不重复进各步：不新增原文没有的事实、数字、命令、性能结论、引文和出处；不把「可能」「通常」「在本书里」这类留有余地的说法改成确定说法；保留否定、条件、范围、时间和归属；围栏里的代码、命令、路径、URL 与 YAML 不改。增量润色只删除和换词，不扩写、不补论证；全章重构可删可换序，但不能发明事实，也不能把限定说成确定。
 
-后一步发现前一步没做完，退回那一步重做，不跳到更后面的步骤补救。
+后一步发现前一步没做完，退回那一步改一次；同一文件第二次仍失败就停在检查输出上，不重走整段。
 
 ## 九步
 
@@ -47,7 +56,8 @@ metadata:
 
 ## 完成判据
 
-- [ ] 九步走完，每一步的产出都落在正文里。
+- [ ] 本轮点名的文件走完它对应的步骤，改动落在正文里；不要求九步全走。
+- [ ] 本轮检查命令退出码为 0；通过后按「加载与结束」在同一轮结束 goal。
 - [ ] 内容与链接核对通过：项目技能列了检查命令时按它执行，否则跑本技能 `scripts/verifying-content.py` 与 `checking-links.py`。
 - [ ] 新人能按正文独立完成任务：前置、动作、结果与失败出口齐全，术语首用有解释；清单见 `quarto/readability.md`。
 - [ ] 混排自查通过：`scripts/checking-prose.py --root <book>` 无高置信问题。

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

@@ -112,3 +112,21 @@
 ```
 
 自查：删掉重复句后，读者还缺哪一条事实？只补缺的那条；「数量不变」「出界不写入」若已在类注释或 `IsInRange` 的契约里写过，就不再复述。
+
+## 混段：函数、终端与测试
+
+不佳（一段里同时讲读接口、终端和测试）：
+
+`GetCellType`、`IsCellEmpty`、`IsInRange` 负责读格子；终端用 `ReadHumanMove` 和 `PrintGame` 显示棋盘；测试用 `gtest_discover_tests` 注册六组用例。
+
+改写（先一句导语，再一项一件）：
+
+`PlaceCell` 尝试把棋子写进棋盘，写入前先检查坐标与目标格。
+
+- `IsInRange`：检查坐标是否落在棋盘内。
+- `IsCellEmpty`：检查目标格是否为空。
+- `PlaceCell`：通过两项检查后写入棋子，失败时棋盘不变。
+
+终端读入、终端打印和测试注册各自另起一段或另起列表。
+
+判定信号：一段里出现三个以上函数名，且分句之间没有「因此」这类递进关系；读者无法从中挑出下一步要改的那一处。

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

@@ -27,6 +27,18 @@
 
 判定信号：设计说明句里选择先于依据，读者要把因果倒过来才能读；「是规则的一部分」这类只贴类别、不改变下一步的分句；删掉关系词后读者仍要自己补因果；「正好装下」在同段复述同一核；后续小节专讲的对象在本段末尾写成「由 X 完成」。
 
+## 技能腔：解释作者的选择
+
+不佳（把「这里不定义自己的异常类型」写进正文，读者没有下一步动作）：
+
+`GetCellType` 越界时抛出 `std::out_of_range`，消息里带行号和列号。这里不定义自己的异常类型：调用方用 `std::out_of_range` 就能接住，测试也不必为项目再记一个类型名。
+
+改写（只留读者看得到的结果）：
+
+`GetCellType` 越界时抛出 `std::out_of_range`，消息里带行号和列号。
+
+判定信号：句子在解释作者为什么不另造类型、测试为什么少记一个名字、注释该怎么组织；删掉后读者执行的动作不变。
+
 ## 拉链句
 
 一句话把两组对象两两配对，删掉任一配对、剩下的仍能单独成立，原句就是拉链句：读者要按顺序把左组一一配到右组，且两个配对共用同一个判据（判定与三条改写见 `steps/05-sentences.md`「拉链句」；步骤链、同物两处与回顾不按拉链判）。以 示例章章首改稿前与 示例章改稿前为对照：

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

@@ -31,7 +31,7 @@
   ```
 
   比例按内容分配：名称与接口列 18–26，返回列 22–32，说明列 34–50，三项合计 100。三列以上时最长列不超过 55，避免其余列被挤成一条线。
-- 表格与代码块同宽：主题用 `table-layout: fixed` 吃上面的比例，四边内边距一致，首列不贴边；表头在格内水平、垂直居中，表体左对齐、顶对齐。
+- 表格与代码块同宽：主题用 `table-layout: fixed` 吃上面的比例，`width: 100%`、`box-sizing: border-box` 与左右零外边距让两者外框对齐；单元格 `0.7rem 1.25rem`，首列不贴边。文本列左对齐，数字列右对齐，表头跟随该列。
 - 宽表在表属性里加 `.responsive`（Quarto 内置类）：Quarto 生成外层 `.table-responsive` 滚动容器，主题在该容器里改回按内容宽度排布，内容超过正文栏时才出现横向滚动。窄表可省。
 - 不写固定宽度（`{width=...}`、`style="width:..."`），也不覆盖 `table-layout`；比例之外的几何由主题负责。
 - 长单元格先改文案：删重复修饰，把条件与结果按「条件 + 结果」排成一句。仍长时允许格内折行，`overflow-wrap: break-word` 已由主题处理。
@@ -41,7 +41,7 @@
 - 一格一个事实，对象先行。不写「名词：一句」的伪列表，列已经分出属性名。
 - 行内代码只放读者要输入的标识符或类型名；一格最多两个，多了会把列撑宽，也让比较点被代码淹没。
 - 空值与未知写「无」或「不判断」，不写 `-`、`N/A`。
-- 数字右对齐、文本左对齐由主题按列决定；不要在单元格里手动空格对齐。
+- 列对齐由管道表的 `---:` 标记决定，主题只给默认左对齐；不要在单元格里手动空格对齐。
 - 中英混排留半角空格，标点用全角，规则见 `quarto/prose.md`。
 
 ## 表题与引用

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

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

package/skills/writing-quarto/scripts/verifying-content.py

@@ -54,6 +54,16 @@ COINED_RELATION_RE = re.compile(r"(?:组成|依赖|继承|调用)边")
 CARRIER_RE = re.compile("承载")
 NEXT_SECTION_RE = re.compile(r"(?:下一节|上一节)")
 LADDER_RE = re.compile(r"(?:分别交给|各说一层)")
+SKILL_TONE_RE = re.compile(r"这里不定义|测试也不必|不必为[^。；\n]{0,20}再记|不写双层循环")
+INLINE_NAME_RE = re.compile(r"`([A-Za-z_][A-Za-z0-9_]*)`")
+FUNCTION_NAME_RE = re.compile(
+    r"^(?:Is|Get|Set|Has|Can|Completes|Place|Read|Write|Print|Run|Make|Collect|Judge|"
+    r"Score|Search|Choose|Add|Clear|Reset|Find|Build|Parse|Format|Render|Report|Show|"
+    r"Start|Stop|Create|Destroy|Update|Check|Validate|To)[A-Z0-9_]"
+    r"|^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$"
+)
+TERMINAL_RE = re.compile(r"终端|打印|显示|输入|读入|命令行")
+TEST_RE = re.compile(r"测试|断言|用例|gtest|CTest")
 
 TREE_CATEGORY_COMMENTS = frozenset({
     "头文件", "源文件", "源码", "实现", "测试", "配置文件",
@@ -196,12 +206,27 @@ def check_heading(path: Path, line: int, level: int, text: str, issues: list[Iss
         issues.append(Issue(path, line, "标题带行内代码；文件名留给正文，标题写对象"))
 
 
-def check_prose_block(path: Path, start_line: int, text: str, issues: list[Issue]) -> None:
+def check_prose_block(
+    path: Path, start_line: int, text: str, issues: list[Issue], is_list: bool = False
+) -> None:
     compact = text.strip()
     if not compact:
         return
     if CHAPTER_NUMBER_RE.search(compact):
         issues.append(Issue(path, start_line, "第 N 章式编号指称（用章节标题或链接）"))
+    if SKILL_TONE_RE.search(compact):
+        issues.append(Issue(path, start_line, "技能腔：只约束作者的选择，整句删掉"))
+    if not is_list and CJK_RE.search(compact):
+        names = {
+            match.group(1)
+            for match in INLINE_NAME_RE.finditer(compact)
+            if FUNCTION_NAME_RE.search(match.group(1))
+        }
+        if len(names) >= 3 and TERMINAL_RE.search(compact) and TEST_RE.search(compact):
+            issues.append(Issue(
+                path, start_line,
+                f"一段里出现 {len(names)} 个函数名，还同时讲终端与测试；拆成列表，一项一件",
+            ))
     if CJK_RE.search(compact):
         length = len(re.sub(r"\s+", "", compact))
         if length > MAX_PARAGRAPH_CHARS:
@@ -569,7 +594,9 @@ def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> li
 
         if raw.lstrip().startswith((">", "-", "*", "+", "1.")):
             flush_paragraph()
-            check_prose_block(path, number, re.sub(r"^\s*(?:[>|]|[-*+]|\d+\.)\s*", "", raw), issues)
+            check_prose_block(
+                path, number, re.sub(r"^\s*(?:[>|]|[-*+]|\d+\.)\s*", "", raw), issues, is_list=True
+            )
             continue
 
         if not paragraph:

package/skills/writing-quarto/steps/03-blocks.md

@@ -260,4 +260,4 @@ int main() {
 
 ## 正反例
 
-通用情况判得准就不打开。判不准时打开同号案例：`examples/03-block-after.md`、`examples/03-excerpt-lead.md`、`examples/03-qmd-elements.md`。
+通用情况判得准就不打开。判不准时只开 `examples/03-block-after.md`，按命中的信号读其中一节；`03-excerpt-lead.md` 与 `03-qmd-elements.md` 留到下一次激活。

package/skills/writing-quarto/steps/04-paragraphs.md

@@ -34,6 +34,7 @@
 | --- | --- |
 | 段内出现第二个互不依赖的对象或主题 | 新起段；新段首句接住上段对象（衔接见本文件「段间：过渡句只在话题切换处」） |
 | 段内出现「话题标签：解释」词条式冒号，或两个以上互不依赖的中心并列推进 | 按「拆核四步（多核混段的拆段方法）」判关系：递进同段衔接推进，并列拆段；词条式冒号改完整主谓句（见「散文伪标签冒号禁令」） |
+| 一段同时讲多个函数、终端打印和测试核对，句子互不从属 | 改成列表，一项一个函数或一种调用场合；正反例见 `examples/04-paragraph-cases.md`「混段：函数、终端与测试」 |
 | 一段同时承担「承接上一章」+「本章交付物清单」+「源文件位置」+「摘录声明」 | 章引言不拆段，形态硬限与摘录声明删除见 `steps/02-structure.md`；其他段落按职责拆段，交付物多项且需扫读 → 列表（目录式堆砌对照见 `examples/02-structure-shape.md`） |
 | 超过约 4 行舒适带、或逼近 7 行 / 篇幅 token 上限 | 先找逻辑边界拆，禁止为凑行数在句中腰斩 |
 | 连续 ≥3 段纯散文且无列表/代码/图 | 改写见本文件「句序与段落形态」 |
@@ -213,4 +214,4 @@
 
 ## 正反例
 
-通用情况判得准就不打开。判不准时打开 `examples/04-paragraph-cases.md`、`examples/04-paragraph-opening.md`。
+通用情况判得准就不打开。判不准时只开 `examples/04-paragraph-cases.md`，按命中的信号读其中一节；`04-paragraph-opening.md` 留到下一次激活。

package/skills/writing-quarto/steps/05-sentences.md

@@ -35,12 +35,13 @@
 - 每个分句只担任一种角色：可观察事实、不变约束、因此作出的选择。次序固定为**事实 → 约束 → 因此选择**；选择句不得出现在依据之前——先写「长度取常量」再补「九个格子」，读者要把因果倒过来读。
 - 光有回指不够。后一分句若不是同一谓语的延续，必须写出「因此 / 所以」；删掉关系词后读者仍要自己补因果，判为不合格。可观察事实（「状态面板一共九个格子」）可以在前，读者据此才知道选择成立。
 - 「是示例项目规则的一部分」这类只贴类别、不改变下一步的分句删除：它不回答「所以代码怎么办」。
+- 「因此选择」必须是读者下一步要执行的动作。只约束作者的选择（不另造类型、测试少记一个名字、注释该怎么组织）整句删掉，不改写成另一句解释；正文不展开与本章对象无关的标准库机制，也不写「不写甲，而是乙」。
 - 一句里用逗号甩出的独立判断，最多留「事实，约束」或「约束，所以选择」一对；第三个判断另起句或删除。单句仍守本文件「句子规则」的 40 字与一动作上限。
 - 递进同一核不拆段复述：长度和装下它的数组是同一个核，同段用「因此」接住，不另起一段再说一遍「正好装下」。
 - 后续小节专讲的对象，本段不写「由 X 完成」：换算如果由下一小节专讲，本段不提前交接（「换算由下一小节完成」）；块内注释或下节首句已经说出的职责，整句删除。
 - 与「对象先行」的对齐方式见 `steps/04-paragraphs.md`「句序与段落形态」。
 
-判定信号：设计说明句里选择先于依据；逗号甩出第三个独立判断；分句只贴类别不改变下一步；删掉关系词后因果要读者自补；段末提前交接后续小节的对象。改写对照见 `examples/05-sentence-frame.md`「句内骨架：先依据后选择」。类型接线句与被下一句否定的全称按本文件「一次对话」判删留，不按本节改写句内次序。
+判定信号：设计说明句里选择先于依据；逗号甩出第三个独立判断；分句只贴类别不改变下一步；删掉关系词后因果要读者自补；段末提前交接后续小节的对象；「因此选择」只约束作者、读者没有下一步动作。改写对照见 `examples/05-sentence-frame.md`「句内骨架：先依据后选择」与「技能腔：解释作者的选择」。类型接线句与被下一句否定的全称按本文件「一次对话」判删留，不按本节改写句内次序。
 
 ### 拉链句
 
@@ -233,4 +234,4 @@
 
 ## 正反例
 
-通用情况判得准就不打开。判不准时打开 `examples/05-sentence-frame.md`、`examples/05-sentence-reference.md`、`examples/05-sentence-brevity.md`。
+通用情况判得准就不打开。判不准时只开 `examples/05-sentence-frame.md`，按命中的信号读其中一节；另外两份 05 案例留到下一次激活。

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

@@ -31,7 +31,7 @@
 | 定句子 | 节首句以「这些／这个／这一步」作话题且同句列不出对象名（所指要等后面的 `###` 或代码围栏） | 节首同句列出对象名；已逐个写出名字后的回指保留 | `steps/05-sentences.md`「代词不能代替未写出的对象」、`examples/05-sentence-reference.md`「定结构与定句子：代词不能代替未写出的对象」 |
 | 定句子 | 类型接线句（两个逗号分句各自是「成员叫法 + 使用 + 某一章的类型」，且两项都已在紧邻导语与围栏出现） | 整段删除，不走拉链的推迟、拆句、一项一行 | `steps/05-sentences.md`「一次对话」、`examples/04-paragraph-cases.md`「定段落：类型接线段整段删除」 |
 | 定句子 | 一句里的全称（全部、所有、唯一）被下一句否定 | 改范围或删除；全称读完下一句仍成立才保留 | `steps/05-sentences.md`「一次对话」 |
-| 定句子 | 先决定后补依据 / 逗号甩判断（一句用逗号并列三个以上独立判断）/ 「由 X 完成」式被动交接 | 按「句内骨架」改为事实 → 约束 → 因此选择；「由 X 完成」在定用词改主动句 | `steps/05-sentences.md`「句内骨架」 |
+| 定句子 | 先决定后补依据 / 逗号甩判断（一句用逗号并列三个以上独立判断）/ 「由 X 完成」式被动交接 | 按「句内骨架」改为事实 → 约束 → 读者下一步要执行的动作；只约束作者的选择整句删除；「由 X 完成」在定用词改主动句 | `steps/05-sentences.md`「句内骨架」 |
 | 定句子 | 元叙述开场（「是规则，代码把它写成」「因此记作／写成 `class`」） | 对象先行：改为「对象 → 名称 → 约束 → 出处」 | `steps/06-wording.md`、`examples/01-language-scope.md` |
 | 定句子 | 拉链句（两组对象配对，删任一仍成立；「分别交给／各说一层／分别是」） | 按推迟 → 拆句 → 一项一行改写 | `steps/05-sentences.md`「拉链句」、`examples/05-sentence-frame.md`「拉链句」 |
 | 定句子 | 假对比「这不仅是 X，更是 Y」两半并不都提供信息；起跑式铺垫（「在开始之前」「首先我们来看」）；句尾把一次操作拔高成意义 | 删宣布与拔高；两半都有信息时保留对比 | `steps/05-sentences.md`「情况：假对比、起跑式铺垫与意义拔高」 |
@@ -59,7 +59,7 @@
 
 ### 润色流程：沿着步骤走
 
-润色任务沿 `SKILL.md` 的写作步骤执行，从定任务走到通过检查，跳步视为未完成；判定标准见 `steps/06-wording.md`。书根 `README.md` 与 `README.en.md` 是仓库说明页，按 `SKILL.md` 的例外只走第 5–8 步，这个例外优先于本步的跳步判定。两种走法共用 1–9：**增量润色**保持最小改动，只改判为不合格的句子，不做风格重塑；**全章重构**按 `SKILL.md`「两种走法」走——章级（1–2）先定删留不动句子，节级（3–4）只拆块和段，句级（5–7）逐句拆开再写回去，该层全部重组，不走最小改动。执行时遵守定段落节的既有判定：分句骨架在定句子判为不合格，不在定段落里顺手改句子。
+润色任务沿 `SKILL.md` 的路由执行：增量任务只走与改动对应的步骤；新章、新阶段或用户明确要求全章重构才从定任务走到通过检查。判定标准见 `steps/06-wording.md`。书根 `README.md` 与 `README.en.md` 是仓库说明页，按 `SKILL.md` 的例外只走第 5–8 步，这个例外优先于本步的跳步判定。两种走法共用 1–9：**增量润色**保持最小改动，只改判为不合格的句子，不做风格重塑；**全章重构**按 `SKILL.md`「两种走法」走——章级（1–2）先定删留不动句子，节级（3–4）只拆块和段，句级（5–7）逐句拆开再写回去，该层全部重组，不走最小改动。执行时遵守定段落节的既有判定：分句骨架在定句子判为不合格，不在定段落里顺手改句子。
 
 **先切模块，再套规则。** 任何一步动笔前先把文本切成单位，围栏、YAML 与链接 URL 跳过（脚本按同一口径统计，计数见 `verifying-content.py` 输出）：
 
@@ -73,13 +73,14 @@
 
 「一次对话」不与这些单位并列成切分单位：脚本切得出标题、空行、句号、列表和表格，切不出「一次说话」。它只留在 `steps/05-sentences.md`「一次对话」的判定里——定段落先问这段有几件内容，再决定删、拆或切成几次说话；定句子才改措辞。
 
-1. **普查建账**：`git ls-files` 按扩展名分类，列出全部含中文自然语言的文件（跳过机器生成物与二进制）。台账写 `temp/`（不入库），逐文件记「审读状态／修改数／备注」；任务结束前每行落到「已审」，无问题也记「未发现」。覆盖率由 `verifying-content.py` 的「中文体检」项背书：台账文件总数与脚本输出的载体组计数对不上即为漏审。
-2. **沿步骤逐篇走**：从定任务到通过检查，每步只改该步判为不合格的句子；后一步发现前一步没做完，退回那一步，不在当前步补结构。某句只在定用词失败，就不重写它的结构；某段在定句子失败，先改骨架，再让定用词看一遍。已合格的句子不重润。
+1. **确定范围**：用户点名的文件，或本轮已改动的文件；项目提供作用域命令时先跑它，只读它列出的文件。全库中文普查只在用户明确要求审完全部中文文件时做，它自己就是那个 goal 的结束条件，不嵌进单章润色。
+2. **沿步骤走本次文件**：每个文件只走它对应的步骤，每步只改该步判为不合格的句子；后一步发现前一步没做完，退回那一步一次，不在当前步补结构。某句只在定用词失败，就不重写它的结构；某段在定句子失败，先改骨架，再让定用词看一遍。已合格的句子不重润。
 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`「完成判据」。
+4. **验收同步**：按改动域跑校验（qmd → `verifying-content.py` + `checking-links.py`；有项目技能时只跑它列出的那一条命令，不跑全量 profile）。检查次数与停手见 `steps/09-check.md`「完成判据」。
 
 ### 完成前核对
 
+- [ ] 本轮范围只含用户点名或已改动的文件；没有默认全库台账。
 - [ ] 信号表逐行扫过，FAIL 清零；WARN 记台账不追清。
 - [ ] 章节骨架与 `steps/02-structure.md` 一致；引言形态守 `steps/02-structure.md`。
 - [ ] 与改前文本对照过：没有新增原文没有的事实、遗漏读者需要的信息，或把限定说成确定；判法见本文件「情况：对照改前文本」。
@@ -96,7 +97,7 @@
 
 ### 情况：现象落在更早的步骤
 
-信号表说现象属于哪一步，就退回那一步改，不在第 8 步改写。一次只退一步，改完重新回读。
+信号表说现象属于哪一步，就退回那一步改，不在第 8 步改写。一次只退一步，改完重新回读；第二次仍失败就停在检查输出上。
 
 ### 情况：章级低频问题