@chengzhao-dev/dsh-quarto-book 0.6.2 → 0.6.4

package/README.en.md

@@ -1,14 +1,11 @@
 # dsh-quarto-book
 
 [![publish](https://github.com/chengzhao-dev/dsh-quarto-book/actions/workflows/publish.yml/badge.svg)](https://github.com/chengzhao-dev/dsh-quarto-book/actions/workflows/publish.yml)
+[![npm](https://img.shields.io/npm/v/@chengzhao-dev/dsh-quarto-book)](https://www.npmjs.com/package/@chengzhao-dev/dsh-quarto-book)
 
 **English** | [简体中文](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/README.md)
 
-Polish Chinese technical chapters, check book structure and mixed Chinese-English prose, and maintain a consistent, readable theme; only inside `type: book` repositories.
-
-- Write `.qmd`: `writing-quarto` covers the chapter skeleton, structure and Chinese 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.
+Take a Quarto Book from chapters to publishable output: `writing-quarto` owns the chapter skeleton, whole-book order and Chinese prose; `designing-theme` owns the theme; after a render, `quarto_render_check` decides whether the HTML is publishable and `quarto_pass_report` prints the closing receipt. Both skills appear only inside `type: book` repositories, and the workflow needs Quarto CLI and Python 3.
 
 ## What it provides
 
@@ -19,31 +16,51 @@ Polish Chinese technical chapters, check book structure and mixed Chinese-Englis
 | `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](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/plugin-flow.md). It is a human-facing walkthrough, not the rule source used while a skill runs.
+Both skills are discovered from the package's `skills/` directory and loaded on demand. Relative paths inside a skill resolve against that skill's directory: `writing-quarto` uses `steps/`, `examples/`, `quarto/`, `references/`, `scripts/`; `designing-theme` uses `references/`, `knowledge/`, `assets/`, `scripts/`.
 
-Both skills are discovered from the package's `skills/` directory and loaded on demand. Relative paths inside a skill resolve against that skill's directory: `writing-quarto` uses `steps/`, `examples/`, `quarto/`, `scripts/`; `designing-theme` uses `references/`, `knowledge/`, `assets/`, `scripts/`.
+## Quick start
 
-## Install
+1. Install the plugin:
 
-```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-quarto-book@0.6.1
-```
+   ```bash
+   dsh plugin --profile web add npm:@chengzhao-dev/dsh-quarto-book@latest
+   ```
 
-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.6.1` only if the app refuses that write. To follow a GitHub tag instead, use `github:chengzhao-dev/dsh-quarto-book#v0.6.1`.
+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.4`; to follow a GitHub tag, write `github:chengzhao-dev/dsh-quarto-book#v0.6.4`.
 
 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. The content, link and naming checks need Python 3; `quarto_render_check` needs the Quarto CLI for an actual render, and the post-render HTML checks also need Python 3. See [docs/plugin-layout.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/plugin-layout.md) for the split.
+Installation is scoped to a profile, not to a repository: it only affects the profile that ran `add`. The workspace check still decides whether the two skill names appear: it checks the session `cwd` for a book, and only then are both names selectable. See [docs/plugin-boundaries.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/plugin-boundaries.md) for the six cases.
 
-Installation is scoped to a profile, not to a repository: it only affects the profile that ran `add`. The workspace gate still decides whether the two skill names appear: it checks the session `cwd` for a book, and only then are both names selectable. See [docs/plugin-boundaries.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/plugin-boundaries.md) for the six cases.
+## Requirements
+
+| Dependency | Purpose |
+| --- | --- |
+| DSH 0.2.x | Host; the plugin registers skills and both tools through `dsh.bundle.patch` |
+| Node.js 22 or newer | Plugin runtime and check scripts |
+| Python 3 | Content, link and naming checks, plus post-render HTML checks |
+| Quarto CLI | Only when `quarto_render_check` actually renders |
+
+The published package already contains compiled `lib/`, so installation needs no build step. See [docs/plugin-layout.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/plugin-layout.md) for the split.
 
 ## Usage
 
-Load `writing-quarto` or `designing-theme` inside a `type: book` repository and follow the steps in `SKILL.md`. The plugin has no resident process and does not execute a skill when a session starts; seeing a name in the skill catalog only means the session `cwd` passed the gate, and a use happens only when `skill`, `quarto_render_check` or `quarto_pass_report` is invoked. The next invocation rereads the skill text; the tool never retries automatically, so the user decides whether to call it again after a failure.
+### Writing chapters
+
+Load `writing-quarto` in a `type: book` repository and follow the nine steps in `SKILL.md`. Each step opens one same-numbered file in `steps/`; read the same-numbered case in `examples/` only when a signal is unclear; open `quarto/` only for figures, render checks or repository-wide refactors.
+
+The repository's root `README.md` is a description page, not a chapter: it takes only steps 5–8, skips the task skeleton and structure of steps 1–4, has no "common errors" or "self-test questions", and never calls `quarto_render_check`. `README.en.md` is treated the same way.
 
-A project supplies exactly one skill of its own: `<book>/.agents/skills/quarto-book-project/`, starting from `templates/quarto-book-project/`. When it exists, both general skills read `SKILL.md` and then the `writing/` files it points to; when it does not, they skip it and do not guess project conventions. **Do not embed same-name skills into a book repository**: DSH picks one skill per name per layer by rank, lowest wins, and `.agents/skills` (rank 200) outranks the packaged provider (rank 550); a copy of `writing-quarto` or `designing-theme` in the book disables the plugin's text.
+The plugin has no daemon and does not run skills when a session starts. A skill name in the catalog only means the check passed; only calling `skill`, `quarto_render_check` or `quarto_pass_report` counts as use. A second call in the same session re-reads the skill body, and failed tools are not retried automatically.
 
-Theme assets live in `skills/designing-theme/assets/theme/`. The package copy is authoritative; the book's `theme/` is the render copy. When a copy exists, `designing-theme` edits only that copy, and only when the user explicitly asks to install the plugin theme into the book and the target directory does not exist yet does the skill copy from the package and place `skills/writing-quarto/scripts/answering-disclosure.lua` at the book's `filters/answering-disclosure.lua`. `_quarto.yml` references only the book's copy, never an npm package or the plugin checkout.
+### Theming
+
+Theme assets live in `skills/designing-theme/assets/theme/`. The package copy is authoritative; a book's `theme/` is the render copy. When a copy exists, `designing-theme` edits only that copy. It copies from the package only when the user explicitly asks to install the theme into the book and the target directory does not exist, and it also places `skills/writing-quarto/scripts/answering-disclosure.lua` at `filters/answering-disclosure.lua`. `_quarto.yml` always references the in-book copy, never an npm package or a checkout path.
+
+### Checks and rendering
 
 Run the content and link checks from the `writing-quarto` skill directory:
 
@@ -54,25 +71,31 @@ python scripts/checking-prose.py --root <book>
 python scripts/checking-names.py --root <book>
 ```
 
-`checking-prose.py` reports only high-confidence CJK/Latin spacing and punctuation issues. Add `checking-names.py` only for a whole-repository refactor; ordinary chapter checks run the first three.
+`checking-prose.py` reports only mixed Chinese-English problems that can be judged directly; `checking-names.py` is for repository-wide refactors. For everyday chapter work, the first three are enough.
+
+Post-render callouts, HTML output and DOM contracts are checked by `quarto_render_check`, which calls the bundled scripts; run `checking-callouts.py`, `checking-output.py` or `checking-dom.py` by hand only when debugging a script. `designing-theme`'s `scripts/checking-layout.py` checks overflow, contrast and page structure on rendered HTML. Neither tool runs those scripts at load time, and neither runs `quarto render`.
+
+Call `quarto_pass_report` once at the end of a run; the card is the receipt, and the reply should not repeat it.
 
-Callouts, HTML output and DOM contracts after a render are checked by `quarto_render_check`, which invokes the packaged scripts; do not run `checking-callouts.py`, `checking-output.py` or `checking-dom.py` by hand. `designing-theme`'s `scripts/checking-layout.py` inspects rendered HTML for overflow, contrast and page structure. `apply()` runs none of these and never runs `quarto render`.
+### Project skill
 
-At the end of a run, call `quarto_pass_report` once to print the receipt card; the card is the receipt, so do not repeat it in the reply.
+A project keeps its own conventions in one skill: `<book>/.agents/skills/quarto-book-project/`, with a template in `templates/quarto-book-project/`. When it exists, both generic skills read its `SKILL.md` first, then the `writing/` files it points to; when it does not exist, they skip it and do not guess.
+
+**Do not vendor a same-named skill into the book repository.** DSH picks one skill per name at its rank: `.agents/skills` (rank 200) wins over the plugin (rank 550), so a copy of `writing-quarto` or `designing-theme` inside the book silently replaces the plugin's rules.
 
 ## Documentation
 
 | Document | Contents |
 | --- | --- |
 | [docs/plugin-flow.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/plugin-flow.md) | The five layers from install to receipt, file routing and render order |
-| [docs/plugin-boundaries.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/plugin-boundaries.md) | The six workspace-gate cases and their decision order |
-| [docs/plugin-layout.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/plugin-layout.md) | Repository tree, published files and the Python/Quarto split |
+| [docs/plugin-boundaries.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/plugin-boundaries.md) | The six workspace-check cases and their order |
+| [docs/plugin-layout.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/plugin-layout.md) | Repository layout, package contents, and the Python/Quarto split |
 | [docs/writing-quarto-layout.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/writing-quarto-layout.md) | The writing skill's directory layers |
 | [docs/versioning.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/versioning.md) | Version numbers and release order |
 
-## Local development
+## Development
 
-The source is TypeScript and the compiled `lib/` is committed. Published packages load `lib/` directly, so installation needs no build step. During development, link this checkout into the writing profile instead of copying skills into a book:
+The source is TypeScript and the compiled `lib/` is committed; the published package loads `lib/` directly and needs no build on install. Link this checkout into the profile you write books with instead of copying skills into the book:
 
 ```bash
 npm ci
@@ -81,18 +104,24 @@ npm run check
 npm run pack
 ```
 
-`npm test` builds before running the tool tests; `npm run check` runs type checking and the skill path self-check; `npm run pack` writes the tarball only into `temp/`, which `.gitignore` already covers. Development install:
+`npm test` compiles and runs the tool tests; `npm run check` type-checks and validates skill paths; `npm run pack` writes the tarball into `temp/`, which is already in `.gitignore`.
+
+Development install:
 
 ```bash
-dsh plugin --profile web add D:\Github\dsh-quarto-book
+dsh plugin --profile web add D:\\Github\\dsh-quarto-book
 ```
 
-`SKILL.md`, `steps/`, `examples/` and `quarto/` are re-read on the next `skill` tool call, so no npm release is needed after an edit. Theme edits inside the package do not reach the book's HTML automatically; to see a page, sync the changed files into the book's `theme/` and run `quarto render` at the book root. Never point `_quarto.yml` at the plugin checkout — that path stops existing on another machine.
+`SKILL.md`, `steps/`, `examples/` and `quarto/` are re-read on the next `skill` call, so rule changes need no npm publish. Theme changes in the package do not reach a book's HTML by themselves: copy the changed files into the book's `theme/` and run `quarto render` in the book root. Do not point `_quarto.yml` at the checkout; that path does not exist on another machine.
+
+The plugin ships as a bundle: `package.json` has `dsh.bundle.patch` pointing at `cordis.patch.yml`, and the patch inserts only the `id: quarto-book`, `name: '@chengzhao-dev/dsh-quarto-book'` line. The entry does not import host internals, so it also loads under pnpm's strict dependency layout.
+
+The legacy `scripts/embedding-agents.ps1` copies both skill trees into a target repository's `.agents/`, which shadows the plugin at rank 200. Do not use it for new books; run it only to archive a standalone skill tree offline. The command is at the top of the script.
 
-The plugin ships as a bundle: `package.json` points `dsh.bundle.patch` at `cordis.patch.yml`, and the patch inserts only `id: quarto-book` / `name: '@chengzhao-dev/dsh-quarto-book'`. The entry imports nothing from the host, so it loads under pnpm's strict dependency layout.
+## Issues and contributing
 
-The legacy `scripts/embedding-agents.ps1` copies both skill trees verbatim into the target repository's `.agents/`, where they outrank the plugin (rank 200 vs 550). Do not use it for new books; run it only to archive a standalone skill tree offline, with the command from the script header.
+Bugs and suggestions go to [GitHub Issues](https://github.com/chengzhao-dev/dsh-quarto-book/issues). Before sending a change, run `npm test` and `npm run check`; for skill prose, also run `node scripts/checking-skill-links.mjs`.
 
-## Licence
+## License
 
-MIT. The bundled LXGW Bright and LXGW Bright Code fonts are used under the SIL Open Font License 1.1; upstream copyright notices and the full licence text are in `skills/designing-theme/assets/theme/assets/fonts/OFL.txt`.
+MIT. LXGW Bright and LXGW Bright Code in the theme are used under the SIL Open Font License 1.1; the upstream copyright notice and full license are in `skills/designing-theme/assets/theme/assets/fonts/OFL.txt`.

package/README.md

@@ -1,14 +1,11 @@
 # dsh-quarto-book
 
 [![publish](https://github.com/chengzhao-dev/dsh-quarto-book/actions/workflows/publish.yml/badge.svg)](https://github.com/chengzhao-dev/dsh-quarto-book/actions/workflows/publish.yml)
+[![npm](https://img.shields.io/npm/v/@chengzhao-dev/dsh-quarto-book)](https://www.npmjs.com/package/@chengzhao-dev/dsh-quarto-book)
 
 [English](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/README.en.md) | **简体中文**
 
-润色中文技术章节、检查 Book 结构与中英混排，并维护一套统一、可读的阅读主题；只在 `type: book` 的仓库里出现。
-
-- 写 `.qmd`：`writing-quarto` 管章节骨架、结构与中文行文。
-- 改主题：`designing-theme` 管 CSS、字体与 palette。
-- 渲染后检查 HTML：`quarto_render_check` 判一次可发布性，`quarto_pass_report` 出收尾回执。
+把一份 Quarto Book 从章节写到可发布：`writing-quarto` 负责章节骨架、整书次序与中文行文，`designing-theme` 负责主题；渲染后由 `quarto_render_check` 判断 HTML 是否可发布，`quarto_pass_report` 给出收尾回执。两个技能只在 `type: book` 的仓库里出现，运行需要 Quarto CLI 与 Python 3。
 
 ## 提供什么
 
@@ -17,33 +14,53 @@
 | `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` | 收尾时把执行结论压成一张固定行数的回执卡片：技能、模式、改过的文件与步骤、未改项、检查结论 | 不保存到磁盘，不贴章节原文，不据回执改文章 |
+| `quarto_pass_report` | 收尾时把执行结论压成固定行数的回执卡片：技能、模式、改过的文件与步骤、未改项、检查结论 | 不保存到磁盘，不贴章节原文，不据回执改文章 |
 
-装上之后什么时候出现、每一步对应哪条规则，见 [docs/plugin-flow.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/plugin-flow.md)。那是给人回看的流程说明，不是技能执行时的规则来源。
+两个技能从包内 `skills/` 目录发现，按需加载；技能里的相对路径以技能目录为基准：`writing-quarto` 用 `steps/`、`examples/`、`quarto/`、`references/`、`scripts/`，`designing-theme` 用 `references/`、`knowledge/`、`assets/`、`scripts/`。
 
-两个技能从包内 `skills/` 目录发现，按需加载；技能里的相对路径以技能目录为基准解析：`writing-quarto` 用 `steps/`、`examples/`、`quarto/`、`scripts/`，`designing-theme` 用 `references/`、`knowledge/`、`assets/`、`scripts/`。
+## 快速开始
 
-## 安装
+1. 安装插件：
 
-```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-quarto-book@0.6.1
-```
+   ```bash
+   dsh plugin --profile web add npm:@chengzhao-dev/dsh-quarto-book@latest
+   ```
 
-`--profile` 换成你实际运行的那个 profile。桌面应用固定跑 `desktop` profile，且该 profile 由应用独占管理，`dsh --profile desktop` 直接启动会被拒绝；安装或升级插件可用 `dsh plugin --profile desktop add <包>`，如果应用拒绝写入，再走「设置 → 插件 → 添加插件」，地址填 `npm:@chengzhao-dev/dsh-quarto-book@0.6.1`。想跟 GitHub 标签，也可以写 `github:chengzhao-dev/dsh-quarto-book#v0.6.1`。
+2. 在书仓库里打开会话。`_quarto.yml` 要有独立一行的 `type: book`，书根至少有一个 `.qmd` 或 `.md` 章节源文件；两个技能名这时才会出现。
+3. 调用技能：写正文用 `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`。
+`--profile` 换成你实际运行的那个 profile。桌面应用固定跑 `desktop` profile，且该 profile 由应用独占管理，`dsh --profile desktop` 直接启动会被拒绝；安装或升级用 `dsh plugin --profile desktop add <包>`，应用拒绝写入时再走「设置 → 插件 → 添加插件」。需要固定版本时写 `npm:@chengzhao-dev/dsh-quarto-book@0.6.4`，跟 GitHub 标签时写 `github:chengzhao-dev/dsh-quarto-book#v0.6.4`。
 
-要求 DSH 0.2.x、Node.js 22 及以上。源码是 TypeScript，发布包已带编译后的 `lib/`，安装后不需要构建。内容、链接与命名检查需要 Python 3；`quarto_render_check` 真正渲染时需要 Quarto CLI，渲染后的 HTML 检查同样用 Python 3。环境分工见 [docs/plugin-layout.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/plugin-layout.md)。
+从旧的无作用域包 `dsh-quarto-book` 升级（该包已随 0.3.4 从 npm 删除，只影响之前装过它的 profile）：先在同一个 profile 里 `dsh plugin --profile <profile> remove dsh-quarto-book`，再装新包。两个包同时留着会以相同的 rank 550 各注册一遍 `writing-quarto` 和 `designing-theme`。
 
-安装单位是 profile，不是仓库：只影响执行 `add` 的那个 profile。装好之后还要过工作区门禁：按会话 `cwd` 判断当前目录是不是一本书，通过后两个技能名才会出现。门禁的六类情形见 [docs/plugin-boundaries.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/plugin-boundaries.md)。
+安装单位是 profile，不是仓库：只影响执行 `add` 的那个 profile。装好之后还要过工作区检查：按会话 `cwd` 判断当前目录是不是一本书，通过后技能名才会出现。检查的六类情形见 [docs/plugin-boundaries.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/plugin-boundaries.md)。
+
+## 环境要求
+
+| 依赖 | 用途 |
+| --- | --- |
+| DSH 0.2.x | 宿主；插件按 `dsh.bundle.patch` 注册技能与两个工具 |
+| Node.js 22 及以上 | 运行插件与检查脚本 |
+| Python 3 | 内容、链接、命名检查，以及渲染后的 HTML 检查 |
+| Quarto CLI | 仅 `quarto_render_check` 真正渲染时需要 |
+
+发布包已经带编译好的 `lib/`，安装后不需要构建。环境分工见 [docs/plugin-layout.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/plugin-layout.md)。
 
 ## 使用
 
-在 `type: book` 的仓库里加载 `writing-quarto` 或 `designing-theme`，按 `SKILL.md` 的步骤执行。插件没有常驻进程，也不会在会话开始时自动执行技能；技能目录里出现名字只说明当前会话过了门禁，只有调用 `skill`、`quarto_render_check` 或 `quarto_pass_report` 才算一次使用。同一会话再次调用会重新读技能正文；工具不会自动重试，失败后由用户决定是否再调一次。
+### 写章节
+
+在 `type: book` 的仓库里加载 `writing-quarto`，按 `SKILL.md` 的九步执行。每一步只打开同号的一个 `steps/` 文件；判不准才读 `examples/` 里同号的案例；要排图、查渲染或全仓重构才打开 `quarto/`。
+
+书仓库根目录的 `README.md` 是说明页，不是章节：只走第 5–8 步，不套第 1–4 步的任务与结构骨架，不写「常见错误」「自测问题」，不调 `quarto_render_check`。`README.en.md` 同样处理。
 
-项目只放一份自己的约定技能：`<book>/.agents/skills/quarto-book-project/`，模板见 `templates/quarto-book-project/`。存在时两个通用技能先读它的 `SKILL.md`，再按它指向的 `writing/` 文件读章节表；不存在就跳过，不猜项目约定。**不要把同名技能嵌进书仓库**：DSH 在同一技能层按 rank 取一个，`.agents/skills`（rank 200）优先于插件（rank 550），书里再放 `writing-quarto` 或 `designing-theme` 会让插件正文失效。
+插件没有常驻进程，也不会在会话开始时自动执行技能。技能目录里出现名字只说明当前会话过了检查；只有调用 `skill`、`quarto_render_check` 或 `quarto_pass_report` 才算一次使用。同一会话再次调用会重读技能正文，工具失败后不会自动重试。
 
-主题资产在 `skills/designing-theme/assets/theme/`，包内是权威来源，书内 `theme/` 是渲染副本；已有副本时 `designing-theme` 只改副本，只有用户明确要求「把插件主题装进这本书」且目标目录不存在时才从包复制，并把 `skills/writing-quarto/scripts/answering-disclosure.lua` 放到书内 `filters/answering-disclosure.lua`。`_quarto.yml` 只引用书内副本，不指向 npm 包或插件检出目录。
+### 改主题
+
+主题资产在 `skills/designing-theme/assets/theme/`，包内是权威来源，书内 `theme/` 是渲染副本。已有副本时 `designing-theme` 只改副本；只有用户明确要求「把插件主题装进这本书」且目标目录不存在，才从包复制，并把 `skills/writing-quarto/scripts/answering-disclosure.lua` 放到书内 `filters/answering-disclosure.lua`。`_quarto.yml` 只引用书内副本，不指向 npm 包或插件检出目录。
+
+### 检查与渲染
 
 内容与链接检查在 `writing-quarto` 技能目录下运行：
 
@@ -56,21 +73,27 @@ python scripts/checking-names.py --root <book>
 
 `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`。
+渲染后的 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`。
 
 一轮结束时调用一次 `quarto_pass_report`，把这次执行的结论压成卡片；卡片就是回执，回复里不再复述。
 
+### 项目技能
+
+项目只放一份自己的约定技能：`<book>/.agents/skills/quarto-book-project/`，模板见 `templates/quarto-book-project/`。存在时两个通用技能先读它的 `SKILL.md`，再按它指向的 `writing/` 文件读章节表；不存在就跳过，不猜项目约定。
+
+**不要把同名技能嵌进书仓库**：DSH 在同一技能层按 rank 取一个，`.agents/skills`（rank 200）优先于插件（rank 550），书里再放 `writing-quarto` 或 `designing-theme` 会让插件正文失效。
+
 ## 文档
 
 | 文档 | 内容 |
 | --- | --- |
 | [docs/plugin-flow.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/plugin-flow.md) | 从安装到回执的五层结构、文件分流与渲染顺序 |
-| [docs/plugin-boundaries.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/plugin-boundaries.md) | 工作区门禁的六类情形与判定顺序 |
+| [docs/plugin-boundaries.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/plugin-boundaries.md) | 工作区检查的六类情形与判定顺序 |
 | [docs/plugin-layout.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/plugin-layout.md) | 仓库目录、发布包内容与 Python/Quarto 分工 |
 | [docs/writing-quarto-layout.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/writing-quarto-layout.md) | 写作技能的目录分层 |
 | [docs/versioning.md](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/docs/versioning.md) | 版本号与发布顺序 |
 
-## 本地开发
+## 开发
 
 源码用 TypeScript，构建产物 `lib/` 提交进仓库；发布包直接加载 `lib/`，安装后不需要构建。开发时把本仓库链接进写书用的 profile，而不是把技能复制进书：
 
@@ -81,10 +104,12 @@ npm run check
 npm run pack
 ```
 
-`npm test` 会先编译再跑工具测试；`npm run check` 做类型检查与技能路径自检；`npm run pack` 把 tarball 只写进 `temp/`，那个目录已在 `.gitignore` 里。开发安装：
+`npm test` 会先编译再跑工具测试；`npm run check` 做类型检查与技能路径自检；`npm run pack` 把 tarball 只写进 `temp/`，那个目录已在 `.gitignore` 里。
+
+开发安装：
 
 ```bash
-dsh plugin --profile web add D:\Github\dsh-quarto-book
+dsh plugin --profile web add D:\\Github\\dsh-quarto-book
 ```
 
 `SKILL.md`、`steps/`、`examples/`、`quarto/` 在下一次 `skill` 工具调用时重读，改完不用发 npm。包内主题改动不会自动进书的 HTML；要看页面效果，把改过的文件同步到书的 `theme/`，再在书根运行 `quarto render`。不要把 `_quarto.yml` 指到插件检出目录，那条路径换机器就不存在。
@@ -93,6 +118,10 @@ dsh plugin --profile web add D:\Github\dsh-quarto-book
 
 旧装机脚本 `scripts/embedding-agents.ps1` 会把两棵技能原样复制进目标仓库的 `.agents/`，按 rank 200 盖住插件；新书不要用它，只有离线归档独立技能树时才执行，命令写在脚本头部。
 
+## 问题与贡献
+
+问题与建议走 [GitHub Issues](https://github.com/chengzhao-dev/dsh-quarto-book/issues)。提交改动前先运行 `npm test` 与 `npm run check`；涉及技能正文时，同时跑 `node scripts/checking-skill-links.mjs`。
+
 ## 许可
 
 MIT。主题内的 LXGW Bright 与 LXGW Bright Code 按 SIL Open Font License 1.1 使用；上游版权声明与许可全文在 `skills/designing-theme/assets/theme/assets/fonts/OFL.txt`。

package/lib/index.js

@@ -24,15 +24,17 @@ const RANK = 550;
 const SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const PACKAGE_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const SKILLS_ROOT = path.join(PACKAGE_ROOT, 'skills');
-/** 读取 SKILL.md 实际用到的几个键，只做最简单的 YAML frontmatter 解析。 */
+/** 读取 SKILL.md 实际用到的几个键，只做最小的 YAML frontmatter 解析。 */
 function parseFrontmatter(source) {
-    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(source);
+    const normalized = source.replace(/^\uFEFF/, '');
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(normalized);
     if (!match)
-        return { data: {}, body: source };
+        return { data: {}, body: normalized };
     const data = {};
     const stack = [{ indent: -1, target: data }];
-    for (const rawLine of match[1].split(/\r?\n/)) {
-        const line = rawLine.replace(/\t/g, '  ');
+    const lines = match[1].split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index].replace(/\t/g, '  ');
         if (!line.trim() || line.trimStart().startsWith('#'))
             continue;
         const indent = line.length - line.trimStart().length;
@@ -43,16 +45,56 @@ function parseFrontmatter(source) {
             stack.pop();
         const parent = stack[stack.length - 1].target;
         const key = pair[1];
-        const value = (pair[2] ?? '').trim();
+        const value = stripInlineComment(pair[2] ?? '').trim();
         if (value === '') {
             const child = {};
             parent[key] = child;
             stack.push({ indent, target: child });
             continue;
         }
+        if (/^[>|][+-]?\d?$/.test(value)) {
+            const block = [];
+            let cursor = index + 1;
+            for (; cursor < lines.length; cursor += 1) {
+                const next = lines[cursor].replace(/\t/g, '  ');
+                if (!next.trim()) {
+                    block.push('');
+                    continue;
+                }
+                const nextIndent = next.length - next.trimStart().length;
+                if (nextIndent <= indent)
+                    break;
+                block.push(next);
+            }
+            const nonBlank = block.filter((item) => item.trim());
+            const cut = nonBlank.length > 0 ? Math.min(...nonBlank.map((item) => item.length - item.trimStart().length)) : 0;
+            const text = block.map((item) => item.slice(cut)).join('\n');
+            parent[key] = value[0] === '|' ? text : text.replace(/([^\n])\n(?=[^\n])/g, '$1 ').replace(/\n{2,}/g, '\n');
+            index = cursor - 1;
+            continue;
+        }
         parent[key] = parseScalar(value);
     }
-    return { data, body: source.slice(match[0].length) };
+    return { data, body: normalized.slice(match[0].length) };
+}
+/** 去掉 plain scalar 末尾的 ` # 注释`；引号内的 # 保留。 */
+function stripInlineComment(value) {
+    let quote;
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value[index];
+        if (quote) {
+            if (char === quote && value[index - 1] !== '\\')
+                quote = undefined;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            continue;
+        }
+        if (char === '#' && (index === 0 || /\s/.test(value[index - 1])))
+            return value.slice(0, index);
+    }
+    return value;
 }
 function parseScalar(value) {
     if ((value.startsWith('"') && value.endsWith('"')) ||

package/lib/tools/pass-report.js

@@ -74,6 +74,7 @@ function normalizeFiles(value) {
         fail('files 必须是数组');
     if (value.length > MAX_FILES)
         fail(`files 最多 ${MAX_FILES} 个路径`);
+    const seen = new Set();
     return value.map((item) => {
         if (!isRecord(item))
             fail('files 的每一项必须是 { path, edits }');
@@ -85,7 +86,11 @@ function normalizeFiles(value) {
             fail('files 的 path 必须是非空字符串');
         if (!isPlainCount(item.edits))
             fail('files 的 edits 必须是非负整数');
-        return { path: filePath.trim(), edits: item.edits };
+        const normalizedPath = filePath.trim();
+        if (seen.has(normalizedPath))
+            fail(`files 的 path 重复：${normalizedPath}`);
+        seen.add(normalizedPath);
+        return { path: normalizedPath, edits: item.edits };
     });
 }
 function normalizeSteps(value, skill) {
@@ -194,17 +199,12 @@ export function buildPassReport(input) {
             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 必须为空');
+        for (const key of ['files', 'steps', 'held', 'checks']) {
+            const value = input[key];
+            if (value === undefined)
+                continue;
+            if (!Array.isArray(value) || value.length > 0)
+                fail(`未执行时 ${key} 必须为空数组`);
         }
         return { receipt: `未执行 ${typedSkill}：${reason.trim()}` };
     }