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

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,10 +26,10 @@ 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.5
+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.5` only if the app refuses that write. To follow a GitHub tag instead, use `github:chengzhao-dev/dsh-quarto-book#v0.3.5`.
+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` (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.
 
@@ -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,10 +26,10 @@
 ## 安装
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-quarto-book@0.3.5
+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.5`。想跟 GitHub 标签，也可以写 `github:chengzhao-dev/dsh-quarto-book#v0.3.5`。
+`--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` 升级时（该包已随 0.3.4 从 npm 删除，只影响之前装过它的 profile），先在同一个 profile 里 `dsh plugin --profile <profile> remove dsh-quarto-book` 再装新包。两个包同时留着会以相同的 rank 550 各注册一遍 `writing-quarto` 和 `designing-theme`。
 
@@ -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.5` 成功，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 安装
 
@@ -31,7 +32,7 @@ profile 里还留着旧的无作用域包 `dsh-quarto-book` 时（该包已随 0
 
 ## 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 @@ profile 里还留着旧的无作用域包 `dsh-quarto-book` 时（该包已随 0
 - `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.5`，git 写 `#v0.3.5`。不带版本号的 `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 坐标，已随 0.3.4 从 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,7 +36,7 @@ flowchart TD
 
 ## 发布
 
-发布时三处一起动：`package.json` 的 `version`、`package-lock.json` 顶部的版本、同号的 annotated git tag（`0.3.5` 对应 `v0.3.5`）。不在 `SKILL.md` 里再维护一套包版本。
+发布时三处一起动：`package.json` 的 `version`、`package-lock.json` 顶部的版本、同号的 annotated git tag（`0.4.0` 对应 `v0.4.0`）。不在 `SKILL.md` 里再维护一套包版本。
 
 发布走 npm trusted publisher。`0.3.4` 是这个作用域包的首个版本，由本机手工 `npm publish` 引导，同时登记了关联（仓库 `chengzhao-dev/dsh-quarto-book`、文件 `publish.yml`、动作 `npm publish`）；旧包 `dsh-quarto-book` 也在这次发布后从 npm 删除。之后的版本不再本机发布，顺序固定：
 
@@ -44,7 +44,7 @@ flowchart TD
 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. 作用域包的关联已在 `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 因关联尚未登记而失败，不作完成判据。npm 上的版本不可撤回，失败就停在那里，不改回版本号。
+5. 以 Actions 全绿且 `npm view @chengzhao-dev/dsh-quarto-book@<版本> version` 返回该版本为发布完成。`0.3.4` 是首发引导版本，由本机手工发布，当次 Actions 因关联尚未登记而失败，不作完成判据；`0.3.5` 是关联登记后第一个由 Actions 全绿发布的版本。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);
     }
 }

package/lib/tools/pass-report.js

@@ -0,0 +1,332 @@
+// `quarto_pass_report`：把一次写作或主题润色的结果压成固定行数的卡片。
+//
+// 入参是闭集：模式、文件、步骤、未改项、检查状态都只能取登记过的值。
+// 卡片由工具自己拼接，返回的文本就是卡片本身，不附章节原文，也不贴改写后的句子。
+// 没改也要出卡，这样「插件没跑」和「跑了但没改」在会话里分得开。
+export const PASS_SKILLS = ['writing-quarto', 'designing-theme'];
+export const PASS_MODES = ['polish', 'rewrite', 'theme', 'skipped'];
+export const HELD_ITEMS = ['fences', 'facts', 'css', 'prose'];
+export const CHECK_NAMES = ['content', 'html', 'layout'];
+export const CHECK_STATUSES = ['pass', 'fail', 'skip'];
+export const MAX_FILES = 8;
+export const MAX_SKIP_REASON = 40;
+/** 写作九步的短名，与 `skills/writing-quarto/SKILL.md` 的「九步」逐字对应。 */
+export const WRITING_STEPS = {
+    '1': '定任务',
+    '2': '定结构',
+    '3': '排列内容块',
+    '4': '定段落',
+    '5': '定句子',
+    '6': '定用词',
+    '7': '定版式',
+    '8': '回读并退回',
+    '9': '检查与渲染',
+};
+/** 主题步骤表的名字，与 `skills/designing-theme/references/theme-spine.md` 逐字对应。 */
+export const THEME_STEPS = ['定表面', '定字体', '定尺度', '定颜色', '定组件', '通过检查'];
+const MODE_LABELS = {
+    polish: '增量润色',
+    rewrite: '全章重构',
+    theme: '主题',
+    skipped: '未执行',
+};
+const HELD_LABELS = {
+    fences: '围栏',
+    facts: '事实',
+    css: '样式',
+    prose: '正文',
+};
+const CHECK_LABELS = {
+    content: '内容',
+    html: 'HTML',
+    layout: '版式',
+};
+const PASS_VERDICTS = {
+    content: '通过',
+    html: '可用',
+    layout: '通过',
+};
+const FAIL_VERDICTS = {
+    content: '未通过',
+    html: '不可用',
+    layout: '未通过',
+};
+const TOP_LEVEL_KEYS = ['skill', 'executed', 'mode', 'files', 'steps', 'held', 'checks', 'skip_reason'];
+function fail(message) {
+    throw new Error(message);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isPlainCount(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
+function allowedSteps(skill) {
+    return skill === 'writing-quarto' ? Object.keys(WRITING_STEPS) : [...THEME_STEPS];
+}
+function stepLabel(skill, name) {
+    return skill === 'writing-quarto' ? (WRITING_STEPS[name] ?? name) : name;
+}
+function normalizeFiles(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        fail('files 必须是数组');
+    if (value.length > MAX_FILES)
+        fail(`files 最多 ${MAX_FILES} 个路径`);
+    return value.map((item) => {
+        if (!isRecord(item))
+            fail('files 的每一项必须是 { path, edits }');
+        const keys = Object.keys(item);
+        if (keys.some((key) => key !== 'path' && key !== 'edits'))
+            fail('files 的每一项只允许 path 和 edits');
+        const filePath = item.path;
+        if (typeof filePath !== 'string' || filePath.trim() === '')
+            fail('files 的 path 必须是非空字符串');
+        if (!isPlainCount(item.edits))
+            fail('files 的 edits 必须是非负整数');
+        return { path: filePath.trim(), edits: item.edits };
+    });
+}
+function normalizeSteps(value, skill) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        fail('steps 必须是数组');
+    const allowed = allowedSteps(skill);
+    const seen = new Set();
+    return value.map((item) => {
+        if (!isRecord(item))
+            fail('steps 的每一项必须是 { name, edits }');
+        const keys = Object.keys(item);
+        if (keys.some((key) => key !== 'name' && key !== 'edits'))
+            fail('steps 的每一项只允许 name 和 edits');
+        const name = item.name;
+        if (typeof name !== 'string' || !allowed.includes(name)) {
+            fail(`steps 的 name 只能是：${allowed.join('、')}`);
+        }
+        if (seen.has(name))
+            fail(`steps 的 name 重复：${name}`);
+        seen.add(name);
+        if (typeof item.edits !== 'number' || !Number.isInteger(item.edits) || item.edits < 1) {
+            fail('steps 的 edits 必须是正整数');
+        }
+        return { name, edits: item.edits };
+    });
+}
+function normalizeHeld(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        fail('held 必须是数组');
+    const seen = new Set();
+    return value.map((item) => {
+        if (typeof item !== 'string' || !HELD_ITEMS.includes(item)) {
+            fail(`held 只能是：${HELD_ITEMS.join('、')}`);
+        }
+        if (seen.has(item))
+            fail(`held 重复：${item}`);
+        seen.add(item);
+        return item;
+    });
+}
+function normalizeChecks(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        fail('checks 必须是数组');
+    const seen = new Set();
+    return value.map((item) => {
+        if (!isRecord(item))
+            fail('checks 的每一项必须是 { name, status }');
+        const keys = Object.keys(item);
+        if (keys.some((key) => key !== 'name' && key !== 'status'))
+            fail('checks 的每一项只允许 name 和 status');
+        const name = item.name;
+        if (typeof name !== 'string' || !CHECK_NAMES.includes(name)) {
+            fail(`checks 的 name 只能是：${CHECK_NAMES.join('、')}`);
+        }
+        if (seen.has(name))
+            fail(`checks 的 name 重复：${name}`);
+        seen.add(name);
+        const status = item.status;
+        if (typeof status !== 'string' || !CHECK_STATUSES.includes(status)) {
+            fail(`checks 的 status 只能是：${CHECK_STATUSES.join('、')}`);
+        }
+        return { name: name, status: status };
+    });
+}
+function checkLine(checks) {
+    const ordered = CHECK_NAMES.map((name) => checks.find((check) => check.name === name)).filter((check) => check !== undefined && check.status !== 'skip');
+    if (ordered.length === 0)
+        return undefined;
+    return '检查：' + ordered.map((check) => {
+        const label = CHECK_LABELS[check.name];
+        const verdict = check.status === 'pass' ? PASS_VERDICTS[check.name] : FAIL_VERDICTS[check.name];
+        // 中文标签直接接结论，英文标签（HTML）前面留一个空格。
+        return `${label}${/[A-Za-z]$/.test(label) ? ' ' : ''}${verdict}`;
+    }).join('；');
+}
+/** 校验入参并生成卡片；入参不合格时抛错，不猜测默认值。 */
+export function buildPassReport(input) {
+    if (!isRecord(input))
+        fail('回执入参必须是对象');
+    const unknownKey = Object.keys(input).find((key) => !TOP_LEVEL_KEYS.includes(key));
+    if (unknownKey)
+        fail(`未知字段：${unknownKey}`);
+    const skill = input.skill;
+    if (typeof skill !== 'string' || !PASS_SKILLS.includes(skill)) {
+        fail(`skill 只能是：${PASS_SKILLS.join('、')}`);
+    }
+    const typedSkill = skill;
+    if (typeof input.executed !== 'boolean')
+        fail('executed 必须是布尔值');
+    const mode = input.mode;
+    if (typeof mode !== 'string' || !PASS_MODES.includes(mode)) {
+        fail(`mode 只能是：${PASS_MODES.join('、')}`);
+    }
+    const typedMode = mode;
+    if (!input.executed) {
+        if (typedMode !== 'skipped')
+            fail('executed 为 false 时 mode 必须是 skipped');
+        const reason = input.skip_reason;
+        if (typeof reason !== 'string' || reason.trim() === '')
+            fail('未执行时必须给出 skip_reason');
+        if ([...reason.trim()].length > MAX_SKIP_REASON)
+            fail(`skip_reason 最多 ${MAX_SKIP_REASON} 个字`);
+        if (input.files !== undefined && Array.isArray(input.files) && input.files.length > 0) {
+            fail('未执行时 files 必须为空');
+        }
+        if (input.steps !== undefined && Array.isArray(input.steps) && input.steps.length > 0) {
+            fail('未执行时 steps 必须为空');
+        }
+        if (input.held !== undefined && Array.isArray(input.held) && input.held.length > 0) {
+            fail('未执行时 held 必须为空');
+        }
+        if (input.checks !== undefined && Array.isArray(input.checks) && input.checks.length > 0) {
+            fail('未执行时 checks 必须为空');
+        }
+        return { receipt: `未执行 ${typedSkill}：${reason.trim()}` };
+    }
+    if (typedMode === 'skipped')
+        fail('executed 为 true 时 mode 不能是 skipped');
+    if (typedSkill === 'designing-theme' && typedMode !== 'theme')
+        fail('designing-theme 只接受 mode: theme');
+    if (typedSkill === 'writing-quarto' && typedMode === 'theme')
+        fail('writing-quarto 不接受 mode: theme');
+    const files = normalizeFiles(input.files);
+    if (files.length === 0)
+        fail('已执行时 files 至少给 1 个路径');
+    const steps = normalizeSteps(input.steps, typedSkill);
+    const held = normalizeHeld(input.held);
+    const checks = normalizeChecks(input.checks);
+    const fileEdits = files.reduce((sum, file) => sum + file.edits, 0);
+    const stepEdits = steps.reduce((sum, step) => sum + step.edits, 0);
+    if (fileEdits !== stepEdits)
+        fail(`files 的改动合计 ${fileEdits} 与 steps 的合计 ${stepEdits} 不一致`);
+    const lines = [`已执行 ${typedSkill} · ${MODE_LABELS[typedMode]}`, files.map((file) => file.path).join('、')];
+    if (fileEdits === 0) {
+        lines.push('改了 0 处');
+    }
+    else {
+        lines.push(`改了 ${fileEdits} 处：` + steps.map((step) => `${stepLabel(typedSkill, step.name)} ${step.edits}`).join('，'));
+    }
+    if (held.length > 0)
+        lines.push('未改：' + held.map((item) => HELD_LABELS[item]).join('、'));
+    const checksText = checkLine(checks);
+    if (checksText)
+        lines.push(checksText);
+    return { receipt: lines.join('\n') };
+}
+const RESULT_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: { receipt: { type: 'string' } },
+    required: ['receipt'],
+};
+export function registerPassReportTool(tools) {
+    tools.register({
+        name: 'quarto_pass_report',
+        description: '一次写作或主题润色收尾时调用一次，出一张短回执卡片：执行了哪个技能、什么模式、改了哪些文件与步骤、未改项、检查结论。入参是闭集：skill、mode、files（最多 8 个，每条带 path 与 edits）、steps（写作 1-9，主题用定表面/定字体/定尺度/定颜色/定组件/通过检查，各带 edits，合计必须等于 files 的 edits 合计）、held、checks、skip_reason。没改也传 0；不适用时 executed:false、mode:skipped、给 skip_reason。卡片就是回执，不要在回复里再复述。',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                skill: { type: 'string', enum: [...PASS_SKILLS] },
+                executed: { type: 'boolean' },
+                mode: { type: 'string', enum: [...PASS_MODES] },
+                files: {
+                    type: 'array',
+                    maxItems: MAX_FILES,
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            path: { type: 'string' },
+                            edits: { type: 'integer', minimum: 0 },
+                        },
+                        required: ['path', 'edits'],
+                    },
+                },
+                steps: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            name: { type: 'string' },
+                            edits: { type: 'integer', minimum: 1 },
+                        },
+                        required: ['name', 'edits'],
+                    },
+                },
+                held: { type: 'array', items: { type: 'string', enum: [...HELD_ITEMS] } },
+                checks: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        properties: {
+                            name: { type: 'string', enum: [...CHECK_NAMES] },
+                            status: { type: 'string', enum: [...CHECK_STATUSES] },
+                        },
+                        required: ['name', 'status'],
+                    },
+                },
+                skip_reason: { type: 'string', maxLength: MAX_SKIP_REASON },
+            },
+            required: ['skill', 'executed', 'mode'],
+        },
+        output: {
+            schema: RESULT_SCHEMA,
+            render: (_args, value) => [{ type: 'text', text: value.receipt }],
+            presentationMeta: (_args, value) => ({ summary: value.receipt.split('\n')[0], lines: value.receipt.split('\n') }),
+        },
+        async execute(args) {
+            return buildPassReport(args);
+        },
+        presentCall(args) {
+            const files = Array.isArray(args.files) ? args.files : [];
+            return {
+                card: 'generic',
+                title: '写作回执',
+                kind: 'execute',
+                locations: files.map((file) => ({ path: String(file.path) })),
+                rawInput: `${args.skill} · ${args.mode}`,
+                content: [
+                    {
+                        type: 'text',
+                        text: args.executed === false ? `${args.skill}：未执行` : `${args.skill} · ${args.mode}（${files.length} 个文件）`,
+                    },
+                ],
+            };
+        },
+        presentResult(_args, result) {
+            return {
+                card: 'generic',
+                title: '写作回执',
+                content: result.content,
+            };
+        },
+    });
+}

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "Quarto Book Writing",
-    "description": "Author Chinese Quarto Book chapters and maintain a reusable book theme: structure checks, prose conventions, Mermaid and typography assets."
+    "description": "Author and check Quarto Book chapters and maintain a reusable theme; no business code, only inside type: book repositories."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "Quarto 图书写作",
-    "description": "编写中文 Quarto Book 章节并维护可复用主题：结构校验、行文约定、Mermaid 与版式资产。"
+    "description": "为 Quarto Book 写章节、校验结构并维护可复用主题；不改业务代码，只在 type: book 的仓库里出现。"
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chengzhao-dev/dsh-quarto-book",
-  "version": "0.3.5",
-  "description": "Quarto Book 写作与主题技能包：章节写作、结构校验与可复用主题 · Quarto Book authoring and theme skills for DeepSeek Harness",
+  "version": "0.4.0",
+  "description": "为 Quarto Book 写章节、校验结构并维护可复用主题；不改业务代码，只在 type: book 的仓库里出现。 · Author and check Quarto Book chapters and maintain a reusable theme; no business code, only inside `type: book` repositories.",
   "type": "module",
   "main": "./lib/index.js",
   "exports": {
@@ -30,6 +30,14 @@
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "catalog": {
+      "category": "workflow",
+      "summary": {
+        "zh": "为 Quarto Book 写章节、校验结构并维护可复用主题；不改业务代码，只在 type: book 的仓库里出现。",
+        "en": "Author and check Quarto Book chapters and maintain a reusable theme; no business code, only inside `type: book` repositories."
+      },
+      "capabilities": ["skills", "tools"]
     }
   },
   "icon": "./icon.svg",

package/skills/designing-theme/SKILL.md

@@ -40,3 +40,4 @@ metadata:
 - [ ] `quarto render` 通过，明暗主题下页面无错位或对比度问题；`scripts/checking-layout.py` 通过。
 - [ ] 代码块 filename 标题在长路径输入下不撑破容器，窄屏仍可读；超长代码在块内横向滚动，不出整页横向滚动条。
 - [ ] 若项目内有主题副本，已在交付说明中写清改动是否同步，以及以哪一份为准。
+- [ ] 收尾调用一次 `quarto_pass_report`：`skill` 填 `designing-theme`，`mode` 填 `theme`，`steps` 用主题步骤表的名字（`定表面`、`定字体`、`定尺度`、`定颜色`、`定组件`、`通过检查`），检查结论照实填。卡片就是回执，回复里不再复述。

package/skills/writing-quarto/SKILL.md

@@ -41,3 +41,4 @@ metadata:
 - [ ] 九步走完，每一步的产出都落在正文里。
 - [ ] 内容与链接核对通过：项目技能存在时跑它列出的 `run.ps1 verify --changed`，否则跑本技能 `scripts/verifying-content.py` 与 `checking-links.py`。
 - [ ] 调 `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`。

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

@@ -43,6 +43,18 @@
 
 不手跑 `quarto render`，也不手跑 `checking-output.py`、`checking-callouts.py`、`checking-dom.py`。工具已经按当前书配置调用它们。
 
+### 执行回执
+
+检查结论确定后，调用一次 `quarto_pass_report`，把这次执行的结论压成一张卡片：
+
+- `skill` 填 `writing-quarto`，`mode` 填 `polish` 或 `rewrite`。
+- `files` 写这次动过的章节路径和改动次数（最多 8 个）；`steps` 只列有改动的步骤编号（1–9）与次数，两者合计必须一致。
+- `held` 写围栏、事实这类明确没有改动的地方；没改就传 0。
+- `checks` 抄内容与渲染的结论，名字只取 `content`、`html`、`layout`，状态只取 `pass`、`fail`、`skip`。
+- 当前文件不是章节时传 `executed: false`、`mode: skipped`，并给一句 `skip_reason`。
+
+卡片就是回执，回复里不再复述；回执不保存到磁盘，也不贴改写后的句子，不根据回执改文章。
+
 ## 情况
 
 ### 情况：全仓重构
@@ -55,7 +67,7 @@
 
 ## 完成判据
 
-内容命令通过，`dry_run: false` 返回 `render_result.ok: true`，且 `html_report.usable: true`，才算完成。任一条件不满足，回到报告指向的步骤。
+内容命令通过，`dry_run: false` 返回 `render_result.ok: true`，且 `html_report.usable: true`，并调用一次 `quarto_pass_report` 出回执，才算完成。任一条件不满足，回到报告指向的步骤。
 
 ## 正反例