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

package/README.en.md

@@ -5,7 +5,7 @@
 
 **English** | [简体中文](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/README.md)
 
-Write Chinese technical chapters in a Quarto Book repository: `writing-quarto` owns the chapter skeleton and prose, `designing-theme` owns the theme. Both skills appear only inside `type: book` repositories. After a render, `quarto_render_check` decides whether the HTML is publishable and `quarto_pass_report` prints the closing receipt.
+Take a Quarto Book from chapters to publishable output: `writing-quarto` owns the chapter skeleton, whole-book order and Chinese prose; `designing-theme` owns the theme; after a render, `quarto_render_check` decides whether the HTML is publishable and `quarto_pass_report` prints the closing receipt. Both skills appear only inside `type: book` repositories, and the workflow needs Quarto CLI and Python 3.
 
 ## What it provides
 
@@ -16,7 +16,7 @@ Write Chinese technical chapters in a Quarto Book repository: `writing-quarto` o
 | `quarto_render_check` | Check that `output-dir` is safe, render once when asked, and inspect HTML in `_book/` for publishing | Editing `.qmd`, fixing config automatically, or re-running a failed render |
 | `quarto_pass_report` | Compress the run into a fixed-line receipt card: skill, mode, files and steps changed, items held, check verdicts | Saving to disk, quoting chapter prose, or changing the text based on the receipt |
 
-Both skills are discovered from the package's `skills/` directory and loaded on demand. Relative paths inside a skill resolve against that skill's directory: `writing-quarto` uses `steps/`, `examples/`, `quarto/`, `scripts/`; `designing-theme` uses `references/`, `knowledge/`, `assets/`, `scripts/`.
+Both skills are discovered from the package's `skills/` directory and loaded on demand. Relative paths inside a skill resolve against that skill's directory: `writing-quarto` uses `steps/`, `examples/`, `quarto/`, `references/`, `scripts/`; `designing-theme` uses `references/`, `knowledge/`, `assets/`, `scripts/`.
 
 ## Quick start
 
@@ -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.3`; to follow a GitHub tag, write `github:chengzhao-dev/dsh-quarto-book#v0.6.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 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.4`; to follow a GitHub tag, write `github:chengzhao-dev/dsh-quarto-book#v0.6.4`.
 
 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

@@ -5,7 +5,7 @@
 
 [English](https://github.com/chengzhao-dev/dsh-quarto-book/blob/main/README.en.md) | **简体中文**
 
-在 Quarto Book 仓库里写中文技术章节：`writing-quarto` 管章节骨架与行文，`designing-theme` 管主题样式。两个技能只在 `type: book` 的仓库里出现。渲染后可以用 `quarto_render_check` 判断 HTML 是否可发布，用 `quarto_pass_report` 出一张收尾回执。
+把一份 Quarto Book 从章节写到可发布：`writing-quarto` 负责章节骨架、整书次序与中文行文，`designing-theme` 负责主题；渲染后由 `quarto_render_check` 判断 HTML 是否可发布，`quarto_pass_report` 给出收尾回执。两个技能只在 `type: book` 的仓库里出现，运行需要 Quarto CLI 与 Python 3。
 
 ## 提供什么
 
@@ -16,7 +16,7 @@
 | `quarto_render_check` | 先判断 `output-dir` 是否安全，再按需渲染一次，检查 `_book/` 里的 HTML 是否可发布 | 不改 `.qmd`，不自动修配置，不重复渲染 |
 | `quarto_pass_report` | 收尾时把执行结论压成固定行数的回执卡片：技能、模式、改过的文件与步骤、未改项、检查结论 | 不保存到磁盘，不贴章节原文，不据回执改文章 |
 
-两个技能从包内 `skills/` 目录发现，按需加载；技能里的相对路径以技能目录为基准：`writing-quarto` 用 `steps/`、`examples/`、`quarto/`、`scripts/`，`designing-theme` 用 `references/`、`knowledge/`、`assets/`、`scripts/`。
+两个技能从包内 `skills/` 目录发现，按需加载；技能里的相对路径以技能目录为基准：`writing-quarto` 用 `steps/`、`examples/`、`quarto/`、`references/`、`scripts/`，`designing-theme` 用 `references/`、`knowledge/`、`assets/`、`scripts/`。
 
 ## 快速开始
 
@@ -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.3`，跟 GitHub 标签时写 `github:chengzhao-dev/dsh-quarto-book#v0.6.3`。
+`--profile` 换成你实际运行的那个 profile。桌面应用固定跑 `desktop` profile，且该 profile 由应用独占管理，`dsh --profile desktop` 直接启动会被拒绝；安装或升级用 `dsh plugin --profile desktop add <包>`，应用拒绝写入时再走「设置 → 插件 → 添加插件」。需要固定版本时写 `npm:@chengzhao-dev/dsh-quarto-book@0.6.4`，跟 GitHub 标签时写 `github:chengzhao-dev/dsh-quarto-book#v0.6.4`。
 
 从旧的无作用域包 `dsh-quarto-book` 升级（该包已随 0.3.4 从 npm 删除，只影响之前装过它的 profile）：先在同一个 profile 里 `dsh plugin --profile <profile> remove dsh-quarto-book`，再装新包。两个包同时留着会以相同的 rank 550 各注册一遍 `writing-quarto` 和 `designing-theme`。
 

package/lib/index.js

@@ -24,15 +24,17 @@ const RANK = 550;
 const SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const PACKAGE_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const SKILLS_ROOT = path.join(PACKAGE_ROOT, 'skills');
-/** 读取 SKILL.md 实际用到的几个键，只做最简单的 YAML frontmatter 解析。 */
+/** 读取 SKILL.md 实际用到的几个键，只做最小的 YAML frontmatter 解析。 */
 function parseFrontmatter(source) {
-    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(source);
+    const normalized = source.replace(/^\uFEFF/, '');
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(normalized);
     if (!match)
-        return { data: {}, body: source };
+        return { data: {}, body: normalized };
     const data = {};
     const stack = [{ indent: -1, target: data }];
-    for (const rawLine of match[1].split(/\r?\n/)) {
-        const line = rawLine.replace(/\t/g, '  ');
+    const lines = match[1].split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index].replace(/\t/g, '  ');
         if (!line.trim() || line.trimStart().startsWith('#'))
             continue;
         const indent = line.length - line.trimStart().length;
@@ -43,16 +45,56 @@ function parseFrontmatter(source) {
             stack.pop();
         const parent = stack[stack.length - 1].target;
         const key = pair[1];
-        const value = (pair[2] ?? '').trim();
+        const value = stripInlineComment(pair[2] ?? '').trim();
         if (value === '') {
             const child = {};
             parent[key] = child;
             stack.push({ indent, target: child });
             continue;
         }
+        if (/^[>|][+-]?\d?$/.test(value)) {
+            const block = [];
+            let cursor = index + 1;
+            for (; cursor < lines.length; cursor += 1) {
+                const next = lines[cursor].replace(/\t/g, '  ');
+                if (!next.trim()) {
+                    block.push('');
+                    continue;
+                }
+                const nextIndent = next.length - next.trimStart().length;
+                if (nextIndent <= indent)
+                    break;
+                block.push(next);
+            }
+            const nonBlank = block.filter((item) => item.trim());
+            const cut = nonBlank.length > 0 ? Math.min(...nonBlank.map((item) => item.length - item.trimStart().length)) : 0;
+            const text = block.map((item) => item.slice(cut)).join('\n');
+            parent[key] = value[0] === '|' ? text : text.replace(/([^\n])\n(?=[^\n])/g, '$1 ').replace(/\n{2,}/g, '\n');
+            index = cursor - 1;
+            continue;
+        }
         parent[key] = parseScalar(value);
     }
-    return { data, body: source.slice(match[0].length) };
+    return { data, body: normalized.slice(match[0].length) };
+}
+/** 去掉 plain scalar 末尾的 ` # 注释`；引号内的 # 保留。 */
+function stripInlineComment(value) {
+    let quote;
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value[index];
+        if (quote) {
+            if (char === quote && value[index - 1] !== '\\')
+                quote = undefined;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            continue;
+        }
+        if (char === '#' && (index === 0 || /\s/.test(value[index - 1])))
+            return value.slice(0, index);
+    }
+    return value;
 }
 function parseScalar(value) {
     if ((value.startsWith('"') && value.endsWith('"')) ||

package/lib/tools/pass-report.js

@@ -74,6 +74,7 @@ function normalizeFiles(value) {
         fail('files 必须是数组');
     if (value.length > MAX_FILES)
         fail(`files 最多 ${MAX_FILES} 个路径`);
+    const seen = new Set();
     return value.map((item) => {
         if (!isRecord(item))
             fail('files 的每一项必须是 { path, edits }');
@@ -85,7 +86,11 @@ function normalizeFiles(value) {
             fail('files 的 path 必须是非空字符串');
         if (!isPlainCount(item.edits))
             fail('files 的 edits 必须是非负整数');
-        return { path: filePath.trim(), edits: item.edits };
+        const normalizedPath = filePath.trim();
+        if (seen.has(normalizedPath))
+            fail(`files 的 path 重复：${normalizedPath}`);
+        seen.add(normalizedPath);
+        return { path: normalizedPath, edits: item.edits };
     });
 }
 function normalizeSteps(value, skill) {
@@ -194,17 +199,12 @@ export function buildPassReport(input) {
             fail('未执行时必须给出 skip_reason');
         if ([...reason.trim()].length > MAX_SKIP_REASON)
             fail(`skip_reason 最多 ${MAX_SKIP_REASON} 个字`);
-        if (input.files !== undefined && Array.isArray(input.files) && input.files.length > 0) {
-            fail('未执行时 files 必须为空');
-        }
-        if (input.steps !== undefined && Array.isArray(input.steps) && input.steps.length > 0) {
-            fail('未执行时 steps 必须为空');
-        }
-        if (input.held !== undefined && Array.isArray(input.held) && input.held.length > 0) {
-            fail('未执行时 held 必须为空');
-        }
-        if (input.checks !== undefined && Array.isArray(input.checks) && input.checks.length > 0) {
-            fail('未执行时 checks 必须为空');
+        for (const key of ['files', 'steps', 'held', 'checks']) {
+            const value = input[key];
+            if (value === undefined)
+                continue;
+            if (!Array.isArray(value) || value.length > 0)
+                fail(`未执行时 ${key} 必须为空数组`);
         }
         return { receipt: `未执行 ${typedSkill}：${reason.trim()}` };
     }

package/lib/tools/render-check.js

@@ -1,7 +1,7 @@
 // `quarto_render_check`：先判断渲染输出目录是否安全，再在 120 秒内跑一次
 // `quarto render`，最后检查产出的 HTML 是否可发布。失败只报告，不自动重新运行。
 import { spawn as nodeSpawn } from 'node:child_process';
-import { readFile, readdir } from 'node:fs/promises';
+import { readFile, readdir, realpath, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { BOOK_PROJECT_RE, findBookRoot, hasBookSource } from '../workspace.js';
@@ -12,6 +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 MAX_HTML_FILES = 1_000;
+const MAX_HTML_BYTES = 8 * 1024 * 1024;
+const MAX_HTML_TOTAL_BYTES = 64 * 1024 * 1024;
 // 只收多字乱码序列。单字（如「璇」「浣」「熨」）在正常中文里也会出现，
 // 拿它们当特征会把合法页面判成乱码。
 const MOJIBAKE_MARKERS = ['锟斤拷', '烫烫烫', '屯屯屯', 'â€', 'ä', 'é', 'ï¼', '锘匡'];
@@ -26,6 +29,18 @@ export function stripQuotes(value) {
     }
     return trimmed;
 }
+/** 解析 YAML 单行标量：去掉成对引号，再剥掉未引用值末尾的 ` # 注释`。 */
+function parseConfigScalar(raw) {
+    const trimmed = raw.trim();
+    const quote = trimmed[0];
+    if (quote === '"' || quote === "'") {
+        const end = trimmed.lastIndexOf(quote);
+        if (end > 0)
+            return trimmed.slice(1, end);
+    }
+    const comment = /\s+#/.exec(trimmed);
+    return (comment ? trimmed.slice(0, comment.index) : trimmed).trimEnd();
+}
 function configValue(yaml, key) {
     const pattern = new RegExp(`^[\\t ]*${key}:[\\t ]*(.*)$`);
     for (const line of yaml.split(/\r?\n/)) {
@@ -33,13 +48,14 @@ function configValue(yaml, key) {
             continue;
         const match = pattern.exec(line);
         if (match)
-            return stripQuotes(match[1]);
+            return parseConfigScalar(match[1]);
     }
     return undefined;
 }
-function hasTruthySwitch(yaml, key) {
-    const value = configValue(yaml, key);
-    return value === 'true';
+/** Quarto 的搜索默认开启；只有显式关掉（false/no/off）才跳过索引检查。 */
+function searchEnabled(yaml) {
+    const value = configValue(yaml, 'search');
+    return value === undefined || !/^(?:false|no|off)$/i.test(value);
 }
 /**
  * `project.output-dir` 只能落在书根内部，且不能就是书根自身。
@@ -75,17 +91,84 @@ export function evaluateOutputDir(root, yaml) {
     }
     return { safe: true, value, resolved };
 }
-function runProcess(command, args, cwd, timeoutMs, spawnFn) {
+async function nearestExistingRealPath(target) {
+    let current = path.resolve(target);
+    while (true) {
+        try {
+            return await realpath(current);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'ENOENT' && code !== 'ENOTDIR')
+                return undefined;
+            const parent = path.dirname(current);
+            if (parent === current)
+                return undefined;
+            current = parent;
+        }
+    }
+}
+/** 输出目录或其最近的现存父目录经符号链接解析后仍须落在书根内。 */
+async function outputDirEscapesRoot(root, resolved) {
+    const realRoot = await nearestExistingRealPath(root);
+    const realTarget = await nearestExistingRealPath(resolved);
+    if (!realRoot || !realTarget)
+        return true;
+    const relative = path.relative(realRoot, realTarget);
+    return relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
+}
+function killProcessTree(child, cwd, spawnFn) {
+    const pid = child.pid;
+    if (pid && process.platform === 'win32') {
+        // Windows 上只杀直接子进程会留下 Quarto 派生的 pandoc/python。
+        try {
+            spawnFn('taskkill', ['/pid', String(pid), '/T', '/F'], {
+                cwd,
+                windowsHide: true,
+                shell: false,
+            });
+        }
+        catch {
+            // taskkill 不可用时退回 child.kill。
+        }
+    }
+    else if (pid && process.platform !== 'win32') {
+        // runProcess 用 detached 启动，负 pid 表示整个进程组。
+        try {
+            process.kill(-pid, 'SIGKILL');
+            return;
+        }
+        catch {
+            // 进程组可能已退出，退回 child.kill。
+        }
+    }
+    try {
+        child.kill();
+    }
+    catch {
+        // 进程可能已经退出。
+    }
+}
+function runProcess(command, args, cwd, timeoutMs, spawnFn, signal) {
     return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve({ ok: false, missing: false, code: null, output: '已取消。', duration_ms: 0 });
+            return;
+        }
         const started = Date.now();
         let settled = false;
         let output = '';
         let child;
+        const onAbort = () => {
+            killProcessTree(child, cwd, spawnFn);
+            finish({ ok: false, missing: false, code: null, output: '已取消。', duration_ms: Date.now() - started });
+        };
         const finish = (result) => {
             if (settled)
                 return;
             settled = true;
             clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
             resolve(result);
         };
         const append = (chunk) => {
@@ -95,19 +178,21 @@ function runProcess(command, args, cwd, timeoutMs, spawnFn) {
         };
         let timer;
         try {
-            child = spawnFn(command, args, { cwd, windowsHide: true, shell: false });
+            child = spawnFn(command, args, {
+                cwd,
+                windowsHide: true,
+                shell: false,
+                signal,
+                detached: process.platform !== 'win32',
+            });
         }
         catch (error) {
             resolve({ ok: false, missing: true, code: null, output: error instanceof Error ? error.message : String(error), duration_ms: Date.now() - started });
             return;
         }
+        signal?.addEventListener('abort', onAbort, { once: true });
         timer = setTimeout(() => {
-            try {
-                child.kill();
-            }
-            catch {
-                // 进程可能已经退出。
-            }
+            killProcessTree(child, cwd, spawnFn);
             finish({
                 ok: false,
                 missing: false,
@@ -127,16 +212,31 @@ function runProcess(command, args, cwd, timeoutMs, spawnFn) {
         });
     });
 }
-async function runPython(script, args, root, explicitPython, spawnFn) {
+async function runPython(script, args, root, explicitPython, spawnFn, signal) {
     const candidates = [explicitPython, process.env.PYTHON, 'python3', 'python'].filter((item) => typeof item === 'string' && item.trim() !== '');
     let last = { ok: false, missing: true, code: null, output: `找不到 Python 解释器：${script}`, duration_ms: 0 };
+    let executedFailure;
     for (const candidate of [...new Set(candidates)]) {
-        const result = await runProcess(candidate, [script, ...args], root, PYTHON_TIMEOUT_MS, spawnFn);
-        if (!result.missing)
+        const result = await runProcess(candidate, [script, ...args], root, PYTHON_TIMEOUT_MS, spawnFn, signal);
+        if (result.ok)
             return result;
         last = result;
+        // 坏解释器（例如 Windows Store 占位符）会启动成功但退出非 0；
+        // 先记住它的输出，再继续试下一个候选，避免只调用一个坏解释器就判书失败。
+        if (!result.missing && result.code !== null)
+            executedFailure = result;
     }
-    return last;
+    return executedFailure ?? last;
+}
+function pythonEnvironmentFailure(result) {
+    if (result.missing || result.code === null)
+        return true;
+    const text = result.output.toLowerCase();
+    return (result.code === 9009 ||
+        text.includes('enoent') ||
+        text.includes('不是内部或外部命令') ||
+        text.includes('command not found') ||
+        text.includes('no such file'));
 }
 function truncate(value, max = 180) {
     const collapsed = value.replace(/\s+/g, ' ').trim();
@@ -175,6 +275,9 @@ function relativeTo(root, file) {
 }
 async function readUtf8(file) {
     try {
+        const info = await stat(file);
+        if (info.size > MAX_HTML_BYTES)
+            return undefined;
         const bytes = await readFile(file);
         if (bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf)
             return undefined;
@@ -218,20 +321,61 @@ export async function inspectHtml(input) {
             : `${relativeTo(input.root, index)} 已生成`,
     });
     const broken = [];
-    for (const file of htmlFiles) {
+    const fileUris = [];
+    let scaffoldFound = false;
+    let scannedBytes = 0;
+    let sizeLimited = false;
+    const scanFiles = htmlFiles.slice(0, MAX_HTML_FILES);
+    for (const file of scanFiles) {
+        const relative = relativeTo(input.outputDir, file);
+        let size = 0;
+        try {
+            size = (await stat(file)).size;
+        }
+        catch {
+            broken.push(`${relative} 无法读取`);
+            errors.push(`${relative} 无法读取`);
+            continue;
+        }
+        if (size > MAX_HTML_BYTES) {
+            broken.push(`${relative} 超过 ${Math.round(MAX_HTML_BYTES / 1024 / 1024)} MiB，未读`);
+            errors.push(`${relative} 太大，未读`);
+            continue;
+        }
+        if (scannedBytes + size > MAX_HTML_TOTAL_BYTES) {
+            sizeLimited = true;
+            errors.push(`HTML 总量超过 ${Math.round(MAX_HTML_TOTAL_BYTES / 1024 / 1024)} MiB，检查提前结束`);
+            break;
+        }
+        scannedBytes += size;
         const text = await readUtf8(file);
         if (text === undefined) {
-            broken.push(`${relativeTo(input.outputDir, file)} 不是 UTF-8 或带 BOM`);
+            broken.push(`${relative} 不是 UTF-8 或带 BOM`);
+            errors.push(`${relative} 读取失败或不是 UTF-8`);
             continue;
         }
         if (text.includes('\ufffd')) {
-            broken.push(`${relativeTo(input.outputDir, file)} 含 U+FFFD 替换符`);
-            continue;
+            broken.push(`${relative} 含 U+FFFD 替换符`);
+        }
+        else {
+            const marker = MOJIBAKE_MARKERS.find((item) => text.includes(item));
+            if (marker)
+                broken.push(`${relative} 命中乱码特征「${marker}」`);
         }
-        const marker = MOJIBAKE_MARKERS.find((item) => text.includes(item));
-        if (marker)
-            broken.push(`${relativeTo(input.outputDir, file)} 命中乱码特征「${marker}」`);
+        if (/(?:href|src)\s*=\s*["'][^"']*file:\/\/\//i.test(text))
+            fileUris.push(relative);
+        if (!scaffoldFound && containsScaffold(text))
+            scaffoldFound = true;
     }
+    checks.push({
+        id: 'html_files',
+        status: htmlFiles.length > MAX_HTML_FILES || sizeLimited ? 'fail' : 'pass',
+        detail: htmlFiles.length > MAX_HTML_FILES
+            ? `HTML 文件 ${htmlFiles.length} 个，超过上限 ${MAX_HTML_FILES}`
+            : sizeLimited
+                ? `HTML 总量超过 ${Math.round(MAX_HTML_TOTAL_BYTES / 1024 / 1024)} MiB`
+                : `${htmlFiles.length} 个 HTML 在检查上限内`,
+    });
     checks.push({
         id: 'utf8',
         status: htmlFiles.length === 0 ? 'skip' : broken.length === 0 ? 'pass' : 'fail',
@@ -251,12 +395,6 @@ export async function inspectHtml(input) {
                 ? '首页声明 charset=utf-8'
                 : '首页缺少 charset=utf-8 声明',
     });
-    const fileUris = [];
-    for (const file of htmlFiles) {
-        const text = await readUtf8(file);
-        if (text?.includes('file:///'))
-            fileUris.push(relativeTo(input.outputDir, file));
-    }
     checks.push({
         id: 'no_file_uri',
         status: htmlFiles.length === 0 ? 'skip' : fileUris.length === 0 ? 'pass' : 'fail',
@@ -283,8 +421,8 @@ export async function inspectHtml(input) {
                     : 'sitemap.xml 没有 <loc> 条目',
         });
     }
-    if (!hasTruthySwitch(input.yaml, 'search')) {
-        checks.push({ id: 'search_index', status: 'skip', detail: '书配置未打开搜索，不要求 search.json' });
+    if (!searchEnabled(input.yaml)) {
+        checks.push({ id: 'search_index', status: 'skip', detail: '书配置显式关闭搜索，不要求 search.json' });
     }
     else {
         const searchIndex = path.join(input.outputDir, 'search.json');
@@ -312,41 +450,56 @@ export async function inspectHtml(input) {
         });
     }
     const calloutsScript = path.join(SKILL_DIR, 'scripts', 'checking-callouts.py');
-    const callouts = await runPython(calloutsScript, ['--root', input.root, '--book-dir', input.outputDir], input.root, input.python, spawnFn);
+    const callouts = await runPython(calloutsScript, ['--root', input.root, '--book-dir', input.outputDir], input.root, input.python, spawnFn, input.signal);
     checks.push({
         id: 'callouts',
-        status: callouts.ok ? 'pass' : 'fail',
-        detail: callouts.ok ? lastMeaningfulLine(callouts.output) : `checking-callouts.py：${lastMeaningfulLine(callouts.output)}`,
+        status: pythonEnvironmentFailure(callouts) ? 'skip' : callouts.ok ? 'pass' : 'fail',
+        detail: pythonEnvironmentFailure(callouts)
+            ? `未运行 checking-callouts.py：${lastMeaningfulLine(callouts.output)}`
+            : callouts.ok
+                ? lastMeaningfulLine(callouts.output)
+                : `checking-callouts.py：${lastMeaningfulLine(callouts.output)}`,
     });
-    const allText = [];
-    for (const file of htmlFiles) {
-        const text = await readUtf8(file);
-        if (text)
-            allText.push(text);
-    }
-    for (const name of await listCssFiles(input.outputDir)) {
-        const text = await readUtf8(name);
-        if (text)
-            allText.push(text);
+    if (pythonEnvironmentFailure(callouts)) {
+        errors.push(`checking-callouts.py 未运行：${lastMeaningfulLine(callouts.output)}`);
+    }
+    if (!scaffoldFound) {
+        for (const name of await listCssFiles(input.outputDir)) {
+            const text = await readUtf8(name);
+            if (text && containsScaffold(text)) {
+                scaffoldFound = true;
+                break;
+            }
+        }
     }
-    if (!allText.some(containsScaffold)) {
+    if (!scaffoldFound) {
         checks.push({ id: 'dom', status: 'skip', detail: '产物没有主题脚手架类，跳过 DOM 契约' });
     }
     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);
-        // 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 dom = await runPython(domScript, ['--root', input.root, '--book-dir', input.outputDir], input.root, input.python, spawnFn, input.signal);
+        // C1/C2 依赖主题 CSS，C6/C7/C8 依赖主题资产；没有 theme/ 的书只跑通用契约。
+        const hasTheme = await isDirectory(path.join(input.root, 'theme'));
+        const universal = ['C3', 'C5', 'C9'];
+        const themeOwned = ['C1', 'C2', 'C6', 'C7', 'C8'];
+        const selected = parseDomLines(dom.output).filter((item) => universal.includes(item.id) || (hasTheme && themeOwned.includes(item.id)));
         const failed = selected.filter((item) => item.status === 'fail');
+        const domUnavailable = pythonEnvironmentFailure(dom);
         checks.push({
             id: 'dom',
-            status: selected.length === 0 ? 'fail' : failed.length === 0 ? 'pass' : 'fail',
-            detail: selected.length === 0
-                ? `checking-dom.py 没有返回可解析的契约行：${lastMeaningfulLine(dom.output)}`
-                : failed.length === 0
-                    ? `${selected.length} 项 DOM 契约通过`
-                    : `${failed.map((item) => `${item.id} ${item.detail}`).join('；')}`,
+            status: domUnavailable ? 'skip' : selected.length === 0 ? 'fail' : failed.length === 0 ? 'pass' : 'fail',
+            detail: domUnavailable
+                ? `未运行 checking-dom.py：${lastMeaningfulLine(dom.output)}`
+                : selected.length === 0
+                    ? `checking-dom.py 没有返回可解析的契约行：${lastMeaningfulLine(dom.output)}`
+                    : failed.length === 0
+                        ? hasTheme
+                            ? `${selected.length} 项 DOM 契约通过`
+                            : `${selected.length} 项通用 DOM 契约通过（无 theme/，跳过主题契约）`
+                        : `${failed.map((item) => `${item.id} ${item.detail}`).join('；')}`,
         });
+        if (domUnavailable)
+            errors.push(`checking-dom.py 未运行：${lastMeaningfulLine(dom.output)}`);
     }
     const usable = checks.every((check) => check.status !== 'fail');
     return {
@@ -359,6 +512,14 @@ export async function inspectHtml(input) {
         errors,
     };
 }
+async function isDirectory(dir) {
+    try {
+        return (await stat(dir)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 async function listCssFiles(dir) {
     const files = [];
     async function walk(current) {
@@ -384,7 +545,8 @@ function renderErrorText(result) {
     const tail = result.output.trim();
     if (!tail)
         return `quarto render 退出码 ${result.exit_code ?? '未知'}，没有输出。`;
-    return truncate(tail, 500);
+    // 只保留输出末尾；truncate 从头截断，不能直接拿整段输出调用。
+    return truncate(tail.slice(-500), 500);
 }
 export async function runRenderCheck(input) {
     const root = path.resolve(input.root);
@@ -416,7 +578,7 @@ export async function runRenderCheck(input) {
     }
     const qmdPath = path.resolve(root, input.qmdPath);
     try {
-        await readFile(qmdPath);
+        await stat(qmdPath);
     }
     catch {
         warnings.push(`检查入口 ${input.qmdPath} 不存在，仍按书根执行渲染检查。`);
@@ -426,10 +588,14 @@ export async function runRenderCheck(input) {
         warnings.push(output.warning ?? '渲染输出目录不安全。');
         return result;
     }
+    if (await outputDirEscapesRoot(root, output.resolved)) {
+        warnings.push(`project.output-dir \`${output.value}\` 经符号链接解析后落在书根之外；渲染会写到书外。改回书根内的普通目录后再查。`);
+        return result;
+    }
     result.safe_to_render = true;
     if (input.dryRun)
         return result;
-    const renderResult = await runProcess('quarto', ['render'], root, input.timeoutMs ?? QUARTO_TIMEOUT_MS, input.spawn ?? nodeSpawn);
+    const renderResult = await runProcess('quarto', ['render'], root, input.timeoutMs ?? QUARTO_TIMEOUT_MS, input.spawn ?? nodeSpawn, input.signal);
     result.render_result = {
         ok: renderResult.ok,
         exit_code: renderResult.code,
@@ -454,8 +620,10 @@ export async function runRenderCheck(input) {
         yaml,
         spawn: input.spawn,
         python: input.python,
+        signal: input.signal,
     });
     result.html_report = inspected.report;
+    errors.push(...inspected.errors);
     return result;
 }
 function reportLine(check) {
@@ -469,7 +637,8 @@ function cardLines(value) {
         lines.push(...value.errors);
     if (value.html_report) {
         lines.push(...value.html_report.checks.map(reportLine));
-        lines.push(`首页：${value.html_report.output_files.find((file) => file === 'index.html') ?? '未生成'}`);
+        const indexCheck = value.html_report.checks.find((check) => check.id === 'index_html');
+        lines.push(`首页：${indexCheck?.status === 'pass' ? '已生成' : '未生成'}`);
     }
     return lines;
 }
@@ -481,7 +650,7 @@ function renderSummary(value) {
         return `可渲染：输出目录安全，dry_run 未执行 quarto render。建议输出目录 ${value.suggested_output_dir}。`;
     }
     if (!value.render_result.ok) {
-        return `渲染失败：${value.errors[0] ?? renderErrorText(value.render_result)}`;
+        return value.errors[0] ?? renderErrorText(value.render_result);
     }
     if (!value.html_report) {
         return '渲染完成，但没有生成 HTML 报告。';
@@ -590,7 +759,7 @@ export function registerRenderCheckTool(tools) {
             if (!root) {
                 return refusedResult('当前会话不在 Quarto Book 项目内：需要 git checkout、_quarto.yml 的 type: book，以及至少一个 .qmd 或 .md 源文件。');
             }
-            return runRenderCheck({ root, qmdPath: path.resolve(cwd, args.qmd_path), dryRun: args.dry_run });
+            return runRenderCheck({ root, qmdPath: path.resolve(cwd, args.qmd_path), dryRun: args.dry_run, signal: exec?.signal });
         },
         presentCall(args) {
             return {