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

package/lib/tools/render-check.js

@@ -1,7 +1,7 @@
 // `quarto_render_check`：先判断渲染输出目录是否安全，再在 120 秒内跑一次
-// `quarto render`，最后检查产出的 HTML 是否可发布。失败只报告，不自动重跑。
+// `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 {

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.2",
-  "description": "润色中文技术章节，检查 Book 结构与中英混排，并维护一套统一、可读的阅读主题。 · Polish Chinese technical chapters, check book structure and mixed Chinese-English prose, and maintain a consistent, readable theme.",
+  "version": "0.6.4",
+  "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": {
@@ -19,7 +19,10 @@
     "README.md",
     "README.en.md",
     "LICENSE",
-    "templates"
+    "templates",
+    "!**/__pycache__",
+    "!**/__pycache__/**",
+    "!**/*.pyc"
   ],
   "engines": {
     "node": ">=22",
@@ -32,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",
@@ -44,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/assets/theme/css/content.css

@@ -199,6 +199,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/assets/theme/css/mermaid.css

@@ -105,14 +105,13 @@ body {
   color: var(--body-color) !important;
 }
 
-/* ---------- 类图：按内容测量出宽，容器横向滚动 ----------
-   程序全图页与包在 .class-diagram 里的子图，标签按测量宽绘制；超出栏宽时由 figure 横向滚动。 */
-body.program-map #quarto-document-content .cell-output-display figure.figure,
+/* ---------- 类图：预算优先，容器只做兜底 ----------
+   类图先按 writing-quarto 技能 quarto/mermaid.md 的内容预算删到栏宽以内；
+   这里只保证高度自适应并居中，内容超宽时由容器兜底。 */
 #quarto-document-content .class-diagram .cell-output-display figure.figure {
   overflow-x: auto;
 }
-body.program-map #quarto-document-content .cell-output-display figure.figure svg,
 #quarto-document-content .class-diagram .cell-output-display figure.figure svg {
-  min-width: max-content;
-  max-width: none;
+  height: auto;
+  margin-inline: auto;
 }

package/skills/designing-theme/knowledge/reading-surface.md

@@ -65,7 +65,7 @@ Bright Code 在 16px 下每个 ASCII 字符前进 8px；现在代码正文 15px
 
 编译默认色板是 Flexoki（亮纸 `#FFFCF0`、暗墨 `#100F0F`），Solarized 是读者运行时可选的第二套。两套都只换语义令牌和语法色，不换字体、栏宽与组件。Flexoki 的 callout 是编辑注：2px 左条、无填充、无圆角，note 取中性灰，其余用官方语义色（tip 绿、warning 橙、important 紫、caution 红）。文本对比度按 WCAG 2.2 的 1.4.3（4.5:1）校验：正文、强调、链接、13px 表头、14px 图注与代码标题在各自底色上低于 4.5:1 时升到更实的一档，不改成纯黑或纯白，也不借用语法蓝。链接本身不靠颜色，常态与正文同色并保留下划线；Solarized 的正文与注释抬到 4.5:1，链接回到官方 rebase（base01 / base1），页面底色、强调色与 callout 条保持官方值。
 
-第三套是读者自己的「山光」四时色板（`palettes/hill-light`，取自 `D:\Github\hill-light\hill-light-theme` 的单一色值来源）：晓雾、午荫、暮烟三种浅纸与夜月一种暗纸。它不是照搬原站，而是过一遍本书的令牌契约：保留原站的色相与命名，按本书的 WCAG 4.5:1 校验抬了正文与表头，callout 类型色与代码语法色沿用本书的语义映射（原站的 callout 与代码几乎是单色）。四种时辰里只有夜月是暗色，所以它同时要驱动 Quarto 的 light/dark 基座——`includes/palette.html` 在首帧写 `quarto-color-scheme` 哨兵，运行时对齐 `body` 类；打印时夜月回落到晓雾令牌，纸面不出深底。
+第三套是读者自己的「山光」四时色板（`palettes/hill-light`，取自 `D:\Github\hill-light\hill-light-theme` 的单一色值来源）：晓雾、午荫、暮烟三种浅纸与夜月一种暗纸。它不是照搬原站，而是过一遍本书的令牌约定：保留原站的色相与命名，按本书的 WCAG 4.5:1 校验抬了正文与表头，callout 类型色与代码语法色沿用本书的语义映射（原站的 callout 与代码几乎是单色）。四种时辰里只有夜月是暗色，所以它同时要驱动 Quarto 的 light/dark 基座——`includes/palette.html` 在首帧写 `quarto-color-scheme` 哨兵，运行时对齐 `body` 类；打印时夜月回落到晓雾令牌，纸面不出深底。
 
 ## 抬色记录与保留的低对比项