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

package/lib/workspace.js

@@ -13,6 +13,7 @@ const BOOK_SOURCE_EXTENSIONS = new Set(['.qmd', '.md']);
 const NON_CHAPTER_FILE_RE = /^(?:readme|changelog|license|licence|contributing|code[_-]of[_-]conduct|security|support|authors|contributors|agents|claude)(?:[.-][a-z0-9_-]+)*\.(?:md|markdown|qmd)$/i;
 const IGNORED_DIRECTORIES = new Set([
     '.git',
+    '.agents',
     '.quarto',
     '.cache',
     '.venv',

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "Quarto Book Writing & Theme",
-    "description": "Polish Chinese technical chapters, check book structure and mixed Chinese-English prose, and maintain a consistent, readable theme."
+    "description": "Write, check, and publish a Chinese Quarto Book: nine-step chapter writing, structure/link/figure checks, a consistent theme, and render acceptance."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "Quarto 图书写作与主题",
-    "description": "润色中文技术章节，检查 Book 结构与中英混排，并维护一套统一、可读的阅读主题。"
+    "description": "把一份 Quarto Book 写成可读、可查、可发布的中文技术书：九步章节写作、结构/链接/图表检查、统一主题与渲染验收。"
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chengzhao-dev/dsh-quarto-book",
-  "version": "0.6.3",
-  "description": "润色中文技术章节，检查 Book 结构与中英混排，并维护一套统一、可读的阅读主题。 · Polish Chinese technical chapters, check book structure and mixed Chinese-English prose, and maintain a consistent, readable theme.",
+  "version": "0.6.4",
+  "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",
   "exports": {
@@ -35,8 +35,8 @@
     "catalog": {
       "category": "skill",
       "summary": {
-        "zh": "润色中文技术章节，检查 Book 结构与中英混排，并维护一套统一、可读的阅读主题。",
-        "en": "Polish Chinese technical chapters, check book structure and mixed Chinese-English prose, and maintain a consistent, readable theme."
+        "zh": "把一份 Quarto Book 写成可读、可查、可发布的中文技术书：九步章节写作、结构/链接/图表检查、统一主题与渲染验收。",
+        "en": "Write, check, and publish a Chinese Quarto Book: a nine-step chapter workflow, structure/link/figure checks, a consistent theme, and render acceptance."
       },
       "capabilities": [
         "skills",
@@ -47,8 +47,11 @@
   "icon": "./icon.svg",
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --test tests/*.test.mjs",
-    "check": "tsc --noEmit -p tsconfig.json && node scripts/checking-skill-links.mjs",
+    "test": "npm run build && node --test \"tests/**/*.test.mjs\"",
+    "check": "tsc --noEmit -p tsconfig.json && node scripts/checking-skill-links.mjs && node scripts/checking-skill-budget.mjs && node scripts/checking-package.mjs",
+    "check:lib": "node scripts/checking-lib.mjs",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run check && npm run check:lib",
     "pack": "node -e \"require('fs').mkdirSync('temp',{recursive:true})\" && npm pack --pack-destination temp",
     "pack:check": "npm pack --dry-run"
   },

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

@@ -199,6 +199,21 @@ mjx-container[display="true"] {
   box-sizing: border-box;
 }
 
+/* 原生 HTML/SVG 图：图与图注作为一个整体居中；图注在图下，沿用上面的 figure 图注样式。 */
+#quarto-document-content .book-figure {
+  margin: 1.25rem auto;
+  text-align: center;
+}
+#quarto-document-content .book-figure > svg {
+  display: block;
+  margin-inline: auto;
+  max-width: 100%;
+  height: auto;
+}
+#quarto-document-content .book-figure > figcaption {
+  margin-top: 0.5rem;
+}
+
 /* jupyter 单元的图必须用 IPython.display.HTML 输出保持 SVG 内联：image/svg+xml 输出会被
    Quarto 外置成 <img>，无法继承站点 data-bs-theme 明暗与文档字体。text/html 输出不被
    Quarto 识别为图像，fig-cap 退化为图后一个裸 <p>，这里按 figcaption 同款图注样式居中。 */

package/skills/designing-theme/scripts/checking-layout.py

@@ -7,7 +7,7 @@ Node、Playwright 与 Edge 可用时，measuring-pages.mjs 验证真实几何。
 规范出处：本技能 `references/theme-system.md`。
 
 用法：python checking-layout.py [--root .] [--book-dir _book] [--browser]
-退出码：0 = 关键令牌全部存在，1 = 有缺失。
+退出码：0 = 关键令牌全部存在，1 = 有缺失，2 = 渲染产物目录缺失，3 = 请求了 --browser 但运行时不可用。
 """
 
 import argparse
@@ -348,7 +348,12 @@ def resolve_node():
 
 
 def resolve_playwright_root():
-    candidates = [os.environ.get("BOARD_GAMES_NODE_PATH"), os.environ.get("NODE_PATH")]
+    candidates = [
+        os.environ.get("BOARD_GAMES_NODE_PATH"),
+        os.environ.get("NODE_PATH"),
+        str(THEME_DIR.parents[1] / "node_modules"),
+        str(ROOT / "node_modules"),
+    ]
     cache = Path.home() / ".cache" / "codex-runtimes"
     if cache.is_dir():
         candidates.extend(
@@ -838,7 +843,7 @@ def main():
         book_dir = ROOT / book_dir
     if not book_dir.is_dir():
         print(f"BookDir not found: {book_dir}. Run 'quarto render' first.")
-        return 1
+        return 2
 
     css_texts = [
         p.read_text(encoding="utf-8", errors="ignore")
@@ -1024,6 +1029,9 @@ def main():
 
     print()
     if fail == 0:
+        if args.browser and browser_note:
+            print(f"SKIP browser-layout  {browser_note}")
+            return 3
         if browser_note:
             print(f"PASS theme-static；SKIP browser-layout {browser_note}")
         else:

package/skills/designing-theme/scripts/measuring-pages.mjs

@@ -6,7 +6,7 @@
 import { mkdir, readdir, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { existsSync } from "node:fs";
-import { dirname, join, relative, resolve, sep } from "node:path";
+import { delimiter, dirname, join, relative, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 
 const argv = process.argv.slice(2);
@@ -79,7 +79,7 @@ function loadPlaywright() {
   try {
     return require("playwright");
   } catch (error) {
-    for (const directory of (process.env.NODE_PATH || "").split(sep).filter(Boolean)) {
+    for (const directory of (process.env.NODE_PATH || "").split(delimiter).filter(Boolean)) {
       const candidate = join(directory, "playwright", "index.js");
       if (existsSync(candidate)) {
         return require(candidate);

package/skills/writing-quarto/SKILL.md

@@ -16,6 +16,12 @@ 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 门禁触发）。
 
+## 整书走法
+
+改多章或排目录时，先读 `references/book-journey.md`：先定全书主线与章节次序，再逐章走九步，最后做全书一致性回读。只润色一章时不读它。
+
+单章与整书共用同一套九步，不另造一套章节规则；项目有章节表时以项目表为准。技能文件体量受 `references/token-budget.md` 约束，新增整书规则只写进 `book-journey.md`。
+
 ## 两种走法
 
 增量润色沿九步走，只改判为不合格的地方，其余保持原样。全章重构仍是这九步，但第 1–2 步先定删留、不动句子，第 3–4 步只拆块和段，第 5–7 步才逐句改。
@@ -29,6 +35,7 @@ metadata:
 1. 定任务：写出读者做完能完成的那件事，再列这一章要覆盖的任务。规则在 `steps/01-task.md`。
 2. 定结构：排页面骨架、二级标题和篇幅预算，只定删留、标题与章题对齐。规则在 `steps/02-structure.md`。
 3. 排列内容块：导语、围栏、收束与 Callout 的次序，一个围栏只放正在讲的那一块。规则在 `steps/03-blocks.md`。
+   图注写在图下、图前只写引出关系；三类图的统一写法见 `quarto/figures.md`。
 4. 定段落：一段一个对象，段间衔接落在话题切换处。规则在 `steps/04-paragraphs.md`。
 5. 定句子：主语选执行者，对象先行，一句一动作。规则在 `steps/05-sentences.md`。
 6. 定用词：统一术语、主动语态和语气。规则在 `steps/06-wording.md`。

package/skills/writing-quarto/examples/03-qmd-elements.md

@@ -48,8 +48,8 @@ constexpr bool IsInRange(Position position) { … }
 不佳（图前图例句复述图注的方位信息，一段三句三个主题）：
 `Position` 把坐标交给 `Board`，负数和行列为 `3` 的位置都会被拒绝。下面的图标出可用的 `(row, col)`。左上角是 `(0, 0)`，行向下增加，列向右增加。
 
-改写（方位与图例由 fig-cap 独自承载，正文只留行为句与桥接句）：
-调用方把 `Position` 交给 `Board`，行列出现负数或 `3` 都会被拒绝。下面的图标出可用的 `(row, col)`。
+改写（方位与图例由 fig-cap 独自说明，正文只留行为句与桥接句）：
+调用方把 `Position` 交给 `Board`，行列出现负数或 `3` 都会被拒绝。图列出可用的 `(row, col)`，桥接句不再交代图面方位。
 ```
 
 判定信号：两个围栏之间只有空行；图后直接进入与图无关的下一块；块前引语同时推进多个对象（如 `Position` 与 `IsInRange` 各讲一句）；图注已写明的方位与图例信息，桥接段或图后正文再讲一遍。
@@ -78,6 +78,33 @@ constexpr bool IsInRange(Position position) { … }
 
 判定信号：图后句删掉任一分句中心仍成立；图注或桥接句已写明的信息在图后再讲一遍。图后正文只给图注讲不完的新结论，图后对照与句段侧的冒号分号堆叠见 `examples/04-paragraph-opening.md`「冒号后堆叠分号解释」。
 
+## 原生 SVG 图注对照
+
+`{=html}` 围栏里的 SVG 不会被 Quarto 包成 figure；图注必须自己用 `<figure>` 和 `<figcaption>` 放在图下，不要在图前留一句“下图标出……”。
+
+````text
+不佳（图注占图前正文，SVG 裸放）：
+下图标出这块棋盘上可用的 (row, col)。
+
+```{=html}
+<svg class="coords-grid" role="img" aria-label="棋盘坐标。">…</svg>
+```
+````
+
+````text
+改写（图注在图下，正文只留引出关系的一句）：
+代码给出行列上限和坐标字段，图把行列编号落到棋盘格子上。
+
+```{=html}
+<figure class="book-figure">
+<svg class="coords-grid" role="img" aria-label="棋盘坐标。">…</svg>
+<figcaption>棋盘坐标图：3 行 3 列，每格标出 (row, col)；行向下、列向右，左上角是 (0, 0)。</figcaption>
+</figure>
+```
+````
+
+判定信号：`<svg>` 是否在 `<figure>` 内、`<figcaption>` 是否在 `svg` 之后；图前是否还有只交代图面的句子；图注与图后正文是否逐句重复。
+
 ## 块后解释先于图对照
 
 同一小节既有代码块项目解释又有图时，解释紧跟代码块，桥接句与图在后；图后不再回头讲代码项。

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

@@ -76,8 +76,9 @@ README 遵循 GitHub Markdown。根目录 `README.md` 是在线阅读链接的
 
 项目解释不得插队到图之后：禁止「导语 → 代码 → 图 → 再解释代码项」，图后正文不再回头讲代码块内的对象。代码块与图之间只有空行、或图后不接结论直接进入与图无关的下一块，都视为堆叠；结论已并入桥接段的小节收尾图除外。反例与改写对照见 `steps/03-blocks.md` 与 `quarto/coords.md`。
 
-图的放置另有三条边界：
+图的放置另有四条边界：
 
+- **图注与正文分工**：图注写图面内容与读法，图前句写这张图核对哪条关系；图前不写“下图标出……”这类只交代图面的句子，图注落在图下。三类图的图注写法见 `quarto/figures.md`。
 - **一图一事**：一张图只核对一条已讲清的关系。图需要同时表达两条关系时，拆成多张图，或按关系拆成多个 `###`，每节一图。
 - **同主题相邻**：代码块与图必须是同一对象的两种呈现。下一块与图主题不同时，先用一句正文收束本对象，再另起 `###`；禁止「代码 A → 一句拐弯 → 图讲 B → 再贴代码 C」的同节混排。
 - **图不承载正文未写的新信息**：图中的每个框、箭头或标记都能在图前正文找到对应对象与关系；读者需要新概念才能读懂的图，先在正文补出该概念，再放图。
@@ -128,4 +129,4 @@ Callout 个数见 `steps/02-structure.md`，本段不写数字；`warning` 只
 
 交叉引用使用真实标题生成的锚点，引用前确认目标页面存在。本项目不手写英文 `{#id}`，标题锚点由中文标题派生；跨章节引用用章节标题链接，不用「第 N 章」。
 
-需要渲染与链接依据时，读 `quarto/render.md` 与 `quarto/mermaid.md`。
+需要渲染与链接依据时，读 `quarto/render.md` 与 `quarto/mermaid.md`；图注、原生 SVG 与图前句的分工读 `quarto/figures.md`。

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

@@ -126,5 +126,6 @@ title: "章节标题"
 ## 延伸
 
 - 正文结构、代码块/终端约定与文档元素：`quarto/authoring.md`
+- 图、图注与图前句的分工：`quarto/figures.md`
 - 外观配置与渲染排错：`quarto/render.md`
 - 页面宽度与视觉依据：`steps/02-structure.md`

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

@@ -12,12 +12,13 @@
 
 - 页面 frontmatter 开 `engine: jupyter`，只给含图页面开启，避免全书每次渲染都起 kernel。
 - 坐标图单元用 ```` ```{python} ```` 围栏，块首写 `#| echo: false`、`#| warning: false`，再写 `#| fig-cap: "图 N：…"` 与 `#| fig-align: center`；图注文字概括图意，不与图后正文逐句重复，也不用 `>` 引用块另起一套图注。
+- 没有执行环境或页面保持静态时，允许直接写原生 HTML/SVG；图必须用 `<figure class="book-figure">` 包住，`<figcaption>` 在图后。三类图的统一图注约定见 `quarto/figures.md`，不要把图注留成图前的独立段落。
 - 单元内从当前目录向上定位含 `_quarto.yml` 的书根，按路径加载本技能 `scripts/diagrams/rendering-coords.py`，绑定名仍是 `coords_grid`，用 `IPython.display.HTML` 输出保持 SVG 内联。不要换成 `IPython.display.SVG`：image/svg+xml 输出会被 Quarto 外置成 `<img>` 文件引用，无法继承站点 `data-bs-theme` 明暗与文档字体（书内字体退回系统字体）。
 - 图注讲不完的读图要点写在图后正文（一两句），不复述图注已写明的信息。
 
 ## 上游代码与图的桥接
 
-坐标图不孤立出现：引出图的代码块与图之间必须有桥接句，说明图核对代码的哪部分契约（如「下面的图标出每个数据项的 (row, col)，与 `IsValid` 接受的范围一致」）；图后先给从图带走的结论，再进入下一块；小节以图收尾时，从图带走的结论可并入桥接段（如 示例章先给 `row` 为 `3` 或 `col` 为 `-1` 这类反例再上图），不在图后孤悬一句。代码块与图之间只有空行视为堆叠，固定序列见 `writing-quarto` 技能 `quarto/authoring.md`「代码与图的桥接」与 `steps/03-blocks.md`。
+坐标图不孤立出现：引出图的代码块与图之间必须有桥接句，说明图核对代码的哪部分契约（如「图核对 `IsValid` 接受的范围」）；图后先给从图带走的结论，再进入下一块；小节以图收尾时，从图带走的结论可并入桥接段（如 示例章先给 `row` 为 `3` 或 `col` 为 `-1` 这类反例再上图），不在图后孤悬一句。代码块与图之间只有空行视为堆叠，固定序列见 `writing-quarto` 技能 `quarto/authoring.md`「代码与图的桥接」与 `steps/03-blocks.md`；图注与图前句的分工见 `quarto/figures.md`。
 
 坐标图单元计入盒子密度（口径见 `steps/03-blocks.md`）：同一 `###` 内坐标图与代码块相邻出现时，桥接句就是盒子之间的承接正文；`verifying-content.py` 对两围栏之间无正文给出 WARN 提示，人审与对照案例仍是主检查。
 

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

@@ -0,0 +1,49 @@
+# 图与图注
+
+图由图像、`{mermaid}`、`{python}` 坐标图和原生 HTML/SVG 共同遵守这一份约定。图注负责读图信息，正文负责图与上下文的关系；两者不互相复述。
+
+## 位置与归属
+
+- 图注默认在图下，图整体居中。Quarto 的 `fig-cap` 默认就是图下题注；不要把图注写成图前独立段落。
+- `{mermaid}` 用 `%%| fig-cap`，`{python}` 坐标图用 `#| fig-cap`，原生 HTML/SVG 用 `<figure>` 内的 `<figcaption>`。三者都落在图下。
+- 图前只写引出关系的一句：为什么这里出现这张图、它核对哪条已讲清的契约。图前不写“下图标出……”这类只交代图面内容的句子；这种句子属于图注。
+- 图后只写从图带走的结论或图外新信息。图注已写明的坐标、方位、图例、成员取舍不再复述。
+
+## 图注写法
+
+图注是一句完整的读者句，至少包含“这张图画的是什么”和“读图要看的那条关系”。不手写“图 1：”，Quarto 按 `lang: zh` 自动编号。
+
+- 不佳：下图标出这块棋盘上可用的 `(row, col)`。
+- 改写（图下）：`棋盘坐标图：3 行 3 列，每格标出 (row, col)；行向下、列向右，左上角是 (0, 0)。`
+  - 原句只是图面说明，移入 `<figcaption>`，不再占据图前正文。
+- 不佳：总览图为什么不列成员？
+- 改写（删除；图注写“总览只画类型与关系”即可）。
+
+图注只解释图本身，不承担章节过渡，也不替读者总结整节。
+
+## 原生 HTML/SVG
+
+原生 HTML/SVG 图用 `<figure>` 包住，图注用 `<figcaption>`，图注必须是 `figure` 的最后一个子元素：
+
+```html
+<figure class="book-figure">
+<svg class="coords-grid" role="img" aria-label="棋盘坐标：3 行 3 列，左上角为 (0, 0)。">…</svg>
+<figcaption>棋盘坐标图：3 行 3 列，每格标出 (row, col)；行向下、列向右，左上角是 (0, 0)。</figcaption>
+</figure>
+```
+
+- `role="img"` 与 `aria-label` 给读屏软件一个短名称；`figcaption` 给视觉读者完整图注。
+- 主题用 `.book-figure` 统一居中、限制最大宽度，并让 `figcaption` 落在图下；不要另写行内样式。
+- 图注内需要行内代码时写 `<code>`，不要写 Markdown 反引号——`{=html}` 围栏按原样输出。
+
+## 与其他图类的关系
+
+- Mermaid 的方向、节点预算与线型约定见 `quarto/mermaid.md`；它的 `fig-cap` 同样遵守本文件。
+- 坐标图优先用 `quarto/coords.md` 的 `{python}` 助手；没有执行环境时，允许静态 HTML/SVG，但必须按本文件包 `<figure>` 与 `<figcaption>`，不能把图注留在图前。
+- 代码到图的固定序列见 `quarto/authoring.md`「代码与图的桥接」与 `steps/03-blocks.md`；桥接句讲关系，图注解图面，两者分工不同。
+
+## 自检
+
+- 图前是否还有“下图 / 图中 / 本图”这类只交代图面的句子？有就移入图注或删除。
+- 图注是否重复了图后正文？重复就删正文或删图注，只留一处。
+- 原生 SVG 是否在 `figure` 内，`figcaption` 是否在 `svg` 之后、`</figure>` 之前？

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

@@ -64,4 +64,4 @@ mermaid 用 init 指令中的字体测量标签宽度，页面 CSS 按 `--ui-fon
 
 每个 `{mermaid}` 图块在围栏开头、init 之前写一行 `%%| fig-cap: "程序结构总览。实线箭头表示调用或依赖，……"`。`fig-cap` 只写图意和读图约定，不手写“图 1：”这类编号；Quarto 按 `lang: zh` 自动在正文中排成“图 1：”。图注紧跟图块开头、落在图下。线型、箭头方向、读图范围这类说明只写进该图的图注，图后正文不再复述；图后只补图外的新信息或从图带走的结论，不点名被省略的成员，也不写“其余成员见某章”。`fig-cap` 是 Quarto 对 Mermaid 的单元选项语法，`%%|` 必须直接写在围栏开头、init 之前（Quarto 只解析块首选项；写在 init 之后会被当成 Mermaid 注释原样渲染），不能改成 `#|` 或图后引用块。
 
-图注文字概括图意，不与图后正文逐句重复；需要交叉引用时同时写 `label: fig-...`，正文用 `@fig-...` 引用。
+图注文字概括图意，不与图后正文逐句重复；需要交叉引用时同时写 `label: fig-...`，正文用 `@fig-...` 引用。图注与图前句的统一分工、原生 HTML/SVG 的图注写法见 `quarto/figures.md`。

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

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

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

@@ -0,0 +1,38 @@
+# 整本书的写作次序
+
+单章润色看一章；整书重构先看这本书要带读者完成什么，再决定章节次序。本文件只定整书层的判断，单章规则仍在 `steps/`。
+
+## 先定一条主线
+
+把目录写成一句可验收的话：读者从什么基础出发，按顺序做完哪些事，最后能独立交付什么。主线要落到一个可运行、可检查的产物；章节是这条主线上的阶段，不是互不相干的 API 清单。
+
+写目录前先删掉三类章：同一对象拆成多章、只罗列类型而没有阶段结果、前后章可以任意交换。保留下来的章，每一章只回答一个关键问题，并在开头接住上一章的结果、结尾交出下一章需要的输入。
+
+## 三遍走
+
+1. **骨架遍**：先排章节次序与每章关键，确认读者按顺序能完成主线；此时不写句子，不补代码。
+2. **章节遍**：每章按 `steps/01-task.md` 到 `steps/09-check.md` 走九步，只改这一章；章与章的接口在章首、章末对齐。
+3. **全书遍**：从头回读，检查术语、项目名、图注、链接与前后承诺；只改跨章不一致，不在这一遍重写单章。
+
+骨架遍改次序，章节遍改正文，全书遍改一致性；三遍不混做。
+
+## 以井字棋书为例
+
+| 阶段 | 章节 | 交给下一章的结果 |
+| --- | --- | --- |
+| 规则 | 对局规则 | 一局怎样算结束 |
+| 结构 | 工程结构、程序结构 | 文件与类的整体形状 |
+| 数据 | 棋盘、对局 | 格子、坐标、落子后的状态 |
+| 决策 | 电脑落子 | 电脑怎样选一格 |
+| 交互 | 终端程序、程序入口 | 人怎样下一局 |
+| 质量 | 调试、测试、构建与运行 | 改动后怎样确认没坏 |
+| 收束 | 局面快照 | 一局怎样保存与还原 |
+
+这张表只是示例。项目有自己的章节表时，以 `.agents/skills/quarto-book-project/writing/chapter-map.md` 为准；没有就按上面的阶段顺序推，不猜项目事实。
+
+## 插件层怎么配合
+
+- 整书规划先读本文件与项目章节表，再逐章加载 `steps/`；不要一次读完九步。
+- 单章判不准时才开 `examples/`；排图、查渲染或全仓重构才开 `quarto/`。
+- 全仓检查用 `scripts/`，渲染验收用 `quarto_render_check`；两件事都放在最后一遍，不在骨架遍执行。
+- 文件体量受 `references/token-budget.md` 约束；新增整书规则只写进本文件，不复制到各步。

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

@@ -0,0 +1,26 @@
+# 技能文件的 token 预算
+
+本文件约束技能 Markdown 的体量。它只管加载成本，不替代 `docs/writing-quarto-layout.md` 的分层规则。
+
+## 预算
+
+估算口径：一个 CJK 字符按 1 token，其余字符按 4 字符 1 token 计。`scripts/checking-skill-budget.mjs` 用同一口径检查，`npm run check` 会执行。
+
+| 目录或文件 | 单文件上限 |
+| --- | --- |
+| `writing-quarto/SKILL.md`、`designing-theme/SKILL.md` | 2000 |
+| `steps/02-structure.md`、`steps/03-blocks.md`、`steps/05-sentences.md` | 12000 |
+| 其余 `steps/*.md` | 8000 |
+| `examples/*.md` | 5000 |
+| `quarto/*.md` | 5000 |
+| `designing-theme/references/theme-system.md` | 8000 |
+| 其余 `references/*.md`、`knowledge/*.md` | 6000 |
+| `assets/**/meta.md` | 2000 |
+| 全部技能 Markdown 合计 | 140000 |
+
+## 怎么用
+
+- 新增规则先判断属于哪一层，再写进已有文件；同一判定只成文一处，其他位置写引用。
+- 文件将超限时，先删重复、合并同源条目，再考虑拆成同目录的新文件；拆文件后同步入口和 `scripts/checking-skill-links.mjs`。
+- 单章润色只加载 `SKILL.md` 与当前一步；不要为了省 token 把整本书的规则塞进 `SKILL.md`。
+- 预算不是目标：没必要的条文直接删，不靠缩写把句子压成暗语。

package/skills/writing-quarto/scripts/checking-callouts.py

@@ -6,7 +6,7 @@ Quarto 只认内置 5 类 callout（note/tip/warning/important/caution）。未
 <section> 没有提示框样式。它还混进右侧目录。本脚本在 _book/**/*.html 里抓这一回归。
 
 用法：python checking-callouts.py [--root .] [--book-dir _book]
-退出码：0 = 全部正常，1 = 发现退化的 callout。
+退出码：0 = 全部正常，1 = 发现退化的 callout，2 = 渲染产物目录缺失。
 """
 
 import argparse
@@ -71,7 +71,7 @@ def main():
         book_dir = root / book_dir
     if not book_dir.is_dir():
         print(f"未找到渲染产物目录：{book_dir}；请先执行 quarto render。")
-        return 1
+        return 2
 
     html_files = sorted(book_dir.rglob("*.html"))
     bad_pages = 0

package/skills/writing-quarto/scripts/checking-dom.py

@@ -240,7 +240,8 @@ def check_contracts(book_dir, htmls, css_pairs, root=None, require_favicon=True)
     ))
 
     # ---------- C1 复制按钮可见性 ----------
-    sibling_ok = False
+    checked = 0
+    bad = 0
     scaffold_pages = 0
     for path, tree, _rels in htmls:
         scaffolds = [n for n in walk(tree) if SCAFFOLD in n.classes]
@@ -249,20 +250,23 @@ def check_contracts(book_dir, htmls, css_pairs, root=None, require_favicon=True)
         scaffold_pages += 1
         for sc in scaffolds:
             code = [c for c in sc.children if c.tag == "div" and SRCODE in c.classes]
+            if not code:
+                continue
+            checked += 1
             btns = [c for c in sc.children if c.tag == "button" and COPY_BTN in c.classes]
-            if code and btns and not any(is_descendant(b, code[0]) for b in btns):
-                sibling_ok = True
+            if not btns or any(is_descendant(b, code[0]) for b in btns):
+                bad += 1
     hover_rule = any(
         ".%s:hover .%s" % (SCAFFOLD, COPY_BTN) in css for _, css in css_pairs
     )
     stale_rule = any(
         "div.%s:hover .%s" % (SRCODE, COPY_BTN) in css for _, css in css_pairs
     )
-    c1 = sibling_ok and hover_rule and not stale_rule
+    c1 = checked > 0 and bad == 0 and hover_rule and not stale_rule
     results.append((
         "C1", "复制按钮 hover 可见（兄弟 DOM + scaffold 选择器）", c1,
-        "pages=%d sibling=%s hover-rule=%s%s"
-        % (scaffold_pages, sibling_ok, hover_rule, " stale-rule!" if stale_rule else ""),
+        "pages=%d checked=%d bad=%d hover-rule=%s%s"
+        % (scaffold_pages, checked, bad, hover_rule, " stale-rule!" if stale_rule else ""),
         [
             "产物中 button.%s 必须与 div.%s 同为 .%s 的直接子元素" % (COPY_BTN, SRCODE, SCAFFOLD),
             "CSS 必须含 .%s:hover .%s（不能停留在 div.%s:hover 的后代写法）"
@@ -535,6 +539,8 @@ def main():
     args = parser.parse_args()
 
     book_dir = Path(args.book_dir)
+    if not book_dir.is_absolute():
+        book_dir = Path(args.root) / book_dir
     if not book_dir.is_dir():
         print("MISS 产物目录不存在：%s（请先运行 quarto render）" % book_dir)
         return 2

package/skills/writing-quarto/scripts/checking-links.py

@@ -21,7 +21,9 @@ from pathlib import Path
 
 LINK_RE = re.compile(r"\[[^\]]*\]\(([^)\s]+)(?:\s+\"[^\"]*\")?\)")
 HTML_LINK_RE = re.compile(r"<(?:a|img)\b[^>]*\b(?:href|src)=\"([^\"]+)\"", re.IGNORECASE)
+FENCE_RE = re.compile(r"^\s*(```+|~~~+)")
 SKIP_PREFIXES = ("http://", "https://", "mailto:", "tel:", "data:", "#", "//")
+SKIP_DIRS = {".git", ".cache", ".quarto", "_book", "_freeze", "_site", "build", "node_modules", "temp"}
 
 
 def collect_sources(root: Path, paths: list[str]) -> list[Path]:
@@ -41,17 +43,24 @@ def collect_sources(root: Path, paths: list[str]) -> list[Path]:
     return sorted(
         path for path in found
         if not any(
-            part in {".git", ".cache", ".quarto", "_book", "_freeze", "_site", "build", "node_modules", "temp"}
-            for part in path.parts
+            part in SKIP_DIRS
+            for part in path.relative_to(root).parts
         )
     )
 
 
-def link_targets(text: str):
-    for match in LINK_RE.finditer(text):
-        yield match.group(1)
-    for match in HTML_LINK_RE.finditer(text):
-        yield match.group(1)
+def iter_links(text: str):
+    in_fence = False
+    for number, line in enumerate(text.splitlines(), start=1):
+        if FENCE_RE.match(line):
+            in_fence = not in_fence
+            continue
+        if in_fence:
+            continue
+        for match in LINK_RE.finditer(line):
+            yield number, match.group(1)
+        for match in HTML_LINK_RE.finditer(line):
+            yield number, match.group(1)
 
 
 def main() -> int:
@@ -72,13 +81,20 @@ def main() -> int:
         return 2
 
     sources = collect_sources(root, args.paths)
-    broken: list[tuple[str, str, str]] = []
+    if not sources:
+        print("失败  没有可检查的 Markdown/Quarto 源文件", file=sys.stderr)
+        return 2
+    broken: list[tuple[str, int, str, str]] = []
     checked = 0
 
     for source in sources:
-        text = source.read_text(encoding="utf-8", errors="replace")
+        try:
+            text = source.read_text(encoding="utf-8")
+        except UnicodeDecodeError as exc:
+            print(f"失败  {source} 不是合法 UTF-8：{exc}", file=sys.stderr)
+            return 1
         rel = source.relative_to(root).as_posix()
-        for raw in link_targets(text):
+        for number, raw in iter_links(text):
             target = raw.strip()
             if not target or target.startswith(SKIP_PREFIXES):
                 continue
@@ -91,7 +107,7 @@ def main() -> int:
             candidates = [source.parent / clean, root / clean]
             if any(candidate.exists() for candidate in candidates):
                 continue
-            broken.append((rel, target, "目标不存在"))
+            broken.append((rel, number, target, "目标不存在"))
 
     print(f"扫描 {len(sources)} 个文件，检查 {checked} 条本地链接。")
     if not broken:
@@ -99,8 +115,8 @@ def main() -> int:
         return 0
 
     print(f"发现 {len(broken)} 条断链：")
-    for rel, target, reason in broken[:80]:
-        print(f"  {rel} -> {target}（{reason}）")
+    for rel, number, target, reason in broken[:80]:
+        print(f"  {rel}:{number} -> {target}（{reason}）")
     return 1
 
 

package/skills/writing-quarto/scripts/checking-names.py

@@ -33,7 +33,7 @@ EXCLUDE_DIR_SUFFIXES = ("_files",)
 
 TOOL_FIXED_NAMES = {
     "CMakeLists.txt", "_quarto.yml", "_quarto.yaml", "SKILL.md", "AGENTS.md",
-    "README.md", "README.en.md", "LICENSE", "CONTRIBUTING.md",
+    "README.md", "README.en.md", "LICENSE", "OFL.txt", "CONTRIBUTING.md",
     ".editorconfig", ".gitignore", ".gitattributes", "openai.yaml",
     "package.json", "package-lock.json", "pnpm-lock.yaml", "tsconfig.json",
 }
@@ -56,6 +56,8 @@ def name_form_error(name: str) -> str | None:
     if " " in name:
         return "含空格"
     if "-" not in name:
+        if not all(ch.islower() or ch.isdigit() or ch == "." for ch in name):
+            return "含非小写字符"
         return None
     parts = name.split("-")
     if any(part == "" for part in parts):

package/skills/writing-quarto/scripts/checking-output.py

@@ -7,7 +7,7 @@
 不在本检查范围内。
 
 用法：python checking-output.py [--book-dir _book] [--root .] [--require-sitemap]
-退出码：0 = 通过；1 = 存在阻塞问题。
+退出码：0 = 通过；1 = 存在阻塞问题；2 = 渲染产物目录或首页缺失。
 """
 
 import argparse
@@ -37,12 +37,12 @@ def main() -> int:
     index = book / "index.html"
     if not index.is_file():
         print(f"缺少产物首页 {book.as_posix()}/index.html：确认在仓库根目录渲染")
-        return 1
+        return 2
 
     html_files = sorted(book.rglob("*.html"))
     if not html_files:
         print(f"{book.as_posix()} 下没有任何 HTML 文件")
-        return 1
+        return 2
 
     for path in html_files:
         rel = path.relative_to(book).as_posix()

package/skills/writing-quarto/scripts/checking-prose.py

@@ -42,13 +42,13 @@ class Issue:
     message: str
 
 
-def strip_frontmatter(text: str) -> str:
+def split_frontmatter(text: str) -> tuple[int, str]:
     lines = text.splitlines()
     if lines and lines[0].strip() == "---":
         for index in range(1, len(lines)):
             if lines[index].strip() == "---":
-                return "\n".join(lines[index + 1 :])
-    return text
+                return index + 1, "\n".join(lines[index + 1 :])
+    return 0, text
 
 
 def mask_links_and_tags(line: str) -> str:
@@ -98,11 +98,11 @@ def check_line(path: str, number: int, line: str) -> list[Issue]:
 
 
 def scan_file(root: Path, path: Path) -> list[Issue]:
-    text = path.read_text(encoding="utf-8", errors="replace")
-    text = strip_frontmatter(text)
+    text = path.read_text(encoding="utf-8")
+    offset, body = split_frontmatter(text)
     issues: list[Issue] = []
     in_fence = False
-    for number, line in enumerate(text.splitlines(), start=1):
+    for number, line in enumerate(body.splitlines(), start=offset + 1):
         if FENCE.match(line):
             in_fence = not in_fence
             continue
@@ -135,7 +135,11 @@ def main() -> int:
 
     issues: list[Issue] = []
     for path in collect_files(root):
-        issues.extend(scan_file(root, path))
+        try:
+            issues.extend(scan_file(root, path))
+        except UnicodeDecodeError as exc:
+            print(f"失败  {path} 不是合法 UTF-8：{exc}", file=sys.stderr)
+            return 1
 
     if args.json:
         print(