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

package/README.en.md

@@ -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.4.3
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-quarto-book@0.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.4.3` only if the app refuses that write. To follow a GitHub tag instead, use `github:chengzhao-dev/dsh-quarto-book#v0.4.3`.
+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`.
 
 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.
 
@@ -43,7 +43,7 @@ Load `writing-quarto` or `designing-theme` inside a `type: book` repository and
 
 A project supplies exactly one skill of its own: `<book>/.agents/skills/quarto-book-project/`, starting from `templates/quarto-book-project/`. When it exists, both general skills read `SKILL.md` and then the `writing/` files it points to; when it does not, they skip it and do not guess project conventions. **Do not embed same-name skills into a book repository**: DSH picks one skill per name per layer by rank, lowest wins, and `.agents/skills` (rank 200) outranks the packaged provider (rank 550); a copy of `writing-quarto` or `designing-theme` in the book disables the plugin's text.
 
-Theme assets live in `skills/designing-theme/assets/theme/`. The package copy is authoritative; the book's `theme/` is the render copy. When a copy exists, `designing-theme` edits only that copy, and only when the user explicitly asks to install the plugin theme into the book and the target directory does not exist yet does the skill copy from the package and write the `filters/answering-disclosure.lua` filter. `_quarto.yml` references only the book's copy, never an npm package or the plugin checkout.
+Theme assets live in `skills/designing-theme/assets/theme/`. The package copy is authoritative; the book's `theme/` is the render copy. When a copy exists, `designing-theme` edits only that copy, and only when the user explicitly asks to install the plugin theme into the book and the target directory does not exist yet does the skill copy from the package and place `skills/writing-quarto/scripts/answering-disclosure.lua` at the book's `filters/answering-disclosure.lua`. `_quarto.yml` references only the book's copy, never an npm package or the plugin checkout.
 
 Run the content and link checks from the `writing-quarto` skill directory:
 

package/README.md

@@ -26,10 +26,10 @@
 ## 安装
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-quarto-book@0.4.3
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-quarto-book@0.6.0
 ```
 
-`--profile` 换成你实际运行的那个 profile。桌面应用固定跑 `desktop` profile，且该 profile 由应用独占管理，`dsh --profile desktop` 直接启动会被拒绝；安装或升级插件可用 `dsh plugin --profile desktop add <包>`，如果应用拒绝写入，再走「设置 → 插件 → 添加插件」，地址填 `npm:@chengzhao-dev/dsh-quarto-book@0.4.3`。想跟 GitHub 标签，也可以写 `github:chengzhao-dev/dsh-quarto-book#v0.4.3`。
+`--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`。
 
 从旧的无作用域包 `dsh-quarto-book` 升级时（该包已随 0.3.4 从 npm 删除，只影响之前装过它的 profile），先在同一个 profile 里 `dsh plugin --profile <profile> remove dsh-quarto-book` 再装新包。两个包同时留着会以相同的 rank 550 各注册一遍 `writing-quarto` 和 `designing-theme`。
 
@@ -43,7 +43,7 @@ dsh plugin --profile web add npm:@chengzhao-dev/dsh-quarto-book@0.4.3
 
 项目只放一份自己的约定技能：`<book>/.agents/skills/quarto-book-project/`，模板见 `templates/quarto-book-project/`。存在时两个通用技能先读它的 `SKILL.md`，再按它指向的 `writing/` 文件读章节表；不存在就跳过，不猜项目约定。**不要把同名技能嵌进书仓库**：DSH 在同一技能层按 rank 取一个，`.agents/skills`（rank 200）优先于插件（rank 550），书里再放 `writing-quarto` 或 `designing-theme` 会让插件正文失效。
 
-主题资产在 `skills/designing-theme/assets/theme/`，包内是权威来源，书内 `theme/` 是渲染副本；已有副本时 `designing-theme` 只改副本，只有用户明确要求「把插件主题装进这本书」且目标目录不存在时才从包复制，并写入过滤器 `filters/answering-disclosure.lua`。`_quarto.yml` 只引用书内副本，不指向 npm 包或插件检出目录。
+主题资产在 `skills/designing-theme/assets/theme/`，包内是权威来源，书内 `theme/` 是渲染副本；已有副本时 `designing-theme` 只改副本，只有用户明确要求「把插件主题装进这本书」且目标目录不存在时才从包复制，并把 `skills/writing-quarto/scripts/answering-disclosure.lua` 放到书内 `filters/answering-disclosure.lua`。`_quarto.yml` 只引用书内副本，不指向 npm 包或插件检出目录。
 
 内容与链接检查在 `writing-quarto` 技能目录下运行：
 

package/lib/tools/render-check.js

@@ -12,7 +12,9 @@ const QUARTO_TIMEOUT_MS = 120_000;
 const PYTHON_TIMEOUT_MS = 60_000;
 const MAX_OUTPUT_FILES = 30;
 const MAX_CAPTURED_OUTPUT = 12_000;
-const MOJIBAKE_MARKERS = ['锟', '鍂', '鐜', '绔', '鎴', '璇', '浣', '鍙', '熨', '闃'];
+// 只收多字乱码序列。单字（如「璇」「浣」「熨」）在正常中文里也会出现，
+// 拿它们当特征会把合法页面判成乱码。
+const MOJIBAKE_MARKERS = ['锟斤拷', '烫烫烫', '屯屯屯', 'â€', 'ä', 'é', 'ï¼', '锘匡'];
 export function stripQuotes(value) {
     const trimmed = value.trim();
     if (trimmed.length >= 2) {
@@ -333,7 +335,8 @@ export async function inspectHtml(input) {
     else {
         const domScript = path.join(SKILL_DIR, 'scripts', 'checking-dom.py');
         const dom = await runPython(domScript, ['--root', input.root, '--book-dir', input.outputDir], input.root, input.python, spawnFn);
-        const selected = parseDomLines(dom.output).filter((item) => ['C1', 'C2', 'C3', 'C5', 'C6', 'C7', 'C8'].includes(item.id));
+        // C9 只在产物里出现 details.answer-disclosure 时判 fail，没有答案时记 N/A。
+        const selected = parseDomLines(dom.output).filter((item) => ['C1', 'C2', 'C3', 'C5', 'C6', 'C7', 'C8', 'C9'].includes(item.id));
         const failed = selected.filter((item) => item.status === 'fail');
         checks.push({
             id: 'dom',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chengzhao-dev/dsh-quarto-book",
-  "version": "0.4.3",
+  "version": "0.6.0",
   "description": "为 Quarto Book 写章节、检查结构并维护主题。 · Write Quarto Book chapters, check their structure, and maintain the theme.",
   "type": "module",
   "main": "./lib/index.js",
@@ -35,7 +35,10 @@
         "zh": "为 Quarto Book 写章节、检查结构并维护主题。",
         "en": "Write Quarto Book chapters, check their structure, and maintain the theme."
       },
-      "capabilities": ["skills", "tools"]
+      "capabilities": [
+        "skills",
+        "tools"
+      ]
     }
   },
   "icon": "./icon.svg",

package/skills/designing-theme/SKILL.md

@@ -15,6 +15,7 @@ metadata:
 - 新增 palette 或页面组件样式。
 - **不适用**：`.qmd` 正文写法（转 `writing-quarto`）；书里项目的业务领域内容（由项目自己的技能负责）。
 - 项目带有 `.agents/skills/quarto-book-project/SKILL.md` 时，先读它的「主题与过滤器路径」，只改 `_quarto.yml` 实际引用的书内副本；没有就跳过。书内副本默认在 `theme/`，过滤器在 `filters/`。
+- 编码与行尾跟 `writing-quarto` 的 `quarto/encoding.md`：UTF-8 无 BOM、样式文件用 LF；`.bat`/`.cmd` 才用 CRLF。
 
 ## 任务路由
 
@@ -23,14 +24,14 @@ metadata:
 | 任务 | 读取 |
 | --- | --- |
 | 主题的分层、令牌与组件边界 | `references/theme-system.md` |
-| 色板接线与暗色分层 | `assets/theme/palettes/github/meta.md` |
+| 色板接线与暗色分层 | `assets/theme/palettes/flexoki/meta.md` |
 | 结构尺度令牌 | `assets/theme/css/tokens.css` 头注释 |
 | 字体、栏宽与阅读表面的取舍理由 | `knowledge/reading-surface.md` |
 
 ## P0 硬约束
 
 1. 主题资产被书根 `_quarto.yml` 以相对路径直接消费；移动或改名必须同步 `_quarto.yml`。
-2. `css/` 组件规则不写色值，语义颜色只来自 `palettes/github/tokens.css`；`css/tokens.css` 只放结构尺度令牌，明暗共用。
+2. `css/` 组件规则不写色值，语义颜色只来自 `palettes/<name>/tokens.css`（默认 Flexoki；Solarized 为运行时覆盖层）；`css/tokens.css` 只放结构尺度令牌，明暗共用。
 3. 这套资产是本插件主题的唯一来源。项目内若存在副本，先确认哪一份被 `_quarto.yml` 引用，再只改被引用的那一份，不假定两处自动同步。
 4. 修改主题或 `_quarto.yml` 后在仓库根目录整本 `quarto render`，验证明暗两套主题；布局调整优先修改 grid 与共享节奏，不用页面局部样式堆叠间距。
 5. 不新增字体文件、不引入新颜色来源：字体与颜色决定的理由在 `knowledge/reading-surface.md`，改决定先改知识再动资产。

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

@@ -12,7 +12,7 @@
        · 章节页 标题→首段引言：由本规则的 line-height / margin-bottom 控制（见下方 #quarto-document-content > p:first-of-type）
        · 首页 标题→描述：由下方 #title-block-header .description 的 margin-top 控制 */
 #title-block-header.quarto-title-block.default .quarto-title .title {
-  font-size: 2rem;   /* 32px，GitHub Markdown h1 */
+  font-size: 2rem;   /* 32px，按正文比例 */
   font-weight: 600;
   letter-spacing: 0;
   line-height: 1.2;
@@ -20,7 +20,7 @@
   text-align: left;        /* 覆盖默认 theme 居中，与左对齐正文/引言成组 */
   margin-bottom: 0;        /* 章节页标题→首段进一步收紧；首页间距交由 .description 控制 */
 }
-/* hero eyebrow（首页眉标，gitcn「GITHUB SKILLS」同款：英文大写标签 + 绿点在文字后）。
+/* hero eyebrow（首页眉标：英文小标签 + 一条短横线）。
    .hero-eyebrow 与标题块同为 #quarto-document-content 直接子级，
    用 flex + order 将其提到标题（h1+description）之前。 */
 #quarto-document-content:has(.hero-eyebrow) {
@@ -35,7 +35,7 @@
 #quarto-document-content:has(.hero-eyebrow) #title-block-header {
   order: 0;
 }
-/* 首页标题 36px（gitcn getting-started hero text-4xl），覆盖内容页默认 30px */
+/* 首页标题 36px（hero 大标题），覆盖内容页默认 32px */
 #quarto-document-content:has(.hero-eyebrow) #title-block-header .quarto-title .title {
   font-size: 2.25rem;
 }
@@ -44,21 +44,18 @@
   align-items: center;
   gap: 0.5rem;
   margin: 0;
-  font-size: 0.875rem;
+  font-size: 0.8125rem;
   font-weight: 400;
-  letter-spacing: normal;
+  letter-spacing: 0;
   text-transform: none;
   color: var(--text-secondary);
 }
 .hero-eyebrow p {
   margin: 0;
 }
-.hero-eyebrow::after {
-  content: "";
-  width: 0.5rem;
-  height: 0.625rem;
-  background-color: var(--dot-accent);
-}
+/* 眉标后面原本有一段 1.75rem 的强调色短横。它只是装饰：与标题之间已有 0.9rem
+   的间距，短横既不能分组也不能指示层级，反而在首页第一屏抢走标题的注意力。
+   留空后眉标靠字号与颜色（13px、次要色）退到标题之前，不再需要额外线条。 */
 #title-block-header .description {
   color: var(--text-secondary);
   font-size: 1.125rem;
@@ -80,26 +77,43 @@
   display: none;
 }
 
+/* C++ 的 ++ 不做逐符号位移。fontTools 实测：Bright 的 + 墨迹中心在 0.23em，
+   汉字在 0.357em，整套西文符号（数字、括号、比较符）都落在同一高度轴上；
+   只抬 ++ 会让它脱离同一行的 × ÷ = 与括号。字形越界才是真问题——缺字会回落到
+   CJK 字体，墨迹中心一下跳到 0.5em，那才是「++ 偏上」的来源，按码位补进子集解决。 */
+
 
 
-/* ---------- 标题：用尺寸区分阅读层级（单字面字体下层级只靠字号） ----------
-   h2 通栏底线显式关闭：Bootstrap 主题（cosmo）自带 h2 border-bottom，
-   不写会被回落默认值重新画上。章节之间靠 margin-top: 3rem 的节奏分隔。 */
+/* ---------- 标题：黑体标题 + 楷体正文的双字面 ----------
+   标题走 --heading-font（系统黑体，有真 600 字重），正文走 --ui-font（Bright 楷体）：
+   字重与字面同时分层，不再只靠字号。h2 通栏底线显式关闭：Bootstrap 主题（cosmo）
+   自带 h2 border-bottom，不写会被回落默认值重新画上。 */
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  font-family: var(--heading-font);
+}
 h1,
 h2 {
   font-size: 1.5rem;
   font-weight: 600;
-  line-height: 1.25;
+  line-height: 1.3;
   letter-spacing: 0;
   text-wrap: balance;
   border-bottom: none;
   padding-bottom: 0;
 }
 h1 { font-size: 2rem; }
+/* 二级标题下不再画短线：全书唯一的横线是通栏 1px 卡片发丝线（顶栏底边、表格线、
+   引用块上下边）。标题自己不带线，章节节奏只靠 margin-top 与字号台阶区分——
+   一条 2.25rem 的短线和通栏发丝线不是同一套语言，反而多出一个「第三种线」。 */
 h3 {
-  font-size: 1.25rem;   /* 20px：标题台阶 32/24/20/18，h3 与 h2 拉开一档 */
+  font-size: 1.1875rem;   /* 19px：标题台阶 32/24/19/18，h3 与 h2 拉开一档 */
   font-weight: 600;
-  line-height: 1.5;
+  line-height: 1.55;
   letter-spacing: 0;
   text-wrap: balance;
 }
@@ -115,18 +129,24 @@ h5 {
   line-height: 1.2;
   letter-spacing: 0;
 }
+h6 {
+  font-size: 0.85rem;
+  font-weight: 600;
+  line-height: 1.2;
+  letter-spacing: 0;
+}
 
 /* h2 通栏底线已移除（2026-10）：章节之间靠 margin-top: 3rem 的节奏分隔，
    不再用横线；原首页/索引页关闭底线的覆盖规则随之删除。 */
 
-/* ---------- 垂直节奏（上边距节奏，参考 mdBook / React / Vue 的 prose 模式） ----------
+/* ---------- 垂直节奏（上边距节奏，书籍阅读的段落呼吸） ----------
    Quarto 把每个 h2 章节内容包在 <section class="level2"> 里，因此对主容器与各 section
    的直属块级子元素统一重置 margin，用上边距节奏控制间距
    —— 正文间距收成四档，档位按「两块内容是不是同一件事」取：
       粘连 0.5rem（标题→首段/列表、标题→callout、caption→其代码块）
-      相关 1rem（代码块↔caption、代码块↔callout、列表内代码块→验证句）
-      换段 1.5rem（段落/列表/代码块之间的默认距离，下方 * + * 是唯一来源，对 content 与首页一视同仁）
-      换节 3rem（h2 之前；h3/h4/h5 之前 2rem） */
+      相关 0.9rem（代码块↔caption、代码块↔callout、列表内代码块→验证句）
+      换段 1.4rem（段落/列表/代码块之间的默认距离，下方 * + * 是唯一来源）
+      换节 3.25rem（h2 之前；h3/h4/h5 之前 2.25rem） */
 #quarto-document-content > *,
 #quarto-document-content section > * {
   margin-top: 0;
@@ -135,11 +155,11 @@ h5 {
 /* 换段档：段落、列表和代码块之间的默认距离。 */
 #quarto-document-content > * + *,
 #quarto-document-content section > * + * {
-  margin-top: 1.5rem;
+  margin-top: 1.4rem;
 }
 #quarto-document-content p,
 #quarto-document-content li {
-  line-height: 1.75;
+  line-height: 1.85;
 }
 /* 代码块上方/下方的说明（caption）：次要灰 + 略小，贴近其描述的代码块；
    代码块本身保持高对比正文色（切勿把灰色涂到 pre 上） */
@@ -151,17 +171,17 @@ h5 {
 /* 代码块 → 下方段落：换段档 */
 #quarto-document-content > :is(.code-copy-outer-scaffold, pre) + p,
 #quarto-document-content section > :is(.code-copy-outer-scaffold, pre) + p {
-  margin-top: 1.5rem;
+  margin-top: 1.4rem;
 }
 /* 代码块 → 下方 caption：相关档，caption 是代码块的附属说明 */
 #quarto-document-content > :is(.code-copy-outer-scaffold, pre) + .code-caption,
 #quarto-document-content section > :is(.code-copy-outer-scaffold, pre) + .code-caption {
-  margin-top: 1rem;
+  margin-top: 0.9rem;
 }
 /* 正文 → 代码块：换段档 */
 #quarto-document-content > :is(p, .code-caption) + :is(.code-copy-outer-scaffold, pre),
 #quarto-document-content section > :is(p, .code-caption) + :is(.code-copy-outer-scaffold, pre) {
-  margin-top: 1.5rem;
+  margin-top: 1.4rem;
 }
 /* 列表项由 li 自身承担块间距，上面的 section 直属子元素规则覆盖不到代码块后的验证句。 */
 #quarto-document-content li > :is(.code-copy-outer-scaffold, .code-with-filename, pre, div.sourceCode) + p {
@@ -179,27 +199,27 @@ h5 {
 #quarto-document-content .callout + :is(.code-copy-outer-scaffold, pre) {
   margin-top: 1rem;
 }
-/* h2 间距：换节档 3rem；margin-bottom 与相邻 margin-top 折叠取大者，
+/* h2 间距：换节档 3.25rem；margin-bottom 与相邻 margin-top 折叠取大者，
    设 0.5rem 让标题与首段保持粘连档，不被折叠抬高一倍 */
 #quarto-document-content > h2,
 #quarto-document-content section > h2 {
-  margin-top: 3rem;
+  margin-top: 3.25rem;
   margin-bottom: 0.5rem;
 }
 /* 章节页首段引言：进一步拉近与标题的间距（标题块 margin-bottom 已为 0，这里再上拉一点）
    —— 间距控制点：标题块 line-height/margin-bottom（上方 #title-block-header… .title）＋ 此处首段 margin-top */
 #quarto-document-content > p:first-of-type {
-  margin-top: 0.5rem;      /* 标题→首段：干净正间距（取代负 margin hack） */
+  margin-top: 0.6rem;      /* 标题→首段：干净正间距（取代负 margin hack） */
 }
 #quarto-document-content > h3,
 #quarto-document-content section > h3 {
-  margin-top: 2rem;
+  margin-top: 2.25rem;
 }
 #quarto-document-content > h4,
 #quarto-document-content > h5,
 #quarto-document-content section > h4,
 #quarto-document-content section > h5 {
-  margin-top: 2rem;
+  margin-top: 2.25rem;
 }
 /* 标题紧接的首段/列表收紧到粘连档，让「标题—首段」成组（段→标题仍保留上方疏朗留白） */
 #quarto-document-content :is(h2, h3, h4) + :is(p, ul, ol) {
@@ -232,17 +252,53 @@ h5 {
 /* ---------- 链接 ---------- */
 a {
   color: var(--link-color);
+  text-underline-offset: 0.18em;
 }
 a:hover {
-  text-decoration: underline;
+  color: var(--link-hover-color);
+  text-decoration-color: var(--action-color);
 }
-/* r4ds：代码里的链接用细下划线 */
+/* 代码里的链接用细下划线 */
 code a:any-link {
   text-decoration: underline;
   text-decoration-color: var(--link-underline);
   text-decoration-thickness: 1px;
 }
 
+/* ---------- 源码模态（code-tools 打开的面板） ----------
+   Quarto 用 Bootstrap 模态显示 .qmd 源文件：默认白底黑字、圆角 0.5rem、
+   遮罩纯黑 50%。这里把遮罩接到 --overlay-scrim，面板接卡片层令牌，
+   标题用黑体，正文区用代码底色（它展示的是代码）。 */
+.modal-backdrop {
+  background-color: var(--overlay-scrim);
+}
+.modal-backdrop.show {
+  opacity: 1;
+}
+.modal-content {
+  background: var(--surface-raised);
+  border: 1px solid var(--card-border);
+  border-radius: var(--radius-lg);
+  box-shadow: 0 24px 60px rgba(0, 0, 0, 0.28);
+}
+.modal-header {
+  border-bottom: 1px solid var(--card-border);
+  padding: 0.8rem 1.1rem;
+}
+.modal-title {
+  color: var(--body-color);
+  font-family: var(--heading-font);
+  font-size: 1.0625rem;
+  font-weight: 600;
+}
+.modal-body {
+  background: var(--code-bg);
+  padding: 0.9rem 1.1rem;
+}
+[data-palette][data-mode="night"] .modal-content .btn-close {
+  filter: invert(1) grayscale(1) brightness(1.6);
+}
+
 /* ---------- 杂项（原 misc.css：过渡 / 小屏 / 页脚 / 返回顶部 / 打印） ---------- */
 #quarto-sidebar .sidebar-item-text.sidebar-link,
 .sidebar.margin-sidebar nav[role="doc-toc"] a,
@@ -266,19 +322,102 @@ code a:any-link {
   }
 }
 
-.footer {
+/* 页脚跟随正文结束，不被 Quarto 的 inline min-height 推到长屏底部留下大片空白。 */
+body #quarto-content {
+  min-height: 0 !important;
+}
+
+/* ---------- 页脚贴底（短页时 colophon 落在视口底部，不在其下留背景带） ---------- */
+body {
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+}
+
+body > #quarto-content {
+  flex: 1 0 auto;
+}
+
+/* Quarto 的三行网格（正文 / 章节翻页 / 页脚）把剩余高度留给页脚行，
+   短页时 colophon 落在视口底部，正文与翻页仍靠在一起。 */
+#quarto-content {
+  grid-template-rows:
+    [content-top] auto
+    [content-bottom] auto
+    [page-bottom] 1fr
+    [footer-bottom];
+}
+
+/* ---------- 页脚：书籍 colophon ---------- */
+.book-footer {
   grid-column: 1 / -1;
+  grid-row: page-bottom / footer-bottom;
+  align-self: end;
+  justify-self: center;
+  width: 100%;
+  max-width: 54rem;
   color: var(--text-secondary);
-  background-color: var(--code-bg);
+  background-color: transparent;
   font-family: var(--ui-font);
   font-weight: 400;
-  font-size: 0.75rem;
+  font-size: 0.8125rem;
+  line-height: 1.7;
+  border-top: 1px solid var(--card-border);
   border-radius: 0;
-  padding: 1.25rem 1rem 1rem;
-  margin-top: 3rem;
+  padding: 1.1rem 1rem 1.75rem;
+  margin: 2.5rem 0 0;
   text-align: center;
 }
 
+.book-footer p {
+  margin: 0;
+}
+
+.book-footer .book-footer-note {
+  color: var(--text-secondary);
+  font-size: 0.75rem;
+}
+
+/* Quarto 自动生成的 footer 只承担窄屏的源码/编辑入口；
+   桌面端空 footer 不再继承 .footer 的 3rem 上边距与背景色带。 */
+footer.footer {
+  display: none;
+}
+
+@media (max-width: 991.98px) {
+  footer.footer:has(.toc-actions) {
+    display: block;
+    grid-column: 1 / -1;
+    padding: 0;
+    margin: 0;
+    background: transparent;
+    border: 0;
+  }
+
+  /* Quarto 的 nav-footer 自带上/下大边距；手机上只留一行「查看代码」。 */
+  footer.footer .nav-footer {
+    padding: 0.25rem 1rem 0.5rem;
+  }
+
+  footer.footer .nav-footer-center {
+    margin: 0;
+  }
+
+  footer.footer .toc-actions {
+    padding: 0;
+  }
+
+  footer.footer .toc-actions ul {
+    justify-content: center;
+    padding: 0;
+    margin: 0;
+  }
+
+  footer.footer .toc-actions li {
+    margin: 0;
+  }
+}
+
 body.quarto-light .navbar,
 body.quarto-dark .navbar {
   --bs-navbar-color: var(--navbar-fg);
@@ -288,35 +427,36 @@ body.quarto-dark .navbar {
   box-shadow: none;
 }
 
-.footer a {
+.book-footer a {
   color: var(--text-link);
 }
-.footer a:hover {
-  text-decoration: underline;
+.book-footer a:hover {
+  color: var(--link-hover-color);
+  text-decoration-color: var(--action-color);
 }
 
 #back-to-top {
   position: fixed;
   right: 1.25rem;
   bottom: 1.25rem;
-  width: 2.5rem;
-  height: 2.5rem;
+  width: 2.25rem;
+  height: 2.25rem;
   display: flex;
   align-items: center;
   justify-content: center;
-  border-radius: 50%;
+  border-radius: var(--radius-sm);
   border: 1px solid var(--card-border);
   background-color: var(--card-bg);
-  color: var(--accent);
-  font-size: 1.1rem;
+  color: var(--text-secondary);
+  font-size: 1rem;
   line-height: 1;
   cursor: pointer;
   opacity: 0;
   visibility: hidden;
-  transform: translateY(0.5rem);
+  transform: translateY(0.4rem);
   transition: opacity var(--transition), transform var(--transition),
-    background-color var(--transition);
-  box-shadow: var(--card-shadow);
+    color var(--transition), border-color var(--transition);
+  box-shadow: none;
   z-index: 1000;
 }
 #back-to-top.show {
@@ -325,7 +465,8 @@ body.quarto-dark .navbar {
   transform: translateY(0);
 }
 #back-to-top:hover {
-  background-color: var(--sidebar-hover-bg);
+  color: var(--link-hover-color);
+  border-color: var(--text-secondary);
 }
 @media (prefers-reduced-motion: reduce) {
   #back-to-top {
@@ -343,11 +484,23 @@ blockquote {
 }
 
 @media print {
+  /* 打印恢复普通文档流：页脚贴底与三行网格只服务屏幕。 */
+  body {
+    display: block;
+    min-height: 0;
+  }
+  #quarto-content {
+    grid-template-rows: none;
+  }
+  .book-footer {
+    grid-row: auto;
+  }
   /* 只隐藏复制按钮：Quarto 1.10 起 .code-copy-outer-scaffold 包裹着代码本身，
      把它一起 display:none 会导致打印/导出 PDF 时所有代码块消失。 */
   #quarto-sidebar,
   #quarto-margin-sidebar,
   .nav-page,
+  .page-navigation,
   .code-copy-button,
   #back-to-top {
     display: none;
@@ -357,12 +510,20 @@ blockquote {
   h4 {
     break-after: avoid;
   }
-  pre {
+  pre,
+  figure,
+  .callout,
+  blockquote {
     break-inside: avoid;
   }
-  #quarto-document-content a[href^="http"]::after {
-    content: " (" attr(href) ")";
-    font-size: 0.85em;
-    word-break: break-all;
+  /* 宽表跨页时表头跟着重复，否则第二页读者不知道列名。 */
+  thead {
+    display: table-header-group;
+  }
+  @page {
+    size: A4;
+    margin: 18mm 16mm;
   }
+  /* 不再打印外链 URL：840px 正文列里长 URL 必然断行成灰字长串，
+     脚注/参考文献里的链接读者可自行点开电子版。 */
 }