@chengzhao-dev/dsh-quarto-book 0.6.15 → 0.6.17

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.15`; to follow a GitHub tag, write `github:chengzhao-dev/dsh-quarto-book#v0.6.15`.
+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.17`; to follow a GitHub tag, write `github:chengzhao-dev/dsh-quarto-book#v0.6.17`.
 
 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.
 

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.15`，跟 GitHub 标签时写 `github:chengzhao-dev/dsh-quarto-book#v0.6.15`。
+`--profile` 换成你实际运行的那个 profile。桌面应用固定跑 `desktop` profile，且该 profile 由应用独占管理，`dsh --profile desktop` 直接启动会被拒绝；安装或升级用 `dsh plugin --profile desktop add <包>`，应用拒绝写入时再走「设置 → 插件 → 添加插件」。需要固定版本时写 `npm:@chengzhao-dev/dsh-quarto-book@0.6.17`，跟 GitHub 标签时写 `github:chengzhao-dev/dsh-quarto-book#v0.6.17`。
 
 从旧的无作用域包 `dsh-quarto-book` 升级（该包已随 0.3.4 从 npm 删除，只影响之前装过它的 profile）：先在同一个 profile 里 `dsh plugin --profile <profile> remove dsh-quarto-book`，再装新包。两个包同时留着会以相同的 rank 550 各注册一遍 `writing-quarto` 和 `designing-theme`。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chengzhao-dev/dsh-quarto-book",
-  "version": "0.6.15",
+  "version": "0.6.17",
   "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",

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

@@ -63,6 +63,10 @@ README 遵循 GitHub Markdown。根目录 `README.md` 是在线阅读链接的
 - 图片提供 Alt 文本和说明。图表标注坐标轴与单位。
 - 仓库文件使用可跳转链接。短技术标识使用行内代码。
 
+### 代码注解
+
+Quarto 原生逐行注解：代码行尾写 `# <1>`，紧接一个有序列表解释该行；`code-annotations` 取 `below`（默认）、`hover` 或 `select`，`none` 去掉编号、`false` 关闭处理。本书默认不用注解，逐行解释写在代码块后的正文里；只有读者需要按行对照、且任务明确要求时才启用，启用后块后正文不再重复注解列表的内容。
+
 ### 代码与图的桥接
 
 代码块引出图（`{mermaid}` 流程图或 `{python}` 坐标图）时按固定序列组织，图是可选中段，不能替代结论句：
@@ -99,6 +103,8 @@ README 遵循 GitHub Markdown。根目录 `README.md` 是在线阅读链接的
 
 参数解释默认使用短无序列表。Callout 不承载必经命令或构建命令，也不把唯一成功判据写成脱离正文的脚注。
 
+可折叠与轻量外观只在读者可能跳过时使用：`collapse="true"` 默认收起、`collapse="false"` 默认展开但仍可折叠；`appearance="simple|minimal"` 去掉彩色标题或图标，`icon="false"` 只关当前块图标，项目级开关是 YAML 的 `callout-appearance` 与 `callout-icon`。需要按编号引用时给块加 `#nte-`/`#wrn-`/`#tip-`/`#imp-`/`#cau-` 标签，正文写 `@nte-...`；不加标签的 Callout 不参与编号。语法与前缀表见 `quarto/crossrefs.md`。
+
 ### Callout 升级判据
 
 何时升级为 Callout、何时留行内括号，只会遇到两种情形：
@@ -127,6 +133,6 @@ Callout 个数见 `steps/02-structure.md`，本段不写数字；`warning` 只
 
 ### 交叉引用
 
-交叉引用使用真实标题生成的锚点，引用前确认目标页面存在。本项目不手写英文 `{#id}`，标题锚点由中文标题派生；跨章节引用用章节标题链接，不用「第 N 章」。
+图、表、公式或 Callout 需要按编号引用时，标签写法、前缀与书内编号规则见 `quarto/crossrefs.md`。本项目是纯 HTML 中文书，`number-sections: false`，章节标题不写 `{#sec-...}`；跨章节引用用章节标题链接，不写「第 N 章」。引用前确认目标页面存在，改标题后按「重构与事实核对」重新核对。
 
 需要渲染与链接依据时，读 `quarto/render.md` 与 `quarto/mermaid.md`；图注、原生 SVG 与图前句的分工读 `quarto/figures.md`。

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

@@ -117,7 +117,7 @@ title: "章节标题"
 - **标题层级**：`##` 表示阅读阶段、范围或一个可验收任务，`###` 表示该阶段中可独立完成或观察的子任务。正文最多到 `###`，禁止 `####` 及更深标题。
 - `###` 只用于源码阅读、验证、可选分支、排错症状等拥有独立动作或观察结果的内容。只有一两句话的解释并入相邻段落，不为目录对称强行拆分。
 - 根首页、part 落地页的卡片标题可以保留 `###`，那是导航组件的视觉层级，不改变正文最多三级的约束。
-- 归并或改名标题前先检索 `@sec-` 与 `#anchor`，避免破坏交叉引用。标题字数与形式见 `steps/02-structure.md`「标题分层」与「形式规则」，章题与正文的对齐见同文件「纵向承诺链」第 9 条。
+- 归并或改名标题前先检索 `@sec-` 与 `#anchor`，避免破坏交叉引用；标签前缀、书内编号与不编号章的限制见 `quarto/crossrefs.md`。标题字数与形式见 `steps/02-structure.md`「标题分层」与「形式规则」，章题与正文的对齐见同文件「纵向承诺链」第 9 条。
 
 ## 输出结构
 

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

@@ -0,0 +1,34 @@
+# 交叉引用
+
+本文件是 Quarto 交叉引用语法的唯一出处：标签怎么写、正文怎么引、书里编号从哪来。什么时候值得引用、引用读起来是否自然，仍归 `steps/` 与 `quarto/prose.md`。
+
+## 标签与引用
+
+| 对象 | 标签写法 | 正文引用 | 渲染示例 |
+| --- | --- | --- | --- |
+| 章或节 | `## 标题 {#sec-name}` | `@sec-name` | 第 3 章、3.2 节 |
+| 图 | 围栏内 `#| label: fig-name`，或图片 `![说明](path){#fig-name}` | `@fig-name` | 图 3.1 |
+| 表 | 表题 `: 说明 {#tbl-name}` | `@tbl-name` | 表 3.1 |
+| 公式 | `$$ ... $$ {#eq-name}` | `@eq-name` | 式 3.1 |
+| Callout | `::: {.callout-note #nte-name}` | `@nte-name` | 提示 3.1 |
+
+前缀决定对象类别：`sec-`、`fig-`、`tbl-`、`eq-`、`lst-` 是常用五类；定理类用 `thm-`、`lem-`、`cor-`、`prp-`、`cnj-`、`def-`、`exm-`、`exr-`、`sol-`、`rem-`；Callout 用 `nte-`、`wrn-`、`imp-`、`tip-`、`cau-`。前缀写错时 Quarto 不把它当可引用对象，正文只会留下字面 `@...`。
+
+标签在同一本书里必须唯一。改名标题等于改锚点，改完要重新核对所有 `@sec-` 与页内链接。
+
+## 书里的编号
+
+- 图和表在书里自动带章号（第 3 章的第二张图渲染为「图 3.2」），前提是所在章参与编号。
+- `.unnumbered` 章不产生章号；整本关闭编号（`number-sections: false`）时也没有章号。两种情况下章内的图、表都无法按章号交叉引用，这类章只放前言、参考文献，或改用普通链接。
+- `number-depth` 控制编号到第几级标题，`toc-depth` 独立控制目录展开深度。两者都是 **format 级选项**：放在 `_quarto.yml` 顶层或 `format: html` 下，不能放进 `book:`。
+- 标题里的编号由 Quarto 生成，不手填；手填序号在增删小节后会与交叉引用和目录一起错位。
+
+## 引用形式
+
+- `@sec-x` 按标题级别渲染成「第 N 章」或「N.M 节」；`[-@sec-x]` 只留编号；`[Chapter @sec-x]` 可换自定义前缀。
+- 纯 HTML 书可以用普通链接 `[说明](file.qmd)` 或 `[说明](file.qmd#anchor)`；要出 PDF、Word 或打印稿时必须用 `@` 引用，读者才能看到编号而不是不可点的链接。
+- 引用前确认目标存在；引用句要能独立读懂，不写「见上文」「如下图所示」。
+
+## 本项目的取舍
+
+`cpp-board-games` 是纯 HTML 中文书，章节标题不写 `{#sec-...}`，跨章引用用章节标题链接。图、表确实需要编号引用时才写英文标签 `{#fig-...}`、`{#tbl-...}`，正文用 `@fig-...`、`@tbl-...`；其余场合不为了「可能要用」预先加标签。这条是项目级选择，不改变上面的通用语法。

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

@@ -11,7 +11,7 @@
 
 ## 图注写法
 
-图注是一句完整的读者句，至少包含“这张图画的是什么”和“读图要看的那条关系”。不手写“图 1：”，Quarto 按 `lang: zh` 自动编号。
+图注是一句完整的读者句，至少包含“这张图画的是什么”和“读图要看的那条关系”。不手写“图 1：”，Quarto 按 `lang: zh` 自动编号。需要正文按编号引用时，给图加英文标签（围栏 `#| label: fig-...`、图片 `{#fig-...}`、Mermaid `label: fig-...`），语法见 `quarto/crossrefs.md`；不引用就不加标签。
 
 - 不佳：下图标出这块棋盘上可用的 `(row, col)`。
 - 改写（图下）：`棋盘坐标图：3 行 3 列，每格标出 (row, col)；行向下、列向右，左上角是 (0, 0)。`

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

@@ -79,7 +79,7 @@
 - 少用「被」和长「的」链；一句一个动作，主语尽量是领域对象，不用「我们」代替读者。
 - 不写「本文将介绍」「下面我们来看」；直接给读者要做的动作和看得见的结果。
 - 同一事实只留一处：标题、段首、块后不互相复述。
-- 交叉引用写章节标题或链接，不写「上图」「下表」；读者可能先读正文再回看图表，方位词会失效。
+- 交叉引用写章节标题、链接或编号，不写「上图」「下表」；读者可能先读正文再回看图表，方位词会失效。编号引用与标签写法见 `quarto/crossrefs.md`。
 - 英文术语不堆叠；能用中文说清就不夹英文，必须夹时首次给原文。
 
 ## 让句子有信息量

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

@@ -17,12 +17,14 @@
 | `filters` | `filters/answering-disclosure.lua`（顶层 `filters:`，书内副本） | 将正文 `.answer` 转为默认收起的原生 `details` |
 | `toc` / `toc-depth` / `toc-location` | `true` / `3` / `right` | 右侧目录最多到 H3，窄屏会折叠，不作唯一定位手段 |
 | `number-sections` | `false` | 因此标题不手填序号，见 `quarto/basics.md` |
-| `code-copy` / `code-overflow` | `true` / `wrap` | 长行换行，不让读者横向拖动 |
+| `code-copy` / `code-overflow` | `true` / `scroll` | 超长行在代码块内横向滚动，不撑破正文列；`wrap` 会注入 `pre-wrap` 盖掉 `theme/css/code.css` 的 `white-space: pre`，打印时才由样式恢复折行 |
 | `grid` | sidebar 300 / body 872 / margin 272 / gutter 1rem | 正文列 840px，约 50 个汉字；四值是最大基准值，窄视口由 Quarto 响应缩放 |
 | `lang` | `zh` | 影响部分 HTML 行为与提示框默认词 |
 
 本书**不开启**代码行号（`code-line-numbers`）与代码折叠（`code-fold`）。站点 QMD 代码块使用 `{.语言 filename="标题"}`；Quarto 会把标题渲染为 `.code-with-filename`，外观与复制按钮位置由主题统一控制。filename 缺失由 `verifying-content.py` 拦截，内容语义与篇幅由 `verifying-content.py` 负责。
 
+站点级项放在 `book:` 下：`site-url`、`repo-url`、`repo-actions: [source]`、`favicon`、`page-navigation: true` 与 `navbar.search: true`。它们只改站壳与导航，不改正文；`repo-actions` 不默认加 `edit`/`issue`，读者侧入口按发布面定。
+
 ### 改动约定
 
 1. 改 `format: html:` 任何取值都属于主题级改动，会触发整本渲染，先确认代价，再用 `quarto_render_check` 渲染。

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

@@ -52,7 +52,7 @@
 
 ## 表题与引用
 
-- 需要正文引用时加表题：表格下一行写 `: 表 3-1 棋盘接口的返回与边界 {#tbl-board-api}`，表题随主题显示在表上方、小一号。
+- 需要正文引用时加表题：表格下一行写 `: 表 3-1 棋盘接口的返回与边界 {#tbl-board-api}`；标签语法与书内编号规则见 `quarto/crossrefs.md`。表题随主题显示在表上方、小一号。
 - 表题只写对象与内容，不写「如下表」「本表说明」。
 - 同一页表题编号连续；正文引用写「表 3-1」，不写「下表」。
 

package/skills/writing-quarto/references/rules-cards.md

@@ -89,10 +89,10 @@
 - 反：`alt="图 1"`
 - 步骤：`steps/07-layout.md`
 
-**C17 交叉引用用锚点。** 引用其他章节写 `@fig-`、`@tbl-` 或 `[](){#...}`，不写「见上文」。
+**C17 交叉引用写对象。** 引用图、表写 `@fig-...`、`@tbl-...`；引用别的章写章节标题链接；不写「见上文」「如下图所示」。
 - 正：`判胜规则见 @fig-board-lines。`
 - 反：`判胜规则见上面的图。`
-- 步骤：`steps/07-layout.md`
+- 步骤：`steps/07-layout.md`；标签语法见 `quarto/crossrefs.md`。
 
 ## 用词与排版