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

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,88 @@ 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 {
+            const killer = spawnFn('taskkill', ['/pid', String(pid), '/T', '/F'], {
+                cwd,
+                windowsHide: true,
+                shell: false,
+            });
+            // taskkill 启动失败会走异步 error；不监听会成为未处理错误。
+            killer.on('error', () => {
+                // 下面仍会尝试 child.kill，这里只保证异步错误有出口。
+            });
+        }
+        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 +182,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 +216,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 +279,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;
@@ -209,29 +316,85 @@ export async function inspectHtml(input) {
     const errors = [];
     const checks = [];
     const index = path.join(input.outputDir, 'index.html');
-    const indexText = await readUtf8(index);
+    const indexPath = relativeTo(input.root, index);
+    let indexText;
+    let indexDetail;
+    try {
+        const indexStat = await stat(index);
+        if (indexStat.size > MAX_HTML_BYTES) {
+            indexDetail = `${indexPath} 超过 ${Math.round(MAX_HTML_BYTES / 1024 / 1024)} MiB，未读`;
+            errors.push(`${indexPath} 太大，未读`);
+        }
+        else {
+            indexText = await readUtf8(index);
+            indexDetail =
+                indexText === undefined ? `缺少可读的 ${indexPath}` : `${indexPath} 已生成`;
+        }
+    }
+    catch {
+        indexDetail = `缺少可读的 ${indexPath}`;
+    }
     checks.push({
         id: 'index_html',
         status: indexText === undefined ? 'fail' : 'pass',
-        detail: indexText === undefined
-            ? `缺少可读的 ${relativeTo(input.root, index)}`
-            : `${relativeTo(input.root, index)} 已生成`,
+        detail: indexDetail,
     });
     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 替换符`);
         }
-        const marker = MOJIBAKE_MARKERS.find((item) => text.includes(item));
-        if (marker)
-            broken.push(`${relativeTo(input.outputDir, file)} 命中乱码特征「${marker}」`);
+        else {
+            const marker = MOJIBAKE_MARKERS.find((item) => text.includes(item));
+            if (marker)
+                broken.push(`${relative} 命中乱码特征「${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 +414,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 +440,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 +469,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 +531,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 +564,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 +597,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 +607,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 +639,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 +656,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 +669,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 +778,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 {

package/lib/workspace.js

@@ -13,6 +13,7 @@ const BOOK_SOURCE_EXTENSIONS = new Set(['.qmd', '.md']);
 const NON_CHAPTER_FILE_RE = /^(?:readme|changelog|license|licence|contributing|code[_-]of[_-]conduct|security|support|authors|contributors|agents|claude)(?:[.-][a-z0-9_-]+)*\.(?:md|markdown|qmd)$/i;
 const IGNORED_DIRECTORIES = new Set([
     '.git',
+    '.agents',
     '.quarto',
     '.cache',
     '.venv',

package/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "Quarto Book Writing & Theme",
-    "description": "Polish Chinese technical chapters, check book structure and mixed Chinese-English prose, and maintain a consistent, readable theme."
+    "description": "Write, check, and publish a Chinese Quarto Book: nine-step chapter writing, structure/link/figure checks, a consistent theme, and render acceptance."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "Quarto 图书写作与主题",
-    "description": "润色中文技术章节，检查 Book 结构与中英混排，并维护一套统一、可读的阅读主题。"
+    "description": "把一份 Quarto Book 写成可读、可查、可发布的中文技术书：九步章节写作、结构/链接/图表检查、统一主题与渲染验收。"
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chengzhao-dev/dsh-quarto-book",
-  "version": "0.6.3",
-  "description": "润色中文技术章节，检查 Book 结构与中英混排，并维护一套统一、可读的阅读主题。 · Polish Chinese technical chapters, check book structure and mixed Chinese-English prose, and maintain a consistent, readable theme.",
+  "version": "0.6.5",
+  "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",
   "exports": {
@@ -35,8 +35,8 @@
     "catalog": {
       "category": "skill",
       "summary": {
-        "zh": "润色中文技术章节，检查 Book 结构与中英混排，并维护一套统一、可读的阅读主题。",
-        "en": "Polish Chinese technical chapters, check book structure and mixed Chinese-English prose, and maintain a consistent, readable theme."
+        "zh": "把一份 Quarto Book 写成可读、可查、可发布的中文技术书：九步章节写作、结构/链接/图表检查、统一主题与渲染验收。",
+        "en": "Write, check, and publish a Chinese Quarto Book: a nine-step chapter workflow, structure/link/figure checks, a consistent theme, and render acceptance."
       },
       "capabilities": [
         "skills",
@@ -47,8 +47,11 @@
   "icon": "./icon.svg",
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --test tests/*.test.mjs",
-    "check": "tsc --noEmit -p tsconfig.json && node scripts/checking-skill-links.mjs",
+    "test": "npm run build && node --test \"tests/**/*.test.mjs\"",
+    "check": "tsc --noEmit -p tsconfig.json && node scripts/checking-skill-links.mjs && node scripts/checking-skill-budget.mjs && node scripts/checking-package.mjs",
+    "check:lib": "node scripts/checking-lib.mjs",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run check && npm run check:lib",
     "pack": "node -e \"require('fs').mkdirSync('temp',{recursive:true})\" && npm pack --pack-destination temp",
     "pack:check": "npm pack --dry-run"
   },

package/skills/designing-theme/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: designing-theme
-description: 维护 Quarto Book 阅读主题：颜色、字体、间距、导航与 Callout 样式；不用于章节正文
+description: 维护 Quarto Book 阅读主题：颜色、字体、字号、行距、表格与 Callout 样式、导航；不用于章节正文
 metadata:
   short-description: 维护 Quarto 图书主题
 ---

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

@@ -1,6 +1,6 @@
 /* dsh-quarto-book Quarto 主题 · 正文内容（表格 / 引用 / 正文组件与排版；自 common.css 拆分） */
 
-/* ---------- 表格（booktabs：顶/底粗线、表头细线，无行线与竖线） ---------- */
+/* ---------- 表格（booktabs：顶/底细线、表头加粗带浅底，无行线与竖线） ---------- */
 .table {
   --bs-table-hover-bg: transparent;
   /* 表体与正文同档：表格字号一旦小于正文，正文里嵌表格就会出现两次字级跳变，
@@ -12,13 +12,19 @@
   max-width: 100%;
   overflow-x: auto;
   -webkit-overflow-scrolling: touch;
+  /* 列宽随内容分配：不写固定像素，长单元格换行，整表窄屏横向滚动。 */
+  table-layout: auto;
+  margin-block: 1.35rem 1.5rem;
   border: none;
   border-radius: 0;
   font-variant-numeric: tabular-nums;
 }
 .table > :not(caption) > * > * {
-  padding: 0.55rem 0.9rem;
-  vertical-align: baseline;
+  padding: 0.55rem 0.95rem;
+  /* 多行单元格从顶部起排，同一行里短格子不被拉到垂直居中。 */
+  vertical-align: top;
+  /* 长 API 名与长句允许在格内折行，避免把整张表撑出内容列。 */
+  overflow-wrap: break-word;
   border-bottom: 0;
 }
 /* 首尾列贴边，让表格与正文左缘对齐 */
@@ -29,13 +35,15 @@
   padding-inline-end: 0;
 }
 .table thead th {
-  background-color: transparent;
-  font-weight: 600;
-  /* 表头比表体小 1px（17px → 15px），层级靠字重与字号，不靠比顶线更粗的线。 */
+  /* 表头用加粗与一道极浅底色标出层级；不套 .compact-table，列宽仍随内容。 */
+  background-color: color-mix(in srgb, var(--table-border) 24%, transparent);
+  font-weight: 700;
+  /* 表头比表体小 1px（17px → 15px），层级靠字重、字号与底色，不靠更粗的线。 */
   font-size: 0.9375rem;
+  line-height: 1.6;
   text-align: left;
-  padding-top: 0;
-  padding-bottom: 0.45rem;
+  padding-top: 0.5rem;
+  padding-bottom: 0.5rem;
   border-top: 1px solid var(--table-border);
   border-bottom: 1px solid var(--table-border);
 }
@@ -199,6 +207,21 @@ mjx-container[display="true"] {
   box-sizing: border-box;
 }
 
+/* 原生 HTML/SVG 图：图与图注作为一个整体居中；图注在图下，沿用上面的 figure 图注样式。 */
+#quarto-document-content .book-figure {
+  margin: 1.25rem auto;
+  text-align: center;
+}
+#quarto-document-content .book-figure > svg {
+  display: block;
+  margin-inline: auto;
+  max-width: 100%;
+  height: auto;
+}
+#quarto-document-content .book-figure > figcaption {
+  margin-top: 0.5rem;
+}
+
 /* jupyter 单元的图必须用 IPython.display.HTML 输出保持 SVG 内联：image/svg+xml 输出会被
    Quarto 外置成 <img>，无法继承站点 data-bs-theme 明暗与文档字体。text/html 输出不被
    Quarto 识别为图像，fig-cap 退化为图后一个裸 <p>，这里按 figcaption 同款图注样式居中。 */

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

@@ -21,4 +21,4 @@
 2. 新规则必须先标明属于哪一步：能放进已有 `##` 就放进去；只有尺度真的变了才允许新开一步。禁止再写一条不标明步骤的禁令。
 3. 字体、栏宽、颜色决定的理由写进 `knowledge/reading-surface.md`，不在 reference 里重复论证。
 4. 同步更新本文件、`SKILL.md`、`theme-system.md`、知识文件与检查脚本。
-5. 改完运行 `scripts/checking-layout.py` 与整本 `quarto render`；两者都通过才算完成。
+5. 改完运行 `scripts/checking-layout.py`，再用 `quarto_render_check` 做整本渲染；两者都通过才算完成。