@chengzhao-dev/dsh-quarto-book 0.6.0 → 0.6.1

package/README.en.md

@@ -4,9 +4,9 @@
 
 **English** | [简体中文](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/README.md)
 
-Write Quarto Book chapters, check their structure, and maintain the theme; only inside `type: book` repositories.
+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 prose.
+- 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.
 
@@ -26,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.6.0
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-quarto-book@0.6.1
 ```
 
-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.0` only if the app refuses that write. To follow a GitHub tag instead, use `github:chengzhao-dev/dsh-quarto-book#v0.6.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.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`.
 
 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.
 
@@ -50,10 +50,11 @@ Run the content and link checks from the `writing-quarto` skill directory:
 ```bash
 python scripts/verifying-content.py --root <book>
 python scripts/checking-links.py --root <book>
+python scripts/checking-prose.py --root <book>
 python scripts/checking-names.py --root <book>
 ```
 
-Add `checking-names.py` only for a whole-repository refactor; ordinary chapter checks run the first two.
+`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.
 
 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`.
 

package/README.md

@@ -4,9 +4,9 @@
 
 [English](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/README.en.md) | **简体中文**
 
-为 Quarto Book 写章节、检查结构并维护主题；只在 `type: book` 的仓库里出现。
+润色中文技术章节、检查 Book 结构与中英混排，并维护一套统一、可读的阅读主题；只在 `type: book` 的仓库里出现。
 
-- 写 `.qmd`：`writing-quarto` 管章节骨架、结构与行文。
+- 写 `.qmd`：`writing-quarto` 管章节骨架、结构与中文行文。
 - 改主题：`designing-theme` 管 CSS、字体与 palette。
 - 渲染后检查 HTML：`quarto_render_check` 判一次可发布性，`quarto_pass_report` 出收尾回执。
 
@@ -26,10 +26,10 @@
 ## 安装
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-quarto-book@0.6.0
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-quarto-book@0.6.1
 ```
 
-`--profile` 换成你实际运行的那个 profile。桌面应用固定跑 `desktop` profile，且该 profile 由应用独占管理，`dsh --profile desktop` 直接启动会被拒绝；安装或升级插件可用 `dsh plugin --profile desktop add <包>`，如果应用拒绝写入，再走「设置 → 插件 → 添加插件」，地址填 `npm:@chengzhao-dev/dsh-quarto-book@0.6.0`。想跟 GitHub 标签，也可以写 `github:chengzhao-dev/dsh-quarto-book#v0.6.0`。
+`--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`。
 
 从旧的无作用域包 `dsh-quarto-book` 升级时（该包已随 0.3.4 从 npm 删除，只影响之前装过它的 profile），先在同一个 profile 里 `dsh plugin --profile <profile> remove dsh-quarto-book` 再装新包。两个包同时留着会以相同的 rank 550 各注册一遍 `writing-quarto` 和 `designing-theme`。
 
@@ -50,10 +50,11 @@ dsh plugin --profile web add npm:@chengzhao-dev/dsh-quarto-book@0.6.0
 ```bash
 python scripts/verifying-content.py --root <book>
 python scripts/checking-links.py --root <book>
+python scripts/checking-prose.py --root <book>
 python scripts/checking-names.py --root <book>
 ```
 
-`checking-names.py` 只在全仓重构时加跑；日常章节检查跑前两条即可。
+`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`。
 

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
-    "title": "Quarto Book Writing",
-    "description": "Write Quarto Book chapters, check their structure, and maintain the theme."
+    "title": "Quarto Book Writing & Theme",
+    "description": "Polish Chinese technical chapters, check book structure and mixed Chinese-English prose, and maintain a consistent, readable theme."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
-    "title": "Quarto 图书写作",
-    "description": "为 Quarto Book 写章节、检查结构并维护主题。"
+    "title": "Quarto 图书写作与主题",
+    "description": "润色中文技术章节，检查 Book 结构与中英混排，并维护一套统一、可读的阅读主题。"
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chengzhao-dev/dsh-quarto-book",
-  "version": "0.6.0",
-  "description": "为 Quarto Book 写章节、检查结构并维护主题。 · Write Quarto Book chapters, check their structure, and maintain the theme.",
+  "version": "0.6.1",
+  "description": "润色中文技术章节，检查 Book 结构与中英混排，并维护一套统一、可读的阅读主题。 · Polish Chinese technical chapters, check book structure and mixed Chinese-English prose, and maintain a consistent, readable theme.",
   "type": "module",
   "main": "./lib/index.js",
   "exports": {
@@ -32,8 +32,8 @@
     "catalog": {
       "category": "skill",
       "summary": {
-        "zh": "为 Quarto Book 写章节、检查结构并维护主题。",
-        "en": "Write Quarto Book chapters, check their structure, and maintain the theme."
+        "zh": "润色中文技术章节，检查 Book 结构与中英混排，并维护一套统一、可读的阅读主题。",
+        "en": "Polish Chinese technical chapters, check book structure and mixed Chinese-English prose, and maintain a consistent, readable theme."
       },
       "capabilities": [
         "skills",

package/skills/designing-theme/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: designing-theme
-description: 维护 Quarto Book 主题资产（CSS、SCSS、字体、palette）；调整页面样式、颜色或字体时使用，不用于改章节正文
+description: 维护 Quarto Book 阅读主题：颜色、字体、间距、导航与 Callout 样式；不用于章节正文
 metadata:
   short-description: 维护 Quarto 图书主题
 ---

package/skills/designing-theme/assets/theme/palettes/hill-light/tokens.css

@@ -319,4 +319,4 @@ html[data-palette="hill-light"][data-mode="night"] body {
   --line-hover-bg: rgba(45, 106, 102, 0.06);
   --overlay-scrim: rgba(0, 0, 0, 0.42);
 }
-}
+}

package/skills/writing-quarto/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: writing-quarto
-description: 编写和修改 Quarto Book 的 .qmd 章节，覆盖中文技术写作、Book 结构、代码与图表、渲染验证；不用于改 CSS、字体或主题颜色
+description: 润色与重构 Quarto Book 章节：任务与结构、术语与中英混排、检查与渲染；不用于改主题样式
 metadata:
-  short-description: 编写中文 Quarto 图书章节
+  short-description: 润色中文 Quarto 图书章节
 ---
 
 # Skill: writing-quarto
@@ -40,5 +40,7 @@ metadata:
 
 - [ ] 九步走完，每一步的产出都落在正文里。
 - [ ] 内容与链接核对通过：项目技能列了检查命令时按它执行，否则跑本技能 `scripts/verifying-content.py` 与 `checking-links.py`。
+- [ ] 新人能按正文独立完成任务：前置、动作、结果与失败出口齐全，术语首用有解释；清单见 `quarto/readability.md`。
+- [ ] 混排自查通过：`scripts/checking-prose.py --root <book>` 无高置信问题。
 - [ ] 调 `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/quarto/prose.md

@@ -2,7 +2,7 @@
 
 > 速查：中文句用中文标点 · 英文句子内部保留英文标点 · 中西文之间一个半角空格 · 数字与单位之间一个空格 · 行内代码只标记要逐字识别的对象
 
-本文件是标点、空格、引号、数字和英文术语写法的唯一出处；句子结构与用词仍归 `steps/05-sentences.md` 与 `steps/06-wording.md`，版式列表与加粗归 `steps/07-layout.md`。标点依据 GB/T 15834—2011 与 W3C CLREQ，空格与润色取舍是本仓约定。
+本文件是标点、空格、引号、数字和英文术语写法的唯一出处；句子结构与用词仍归 `steps/05-sentences.md` 与 `steps/06-wording.md`，版式列表与加粗归 `steps/07-layout.md`，新人可读性与任务完整性归 `quarto/readability.md`。标点依据 GB/T 15834—2011 与 W3C CLREQ，空格与润色取舍是本仓约定。
 
 ## 一条主轴
 
@@ -30,7 +30,8 @@
 
 ## 引号与术语
 
-- 术语首次出现写「中文译名（English original）」，后文统一用中文或原文，全书只选一种。
+- 术语首次出现写「中文译名（English original）」，紧跟一句可观察行为或用途解释；后文统一用中文或原文，全书只选一种。
+- 缩写首次出现写全称，再写括号缩写；读者不需要额外查表就能继续读。
 - API、类型、函数、参数、命令、路径和取值一律用行内代码，不翻译、不改大小写。
 - 英文句子独立成句时，句末用英文标点；中文句子里夹一个英文词时，句末仍用中文标点。
 - 不用全角拉丁字母或数字；不用中文引号包代码；不在术语中间插入空格。
@@ -42,6 +43,13 @@
 - 版本号、坐标、代码里的数字保持源码形式，不补空格、不换全角。
 - 单位符号与数字之间加空格；角度、百分比按行业习惯，同一本书内保持一致。
 
+## 条件与步骤
+
+- 条件写在动作前：「若要删除整个文档，先点 Delete」，不写「点 Delete，若你想删除整个文档」。
+- 这条只约束操作步骤；解释分支结果时仍先写可观察结果，再补条件。
+- 一步一个动作，动作后紧跟结果或验收方式；不要把三个动作塞进一句。
+- 步骤只写读者此刻要做的事，设计取舍另起一段放在动作完成后。
+
 ## 去套话
 
 - 删「进行／作出＋名词」「值得注意的是」「不难发现」「综上所述」「首先、其次、最后」的堆叠。
@@ -75,7 +83,8 @@
 - 段首是否用「这一章」「接下来」「首先」代替了具体对象。
 - 是否出现「进行」「负责」「完成」加名词的空心动作，能换成具体动词吗。
 - 段内是否至少有一句 20 字以内的短句。
-- 首次出现的英文术语是否给了中文，后文是否统一。
+- 首次出现的英文术语是否给了中文，是否紧跟一句可观察解释，后文是否统一。
+- 条件是否写在动作前，一句是否只做一个动作。
 
 ## 依据
 

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

@@ -0,0 +1,55 @@
+# 新人可读性与任务完整性
+
+> 速查：读者能独立做完 = 前置 + 动作 + 结果 + 失败出口；术语首次出现给定义，条件写在动作前。
+
+本文件补句子规则之外的两件事：新人能不能独立完成任务，术语有没有解释。句子、段落与版式仍归 `steps/05-sentences.md`、`steps/04-paragraphs.md` 与 `steps/07-layout.md`；本文件不重复它们的规则。
+
+## 读者三问
+
+每个任务节要让读者回答三个问题：我在哪里、我要做什么、做完看到什么。
+
+- **前置**：开始前需要哪一章的结果、哪个文件、哪个环境或哪条命令。缺一项就补一句。
+- **动作**：一个步骤一个动作，动词开头，对象明确。
+- **结果**：命令输出、文件变化、界面变化、返回值或测试结果，至少有一项可观察。
+- **失败出口**：出错时看哪条信息、回到哪一节、下一步试什么。
+
+只写「运行脚本」而不写运行后看到什么，读者无法判断自己是否成功。
+
+## 术语
+
+术语的写法（首次「中文（English）」、一句可观察解释、缩写先全称、后文统一）以 `quarto/prose.md`「引号与术语」为准。本节只管解释放在哪里：
+
+- 解释放在首次真正使用的位置，不放章首清单，也不留给下一章补课。
+- 能换成日常词就不造术语；不为「显得专业」引入新词。
+- 判定句：把术语换成「这个东西」，句子是否仍然成立？不成立说明解释不够。
+
+## 步骤完整
+
+- 动作之后紧跟结果或验收方式，结果不要等到节末才出现。
+- 失败路径写触发条件、可观察现象与恢复动作，不写空泛的「注意报错」。
+- 操作节不插入与当前动作无关的设计辩论；取舍另起一段放在动作完成后。
+- 条件与动作的先后见 `quarto/prose.md`「条件与步骤」。
+
+## 完整性清单
+
+- [ ] 读者知道开始前需要什么：环境、文件、上一章产物。
+- [ ] 每个任务有可观察的完成标志，不只写「运行一下」。
+- [ ] 新术语首用有解释，缩写有全称。
+- [ ] 条件在动作前，一句只做一个动作。
+- [ ] 失败时知道看什么、回到哪一节。
+- [ ] 没有「以后会讲」但当前就必须使用的名字。
+- [ ] 删掉本段后读者仍能完成任务的内容已经删除。
+- [ ] 读者不需要作者的补充说明，就能把这一节独立走完。
+
+## 混排自查
+
+`python <skill>/scripts/checking-prose.py --root <book>` 检查中文与拉丁字母、数字、行内代码之间的空格，以及中文句里的半角标点。脚本只报高置信项，不替代人工回读。
+
+## 依据
+
+- Google developer documentation style guide：https://developers.google.com/style/highlights
+- Google Jargon：https://developers.google.com/style/jargon
+- Google sentence structure（条件先于指令）：https://developers.google.com/style/sentence-structure
+- Diátaxis 质量模型：https://diataxis.fr/quality/
+- Digital.gov Plain language：https://digital.gov/guides/plain-language/principles
+- 中文技术文档写作风格指南：https://zh-style-guide.readthedocs.io/

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

@@ -35,6 +35,23 @@
 
 渲染后确认：目录深度与位置符合预期、明暗两套高亮都可读。渲染产物结构由 `checking-output.py` 与 `checking-callouts.py` 自动核对；页面宽度与视觉依据见 `steps/02-structure.md`。主题或目录看起来没生效时先硬刷新排除缓存，再核对选项嵌套层级。
 
+## 排查顺序
+
+先确定失败在哪一层，再查症状。一次只改一层，改完复跑同一层；不要用改 YAML 或重装依赖来碰运气。
+
+1. **内容层**：先跑 `verifying-content.py`（或项目技能的内容检查命令）。章节表、标题、句段长度、围栏与链接的失败都在这一层修。
+2. **混排层**：跑 `checking-prose.py`。缺空格、中文句里的半角标点在这一层修；不要顺手改句子结构。
+3. **渲染层**：调 `quarto_render_check` 的 `dry_run: false`。失败时先读 `render_result` 末尾的报错块，判断是 YAML、Lua 过滤器还是代码执行。
+4. **HTML 层**：读 `html_report.checks`。`index_html`、`utf8`、`charset` 失败回写作层；`dom` 或版式失败转 `designing-theme`。
+
+排查时守住三条：
+
+- **首个错误优先**：只修报错里的第一处，修完复跑；不要一次改五处再猜是哪处生效。
+- **缩小范围**：整书失败时先只渲染当前章节，确认单章能过，再看全书配置与跨章链接。
+- **不做破坏性验证**：不删 `_book/`、不关检查、不改成 `warning` 绕过；失败原因写进回复或 `temp/` 台账。
+
+找不到失败层时，把完整命令、首个错误原文与最近一次改动列出来，再按上表从上往下复跑。
+
 ## 渲染与发布排查索引
 
 按症状查此表：每条只给可执行处置。行为成因与取舍的唯一出处是知识库，用

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

@@ -40,7 +40,10 @@ def collect_sources(root: Path, paths: list[str]) -> list[Path]:
     found = list(root.rglob("*.qmd")) + list(root.rglob("*.md"))
     return sorted(
         path for path in found
-        if not any(part in {".git", "_book", "_site", "node_modules", ".quarto"} for part in path.parts)
+        if not any(
+            part in {".git", ".cache", ".quarto", "_book", "_freeze", "_site", "build", "node_modules", "temp"}
+            for part in path.parts
+        )
     )
 
 

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

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""检查 Quarto 章节里的高置信中英混排问题。
+
+只报能直接判断的错误：中文与拉丁字母、数字或行内代码之间缺空格，
+中文句里混入半角标点，中文标点前多了空格。句子长短、术语解释等
+仍需按 writing-quarto 的步骤人工回读。
+
+用法：
+    python checking-prose.py --root <book>
+    python checking-prose.py --root <book> --json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+CJK = r"\u4e00-\u9fff"
+CJK_CHAR = re.compile(f"[{CJK}]")
+CJK_LATIN = re.compile(f"([{CJK}])([A-Za-z0-9])")
+LATIN_CJK = re.compile(f"([A-Za-z0-9])([{CJK}])")
+HALF_PUNCT_IN_CJK = re.compile(f"([{CJK}])[,.;:?!]([{CJK}])")
+SPACE_BEFORE_PUNCT = re.compile(f"([^\\s])[ \\t]+([，。；：！？、])")
+DOUBLE_SPACE = re.compile(r"(?<=\S)[ \t]{2,}(?=\S)")
+FENCE = re.compile(r"^\s*(```+|~~~+)")
+INLINE_CODE = re.compile(r"`[^`\n]*`")
+URL = re.compile(r"https?://[^\s)>\]]+")
+LINK_TARGET = re.compile(r"\]\([^)]*\)")
+HTML_TAG = re.compile(r"<[^>]+>")
+SKIP_PREFIXES = (":::", "| ---", "|---")
+SKIP_DIRS = {"_book", ".quarto", "node_modules", ".git", "temp", ".cache"}
+
+
+@dataclass(frozen=True)
+class Issue:
+    path: str
+    line: int
+    message: str
+
+
+def strip_frontmatter(text: str) -> 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
+
+
+def mask_links_and_tags(line: str) -> str:
+    line = URL.sub("\x00", line)
+    line = LINK_TARGET.sub("\x00", line)
+    line = HTML_TAG.sub("\x00", line)
+    return line
+
+
+def mask_inline_code(line: str) -> str:
+    return INLINE_CODE.sub("\x00", line)
+
+
+def check_line(path: str, number: int, line: str) -> list[Issue]:
+    stripped = line.strip()
+    if not stripped or stripped.startswith(SKIP_PREFIXES) or stripped.startswith("<!--"):
+        return []
+    if stripped.startswith("#") and stripped.endswith("#"):
+        return []
+    if stripped.startswith("|") and set(stripped) <= set("|-: "):
+        return []
+
+    issues: list[Issue] = []
+    base = mask_links_and_tags(line)
+    visible = mask_inline_code(base)
+
+    for match in CJK_LATIN.finditer(visible):
+        issues.append(Issue(path, number, f"中文与拉丁字母/数字之间缺空格：{match.group(0)}"))
+    for match in LATIN_CJK.finditer(visible):
+        issues.append(Issue(path, number, f"拉丁字母/数字与中文之间缺空格：{match.group(0)}"))
+    for match in HALF_PUNCT_IN_CJK.finditer(visible):
+        issues.append(Issue(path, number, f"中文句里混入半角标点：{match.group(0)}"))
+    for match in SPACE_BEFORE_PUNCT.finditer(visible):
+        issues.append(Issue(path, number, f"中文标点前多了空格：{match.group(0)}"))
+    for match in DOUBLE_SPACE.finditer(visible):
+        issues.append(Issue(path, number, f"正文里有连续空格：{match.group(0)!r}"))
+
+    for match in INLINE_CODE.finditer(base):
+        before = base[match.start() - 1] if match.start() else ""
+        after = base[match.end()] if match.end() < len(base) else ""
+        if before and CJK_CHAR.match(before):
+            issues.append(Issue(path, number, "中文与行内代码之间缺空格"))
+        if after and CJK_CHAR.match(after):
+            issues.append(Issue(path, number, "行内代码与中文之间缺空格"))
+
+    return issues
+
+
+def scan_file(root: Path, path: Path) -> list[Issue]:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    text = strip_frontmatter(text)
+    issues: list[Issue] = []
+    in_fence = False
+    for number, line in enumerate(text.splitlines(), start=1):
+        if FENCE.match(line):
+            in_fence = not in_fence
+            continue
+        if in_fence:
+            continue
+        issues.extend(check_line(path.relative_to(root).as_posix(), number, line))
+    return issues
+
+
+def collect_files(root: Path) -> list[Path]:
+    files: list[Path] = []
+    for path in sorted(root.rglob("*.qmd")):
+        if any(part in SKIP_DIRS for part in path.relative_to(root).parts):
+            continue
+        files.append(path)
+    return files
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", default=".", help="书仓库根目录")
+    parser.add_argument("--json", action="store_true", help="输出 JSON")
+    parser.add_argument("--quiet", action="store_true", help="没有问题时也保持安静")
+    args = parser.parse_args()
+
+    root = Path(args.root).resolve()
+    if not root.is_dir():
+        print(f"失败  根目录不存在：{root}", file=sys.stderr)
+        return 2
+
+    issues: list[Issue] = []
+    for path in collect_files(root):
+        issues.extend(scan_file(root, path))
+
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    "root": str(root),
+                    "files": len(collect_files(root)),
+                    "issues": [issue.__dict__ for issue in issues],
+                },
+                ensure_ascii=False,
+                indent=2,
+            )
+        )
+    elif issues:
+        print(f"发现 {len(issues)} 个混排问题：")
+        for issue in issues:
+            print(f"{issue.path}:{issue.line}: {issue.message}")
+    elif not args.quiet:
+        print(f"OK：{len(collect_files(root))} 个章节通过混排检查。")
+
+    return 1 if issues else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/writing-quarto/steps/01-task.md

@@ -41,7 +41,7 @@
 
 ### 术语门槛
 
-- 保留编译、链接、目标、状态、回合等标准术语；首次出现时用一句话解释或就近术语卡，再进入命令。
+- 保留编译、链接、目标、状态、回合等标准术语；首次出现时用一句话解释或就近术语卡，再进入命令。解释写成可观察行为，缩写先写全称；细则见 `quarto/readability.md`。
 - 不解释对当前操作没有影响的内部格式。只保留判断成功所需的输出。
 - 面向新人的正文不堆砌入门前置名词；标题只用读者此刻已认识的词。
 

package/skills/writing-quarto/steps/08-reread.md

@@ -36,6 +36,8 @@
 | 定句子 | 没点名载体（「一个下标」「这个下标」「这次代入」），或一句里同时有跳过整行、列偏移和得数，或公式项列表 | 按列表选择换算条写成同一段短句 | `steps/07-layout.md`「列表选择」 |
 | 定句子 | `Get*` 概述纯名词句（`/// 当前流程结果。`） | 改「获取…」，动词与函数名前缀硬对齐；只对齐围栏里的声明，不改源码注释 | `steps/03-blocks.md` |
 | 定句子 | 分支解释把条件压在句首（拒绝、终局句读到句末才知道结果） | 主句先写可观察结果，条件跟在后面或另起一句 | `steps/05-sentences.md`「句子规则」 |
+| 定句子 | 操作步骤先写动作、条件放在后面（「点 Delete，若你想…」） | 把条件句移到动作前，一步只留一个动作 | Google sentence structure；`quarto/readability.md` |
+| 定用词 | 新术语首次出现只有名称或只有英文缩写，没有一句可观察解释 | 首用补「中文（English）」与一句定义，缩写先全称 | Google Jargon；`quarto/readability.md` |
 | 定句子 | 行尾把格子状态、先手或后手、操作动作写进同一句 | 换成术语表「数据项类型」里的三句，与头文件逐字一致 | `steps/05-sentences.md`、`steps/06-wording.md` |
 | 定句子 | 一句里的量被「确定、体现、界定、表达」盖住（时间义「已经确定」合格） | 改写成相等、乘除加减、上下界或成员记法；「由 A 得到 B」「将 A 转换为 B」的换算注释不在此改 | `steps/05-sentences.md`「关系写成能核对的运算」 |
 | 定段落 | 散文伪标签冒号（话题 + `：` 词条式冒号）；多核混段 | 词条式冒号改完整主谓句或真列表项；多核混段按拆核四步改写 | `steps/04-paragraphs.md`「散文伪标签冒号禁令」「拆核四步（多核混段的拆段方法）」 |

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

@@ -2,15 +2,15 @@
 
 产出：内容核对结果、一次渲染检查和 HTML 可用性报告。这一步只跑命令，不按报告改写法。
 
-内容与链接检查需要 Python 3；`dry_run: false` 的渲染还需要 Quarto CLI。缺少依赖时停住并报告，不改回手跑 `quarto render`。
+内容与链接检查需要 Python 3；`dry_run: false` 的渲染还需要 Quarto CLI。缺少依赖时停住并报告，不改回手跑 `quarto render`。跨层失败先按 `quarto/render.md`「排查顺序」定位，再回到对应步骤。
 
 ## 通用情况
 
 ### 内容与链接
 
-项目技能列了内容检查命令时，只跑它列出的命令。没有项目技能时，在书根跑本技能 `scripts/` 下的 `verifying-content.py` 与 `checking-links.py`。
+项目技能列了内容检查命令时，只跑它列出的命令。没有项目技能时，在书根跑本技能 `scripts/` 下的 `verifying-content.py`、`checking-links.py` 与 `checking-prose.py`。
 
-`verifying-content.py` 查章节表、YAML 标题、标题层级、句段长度、围栏语言、Mermaid 围栏、占位文字和本地链接。项目专属检查只在书的 `.agents/skills/quarto-book-project/` 存在时启用。
+`verifying-content.py` 查章节表、YAML 标题、标题层级、句段长度、围栏语言、Mermaid 围栏、占位文字和本地链接；`checking-prose.py` 查中文与拉丁字母、数字、行内代码之间的空格，以及中文句里的半角标点。项目专属检查只在书的 `.agents/skills/quarto-book-project/` 存在时启用。
 
 ### 渲染与 HTML
 
@@ -69,7 +69,7 @@
 
 ## 完成判据
 
-内容命令通过，`dry_run: false` 返回 `render_result.ok: true`，且 `html_report.usable: true`，并调用一次 `quarto_pass_report` 出回执，才算完成。任一条件不满足，回到报告指向的步骤。
+内容命令与混排检查通过，`dry_run: false` 返回 `render_result.ok: true`，且 `html_report.usable: true`，并调用一次 `quarto_pass_report` 出回执，才算完成。任一条件不满足，回到报告指向的步骤。
 
 ## 正反例
 

package/templates/quarto-book-project/SKILL.md

@@ -16,7 +16,9 @@ description: 记录某一本 Quarto Book 的项目级约定：书名、读者、
 - 书名：
 - 一句话定位：
 - 目标读者与前置知识：
+- 读者完成后能独立完成：
 - 本书不覆盖的内容：
+- 术语首次解释的落点（就近术语卡 / 章首术语表）：
 
 ## 章节对照