@ggboy123/dsh-paper-reader 1.3.4 → 1.4.0

package/dist/library.js

@@ -6,9 +6,12 @@
 //   <dataDir>/<专题>/<文献>.pages.json   页码偏移表（转录时生成，检索映射页码用）
 // pdf2zh 的产物（-en / -zh / -dual）不算用户文献。
 // （问答不落盘存档——会话持久化交给 dsh 自己；pdfqa 时代的 -qa/ 目录不再读写。）
-import { readdirSync, existsSync, mkdirSync, statSync, renameSync, rmSync } from 'node:fs';
-import { join, resolve, extname, basename } from 'node:path';
+import { readdirSync, existsSync, mkdirSync, statSync, realpathSync, lstatSync } from 'node:fs';
+import { join, resolve, extname, basename, sep } from 'node:path';
 import { homedir } from 'node:os';
+// 破坏性原语与回收站实现（我们的加固层）：适配器只做「复用 #4 边界层 + 翻译签名/返回形状」，
+// 真正的删除/改名永远只有 library-manage 一份实现。
+import * as manage from "./library-manage.js";
 const PDF2ZH_SUFFIXES = ['-en', '-zh', '-dual'];
 /** 判定是否为用户文献：排除 pdf2zh 的中间/产出文件。 */
 export function isPaperPDF(filename) {
@@ -62,6 +65,9 @@ function refFor(topic, name, pdfPath) {
         pdfPath,
         txtPath: base + '.txt',
         pagesPath: base + '.pages.json',
+        transcriptPath: base + '.transcript.json',
+        mineruMdPath: base + '.mineru.md',
+        mineruJsonPath: base + '.mineru.json',
     };
 }
 /**
@@ -101,7 +107,23 @@ export function transcriptCached(ref) {
         return false;
     }
 }
-// ================= 库管理：改名/删除（纯文件系统操作，供 host 路由调用） =================
+// ═══════════════════════════════════════════════════════════════════════════
+// 边界校验层（词法 + realpath 子路径双层）—— **逐字复用上游 #4**
+// （d8f24ec《fix(security)：路径穿越修复》）的实现。
+//
+// 准确口径（评审 F-F，回复上游时按这个说，别写成「唯一实现」）：
+//   · **共享的是 4 个原语**：`validateEntryName` / `validateEntryBoundary` /
+//     `realDataDir` / `assertInside`（其中后两个只多了 `export`，供 library-manage 消费）；
+//   · host.ts 的路由层消费 `validateEntryName` / `validateEntryBoundary`（badEntry 词法门）
+//     与 `resolveUploadTopic`（upload 的 realpath 层）；
+//   · **组合层两套并存**：生产写路径走 library-manage 的 `resolveTopicDirChecked`
+//     （在其上更严：符号链接专题一律拒、`real === join(root, topic)`、`target === root` 拒），
+//     #4 的 `resolveSafeTopic` 组合层只被本文件下方的**适配器**调用，而那些适配器只服务
+//     上游那 6 个 `library-*.test.mjs` 与老调用方。
+// PR #5 整合时我们曾用自己那套「整段替换」掉这一层，代价是丢掉 #4 的两处覆盖
+// （悬空符号链接的写路径、trim 语义）与上游 35 个用例中的 29 个；按上游评审 A.1
+// 「复用 #4 的边界校验层，在其上加回收站与交互层」的要求，原语层照抄、加严叠在其上。
+// ═══════════════════════════════════════════════════════════════════════════
 /** 名字校验（专题/文献共用）。合法返回 null，否则返回中文错误文案。 */
 export function validateEntryName(raw) {
     const name = raw.trim();
@@ -111,84 +133,180 @@ export function validateEntryName(raw) {
         return '名字过长（最多 120 个字符）';
     if (/[\\/]|\.\./.test(name))
         return '名字不能包含 / \\ 或 ..';
+    if (/[\u0000-\u001f\u007f]/.test(name))
+        return '名字不能包含控制字符';
     if (name.startsWith('.'))
         return '名字不能以 . 开头';
     return null;
 }
+/**
+ * 边界类名字校验（删除/改名-from 用）：只挡安全边界——空、分隔符/..、NUL。
+ * 与 validateEntryName 的分工：命名规范类（长度上限、前导点、非 NUL 控制字符）只在创建/改名时
+ * 强制（那是用户在起名字）；删除是对已存在文件的操作——upload 能创建的名字（前导点、超长、
+ * \x01 等控制字符）必须能删，否则会成为无法清理的孤儿。NUL 必须挡：它会让 Node fs 抛
+ * ERR_INVALID_ARG_VALUE 并把绝对路径带进错误文案（错误回显卫生）。
+ */
+export function validateEntryBoundary(raw) {
+    const name = raw.trim();
+    if (!name)
+        return '名字不能为空';
+    if (/[\\/]|\.\./.test(name))
+        return '名字不能包含 / \\ 或 ..';
+    if (name.includes('\u0000'))
+        return '名字不能包含控制字符';
+    return null;
+}
+// ================= 路径穿越防护（词法 + realpath 子路径双层） =================
+// 这些 CRUD 原语以前只对 `to` 做过校验，`topic`/`name`/`from` 直接 `join(dataDir, x)`：
+// `../sentinel` 这类输入会让 rmSync/renameSync 作用于 dataDir 之外的目录（可递归强制删除）。
+// 这里补两层结构性防护：① 词法层（validateEntryName 拒绝 / \ .. 与隐藏名）；② realpath
+// 层（目标目录的 real 路径必须落在 dataDir 的 real 路径之内，挡住 `..` 之外的符号链接逃逸）。
+/** dataDir 的 real 绝对路径（resolve + realpath，去符号链接与 `..`）。目录缺失时给无路径文案。 */
+export function realDataDir(dataDir) {
+    const abs = resolve(dataDir);
+    if (!existsSync(abs))
+        throw new Error('文献库数据目录不存在');
+    return realpathSync(abs);
+}
+/** target 必须落在 root 之内（严格子路径，不含 root 本身），否则视为越界。 */
+export function assertInside(root, target) {
+    const r = root.endsWith(sep) ? root : root + sep;
+    if (target !== root && !target.startsWith(r))
+        throw new Error('路径越界，已拒绝');
+}
+/**
+ * 安全解析专题目录：词法校验 + realpath 严格子路径包含。
+ * 返回可直接 rename/delete 的目录路径（join 后的路径，非 realpath——顶层符号链接对
+ * rmSync/renameSync 只操作链接本身，不跟随，语义保持不变）。任何调用方（不只路由）
+ * 传入越界 topic 都会被拒：`..`、绝对路径、`a/../b`、指向库外的符号链接等。
+ */
+function resolveSafeTopic(dataDir, topic) {
+    const err = validateEntryName(topic);
+    if (err)
+        throw new Error(err);
+    const root = realDataDir(dataDir);
+    const dir = join(root, topic.trim());
+    if (!existsSync(dir))
+        throw new Error(`专题不存在: ${topic.trim()}`);
+    let real;
+    try {
+        real = realpathSync(dir);
+    }
+    catch {
+        throw new Error(`专题不存在: ${topic.trim()}`);
+    }
+    assertInside(root, real);
+    return dir;
+}
+/**
+ * 安全解析「待创建」的专题目录（upload 用）：词法校验 + realpath 严格子路径包含。
+ * 与 resolveSafeTopic 不同：专题可以尚不存在（upload 会 mkdir 创建），但已存在的条目
+ * （目录/文件/符号链接）仍必须 realpath 落在 dataDir 之内——挡住「data/evil → 库外」这类
+ * 符号链接逃逸写。返回可直接 mkdir/writeFile 的目录路径（join 后的路径，非 realpath）。
+ */
+export function resolveUploadTopic(dataDir, topic) {
+    const err = validateEntryName(topic);
+    if (err)
+        throw new Error(err);
+    const root = realDataDir(dataDir);
+    const dir = join(root, topic.trim());
+    let exists = false;
+    try {
+        lstatSync(dir); // lstat 不跟随符号链接：悬空链接也算「已存在」，交给 realpath 兜底
+        exists = true;
+    }
+    catch {
+        exists = false;
+    }
+    if (!exists)
+        return dir; // 尚不存在：mkdir(recursive) 会创建真实目录（词法层已保证无分隔符/../隐藏名）
+    let real;
+    try {
+        real = realpathSync(dir);
+    }
+    catch {
+        throw new Error(`专题不存在: ${topic.trim()}`);
+    }
+    assertInside(root, real);
+    return dir;
+}
 /** 构造文献引用（不做存在性校验；给只按路径判定的调用方用，如翻译 busy 检查）。 */
 export function paperRefFor(dataDir, topic, name) {
     const pdfPath = join(dataDir, topic, name + '.pdf');
     const base = pdfPath.slice(0, -'.pdf'.length);
-    return { topic, name, pdfPath, txtPath: base + '.txt', pagesPath: base + '.pages.json' };
-}
-/** 文献的全部关联文件后缀（含本体 .pdf）：转录缓存 + 页码索引 + babeldoc 译文 + 学习档案。
- *  命名与 translate.ts（-zh/-dual）和 study.ts（.study.json）的产物规则一致。 */
-const PAPER_SIDECARS = ['.pdf', '.txt', '.pages.json', '-zh.pdf', '-dual.pdf', '.study.json'];
-/** 某文献的全部关联文件路径（存在与否由调用方自查）。 */
-export function derivedFilesFor(pdfPath) {
-    const stem = pdfPath.slice(0, -'.pdf'.length);
-    return PAPER_SIDECARS.map((s) => stem + s);
-}
-/** 改名专题（目录 rename）。from 不存在 / to 已存在 / 名字非法 → throw 中文 Error。
- *  已知局限：大小写不敏感文件系统（macOS/Windows）上纯大小写改名会被「目标已存在」
- *  拒绝——不做临时名两跳绕过，保持简单。 */
+    return {
+        topic,
+        name,
+        pdfPath,
+        txtPath: base + '.txt',
+        pagesPath: base + '.pages.json',
+        transcriptPath: base + '.transcript.json',
+        mineruMdPath: base + '.mineru.md',
+        mineruJsonPath: base + '.mineru.json',
+    };
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// 兼容适配器（薄壳）：只为上游 6 个 `library-*.test.mjs` 与老调用方保留上游的
+// 函数签名 / 返回形状；底层永远是 library-manage 的加固实现
+// （回收站可恢复 + 精确 stem + 非递归 rmdir；会话/翻译/在途 409 在路由层）。
+// 每个适配器都**先过上面那一层**（词法 validateEntryName/validateEntryBoundary →
+// realpath resolveSafeTopic），再交给加固层——顺序固定，两层的语义不互相替代。
+// ═══════════════════════════════════════════════════════════════════════════
+/** 边界层错误 → 带机器码的普通 Error（保留上游用例断言的 `e.message`）。 */
+function boundaryError(message) {
+    const err = new Error(message);
+    err.code = message.includes('路径越界') ? 'escape-rejected' : 'bad-name';
+    return err;
+}
+/** 删除文献（上游签名）：词法-边界层 + realpath 层 → 加固层移入 `.trash/`；返回被移动的文件名清单。 */
+export function deletePaper(dataDir, topic, name) {
+    const errName = validateEntryBoundary(name);
+    if (errName)
+        throw boundaryError(errName);
+    const topicName = topic.trim();
+    resolveSafeTopic(dataDir, topicName); // realpath 第二层：专题必须落在 dataDir 内
+    return manage.deletePaper(dataDir, topicName, name).moved;
+}
+/** 删除专题（上游签名）：仅空专题；隐藏条目进回收站；非递归 rmdir（绝无 rm -rf）。 */
+export function deleteTopic(dataDir, topic) {
+    const err = validateEntryName(topic);
+    if (err)
+        throw boundaryError(err);
+    const topicName = topic.trim();
+    resolveSafeTopic(dataDir, topicName);
+    manage.deleteTopic(dataDir, topicName); // 非空 → 抛 409 topic-not-empty（我们的产品决策）
+}
+/** 重命名专题（上游签名）：`to` 走命名规范层，`from` 走 realpath 层。 */
 export function renameTopic(dataDir, from, to) {
     const err = validateEntryName(to);
     if (err)
-        throw new Error(err);
-    if (to.trim() === from)
+        throw boundaryError(err);
+    const fromName = from.trim();
+    const toName = to.trim();
+    if (fromName === toName)
         return;
-    const src = join(dataDir, from);
-    if (!existsSync(src))
-        throw new Error(`专题不存在: ${from}`);
-    const dst = join(dataDir, to.trim());
-    if (existsSync(dst))
-        throw new Error(`已存在同名专题: ${to.trim()}`);
-    renameSync(src, dst);
-}
-/** 改名文献：连带派生文件（转录/页码索引/译文/学习档案）逐个跟随，不存在的跳过。
- *  返回实际改名的文件名清单（含 .pdf 本体）。 */
+    resolveSafeTopic(dataDir, fromName);
+    manage.renameTopic(dataDir, fromName, toName);
+}
+/**
+ * 重命名文献（上游签名）：返回**改名前的**文件名清单（上游用例据此断言，如 `['CaseA.pdf']`）。
+ * `from` 走边界层（历史丑名也能改），`to` 走命名规范层；产物清单由加固层的精确 stem 匹配给出。
+ */
 export function renamePaper(dataDir, topic, from, to) {
-    const err = validateEntryName(to);
-    if (err)
-        throw new Error(err);
-    to = to.trim();
-    if (to === from)
+    const errTo = validateEntryName(to);
+    if (errTo)
+        throw boundaryError(errTo);
+    const errFrom = validateEntryBoundary(from);
+    if (errFrom)
+        throw boundaryError(errFrom);
+    const topicName = topic.trim();
+    const fromName = from.trim();
+    const toName = to.trim();
+    if (fromName === toName)
         return [];
-    const dir = join(dataDir, topic);
-    if (!existsSync(join(dir, from + '.pdf')))
-        throw new Error(`文献不存在: ${topic}/${from}`);
-    if (existsSync(join(dir, to + '.pdf')))
-        throw new Error(`已存在同名文献: ${to}`);
-    const renamed = [];
-    for (const suf of PAPER_SIDECARS) {
-        const src = join(dir, from + suf);
-        if (!existsSync(src))
-            continue;
-        renameSync(src, join(dir, to + suf));
-        renamed.push(from + suf);
-    }
-    return renamed;
-}
-/** 删除文献及其全部派生文件。返回实际删除的文件名清单。 */
-export function deletePaper(dataDir, topic, name) {
-    const dir = join(dataDir, topic);
-    const pdfPath = join(dir, name + '.pdf');
-    if (!existsSync(pdfPath))
-        throw new Error(`文献不存在: ${topic}/${name}`);
-    const deleted = [];
-    for (const f of derivedFilesFor(pdfPath)) {
-        if (!existsSync(f))
-            continue;
-        rmSync(f);
-        deleted.push(basename(f));
-    }
-    return deleted;
-}
-/** 删除专题（递归，含其下全部文献与派生文件）。 */
-export function deleteTopic(dataDir, topic) {
-    const dir = join(dataDir, topic);
-    if (!existsSync(dir))
-        throw new Error(`专题不存在: ${topic}`);
-    rmSync(dir, { recursive: true, force: true });
+    resolveSafeTopic(dataDir, topicName);
+    const topicDir = manage.resolveExistingTopicDir(dataDir, topicName);
+    const before = manage.listArtifacts(topicDir, fromName).map((f) => f.name);
+    manage.renamePaper(dataDir, topicName, fromName, toName);
+    return before;
 }

package/dist/mineru-config.js

@@ -0,0 +1,343 @@
+// mineru-config.ts — MinerU 解析后端的配置落盘与解析（纯函数，不依赖 Cordis）。
+//
+// 存 $DSH_HOME/.dsh-paper-reader/mineru.json（0600）——与 translate/typesafe 同一套约定：
+// dataDir 是文献库目录，可能被 git / 云盘同步，密钥不该跟着走。
+// 优先级（逐字段）：文件 > profile 的 cordis.patch.yml config.mineru > 环境变量 > 默认值。
+// 环境变量只冻结两个：MINERU_API_KEY（cloud.apiKey）、DSH_MINERU_LOCAL_URL（local.baseUrl）。
+// 密钥只落盘、只回显掩码：任何读接口都不返回明文（apiKeyHint 是掩码后的展示串）。
+import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { dshHome } from "./library.js";
+import { maskApiKey } from "./translate-config.js";
+// 预检会把响应体片段拼进错误文案，必须先脱敏（requirements §9.6 / 二轮评审 F-R2-1）。
+// mineru.ts 对 mineru-config.ts 只有 type-only import（运行时无环），这里做值导入是安全的。
+import { sanitizeDetail } from "./mineru.js";
+export { maskApiKey };
+/** 冻结的默认值（§9.2）。mode 默认 off，保证未配置时零行为变化。 */
+export const MINERU_DEFAULTS = {
+    mode: 'off',
+    local: {
+        baseUrl: 'http://127.0.0.1:8000',
+        apiKey: '',
+        backend: 'pipeline',
+        effort: 'medium',
+        parseMethod: 'auto',
+        serverUrl: '',
+        langList: ['ch'],
+        imageAnalysis: false,
+        requestTimeoutMs: 60_000,
+        pollIntervalMs: 1500,
+        noResponseTimeoutMs: 600_000,
+        jobTimeoutMs: 1_800_000,
+    },
+    cloud: {
+        baseUrl: 'https://mineru.net/api/v4',
+        apiKey: '',
+        modelVersion: 'pipeline',
+        pollIntervalMs: 3000,
+        zipTimeoutMs: 300_000,
+    },
+};
+const MODES = ['off', 'local', 'cloud'];
+const BACKENDS = ['pipeline', 'vlm-engine', 'hybrid-engine', 'vlm-http-client', 'hybrid-http-client'];
+const CLOUD_MODELS = ['pipeline', 'vlm'];
+const PARSE_METHODS = ['auto', 'txt', 'ocr'];
+const LANGS = ['ch', 'ch_server', 'korean', 'ta', 'te', 'ka', 'th', 'el', 'arabic', 'east_slavic', 'cyrillic', 'devanagari'];
+export function mineruConfigPath(home = dshHome()) {
+    return join(home, '.dsh-paper-reader', 'mineru.json');
+}
+/** baseUrl 规范化：http(s)://origin + path（去尾斜杠），非法/为空回落到默认值（照抄参考实现）。 */
+export function normalizeLocalBaseUrl(value) {
+    const raw = typeof value === 'string' ? value.trim() : '';
+    if (!raw)
+        return MINERU_DEFAULTS.local.baseUrl;
+    try {
+        const url = new URL(raw);
+        if ((url.protocol === 'http:' || url.protocol === 'https:') && url.host) {
+            const path = url.pathname.replace(/\/+$/, '');
+            return `${url.origin}${path}`;
+        }
+    }
+    catch { /* 非法 URL 回落到默认值 */ }
+    return MINERU_DEFAULTS.local.baseUrl;
+}
+function str(v, fallback) {
+    return typeof v === 'string' ? v : fallback;
+}
+function num(v, fallback) {
+    return typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : fallback;
+}
+function bool(v, fallback) {
+    return typeof v === 'boolean' ? v : fallback;
+}
+function strArr(v, fallback) {
+    if (!Array.isArray(v))
+        return fallback;
+    const out = v.filter((x) => typeof x === 'string');
+    return out.length ? out : fallback;
+}
+function modeOf(v) {
+    return MODES.includes(v) ? v : MINERU_DEFAULTS.mode;
+}
+function backendOf(v) {
+    return BACKENDS.includes(v) ? v : MINERU_DEFAULTS.local.backend;
+}
+function cloudModelOf(v) {
+    return CLOUD_MODELS.includes(v) ? v : MINERU_DEFAULTS.cloud.modelVersion;
+}
+function parseMethodOf(v) {
+    return PARSE_METHODS.includes(v) ? v : MINERU_DEFAULTS.local.parseMethod;
+}
+function langOf(v) {
+    const arr = strArr(v, []);
+    return arr.every((l) => LANGS.includes(l)) ? arr : MINERU_DEFAULTS.local.langList;
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function applyLocal(rec) {
+    const d = MINERU_DEFAULTS.local;
+    if (!rec)
+        return { ...d };
+    return {
+        baseUrl: normalizeLocalBaseUrl(rec['baseUrl'] ?? d.baseUrl),
+        apiKey: str(rec['apiKey'], d.apiKey),
+        backend: backendOf(rec['backend']),
+        effort: rec['effort'] === 'high' ? 'high' : d.effort,
+        parseMethod: parseMethodOf(rec['parseMethod']),
+        serverUrl: str(rec['serverUrl'], d.serverUrl),
+        langList: langOf(rec['langList']),
+        imageAnalysis: bool(rec['imageAnalysis'], d.imageAnalysis),
+        requestTimeoutMs: num(rec['requestTimeoutMs'], d.requestTimeoutMs),
+        pollIntervalMs: num(rec['pollIntervalMs'], d.pollIntervalMs),
+        noResponseTimeoutMs: num(rec['noResponseTimeoutMs'], d.noResponseTimeoutMs),
+        jobTimeoutMs: num(rec['jobTimeoutMs'], d.jobTimeoutMs),
+    };
+}
+function applyCloud(rec) {
+    const d = MINERU_DEFAULTS.cloud;
+    if (!rec)
+        return { ...d };
+    return {
+        baseUrl: str(rec['baseUrl'], d.baseUrl),
+        apiKey: str(rec['apiKey'], d.apiKey),
+        modelVersion: cloudModelOf(rec['modelVersion']),
+        pollIntervalMs: num(rec['pollIntervalMs'], d.pollIntervalMs),
+        zipTimeoutMs: num(rec['zipTimeoutMs'], d.zipTimeoutMs),
+    };
+}
+/** 从原始 JSON 解析出 MineruConfig；没有任何已识别字段时返回 null。 */
+function configFromRecord(data) {
+    if (!isRecord(data))
+        return null;
+    const rec = data;
+    const local = isRecord(rec['local']) ? rec['local'] : undefined;
+    const cloud = isRecord(rec['cloud']) ? rec['cloud'] : undefined;
+    const hasAny = 'mode' in rec || local !== undefined || cloud !== undefined;
+    if (!hasAny)
+        return null;
+    return {
+        mode: modeOf(rec['mode']),
+        local: applyLocal(local),
+        cloud: applyCloud(cloud),
+    };
+}
+/** 读配置文件原始 JSON（不做默认值填充）；文件缺失/损坏/非对象一律返回 null。 */
+export async function readMineruConfigRecord(home = dshHome()) {
+    try {
+        const data = JSON.parse(await readFile(mineruConfigPath(home), 'utf8'));
+        return isRecord(data) ? data : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 读配置；文件缺失/损坏/形状不对一律返回 null（与 translate-config 的读策略一致）。 */
+export async function readMineruConfig(home = dshHome()) {
+    return configFromRecord(await readMineruConfigRecord(home));
+}
+/** 写配置。0600：文件含明文密钥，不靠 umask。 */
+export async function writeMineruConfig(cfg, home = dshHome()) {
+    const file = mineruConfigPath(home);
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, JSON.stringify(cfg, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
+    await chmod(file, 0o600); // mode 只在新建时生效；已存在的文件要显式收紧
+}
+/** 删除配置（回落到 profile / 环境变量）。文件不存在也算成功。 */
+export async function clearMineruConfig(home = dshHome()) {
+    await rm(mineruConfigPath(home), { force: true });
+}
+/** 逐字段合并多个 record：后面的覆盖前面的，只有「定义了」的字段才覆盖；嵌套对象浅合并。 */
+function mergeRecords(...sources) {
+    const out = {};
+    for (const src of sources) {
+        if (!src)
+            continue;
+        for (const [k, v] of Object.entries(src)) {
+            if (v === undefined)
+                continue;
+            if (isRecord(v) && isRecord(out[k])) {
+                out[k] = mergeRecords(out[k], v);
+            }
+            else {
+                out[k] = v;
+            }
+        }
+    }
+    return out;
+}
+/** profile 是否提供了任一 mineru 字段（判定 source 用，§10.3）。 */
+function profileHasFields(profile) {
+    if (!isRecord(profile))
+        return false;
+    return 'mode' in profile || 'local' in profile || 'cloud' in profile;
+}
+/** 解析生效配置：逐字段 file > profile > env > 默认；source 按 §10.3 判定。 */
+export async function resolveMineruConfig(profile, home = dshHome(), env = process.env) {
+    const file = await readMineruConfigRecord(home);
+    // 只有文件里含「已识别的 mineru 字段」才算 file 来源；一个空对象或无关字段的
+    // JSON 不应把来源标成 file（§10.3：文件存在**且含任一 mineru 字段** → file）。
+    const fileRecognized = configFromRecord(file) !== null;
+    const envKey = env['MINERU_API_KEY']?.trim();
+    const envLocalUrl = env['DSH_MINERU_LOCAL_URL']?.trim();
+    // 环境变量层：只冻结两个变量，命中才参与合并（§9.4）
+    const envLocal = {};
+    if (envLocalUrl)
+        envLocal['baseUrl'] = envLocalUrl;
+    const envCloud = {};
+    if (envKey)
+        envCloud['apiKey'] = envKey;
+    const envRec = {};
+    if (Object.keys(envLocal).length)
+        envRec['local'] = envLocal;
+    if (Object.keys(envCloud).length)
+        envRec['cloud'] = envCloud;
+    // 合并顺序（后面的覆盖前面的）：默认 ← env ← profile ← file（§9.5 优先级）
+    const merged = mergeRecords(envRec, profile, file);
+    const config = configFromRecord(merged) ?? configFromRecord({ mode: MINERU_DEFAULTS.mode });
+    const source = fileRecognized
+        ? 'file'
+        : profileHasFields(profile)
+            ? 'profile'
+            : (envKey || envLocalUrl) ? 'env' : 'none';
+    return { config, source };
+}
+/** 连通性预检：GET {baseUrl}/health（超时 5s）。判据与 §2.1 一致。 */
+export async function testMineruLocal(baseUrl, timeoutMs = 5000) {
+    const base = normalizeLocalBaseUrl(baseUrl);
+    try {
+        const r = await fetch(`${base}/health`, { signal: AbortSignal.timeout(timeoutMs) });
+        const text = (await r.text().catch(() => '')).slice(0, 2000);
+        let data = null;
+        try {
+            data = JSON.parse(text);
+        }
+        catch { /* 非 JSON 走失败 */ }
+        if (!r.ok) {
+            // 响应体片段先脱敏再拼入（同 F-R2-1 的处理；此处不发 apiKey，属统一的模式加固）
+            return { ok: false, detail: `HTTP ${r.status}${text ? ' ' + sanitizeDetail(text.slice(0, 120)) : ''}` };
+        }
+        if (!isRecord(data)) {
+            return { ok: false, detail: '响应不是 JSON' };
+        }
+        if (!['healthy', 'ok'].includes(String(data['status'])) || typeof data['version'] !== 'string') {
+            return { ok: false, detail: '不是已识别的 MinerU API 服务（status/version 缺失）' };
+        }
+        return { ok: true, version: data['version'], health: data };
+    }
+    catch (err) {
+        const cause = err instanceof Error && err.cause instanceof Error ? `: ${err.cause.message}` : '';
+        return { ok: false, detail: (err instanceof Error ? err.message : String(err)) + cause };
+    }
+}
+/**
+ * 云端 token 失效类业务码。mineru.net 可能以 **HTTP 200 + body.code** 的形式返回 token 错误，
+ * 只判 401/403 会把坏 token 当「连通且有效」放行（评审 F1）。判据见 requirements §9.7：
+ * 「401/403 / code A0202/A0211 → 报 token 错」。
+ * 刻意**不**把 -60012/-60013 等「批次/任务不存在或无权」类码算进来——预检打的就是一个不存在的
+ * 批次（`_test`），那类码是预期内的成功信号。
+ */
+const CLOUD_TOKEN_ERROR_CODES = new Set(['A0202', 'A0211']);
+/** 云端预检：GET {baseUrl}/extract-results/batch/_test（故意不存在的批次 id）。 */
+export async function testMineruCloud(baseUrl, apiKey, timeoutMs = 15_000) {
+    const base = baseUrl.replace(/\/+$/, '') || MINERU_DEFAULTS.cloud.baseUrl;
+    if (!apiKey)
+        return { ok: false, detail: '云端 API Key 不能为空' };
+    try {
+        const r = await fetch(`${base}/extract-results/batch/_test`, {
+            headers: { authorization: `Bearer ${apiKey}` },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (r.status === 401 || r.status === 403) {
+            return { ok: false, detail: `HTTP ${r.status}：云端 token 无效或已过期（请检查 mineru.net 的 API Key）` };
+        }
+        const text = (await r.text().catch(() => '')).slice(0, 2000);
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            // 非 JSON 响应体可能回显 Authorization/错误页：先按本次 key 脱敏再截断拼入（F-R2-1）
+            return { ok: false, detail: `响应不是 JSON（HTTP ${r.status}）：${sanitizeDetail(text.slice(0, 120), apiKey)}` };
+        }
+        // HTTP 200 也可能是 token 失效（业务码判据，§9.7 / 评审 F1）：不查 body.code 会「假绿灯」落盘坏 token
+        const code = isRecord(body) ? String(body['code'] ?? '').trim().toUpperCase() : '';
+        if (CLOUD_TOKEN_ERROR_CODES.has(code)) {
+            return { ok: false, detail: `云端 token 无效或已过期（业务码 ${code}，请检查 mineru.net 的 API Key）` };
+        }
+        // 能拿到 JSON 响应（含业务级「批次不存在」）即视为「连通 + token 有效」（§9.7）。
+        return { ok: true };
+    }
+    catch (err) {
+        const cause = err instanceof Error && err.cause instanceof Error ? `: ${err.cause.message}` : '';
+        return { ok: false, detail: (err instanceof Error ? err.message : String(err)) + cause };
+    }
+}
+/** 按生效 mode 分发预检。mode=off 无需预检直接通过。 */
+export async function precheckMineruConfig(config) {
+    if (config.mode === 'off')
+        return { ok: true };
+    if (config.mode === 'local') {
+        const t = await testMineruLocal(config.local.baseUrl);
+        return t.ok ? { ok: true } : { ok: false, detail: `本地 MinerU 连接测试失败：${t.detail ?? '未知原因'}` };
+    }
+    const t = await testMineruCloud(config.cloud.baseUrl, config.cloud.apiKey);
+    return t.ok ? { ok: true } : { ok: false, detail: `云端 MinerU 连接测试失败：${t.detail ?? '未知原因'}` };
+}
+/** 把设置面板 POST 的 body 合并进已有生效配置：apiKey 留空沿用已存值；非法枚举回落已有值；超时等不暴露字段保持原样。 */
+export function mergeMineruBody(prev, body) {
+    const rec = isRecord(body) ? body : {};
+    const localRec = isRecord(rec['local']) ? rec['local'] : {};
+    const cloudRec = isRecord(rec['cloud']) ? rec['cloud'] : {};
+    const localBaseUrl = typeof localRec['baseUrl'] === 'string' && localRec['baseUrl'].trim()
+        ? normalizeLocalBaseUrl(localRec['baseUrl'])
+        : prev.local.baseUrl;
+    const localApiKey = typeof localRec['apiKey'] === 'string' ? localRec['apiKey'].trim() : '';
+    const cloudBaseUrlRaw = typeof cloudRec['baseUrl'] === 'string' ? cloudRec['baseUrl'].trim() : '';
+    const cloudBaseUrl = cloudBaseUrlRaw || prev.cloud.baseUrl;
+    const cloudApiKey = typeof cloudRec['apiKey'] === 'string' ? cloudRec['apiKey'].trim() : '';
+    return {
+        mode: modeOf(rec['mode'] ?? prev.mode),
+        local: {
+            baseUrl: localBaseUrl,
+            apiKey: localApiKey || prev.local.apiKey,
+            backend: backendOf(localRec['backend'] ?? prev.local.backend),
+            effort: localRec['effort'] === 'high' || localRec['effort'] === 'medium' ? localRec['effort'] : prev.local.effort,
+            parseMethod: parseMethodOf(localRec['parseMethod'] ?? prev.local.parseMethod),
+            serverUrl: typeof localRec['serverUrl'] === 'string' ? localRec['serverUrl'].trim() : prev.local.serverUrl,
+            langList: localRec['langList'] !== undefined ? langOf(localRec['langList']) : prev.local.langList,
+            imageAnalysis: typeof localRec['imageAnalysis'] === 'boolean' ? localRec['imageAnalysis'] : prev.local.imageAnalysis,
+            requestTimeoutMs: prev.local.requestTimeoutMs,
+            pollIntervalMs: prev.local.pollIntervalMs,
+            noResponseTimeoutMs: prev.local.noResponseTimeoutMs,
+            jobTimeoutMs: prev.local.jobTimeoutMs,
+        },
+        cloud: {
+            baseUrl: cloudBaseUrl,
+            apiKey: cloudApiKey || prev.cloud.apiKey,
+            modelVersion: cloudModelOf(cloudRec['modelVersion'] ?? prev.cloud.modelVersion),
+            pollIntervalMs: prev.cloud.pollIntervalMs,
+            zipTimeoutMs: prev.cloud.zipTimeoutMs,
+        },
+    };
+}