@chengzhao-dev/dsh-quarto-book 0.3.4 → 0.4.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 chengzhao-dev
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+MIT License
+
+Copyright (c) 2026 chengzhao-dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

package/README.en.md

@@ -4,7 +4,11 @@
 
 **English** | [简体中文](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/README.md)
 
-Two skills and one tool for [DeepSeek Harness](https://github.com/deepseek-ai) (DSH): authoring Quarto Book chapters, maintaining a reusable book theme, and checking rendered HTML before publishing. The skills are read-only — they never execute book code and never edit `.qmd` files. `quarto_render_check` runs `quarto render` once when called, so it executes the book's configured engine and writes `_book/`.
+Author and check Quarto Book chapters and maintain a reusable theme; no business code, only inside `type: book` repositories.
+
+- Write `.qmd`: `writing-quarto` covers the chapter skeleton, structure and prose.
+- Change the theme: `designing-theme` covers CSS, fonts and palettes.
+- Check rendered HTML: `quarto_render_check` judges publishability once, and `quarto_pass_report` prints the closing receipt.
 
 ## What it provides
 
@@ -13,6 +17,7 @@ Two skills and one tool for [DeepSeek Harness](https://github.com/deepseek-ai) (
 | `writing-quarto` | Creating or editing `content/**/*.qmd`, `index.qmd`, `_quarto.yml`; chapter skeletons, Chinese prose, code and figures, content checks | CSS, fonts and colours |
 | `designing-theme` | Theme CSS, SCSS, fonts, palettes, navigation and callout styling | Chapter prose |
 | `quarto_render_check` | Check that `output-dir` is safe, render once when asked, and inspect HTML in `_book/` for publishing | Editing `.qmd`, fixing config automatically, or re-running a failed render |
+| `quarto_pass_report` | Compress the run into a fixed-line receipt card: skill, mode, files and steps changed, items held, check verdicts | Saving to disk, quoting chapter prose, or changing the text based on the receipt |
 
 For when the skills appear and which rule each step maps to, see [`docs/plugin-flow.md`](docs/plugin-flow.md). It is a human-facing walkthrough, not the rule source used while a skill runs.
 
@@ -21,12 +26,12 @@ Both skills are discovered from the package's `skills/` directory and loaded on
 ## Install
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-quarto-book@0.3.4
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-quarto-book@0.4.0
 ```
 
-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 a plugin with `dsh plugin --profile desktop add <package>`, and use the app's Settings → Plugins → Add plugin with `npm:@chengzhao-dev/dsh-quarto-book@0.3.4` only if the app refuses that write. To follow a GitHub tag instead, use `github:chengzhao-dev/dsh-quarto-book#v0.3.4`.
+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 a plugin with `dsh plugin --profile desktop add <package>`, and use the app's Settings → Plugins → Add plugin with `npm:@chengzhao-dev/dsh-quarto-book@0.4.0` only if the app refuses that write. To follow a GitHub tag instead, use `github:chengzhao-dev/dsh-quarto-book#v0.4.0`.
 
-Upgrading from the old unscoped package `dsh-quarto-book`: 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.
+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.
 
 Requires DSH 0.2.x and Node.js 22 or newer. The source is TypeScript; the published package already contains compiled `lib/`, so installation needs no build step.
 
@@ -119,6 +124,32 @@ Call `quarto_render_check(qmd_path: "content/chapter.qmd", dry_run: true)`. It r
 
 The raw render output never becomes a separate terminal card. The render timeout is 120 seconds; timeouts, a missing `quarto` executable and non-zero exits all go into `errors`.
 
+## Run receipt
+
+At the end of a run the skill calls `quarto_pass_report` once, compressing the run into a few fixed lines. The card is the receipt; the reply does not repeat it, and the tool saves nothing to disk, quotes no chapter prose, and changes no text based on the receipt.
+
+Every parameter is a closed set:
+
+| Field | Values |
+| --- | --- |
+| `skill` | `writing-quarto` or `designing-theme` |
+| `executed` | Boolean; when `false`, `mode` must be `skipped` and `skip_reason` (at most 40 characters) is required |
+| `mode` | `polish`, `rewrite` (writing), `theme` (theme), `skipped` (not executed) |
+| `files` | Up to 8 `{ path, edits }` entries |
+| `steps` | Only steps with edits: `1`–`9` for writing, or `定表面`, `定字体`, `定尺度`, `定颜色`, `定组件`, `通过检查` for the theme; their `edits` must sum to the `files` total |
+| `held` | `fences`, `facts`, `css`, `prose` |
+| `checks` | `content`, `html`, `layout`, with status `pass`, `fail` or `skip` |
+
+```text
+已执行 writing-quarto · 增量润色
+content/ch.qmd
+改了 5 处：定句子 3，定用词 1，定版式 1
+未改：围栏、事实
+检查：内容通过；HTML 可用
+```
+
+A zero-change run still prints a card (`改了 0 处`), so "the plugin never ran" stays distinguishable from "it ran and changed nothing"; when the current file is not a chapter the output is one line: `未执行 writing-quarto：…`.
+
 ## Theme
 
 Theme assets live in `skills/designing-theme/assets/theme/`:

package/README.md

@@ -4,7 +4,11 @@
 
 [English](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/README.en.md) | **简体中文**
 
-为 [DeepSeek Harness](https://github.com/deepseek-ai)（DSH）提供两个技能和一个工具：写 Quarto Book 章节、维护可复用的书主题、在渲染后检查 HTML 是否可发布。技能只读，不执行书里的代码，也不改写 `.qmd`；`quarto_render_check` 只在被调用时运行一次 `quarto render`，会执行书配置的引擎并写入 `_book/`。
+为 Quarto Book 写章节、校验结构并维护可复用主题；不改业务代码，只在 `type: book` 的仓库里出现。
+
+- 写 `.qmd`：`writing-quarto` 管章节骨架、结构与行文。
+- 改主题：`designing-theme` 管 CSS、字体与 palette。
+- 渲染后检查 HTML：`quarto_render_check` 判一次可发布性，`quarto_pass_report` 出收尾回执。
 
 ## 提供什么
 
@@ -13,6 +17,7 @@
 | `writing-quarto` | 新建或修改 `content/**/*.qmd`、`index.qmd`、`_quarto.yml`；章节骨架、中文行文、代码与图表、内容检查 | 不改 CSS、字体和颜色 |
 | `designing-theme` | 调整主题的 CSS、SCSS、字体、palette、导航与 Callout 样式 | 不改章节正文 |
 | `quarto_render_check` | 先判断 `output-dir` 是否安全，再按需渲染一次，检查 `_book/` 里的 HTML 是否可发布 | 不改 `.qmd`，不自动修配置，不重复渲染 |
+| `quarto_pass_report` | 收尾时把执行结论压成一张固定行数的回执卡片：技能、模式、改过的文件与步骤、未改项、检查结论 | 不保存到磁盘，不贴章节原文，不据回执改文章 |
 
 装上之后什么时候出现、每一步对应哪条规则，见 [`docs/plugin-flow.md`](docs/plugin-flow.md)。那是给人回看的流程说明，不是技能执行时的规则来源。
 
@@ -21,12 +26,12 @@
 ## 安装
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-quarto-book@0.3.4
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-quarto-book@0.4.0
 ```
 
-`--profile` 换成你实际运行的那个 profile。桌面应用固定跑 `desktop` profile，且该 profile 由应用独占管理，`dsh --profile desktop` 直接启动会被拒绝；安装或升级插件可用 `dsh plugin --profile desktop add <包>`，如果应用拒绝写入，再走「设置 → 插件 → 添加插件」，地址填 `npm:@chengzhao-dev/dsh-quarto-book@0.3.4`。想跟 GitHub 标签，也可以写 `github:chengzhao-dev/dsh-quarto-book#v0.3.4`。
+`--profile` 换成你实际运行的那个 profile。桌面应用固定跑 `desktop` profile，且该 profile 由应用独占管理，`dsh --profile desktop` 直接启动会被拒绝；安装或升级插件可用 `dsh plugin --profile desktop add <包>`，如果应用拒绝写入，再走「设置 → 插件 → 添加插件」，地址填 `npm:@chengzhao-dev/dsh-quarto-book@0.4.0`。想跟 GitHub 标签，也可以写 `github:chengzhao-dev/dsh-quarto-book#v0.4.0`。
 
-从旧的无作用域包 `dsh-quarto-book` 升级时，先在同一个 profile 里 `dsh plugin --profile <profile> remove dsh-quarto-book` 再装新包。两个包同时留着会以相同的 rank 550 各注册一遍 `writing-quarto` 和 `designing-theme`。
+从旧的无作用域包 `dsh-quarto-book` 升级时（该包已随 0.3.4 从 npm 删除，只影响之前装过它的 profile），先在同一个 profile 里 `dsh plugin --profile <profile> remove dsh-quarto-book` 再装新包。两个包同时留着会以相同的 rank 550 各注册一遍 `writing-quarto` 和 `designing-theme`。
 
 要求 DSH 0.2.x、Node.js 22 及以上。源码是 TypeScript，发布包已带编译后的 `lib/`；安装后不需要构建。
 
@@ -119,6 +124,32 @@ project:
 
 渲染进程的原始输出不单独占一张终端卡片。命令超时是 120 秒；超时、找不到 `quarto` 或非零退出都写进 `errors`。
 
+## 执行回执
+
+技能收尾时调用一次 `quarto_pass_report`，把这次执行的结论压成固定几行。卡片就是回执，回复里不再复述；工具不保存到磁盘，不贴章节原文，也不据回执改文章。
+
+入参是闭集：
+
+| 字段 | 取值 |
+| --- | --- |
+| `skill` | `writing-quarto` 或 `designing-theme` |
+| `executed` | 布尔；为 `false` 时 `mode` 必须是 `skipped`，并给 `skip_reason`（最多 40 字） |
+| `mode` | `polish`、`rewrite`（写作），`theme`（主题），`skipped`（未执行） |
+| `files` | 最多 8 个 `{ path, edits }` |
+| `steps` | 只列有改动的步骤：写作填 `1`–`9`，主题填 `定表面`、`定字体`、`定尺度`、`定颜色`、`定组件`、`通过检查`；`edits` 合计必须等于 `files` 的合计 |
+| `held` | `fences`、`facts`、`css`、`prose` |
+| `checks` | `content`、`html`、`layout`，状态只取 `pass`、`fail`、`skip` |
+
+```text
+已执行 writing-quarto · 增量润色
+content/ch.qmd
+改了 5 处：定句子 3，定用词 1，定版式 1
+未改：围栏、事实
+检查：内容通过；HTML 可用
+```
+
+没改也会出卡（`改了 0 处`），这样「插件没跑」和「跑了但没改」分得开；当前文件不是章节时输出一行 `未执行 writing-quarto：…`。
+
 ## 主题
 
 主题资产在 `skills/designing-theme/assets/theme/`：

package/cordis.patch.yml

@@ -1,8 +1,8 @@
 # dsh-quarto-book 的 bundle 补丁。
 #
 # 只做加法：插入一行宿主插件，不修改、禁用或替换官方已有的行。这一行加载本包
-# 的 `main` 入口，由它在 `ctx.skills` 上注册包内的 writing-quarto 与
-# designing-theme 两个技能。
+# 的 `main` 入口，由它注册包内的 writing-quarto 与 designing-theme 两个技能，
+# 以及 quarto_render_check 与 quarto_pass_report 两个工具。
 #
 # 从 Git 或 npm 安装，例如：
 #

package/docs/plugin-flow.md

@@ -2,14 +2,15 @@
 
 本文写给排障的人和回看的维护者，回答「装好之后，哪一层在什么条件下生效」。它是人读的流程说明，不是技能执行时的规则来源：技能正文不读本文，作用于写作的约束都写在 `skills/writing-quarto/SKILL.md` 与 `skills/designing-theme/SKILL.md` 里。
 
-## 四层
+## 五层
 
 | 层 | 读者看到什么 | 生效条件 | 排障入口 |
 | --- | --- | --- | --- |
-| 1 安装 | 插件出现在 profile 的依赖里 | `dsh plugin --profile <profile> add npm:@chengzhao-dev/dsh-quarto-book@0.3.4` 成功，profile 的 `package.json` 有这条依赖 | `docs/versioning.md` |
+| 1 安装 | 插件出现在 profile 的依赖里 | `dsh plugin --profile <profile> add npm:@chengzhao-dev/dsh-quarto-book@0.4.0` 成功，profile 的 `package.json` 有这条依赖 | `docs/versioning.md` |
 | 2 技能名出现 | 选题里能看到 `writing-quarto`、`designing-theme` | 会话 `cwd` 向上找到 git 根，沿途 `_quarto.yml` 有一行独立的 `type: book`，且这本书至少有一个章节源文件 | `docs/plugin-boundaries.md` |
 | 3 开始写章节 | 九个写作步骤和三套案例文件 | 第 2 层通过；章节文件是 `.qmd` 或 `.md` | `skills/writing-quarto/SKILL.md` |
 | 4 渲染检查 | `quarto_render_check` 返回 `safe_to_render` 与 `html_report` | 与第 2 层同一道门禁 | `skills/writing-quarto/steps/09-check.md` |
+| 5 执行回执 | 一轮结束时出现 `quarto_pass_report` 卡片 | 技能完成判据要求收尾调用一次；写作与主题共用 | `skills/writing-quarto/steps/09-check.md` |
 
 ## 1 安装
 
@@ -27,11 +28,11 @@
 
 装好后 profile 的 `package.json` 里出现 `@chengzhao-dev/dsh-quarto-book`。两处名字必须逐字一致：`package.json` 的 `name` 与 `cordis.patch.yml` 里 `- name:` 指向同一个包名；不一致时补丁插不进去，工具和技能都不会注册。
 
-从旧的无作用域包 `dsh-quarto-book` 升级时，先在同一个 profile 里删旧包再装新包。两个包同时留着时，会以相同的 rank 550 各注册一遍 `writing-quarto` 和 `designing-theme`。版本号与发布步骤见 `docs/versioning.md`。
+profile 里还留着旧的无作用域包 `dsh-quarto-book` 时（该包已随 0.3.4 从 npm 删除），先在同一个 profile 里删旧包再装新包。两个包同时留着时，会以相同的 rank 550 各注册一遍 `writing-quarto` 和 `designing-theme`。版本号与发布步骤见 `docs/versioning.md`。
 
 ## 2 技能名出现
 
-`apply()` 注册技能 provider 和 `quarto_render_check` 工具，不写文件。provider 的 `list({ cwd })` 只在发现候选时做一次有界只读检查：
+`apply()` 注册技能 provider 与两个工具（`quarto_render_check`、`quarto_pass_report`），不写文件。provider 的 `list({ cwd })` 只在发现候选时做一次有界只读检查：
 
 - 从会话 `cwd` 向上找到 git 根，沿途的 `_quarto.yml` 里有一行独立的 `type: book`，并且这本书至少有一个 `.qmd` 或 `.md` 章节源文件，就返回两个技能；否则返回空列表。书根下的 `README.md`、`CHANGELOG.md`、`LICENSE.md` 等仓库说明文件不算章节源文件。
 - 没有 `cwd`、不在 git checkout 里、`_quarto.yml` 缺失、只在注释里写了 `# type: book`、或只有 book 配置没有任何章节源文件，都按「不是书」处理。
@@ -58,3 +59,13 @@
 - `dry_run: false` 才运行一次 `quarto render`，最多 1 次；成功时同一次返回 `html_report`，不再为同一份文件重跑。`html_report.usable` 是最终结论。
 - 工具与技能共用同一道门禁：不在书里、`_quarto.yml` 不是 `type: book`、或书里没有章节源文件时直接拒绝，不启动渲染。渲染根取 `cwd` 向上最近的合法书根，`qmd_path` 只用来定位卡片。
 - 不手跑 `quarto render`，也不截图 PNG；命令超时是 120 秒。实现与返回字段见 `src/tools/render-check.ts`，判定流程见 `steps/09-check.md`。
+
+## 5 执行回执
+
+第 9 步的「完成判据」要求收尾调用一次 `quarto_pass_report`，写作与主题共用：
+
+- 入参是闭集：`skill`、`executed`、`mode`、`files`、`steps`、`held`、`checks`。`executed: false` 时 `mode` 必须是 `skipped` 并给 `skip_reason`，否则卡片会指出前后矛盾。
+- 卡片就是回执：技能与模式、改过的文件、改了哪些步骤、未改项、检查结论。回复里不再复述；工具不保存到磁盘，不贴章节原文。
+- `steps` 的 `edits` 合计必须等于 `files` 的合计；主题只认六个步骤名，不在名单里的名字（例如 `01-task`）直接拒绝。
+- 当前文件不是章节时输出一行 `未执行 writing-quarto：…`；没改也会出卡（`改了 0 处`），把「插件没跑」和「跑了但没改」分开。
+- 实现与参数见 `src/tools/pass-report.ts`，完成判据见 `steps/09-check.md`。

package/docs/versioning.md

@@ -10,16 +10,16 @@
 - 磁盘：profile 的 `package.json` 里 `dependencies`，以及 `node_modules/@chengzhao-dev/dsh-quarto-book/package.json` 的 `version`。
 - 运行时加载清单：`dsh --profile <profile> --dump-config`，确认 `# == @chengzhao-dev/dsh-quarto-book` 这一层在。官方「设置 → 插件」只显示模块名和启用状态，不显示版本。
 
-README 里的安装命令钉住一次发布：npm 写 `@0.3.4`，git 写 `#v0.3.4`。不带版本号的 `github:` 地址跟踪默认分支的某次提交，`package.json` 的版本号不会自动变成发布号。
+README 里的安装命令钉住一次发布：npm 写 `@0.4.0`，git 写 `#v0.4.0`。不带版本号的 `github:` 地址跟踪默认分支的某次提交，`package.json` 的版本号不会自动变成发布号。
 
-包名与模块名不是一回事：npm 与 profile 依赖里是 `@chengzhao-dev/dsh-quarto-book`，`cordis.patch.yml` 的 `name` 必须与它逐字相同；插件模块导出的 `name` 与技能 provider 的常量仍是短名 `dsh-quarto-book`，技能名与工具名不变。旧的无作用域包 `dsh-quarto-book` 是另一个 npm 坐标，已装过它的 profile 要先 `remove` 再装新包；两份同时留着会以相同的 rank 550 各注册一遍 `writing-quarto` 和 `designing-theme`。
+包名与模块名不是一回事：npm 与 profile 依赖里是 `@chengzhao-dev/dsh-quarto-book`，`cordis.patch.yml` 的 `name` 必须与它逐字相同；插件模块导出的 `name` 与技能 provider 的常量仍是短名 `dsh-quarto-book`，技能名与工具名不变。旧的无作用域包 `dsh-quarto-book` 是另一个 npm 坐标，已在迁到作用域包时从 npm 删除；之前装过它的 profile 仍要先 `remove` 再装新包，两份同时留着会以相同的 rank 550 各注册一遍 `writing-quarto` 和 `designing-theme`。
 
 ## 三档
 
 到达 `1.0.0` 之前停在 `0.x`。抬哪一档只看对外契约，不看改了多少字。
 
 - **修订号（`0.1.1`、`0.2.1`…）**：约定措辞、正反例、参考文、README、注释、不改变既有书通过与否的检查词表或提示。以后绝大多数提交走这一档。
-- **次版本 `0.2.0`、`0.3.0`**：新增技能名或工具名、新增会让旧书失败的检查、脚本命令行不兼容、主题路径或 `_quarto.yml` 接线契约变化、完成判据变成强制步骤。
+- **次版本 `0.2.0`、`0.3.0`、`0.4.0`**：新增技能名或工具名、新增会让旧书失败的检查、脚本命令行不兼容、主题路径或 `_quarto.yml` 接线契约变化、完成判据变成强制步骤（`0.4.0` 新增 `quarto_pass_report`，并把收尾回执写进完成判据）。
 - **`1.0.0`**：技能名、工具名、cwd 门禁、脚本入口和「项目只放 `quarto-book-project`」这些对外契约冻结，并承诺以后的修订号不再让旧书突然失败。
 - **`engines.dsh`**：只在要支持的 DSH 版本窗口变化时改，与上面三档无关。DSH 进入 `0.3` 时再把上界打开。
 
@@ -36,20 +36,20 @@ flowchart TD
 
 ## 发布
 
-发布时三处一起动：`package.json` 的 `version`、`package-lock.json` 顶部的版本、同号的 annotated git tag（`0.3.4` 对应 `v0.3.4`）。不在 `SKILL.md` 里再维护一套包版本。
+发布时三处一起动：`package.json` 的 `version`、`package-lock.json` 顶部的版本、同号的 annotated git tag（`0.4.0` 对应 `v0.4.0`）。不在 `SKILL.md` 里再维护一套包版本。
 
-发布走 npm trusted publisher，本机不执行 `npm publish`，也不执行 `npm trust github`。顺序固定：
+发布走 npm trusted publisher。`0.3.4` 是这个作用域包的首个版本，由本机手工 `npm publish` 引导，同时登记了关联（仓库 `chengzhao-dev/dsh-quarto-book`、文件 `publish.yml`、动作 `npm publish`）；旧包 `dsh-quarto-book` 也在这次发布后从 npm 删除。之后的版本不再本机发布，顺序固定：
 
 1. 提交并推送默认分支，先不打标签。
 2. 只读核对：`npm view @chengzhao-dev/dsh-quarto-book version` 应仍是上一个发布号；`npm whoami` 未登录就停；`npm trust list @chengzhao-dev/dsh-quarto-book --json` 要能匹配 GitHub Actions、仓库 `chengzhao-dev/dsh-quarto-book`、文件 `publish.yml`、动作 `npm publish`。
-3. 作用域包是新的 npm 坐标，旧包 `dsh-quarto-book` 的 trusted publisher 不会带过来。关联不存在或对不上就停住，把 `npm trust github @chengzhao-dev/dsh-quarto-book --repository chengzhao-dev/dsh-quarto-book --file publish.yml --allow-publish` 交给用户执行。用户回复「publisher 已配置」后重查，不自行执行，也不跳过。
-4. 关联匹配后打 annotated `v0.3.4` 并推送；`publish.yml` 在 `v*` 标签上运行。
-5. 以 Actions 全绿且 `npm view @chengzhao-dev/dsh-quarto-book@0.3.4 version` 返回 `0.3.4` 为发布完成。npm 上的版本不可撤回，失败就停在那里，不改回版本号。
+3. 作用域包的关联已在 `0.3.4` 首发时登记，`npm trust list` 查不到或对不上就停住，把 `npm trust github @chengzhao-dev/dsh-quarto-book --repository chengzhao-dev/dsh-quarto-book --file publish.yml --allow-publish` 交给用户执行。用户回复「publisher 已配置」后重查，不跳过。
+4. 关联匹配后打 annotated `v<版本>` 并推送；`publish.yml` 在 `v*` 标签上运行。
+5. 以 Actions 全绿且 `npm view @chengzhao-dev/dsh-quarto-book@<版本> version` 返回该版本为发布完成。`0.3.4` 是首发引导版本，由本机手工发布，当次 Actions 因关联尚未登记而失败，不作完成判据；`0.3.5` 是关联登记后第一个由 Actions 全绿发布的版本。npm 上的版本不可撤回，失败就停在那里，不改回版本号。
 
 关联登记后两天内必须推标签；过期就重新登记，不沿用旧凭据。
 
 `.github/workflows/publish.yml` 只在 `v*` 标签上运行，权限是 `contents: read` 与 `id-token: write`，不设 GitHub Environment。步骤是 checkout、`actions/setup-node@v6`（Node 24、`registry-url: https://registry.npmjs.org`）、`npm ci`、`npm test`、`npm run build`、`npm publish --provenance`。`package.json` 的 `repository.url` 保持 `git+https://github.com/chengzhao-dev/dsh-quarto-book.git`，`publishConfig` 为 `access: public` 与 `provenance: true`。
 
-发布后两种安装各钉各的：git 用 `#v0.3.4`，npm 用 `@0.3.4`。
+发布后两种安装各钉各的：git 用 `#v<版本>`，npm 用 `@<版本>`。
 
 写书时不读这份文档：它是本仓库的维护规则，不进任何一步。

package/lib/index.js

@@ -1,7 +1,7 @@
 // dsh-quarto-book 的 bundle 入口。
 //
 // 把包内两个技能注册成一个 bundle 作用域的技能 provider，并注册
-// `quarto_render_check` 工具。provider 只读，只扫描 `skills/<name>/SKILL.md`；
+// `quarto_render_check` 与 `quarto_pass_report` 两个工具。provider 只读，只扫描 `skills/<name>/SKILL.md`；
 // 每个技能目录作为 resourceBase，使相对引用、脚本和主题资源都从安装后的
 // 包内解析。
 //
@@ -16,6 +16,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { findBookRoot } from './workspace.js';
 import { registerRenderCheckTool } from './tools/render-check.js';
+import { registerPassReportTool } from './tools/pass-report.js';
 export const name = 'dsh-quarto-book';
 export const inject = ['skills', 'tools'];
 const PROVIDER = 'dsh-quarto-book';
@@ -185,5 +186,6 @@ export function apply(ctx) {
     }));
     if (ctx.tools && typeof ctx.tools.register === 'function') {
         registerRenderCheckTool(ctx.tools);
+        registerPassReportTool(ctx.tools);
     }
 }