@chengzhao-dev/dsh-quarto-book 0.6.12 → 0.6.13

package/README.en.md

@@ -29,7 +29,7 @@ Both skills are discovered from the package's `skills/` directory and loaded on
 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.12`; to follow a GitHub tag, write `github:chengzhao-dev/dsh-quarto-book#v0.6.12`.
+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.13`; to follow a GitHub tag, write `github:chengzhao-dev/dsh-quarto-book#v0.6.13`.
 
 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.
 
@@ -106,6 +106,14 @@ npm run pack
 
 `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`.
 
+Replay the CI sequence locally with one command before pushing:
+
+```bash
+npm run ci
+```
+
+It runs `npm ci`, `npm test`, `npm run check:lib`, `npm run check`, and `npm run pack:check` — the same steps as `.github/workflows/ci.yml`, plus the publish-time package gate.
+
 Development install:
 
 ```bash

package/README.md

@@ -29,7 +29,7 @@
 2. 在书仓库里打开会话。`_quarto.yml` 要有独立一行的 `type: book`，书根至少有一个 `.qmd` 或 `.md` 章节源文件；两个技能名这时才会出现。
 3. 调用技能：写正文用 `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.12`，跟 GitHub 标签时写 `github:chengzhao-dev/dsh-quarto-book#v0.6.12`。
+`--profile` 换成你实际运行的那个 profile。桌面应用固定跑 `desktop` profile，且该 profile 由应用独占管理，`dsh --profile desktop` 直接启动会被拒绝；安装或升级用 `dsh plugin --profile desktop add <包>`，应用拒绝写入时再走「设置 → 插件 → 添加插件」。需要固定版本时写 `npm:@chengzhao-dev/dsh-quarto-book@0.6.13`，跟 GitHub 标签时写 `github:chengzhao-dev/dsh-quarto-book#v0.6.13`。
 
 从旧的无作用域包 `dsh-quarto-book` 升级（该包已随 0.3.4 从 npm 删除，只影响之前装过它的 profile）：先在同一个 profile 里 `dsh plugin --profile <profile> remove dsh-quarto-book`，再装新包。两个包同时留着会以相同的 rank 550 各注册一遍 `writing-quarto` 和 `designing-theme`。
 
@@ -108,6 +108,14 @@ npm run pack
 
 `npm test` 会先编译再跑工具测试；`npm run check` 做类型检查与技能路径自检；`npm run pack` 把 tarball 只写进 `temp/`，那个目录已在 `.gitignore` 里。
 
+推送前用一条命令复现 CI 的检查序列：
+
+```bash
+npm run ci
+```
+
+`npm run ci` 依次执行 `npm ci`、`npm test`、`npm run check:lib`、`npm run check` 与 `npm run pack:check`，覆盖 `.github/workflows/ci.yml` 的全部步骤，并在打包前挡住发布内容的问题。
+
 开发安装：
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chengzhao-dev/dsh-quarto-book",
-  "version": "0.6.12",
+  "version": "0.6.13",
   "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",
@@ -48,6 +48,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "npm run build && node scripts/checking-github-workflows.mjs && node --test \"tests/**/*.test.mjs\"",
+    "ci": "npm ci && npm test && npm run check:lib && npm run check && npm run pack:check",
     "check": "tsc --noEmit -p tsconfig.json && node scripts/checking-skill-links.mjs && node scripts/checking-skill-budget.mjs && node scripts/checking-package.mjs && node scripts/checking-github-workflows.mjs",
     "check:lib": "node scripts/checking-lib.mjs",
     "check:workflows": "node scripts/checking-github-workflows.mjs",

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

@@ -570,13 +570,29 @@ html[data-palette="solarized"] .navbar-brand::before {
     width: 6rem;
   }
 
+  /* 只剩书标：书标放到 1.375rem 补回丢掉标题后的视觉重量，并撤掉桌面端那条
+     0.2rem 抬升——它原本用来对齐汉字基线，没有标题时反而把图标顶高。 */
+  .navbar-brand {
+    position: relative;
+  }
   .navbar-brand::before {
-    width: 1.25rem;
-    height: 1.25rem;
+    width: 1.375rem;
+    height: 1.375rem;
+    margin-bottom: 0;
   }
 
+  /* 书名改成视觉隐藏而不是 display:none：这枚链接仍是「回到首页」，
+     屏幕阅读器要能读出书名，否则书标就是一个没有名字的链接。 */
   .navbar-title {
-    display: none;
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    margin: -1px;
+    padding: 0;
+    border: 0;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
   }
 }
 /* 主题切换：可点区域 44px，图标仍是 16px */
@@ -689,6 +705,11 @@ nav.quarto-secondary-nav .container-fluid.d-flex {
 nav.quarto-secondary-nav .quarto-search-button {
   display: none;
 }
+/* 首页与部首页在次级导航里只有一项（书名或部名），紧挨顶栏品牌又说一遍；
+   它也说不出“书内位置”，故只留侧栏开关，让次级导航只承担章节轨迹。 */
+nav.quarto-secondary-nav .quarto-page-breadcrumbs ol.breadcrumb:has(> li:only-child) {
+  display: none;
+}
 /* 宽屏只隐藏次级导航里的面包屑（仅留汉堡）；标题块面包屑桌面端显示、与标题同栏左对齐，
    窄屏由 Quarto 生成的 d-none 自动隐藏（改显次级导航实例） */
 @media (min-width: 992px) {

package/skills/designing-theme/references/theme-system.md

@@ -86,7 +86,7 @@
 - **任务列表**：`input[type=checkbox]` 用 `accent-color: var(--action-color)`，不用系统蓝。
 - **图片**：正文图与坐标图圆角一律 `--radius-sm`（3px），不用 6px 大圆角；图注选择器同时覆盖 `figure figcaption`、`.quarto-float-caption`、`.figure-caption`（`lang: zh` 后 Quarto 生成「图 3.1: …」，`lang` 必须写在 `_quarto.yml`，否则图/表题回落英文 Figure/Table）。
 - **图片灯箱**：`format.html.lightbox` 打开后 GLightbox 默认 0.7 黑遮罩，页面图注会从图后透出；主题把遮罩加深到 0.86、关闭/翻页按钮做成 32% 黑的圆钮白描边。透明底 SVG 必须垫白卡（`img[src$=".svg"]`），否则深色遮罩上会整幅消失；位图不加白边。
-- **顶栏品牌标**：`palettes/<name>/brand-mark.svg` 作 `mask`、以 `--navbar-fg` 上色；外形是同一枚「打开的书」，16px 仍可辨。标签页用同目录 `favicon-light.svg` / `favicon-dark.svg`，`book.favicon` 指 Flexoki light，其余五份随 `resources` 发布，`palette.html` 按色板与明暗换 href。图标高 1.25rem、与标题间距 0.5rem，`margin-bottom: 0.2rem` 对齐汉字基线；窄屏先压搜索再省标题。
+- **顶栏品牌标**：`palettes/<name>/brand-mark.svg` 作 `mask`、以 `--navbar-fg` 上色；外形是同一枚「打开的书」，16px 仍可辨。标签页用同目录 `favicon-light.svg` / `favicon-dark.svg`，`book.favicon` 指 Flexoki light，其余五份随 `resources` 发布，`palette.html` 按色板与明暗换 href。图标高 1.25rem、与标题间距 0.5rem，`margin-bottom: 0.2rem` 对齐汉字基线；窄屏先压搜索再省标题：`≤420px` 只留书标，图标长到 1.375rem 并撤掉那条抬升，书名改成视觉隐藏（`clip-path: inset(50%)`）而不是 `display:none`——这枚链接仍是「回到首页」，读屏必须能读出书名。次级导航的面包屑在首页与部首页只有一项（书名或部名），紧挨品牌重复一遍，用 `:has(> li:only-child)` 整条收起，只留侧栏开关；两项以上的章节轨迹才显示。
 - **顶栏搜索**：Quarto 的 Algolia detached button 自带 `svg.aa-SubmitIcon`，主题不再给 `#quarto-search` 画伪元素放大镜；按钮 32×32、图标 18px、用 `--navbar-muted` 上色，hover 用 `--navbar-hover-bg`。浮层容器、表单和输入框都用纸面/正文令牌，输入框需用与 Quarto 同等长的选择器（`.aa-DetachedContainer .aa-DetachedFormContainer .aa-Form .aa-InputWrapper .aa-Input`）压过编译期暗色值；占位文字用 `--text-secondary`，取消按钮 `white-space: nowrap`，结果选中项用 `--surface-raised`。`≤575.98px` 时浮层收成贴顶通栏，左右无圆角，避免 Quarto 的桌面 `top:100px` 把搜索条压在正文中部。
 - **色板切换**：`.palette-picker` 是 select-only combobox——按钮 `role="combobox"` + `aria-haspopup="listbox"`，面板 `.palette-menu-list` 为 `role="listbox"`，选项 `role="option"`；焦点留在按钮上，用 `aria-activedescendant` 指当前项。闭合态是 2rem 高胶囊：色点 + 英文名（Flexoki / Solarized / Hill Light）+ 方向箭头；展开后三行「色点 + 名称」，当前项右侧打勾。键位照 APG：↑/↓/Home/End 移动、首字母跳转、Enter 或 Space 提交、Esc 无提交关闭、Tab 关闭并走开。名称用英文，与 `book-palette` 的取值和色板目录同名，不另起中文译名。选择仍写 `book-palette`，首屏恢复逻辑不变，样式在 `css/nav.css`。不用原生 `<select>`（暗色下会保持系统浅色下拉）。
 - **明暗圆钮**：Quarto 自带的是 16px「开关」位图（`bi-toggle-off/on` 的 data-URI `background-image`，填充色写死在 SVG 里），紧挨色板胶囊时两枚圆角疙瘩容易看混。主题把 `::before` 改成只做 `mask`、颜色吃 `currentColor` 的对比圆盘（描边 1.2、半径 6.2，实心半圆让到描边内缘），`.alternate`（夜间）旋转 180°，实心半圆换边；可点区域 44px、图标 16px。

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

@@ -518,6 +518,37 @@ def browser_layout(book_dir, verbose):
                         f"{label}: 次级导航底边 "
                         f"{header_rule['secondaryBorderBottomWidth']}px，会和顶栏底边叠成双线"
                     )
+            # 品牌区：窄屏（≤420）只留书标，链接不能因此变成无名链接——
+            # 书名必须留在可访问树里（视觉隐藏即可），图标补回一点尺寸。
+            brand = data.get("navBrand") or {}
+            if brand:
+                if not brand.get("label"):
+                    problems.append(
+                        f"{label}: 顶栏品牌链接没有可读名称，屏幕阅读器读不出书名"
+                    )
+                if brand.get("titleDisplay") == "none":
+                    problems.append(
+                        f"{label}: 书名被 display:none 摘出可访问树，窄屏书标成了无名链接"
+                    )
+                expected_icon = 22 if width <= 420 else 20
+                if abs(brand.get("iconWidth", 0) - expected_icon) > 0.6:
+                    problems.append(
+                        f"{label}: 书标 {brand.get('iconWidth')}px，"
+                        f"应为 {expected_icon}px"
+                    )
+            # 次级导航只有一项面包屑（首页/部首页的书名）时应整条收起：
+            # 它紧挨顶栏品牌重复一遍，也说不出「书内位置」。
+            crumb = data.get("secondaryBreadcrumb") or {}
+            if (
+                crumb
+                and crumb.get("navDisplay") != "none"
+                and crumb.get("listDisplay") != "none"
+                and crumb.get("items", 0) < 2
+            ):
+                problems.append(
+                    f"{label}: 次级导航只有 {crumb.get('items', 0)} 项面包屑"
+                    "（与顶栏书名重复），应整条隐藏"
+                )
             h2_after = data.get("h2Rules") or []
             if h2_after:
                 first = h2_after[0]

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

@@ -151,7 +151,9 @@ async function collect(page, pageId, scheme) {
       }
       for (const element of scope.querySelectorAll("*")) {
         if (
-          element.closest(".screen-reader-only, .sr-only, [aria-hidden='true']")
+          // `.visually-hidden` 是 Bootstrap 的屏幕阅读器工具类（clip-path 藏在 1px 盒子里），
+          // 与下面 `svg` 同理：它本来就要超出自身 1px 盒宽，不能当版式溢出上报。
+          element.closest(".screen-reader-only, .sr-only, .visually-hidden, [aria-hidden='true']")
           // 内联 SVG（棋盘快照等）没有 CSS 盒模型，<text> 的 clientWidth 恒为 0、
           // scrollWidth 按字形量出，天然「溢出」，不能当版式问题。
           || element.closest("svg")
@@ -232,6 +234,35 @@ async function collect(page, pageId, scheme) {
           };
         })
       : null;
+    // 品牌区：窄屏收起书名只留书标时，链接仍要有可读名称（屏幕阅读器读不到书名
+    // 就等于失去「回到首页」的语义），所以书名只能视觉隐藏、不能 display:none。
+    // 书标随书名一起收掉后需要补一点视觉重量，图标尺寸由断点决定。
+    const brand = document.querySelector(".navbar-brand");
+    const brandTitle = brand ? brand.querySelector(".navbar-title") : null;
+    const navBrand = brand
+      ? {
+          label: (
+            brand.getAttribute("aria-label")
+            || (brandTitle ? brandTitle.textContent : "")
+            || ""
+          ).trim(),
+          titleDisplay: brandTitle ? style(brandTitle).display : null,
+          width: Math.round(brand.getBoundingClientRect().width),
+          iconWidth: px(getComputedStyle(brand, "::before").width),
+        }
+      : null;
+    // 次级导航的面包屑在首页与部首页只有一项（书名或部名），紧挨顶栏品牌重复一遍，
+    // 也说不出「书内位置」，应整条收起；两项及以上（章节页）才显示。
+    const crumbList = document.querySelector(
+      "nav.quarto-secondary-nav .quarto-page-breadcrumbs ol.breadcrumb"
+    );
+    const secondaryBreadcrumb = crumbList
+      ? {
+          items: crumbList.querySelectorAll(":scope > li").length,
+          listDisplay: style(crumbList).display,
+          navDisplay: style(crumbList.closest(".quarto-page-breadcrumbs")).display,
+        }
+      : null;
     const rootStyle = style(root);
     return {
       pageId,
@@ -259,6 +290,8 @@ async function collect(page, pageId, scheme) {
       copyButtonOpacities,
       sidebarOverlay,
       sidebarSections,
+      navBrand,
+      secondaryBreadcrumb,
       headerRule,
       h2Rules,
       contentWidth: px(rootStyle.width),

package/skills/writing-quarto/SKILL.md

@@ -33,7 +33,7 @@ metadata:
 
 ## 两种走法
 
-增量任务只走与改动对应的步骤，只改判为不合格的地方，其余保持原样；九步同走只用于新章、新阶段或用户明确要求全章重构。全章重构仍是这九步，但第 1–2 步先定删留、不动句子，第 3–4 步只拆块和段，第 5–7 步才逐句改。
+增量任务只走对应步骤，只改判为不合格的地方；全章重构仍走九步，但第 1–2 步先定删留、不动句子，第 3–4 步只拆块和段，第 5–7 步才逐句改。
 
 两条走法共守同一组不变量，写在这里，不重复进各步：不新增原文没有的事实、数字、命令、性能结论、引文和出处；不把「可能」「通常」「在本书里」这类留有余地的说法改成确定说法；保留否定、条件、范围、时间和归属；围栏里的代码、命令、路径、URL 与 YAML 不改。增量润色只删除和换词，不扩写、不补论证；全章重构可删可换序，但不能发明事实，也不能把限定说成确定。
 
@@ -45,7 +45,7 @@ metadata:
 
 1. 定任务：写出读者做完能完成的那件事，再列这一章要覆盖的任务。规则在 `steps/01-task.md`。
 2. 定结构：排页面骨架、二级标题和篇幅预算，只定删留、标题与章题对齐。规则在 `steps/02-structure.md`。
-3. 排列内容块：导语、围栏、收束与 Callout 的次序，一个围栏只放正在讲的那一块。规则在 `steps/03-blocks.md`，表格写法见 `quarto/tables.md`。
+3. 排列内容块：导语、围栏、收束与 Callout 的次序，一个围栏只放正在讲的那一块。规则在 `steps/03-blocks.md`，表格写法见 `quarto/tables.md`；围栏给声明还是给定义，按 `references/fence-semantics.md` 判。
    图注写在图下、图前只写引出关系；三类图的统一写法见 `quarto/figures.md`。
 4. 定段落：一段一个关键，下一句接住上一句的新信息；段间衔接落在话题切换处。规则在 `steps/04-paragraphs.md`。
 5. 定句子：主语选执行者，对象先行，一句一动作。规则在 `steps/05-sentences.md`。

package/skills/writing-quarto/references/fence-semantics.md

@@ -0,0 +1,68 @@
+# 围栏与正文的配对
+
+本文件只回答一个问题：代码围栏里给读者看的是声明还是定义，正文就只讲哪种话。
+
+## 两种素材，两种话
+
+| 素材 | 围栏里是什么 | 正文可以讲什么 |
+| --- | --- | --- |
+| 声明围栏 | `.h` 里的签名、成员、类定义 | 契约：参数、返回值、异常、边界、副作用、与其它接口的分工 |
+| 定义围栏 | `.cpp`（或头文件里的函数体）里的实现 | 机制：用了哪个函数、什么表达式、是否复制、扫描顺序、为什么这样写 |
+
+判据只有一句：**删掉定义文件，这句话还成立吗？** 成立是契约，不成立是实现。
+
+## 三种合法配对
+
+| 配对 | 围栏 | 正文 | 用在 |
+| --- | --- | --- | --- |
+| 契约型 | 声明 | 契约文字 | 定义平凡：单行 `return`、一跳转发、两行赋值 |
+| 机制型 | 声明 + 定义 | 实现文字 | 定义非平凡，需要讲分支、算法或取舍 |
+| 纯定义型 | 定义 | 实现文字 | 定义就在头文件（`constexpr`、模板），或声明已在本章前文出现过 |
+
+补充一条**组合转发例外**：同一小节里几个一跳转发的定义可以合并成一个短围栏，正文讲它们如何组合；合并后仍遵守「正文只讲围栏里看得到的代码」。
+
+## 不允许的写法
+
+1. 声明围栏 + 实现文字（本节讲机制，读者手上却只有接口）。
+2. 声明围栏 + 「完整实现见源文件」这类指路句：读者在书里看不到，等于没给。
+3. 正文出现围栏里不存在的函数名或表达式（正文讲 `GetWinner`，围栏只有 `IsWin` 的声明）。
+4. 声明与定义之间隔了整段机制解释，读者翻到围栏时讲解已经结束。
+5. 定义不平凡却只写契约，再在「常见错误」或 Callout 里补一段机制。
+
+## 平凡定义的判定
+
+- 平凡：单次比较、单个 `return`、两行赋值、纯委托（`return Other();`）、只做一次边界检查后返回。
+- 不平凡：含循环或分支组合、更新状态、与别的类型协作、需要解释「为什么不用另一种写法」。
+
+平凡判例：`IsInRange` 的 `return row >= 0 && row < kRows && col >= 0 && col < kCols;`、`IsWin` 的 `return GetWinner().has_value();`。
+
+## 正反例（棋盘章的真实片段）
+
+改前——声明围栏，正文讲定义：
+
+```markdown
+```{.cpp filename="board.h"}
+  /// @return 是否有任意一枚棋子连成一条线。
+  [[nodiscard]] bool IsWin() const;
+```
+
+`IsWin` 复用 `GetWinner` 的三连判定，不再单独扫描棋盘。
+```
+
+改后——组合围栏，正文对着代码讲组合：
+
+```markdown
+```{.cpp filename="board.cpp"}
+bool Board::IsGameOver() const { return IsWin() || IsDraw(); }
+bool Board::IsWin() const { return GetWinner().has_value(); }
+bool Board::IsDraw() const { return IsFull() && !IsWin(); }
+```
+
+`IsGameOver` 把两个判断用 `||` 连起来；`IsWin` 与 `IsDraw` 各自只回答一个问题，真正的扫描都在别处。
+```
+
+## 与其它规则的关系
+
+- **代码块门槛**（`steps/03-blocks.md`）：平凡实现不出围栏；本文件给的是「已经决定要讲」时该怎么配围栏。
+- **正文与注释分工**：契约与边界写进 `///`，正文不转述；实现文字只补围栏里没有的上下文（为什么这样组合、和谁配合）。
+- **检查器**：`scripts/verifying-content.py` 按 `###` 小节扫描，只有 `.h` 围栏而正文出现实现词时报 `decl-without-def`；「常见错误」「自测问题」「本章回顾」与表格行豁免。

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

@@ -30,6 +30,10 @@ EXCLUDE_DIRS = {
     "dist", "_freeze", "temp", "__pycache__", ".venv", "venv",
 }
 EXCLUDE_DIR_SUFFIXES = ("_files",)
+# 构建目录的变体：build-debug / build-release / _build 都是输出目录，
+# 里面是 CMake 自己生成的文件名（CompilerIdCXX.cpp、cmake_install.cmake），
+# 不该参与命名检查，否则每次构建后都报一堆假阳性。
+EXCLUDE_DIR_PREFIXES = ("build-", "_build")
 
 TOOL_FIXED_NAMES = {
     "CMakeLists.txt", "_quarto.yml", "_quarto.yaml", "SKILL.md", "AGENTS.md",
@@ -49,6 +53,13 @@ def first_non_ascii(name: str) -> str | None:
 def name_form_error(name: str) -> str | None:
     if name in TOOL_FIXED_NAMES:
         return None
+    # CMake 模块名按社区习惯写 CamelCase（CompileSettings.cmake），由
+    # include() / find_package() 按名查找，改名会直接断掉构建，故与
+    # CMakeLists.txt 同类放行；只看大小写规则，不放过下划线或空格。
+    if name.endswith(".cmake"):
+        if "_" in name or " " in name:
+            return "含下划线" if "_" in name else "含空格"
+        return None
     if any(a.islower() and b.isupper() for a, b in zip(name, name[1:])):
         return "含驼峰"
     if "_" in name:
@@ -86,6 +97,7 @@ def main() -> int:
 
     print(f"扫描：{repo_root}")
     print(f"排除目录：{', '.join(sorted(EXCLUDE_DIRS))}")
+    print(f"排除目录前缀：{', '.join(EXCLUDE_DIR_PREFIXES)}")
     print()
 
     bad: list[tuple[str, str]] = []
@@ -93,7 +105,9 @@ def main() -> int:
     for dirpath, dirnames, filenames in os.walk(repo_root):
         dirnames[:] = [
             d for d in dirnames
-            if d not in EXCLUDE_DIRS and not d.endswith(EXCLUDE_DIR_SUFFIXES)
+            if d not in EXCLUDE_DIRS
+            and not d.endswith(EXCLUDE_DIR_SUFFIXES)
+            and not d.startswith(EXCLUDE_DIR_PREFIXES)
         ]
         for name in dirnames + filenames:
             count += 1

package/skills/writing-quarto/scripts/verifying-content.py

@@ -68,6 +68,14 @@ FUNCTION_NAME_RE = re.compile(
 TERMINAL_RE = re.compile(r"终端|打印|显示|输入|读入|命令行")
 TEST_RE = re.compile(r"测试|断言|用例|gtest|CTest")
 
+# 围栏与正文的配对：声明围栏只配契约文字。正文出现实现词而小节里没有定义围栏时
+# 报 decl-without-def，规则与正反例见 references/fence-semantics.md。
+FENCE_FILENAME_RE = re.compile(r'filename="([^"]+)"')
+IMPL_MARKER_RE = re.compile(r"复用|委托给|扫描|遍历|对每个|短路|表达式|状态位|缓存|不再单独|递归")
+FENCE_SKIP_SECTION_RE = re.compile(r"常见错误|自测|回顾|练习|小结")
+DECL_SUFFIXES = (".h", ".hpp", ".hh", ".hxx")
+DEF_SUFFIXES = (".cpp", ".cc", ".cxx", ".inl")
+
 TREE_CATEGORY_COMMENTS = frozenset({
     "头文件", "源文件", "源码", "实现", "测试", "配置文件",
     "构建脚本", "构建规则", "动态库", "可执行文件",
@@ -175,12 +183,24 @@ def parse_chapters(quarto_yml: Path) -> list[str]:
     return chapters
 
 
+EXCLUDED_DIRS = {
+    "node_modules", "_book", ".quarto", ".git", "_freeze", "_site",
+    "temp", "build", "dist", "_build",
+}
+EXCLUDED_DIR_PREFIXES = ("build-",)
+
+
+def is_generated_dir(part: str) -> bool:
+    # 生成物与缓存目录整棵跳过：临时试验稿、构建产物里的 .qmd 不属于书稿源，
+    # 整仓扫描时报出它们的问题会让作者去改根本没有交付的文件。
+    return part in EXCLUDED_DIRS or part.startswith(".") or part.startswith(EXCLUDED_DIR_PREFIXES)
+
+
 def collect_all_qmd(root: Path) -> list[Path]:
-    excluded = {"node_modules", "_book", ".quarto", ".git", "_freeze", "_site"}
     found: list[Path] = []
     for candidate in sorted(root.rglob("*.qmd")):
         rel_parts = candidate.relative_to(root).parts
-        if any(part in excluded or part.startswith(".") for part in rel_parts):
+        if any(is_generated_dir(part) for part in rel_parts):
             continue
         found.append(candidate)
     return found
@@ -546,6 +566,72 @@ def check_lead(
         ))
 
 
+def check_fence_semantics(path: Path, lines: list[str]) -> list[Issue]:
+    """声明围栏只能配契约文字：小节内没有定义围栏却讲实现时报错。"""
+    issues: list[Issue] = []
+    section_title: str | None = None
+    section_line = 0
+    fences: list[str] = []
+    prose: list[str] = []
+    in_fence = False
+    in_section = False
+
+    def flush() -> None:
+        nonlocal fences, prose
+        if section_title is None:
+            return
+        if not FENCE_SKIP_SECTION_RE.search(section_title):
+            has_decl = any(name.endswith(DECL_SUFFIXES) for name in fences if name)
+            has_def = any(name.endswith(DEF_SUFFIXES) for name in fences if name)
+            if has_decl and not has_def and prose:
+                text = " ".join(prose)
+                marker = IMPL_MARKER_RE.search(text)
+                if marker:
+                    issues.append(Issue(
+                        path, section_line,
+                        f"小节「{section_title}」只有声明围栏，正文却讲实现（{marker.group(0)}）；"
+                        "按 references/fence-semantics.md 改成契约文字，或补定义围栏",
+                    ))
+        fences = []
+        prose = []
+
+    section_title = None
+    fences = []
+    prose = []
+    in_fence = False
+    in_section = False
+    for number, raw in enumerate(lines, start=1):
+        if FENCE_RE.match(raw):
+            if not in_fence:
+                match = FENCE_FILENAME_RE.search(raw)
+                fences.append(match.group(1) if match else "")
+            in_fence = not in_fence
+            continue
+        if in_fence:
+            continue
+        heading = HEADING_RE.match(raw)
+        if heading:
+            level = len(heading.group(1))
+            if level in (2, 3):
+                flush()
+                section_title = heading.group(2)
+                section_line = number
+                in_section = True
+            elif level == 1:
+                flush()
+                section_title = None
+                in_section = False
+            continue
+        if not in_section or not raw.strip():
+            continue
+        stripped = raw.strip()
+        if stripped.startswith(("|", ">", ":::", "-", "*", "+")) or re.match(r"^\d+\.\s", stripped):
+            continue
+        prose.append(stripped)
+    flush()
+    return issues
+
+
 def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> list[Issue]:
     issues: list[Issue] = []
     text = read_text(path)
@@ -672,6 +758,8 @@ def check_file(path: Path, root: Path, project: dict, chapters: list[str]) -> li
     if in_fence:
         issues.append(Issue(path, fence_start, "代码围栏未闭合"))
 
+    issues.extend(check_fence_semantics(path, lines))
+
     for block in fence_blocks:
         issues.extend(check_tree_block(path, block))
 

package/skills/writing-quarto/steps/03-blocks.md

@@ -74,6 +74,10 @@ int main() {
 - 仅为证明「源码有此函数」而贴出的实现。
 - 打断小节中心的硬插块。
 
+### 声明围栏与定义围栏
+
+围栏里是声明，正文就只能讲契约；正文要讲实现（复用哪个函数、怎么组合、扫不扫描），围栏里必须给出对应的定义。三种合法配对、平凡定义的判定与正反例见 `references/fence-semantics.md`；`verifying-content.py` 对「只有 `.h` 围栏却讲实现」的小节报 `decl-without-def`。
+
 ### 类与多函数摘录的垂直空白
 
 摘录 `class` 或多函数片段时**保留**源码中函数之间的空行，禁止为省行数坍缩成函数注释贴着下一声明；省略部分成员时，被保留的相邻函数之间仍空 1 行；同一 access 段内最后一组数据成员与函数之间空 1 行，数据成员组内不空行。与「逐字摘录」冲突时以源码空白为准：教学缩略可删成员，不可删「函数间距」惯例。

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

@@ -21,6 +21,7 @@
 | 定段落 | 一段内两个独立中心 | 按「拆核四步」拆段或改列表 | `steps/04-paragraphs.md`「拆核四步（多核混段的拆段方法）」、`examples/04-paragraph-cases.md`「自然段多中心未拆」 |
 | 定结构 | 章引言顿号串 ≥3 个交付物 | 下沉为列表或正文 `##` | `steps/02-structure.md`「六段块序列」、`examples/02-structure-shape.md`「目录式堆砌」 |
 | 排列内容块 | 过简实现围栏（单次比较或直接 `return`） | 删围栏，改入口列表 + 失败策略列表 | `steps/03-blocks.md` |
+| 排列内容块 | 声明围栏 + 实现文字（正文讲复用、委托、扫描，围栏只有 `.h`） | 按 `references/fence-semantics.md` 三选一：改契约文字、补组合或定义围栏、删实现句 | `steps/03-blocks.md`「声明围栏与定义围栏」、`references/fence-semantics.md` |
 | 排列内容块 | 块间闭环缺失（标题下无引导、段→列表无 lead-in、代码→图只有空行、表前无关系句、Callout 复述块内） | 按块链检查清单补桥接 | `steps/03-blocks.md`「块链检查清单」、`steps/03-blocks.md` |
 | 排列内容块 | 节末旁注裸句（`##` 最后一块是一句可跳过的补充，前面是列表、表格或围栏） | 改写为独立可读的 Callout 收尾，正文删同句；超过两句改小节 | `steps/03-blocks.md`「节末旁注与 Callout 收尾」、`examples/03-qmd-elements.md`「节末旁注改为 Callout 收尾」 |
 | 定段落 | 段内同义堆叠（两句换说法讲同一机制） | 删辅句或合并；公式递进与简洁边界豁免 | `steps/04-paragraphs.md`「段内同义堆叠禁令」 |