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

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

@@ -15,17 +15,53 @@ Quarto 只执行 ` ```{mermaid} ` 属性围栏；plain 的 ` ```mermaid ` 围栏
 每个 `{mermaid}` 块的第一行写：
 
 ```text
-%%{init: {"fontFamily": "LXGW Bright Medium, system-ui, sans-serif"}}%%
+%%{init: {"fontFamily": "LXGW Bright Medium, system-ui, sans-serif", "class": {"hideEmptyMembersBox": true}}}%%
 ```
 
 mermaid 用 init 指令中的字体测量标签宽度，页面 CSS 按 `--ui-font` 渲染文字；两者使用同一字体栈，标签测量与最终渲染一致，避免文字溢出或留白。`mermaid.css` 的排版守卫依赖这一约定。
 
+`class.hideEmptyMembersBox` 只影响类图：没有成员的类只画类名和注解，不画空成员栏。接口、派生类和函数节点都靠它收紧；`verifying-content.py` 要求每个类图块首出现这一项。
+
+## 类图：先定内容预算
+
+正文栏宽随视口变化：默认 1280 宽的 Edge 窗口下约 644 px，1440 宽下约 804 px。类图按自然宽度绘制，预算按最窄的 644 px 定，目标宽度不超过 600 px。把图缩到栏宽会让 15 px 的字降到读不清，横向滚动又会把图切成几段；两种结果都不合格。类图先按下面的预算删内容，再考虑拆图：
+
+| 项 | 上限 | 说明 |
+| --- | --- | --- |
+| 类型节点 | 6 个 | 包括空类、接口、枚举与函数节点 |
+| 成员行合计 | 14 行 | `<<enum>>` 这类注解不计 |
+| 单个类的成员行 | 5 行 | 只留本章连边或正文要用的成员 |
+| 单行成员显示列 | 40 列 | 汉字按 2 列计；参数省略类型名 |
+| 估算宽度 | 600 px | 渲染后按 `svg` 的 `max-width` 核对；超过就删内容或改方向 |
+| 方向 | 有成员用 `TB`，无成员可用 `LR` | 基类在上，派生类在下 |
+
+超预算时先删节点和成员，再按前后半拆图；不缩字号、不缩图、不等横向滚动兜底。
+
+总览图只画类型和边，不列成员：成员会把每个类框撑宽，让关系退到视口外。成员放进分块明细或对应章节，总览只画“谁和谁相连”。
+
+## 类图成员写法
+
+- 成员行用 `+`/`-` 标出可见性，类型写在名字前，参数只保留名字：`+bool CompletesLine(position, cell_type)`；
+- 一行只写一个成员，不把多个方法压进同一行；
+- 只列本章用到的成员；完整声明留在代码块和章节正文里，图内不补空成员，也不在图后写“其余成员见某章”；
+- 空类、接口和派生类只写类名与 `<<interface>>` 一类注解，不补空成员占位；
+- 关系边标签只写动词或名词短语，不写方法签名清单。
+
+## 流程图与类图的方向
+
+- 分层结构用 `TB`；单向推进链节点数 ≥ 5 时默认 `TB` 单列，一屏过高时拆成两张图，禁止长 `LR` 挤爆视口；节点数 ≤ 4 的短链可用 `LR`；
+- 类图有成员时用 `TB`，基类在上、派生类在下；无成员的纯类型关系图才用 `LR`；
+- 单图节点不超过 6 个，一图一事不变，超出优先拆图而不是压缩标签。
+
 ## 节点与边标签写法
 
 - 节点标签一律放在双引号内，例如 `A["标签文字"]`，不依赖裸文本解析；
 - 节点标签只画抽象层名，不把职责明细塞进节点括号；逐项职责用图后列表交代；
 - 标签中不使用全角冒号与直角引号「」承载分隔语义；并列用顿号，补充说明用全角括号；
-- 边标签写在 `-- 文字 -->` 中，保持简短中文；
-- 图表方向以窄屏可读为底线：分层结构用 `TB`；单向推进链节点数 ≥ 5 时默认 `TB` 单列，一屏过高时拆成两张图（如按前后半各一张），禁止长 `LR` 挤爆视口；节点数 ≤ 4 的短链可用 `LR`；
-- 单图节点建议 ≤ 6，一图一事不变，超出优先拆图而不是压缩标签。类图方向用 TB：基类在上，派生类在下。
-- 图后不设 `>` 引用块图注：图注内容并入图后列表的引言句或正文句，图表之后直接跟职责列表，不让图独立承载全部信息。
+- 边标签写在 `-- 文字 -->` 中，保持简短中文。
+
+## 图注
+
+每个 `{mermaid}` 图块在围栏开头、init 之前写一行 `%%| fig-cap: "程序结构总览。实线箭头表示调用或依赖，……"`。`fig-cap` 只写图意和读图约定，不手写“图 1：”这类编号；Quarto 按 `lang: zh` 自动在正文中排成“图 1：”。图注紧跟图块开头、落在图下。线型、箭头方向、读图范围这类说明只写进该图的图注，图后正文不再复述；图后只补图外的新信息或从图带走的结论，不点名被省略的成员，也不写“其余成员见某章”。`fig-cap` 是 Quarto 对 Mermaid 的单元选项语法，`%%|` 必须直接写在围栏开头、init 之前（Quarto 只解析块首选项；写在 init 之后会被当成 Mermaid 注释原样渲染），不能改成 `#|` 或图后引用块。
+
+图注文字概括图意，不与图后正文逐句重复；需要交叉引用时同时写 `label: fig-...`，正文用 `@fig-...` 引用。图注与图前句的统一分工、原生 HTML/SVG 的图注写法见 `quarto/figures.md`。

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

@@ -36,9 +36,9 @@
 - 冒号前必须是总说或提示语；冒号后的内容离开前文能读成完整一句。
 - 同一列表的末项标点统一：都用句号，或都不带句号。
 
-反例：`Board` 只保存九个棋盘格子。落子、满盘、成线与赢家都由它回答。写入前先检查坐标。声明在工程目录的 board.h。实现放在 board.cpp。
+反例：`Board` 只保存九个棋盘格子。落子、满盘、成线与赢家都从这些格子得出。写入前先检查坐标。声明在工程目录的 board.h。实现放在 board.cpp。
 
-改写：`Board` 只保存九个棋盘格子。它回答四类问题：坐标是否越界、棋盘是否已满、是否成线以及赢家是谁。写入前先检查坐标。接口声明在工程目录的 board.h，实现放在 board.cpp。
+改写：`Board` 从九个棋盘格子得出四类结果：坐标是否越界、棋盘是否已满、是否连成三个、赢家是谁。写入前先检查坐标；接口声明在工程目录的 board.h，实现放在 board.cpp。
 
 判定信号：同一段连续 4 个以上句号且多数句子短于 15 字；顿号串在分句之间；声明与实现各占一句，只剩位置碎片。
 
@@ -85,9 +85,9 @@
 
 润色要的「灵性」不靠形容词，靠三件事：主语是具体对象，动词是具体动作，读完能看见结果。
 
-- 删掉章节行程，直接给对象和它回答的问题。
+- 删掉章节行程，直接给对象和它产生的结果。
   - 原句：这一章介绍棋盘类的设计，首先看成员，然后看落子，最后看胜负判定。
-  - 改写：棋盘只保存九个格子。落子、满盘、成线与赢家都由它回答。
+  - 改写：棋盘只保存九个格子。落子、满盘、成线与赢家都从这些格子得出。
 - 把「进行校验」「负责计算」换成调用方看得见的动作与返回值。
   - 原句：程序会对输入进行校验，如果坐标不合法就会返回错误。
   - 改写：坐标越界、格子被占用或对局已结束时，`TryPlace` 返回 `kRejected`，棋盘不变。

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/quarto/terminal.md

@@ -75,7 +75,7 @@
 3. 如何恢复：能否重新生成，或恢复需要哪些前置。
 4. 替代方案：先给出可逆写法，把不可逆写法放在确认新状态正常之后。
 
-`rm -rf` 只有在没有安全替代、且恢复路径明确时才写，并放在 warning callout 或独立段落里，不与成功路径混排。删除 `build/` 属于可重建产物，恢复方式是重跑配置。
+`rm -rf` 只有在没有安全替代、且恢复路径明确时才写，并放在 warning callout 或独立段落里，不与成功路径混排。删除 `build/` 属于可重新生成的产物，恢复方式是重新运行配置。
 
 ## 常见错误条目形态与三步诊断流
 

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(