picturereader 2.0.0 → 3.0.0

package/scripts/doc-to-image.py

@@ -0,0 +1,194 @@
+# -*- coding: utf-8 -*-
+"""
+doc-to-image.py — Office/PDF 逐页转 PNG 渲染脚本（由 DSH document_to_image 工具调用）。
+
+完整链路:
+  .pdf                       ──直接──► PyMuPDF(fitz) 逐页渲染 PNG
+  .docx/.doc/.xlsx/.xls/.pptx/.ppt ──► LibreOffice(soffice) headless 转 PDF ──► fitz 渲染 PNG
+
+用法（argv）:
+  python doc-to-image.py <input> <out_dir> <prefix> <dpi> <max_pages>
+
+  <input>      源文档的绝对本地路径（pdf 或 office 文件；Node 侧已落盘）。
+  <out_dir>    输出目录（已存在；PNG 写到这里）。
+  <prefix>     PNG 文件名前缀，输出形如 <out_dir>/<prefix>_<i>.png，i 从 1 起。
+  <dpi>        渲染分辨率（72..300，默认 150）。
+  <max_pages>  最多渲染前 N 页（默认 50）。
+
+输出:
+  stdout 打印一行 JSON:
+    {"pages": [{"path": "...", "width": 888, "height": 1258, "bytes": 123456}], "page_count": 42, "truncated": false}
+
+  page_count 是文档实际总页数；pages 只含实际渲染的（<= max_pages）页面。
+  任何错误以非零退出码 + stderr 信息返回。
+
+soffice 可执行路径:
+  优先读环境变量 DSH_SOFFICE；未设置则用默认
+  C:/Program Files/LibreOffice/program/soffice.exe，并通过 glob 兜底大小写
+  （实际 Windows 安装是 "Program"/"program" 小写目录）。soffice 缺失时报清晰错误。
+"""
+import glob
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+
+# ---- 常量 ------------------------------------------------------------------
+
+SUPPORTED_EXTS = {".pdf", ".docx", ".doc", ".xlsx", ".xls", ".pptx", ".ppt"}
+OFFICE_EXTS = SUPPORTED_EXTS - {".pdf"}
+DEFAULT_SOFFICE = r"C:/Program Files/LibreOffice/program/soffice.exe"
+SOFFICE_CANDIDATES = (
+    "C:/Program Files/LibreOffice/program/soffice.exe",
+    "C:/Program Files/LibreOffice/Program/soffice.exe",
+    "C:/Program Files (x86)/LibreOffice/program/soffice.exe",
+    "C:/Program Files (x86)/LibreOffice/Program/soffice.exe",
+)
+
+
+def find_soffice():
+    """返回可用的 soffice 可执行路径，找不到返回 None。glob 兜底大小写差异。"""
+    env = os.environ.get("DSH_SOFFICE", "").strip()
+    if env:
+        if os.path.exists(env):
+            return env
+        # 环境变量指了但不存在 -> 继续往下，但先尝试把它的上级目录 glob 一下
+        pattern = os.path.join(os.path.dirname(env), "soffice.exe")
+        for hit in glob.glob(pattern):
+            return hit
+    for cand in SOFFICE_CANDIDATES:
+        if os.path.exists(cand):
+            return cand
+    # 大小写兜底：在标准根目录里找 program* / Program* 下的 soffice.exe
+    for base in ("C:/Program Files/LibreOffice", "C:/Program Files (x86)/LibreOffice"):
+        for sub in ("program", "Program", "PROGRAM", "Program Files"):
+            p = os.path.join(base, sub, "soffice.exe")
+            if os.path.exists(p):
+                return p
+    return None
+
+
+def soffice_to_pdf(src, out_dir, soffice, timeout_s=120):
+    """headless 把 office 文件转成 pdf，返回 pdf 路径。带独立 UserInstallation profile 避免锁冲突。"""
+    profile_dir = os.path.join(out_dir, ".lo_profile")
+    os.makedirs(profile_dir, exist_ok=True)
+    profile_uri = "file:///" + profile_dir.replace("\\", "/")
+    cmd = [
+        soffice,
+        "--headless",
+        "--norestore",
+        "--nofirststartwizard",
+        "-env:UserInstallation=" + profile_uri,
+        "--convert-to", "pdf",
+        "--outdir", out_dir,
+        src,
+    ]
+    # soffice 不开管道，capture_output 会乖乖返回；timeout 兜底防挂起。
+    proc = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout_s)
+    base = os.path.splitext(os.path.basename(src))[0]
+    pdf_path = os.path.join(out_dir, base + ".pdf")
+    if not os.path.exists(pdf_path):
+        msg = "soffice 未产出 pdf"
+        if proc.stderr and proc.stderr.strip():
+            msg += ": " + proc.stderr.strip()[-500:]
+        raise RuntimeError(msg)
+    return pdf_path
+
+
+def render_pdf(pdf_path, out_dir, prefix, dpi, max_pages):
+    """用 fitz 把 pdf 逐页渲染成 PNG，返回 (pages:list[dict], page_count:int, truncated:bool)。"""
+    import fitz  # PyMuPDF
+
+    doc = fitz.open(pdf_path)
+    total = doc.page_count
+    n = min(total, max_pages)
+    pages = []
+    for i in range(n):
+        pix = doc[i].get_pixmap(dpi=dpi)
+        p = os.path.join(out_dir, "{}_{}.png".format(prefix, i + 1))
+        pix.save(p)
+        size = os.path.getsize(p)
+        pages.append({
+            "path": p,
+            "width": pix.width,
+            "height": pix.height,
+            "bytes": size,
+            "index": i + 1,
+        })
+    truncated = total > max_pages
+    return pages, total, truncated
+
+
+def main(argv):
+    if len(argv) < 5:
+        print(json.dumps({"error": "usage: doc-to-image.py <input> <out_dir> <prefix> <dpi> <max_pages>"}))
+        return 2
+
+    src, out_dir, prefix = argv[0], argv[1], argv[2]
+    dpi = int(argv[3])
+    max_pages = int(argv[4])
+
+    if not os.path.exists(src):
+        print(json.dumps({"error": "input file not found: {}".format(src)}))
+        return 1
+
+    ext = os.path.splitext(src)[1].lower()
+    if ext not in SUPPORTED_EXTS:
+        print(json.dumps({"error": "unsupported extension '{}' (supported: {})".format(
+            ext, ", ".join(sorted(SUPPORTED_EXTS)))}))
+        return 1
+
+    os.makedirs(out_dir, exist_ok=True)
+
+    # 1) 得到待渲染的 pdf 路径。
+    pdf_path = None
+    tmp_dir = None
+    if ext == ".pdf":
+        pdf_path = src
+    else:
+        soffice = find_soffice()
+        if not soffice:
+            print(json.dumps({"error": "LibreOffice(soffice) 未找到。请安装 LibreOffice，或设置环境变量 "
+                                        "DSH_SOFFICE 指向 soffice.exe 的可执行路径。"}))
+            return 1
+        # 独立临时目录放中间 pdf，避免多个同 base 文件互覆盖。
+        tmp_dir = tempfile.mkdtemp(prefix="lo_pdf_", dir=out_dir)
+        try:
+            pdf_path = soffice_to_pdf(src, tmp_dir, soffice)
+        except subprocess.TimeoutExpired:
+            print(json.dumps({"error": "soffice 转换超时（>120s），请检查文档是否损坏或过大。"}))
+            return 1
+        except Exception as e:  # noqa: BLE001
+            print(json.dumps({"error": "soffice 转换失败: {}".format(e)}))
+            return 1
+
+    # 2) fitz 渲染。
+    try:
+        pages, page_count, truncated = render_pdf(pdf_path, out_dir, prefix, dpi, max_pages)
+    except Exception as e:  # noqa: BLE001
+        print(json.dumps({"error": "pdf 渲染失败: {}".format(e)}))
+        return 1
+    finally:
+        # 清理中间 pdf 临时目录（保留最终 PNG）。
+        if tmp_dir and os.path.isdir(tmp_dir):
+            shutil.rmtree(tmp_dir, ignore_errors=True)
+
+    print(json.dumps({
+        "pages": pages,
+        "page_count": page_count,
+        "truncated": truncated,
+        "input": os.path.basename(src),
+        "out_dir": out_dir,
+    }))
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        code = main(sys.argv[1:])
+    except Exception as e:  # 顶层兜底：任何未捕获异常都以 JSON error 传出
+        print(json.dumps({"error": "unexpected: {}".format(e)}))
+        code = 1
+    sys.exit(code)

package/scripts/setup-doc-venv.mjs

@@ -0,0 +1,66 @@
+/**
+ * Optional install helper for the document_to_image tool's Python environment.
+ *
+ * The document conversion chain (LibreOffice -> PyMuPDF/fitz) runs in an
+ * isolated venv at C:\Users\Administrator\doc_venv so it does not depend on
+ * the global Python. This script makes sure that venv exists with pymupdf
+ * installed, mirroring the pattern of scripts/setup-ocr.mjs.
+ *
+ * What this does:
+ *  1. Locates the global Python 3.14 interpreter.
+ *  2. Creates doc_venv if missing (from that interpreter).
+ *  3. Installs pymupdf (fitz) into the venv from the Tsinghua PyPI mirror if
+ *     `import fitz` does not already work.
+ *
+ * Idempotent: if the venv python exists and can import fitz, it does nothing.
+ *
+ * Usage: node scripts/setup-doc-venv.mjs
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const BASE_PY = 'C:\\Users\\Administrator\\AppData\\Local\\Programs\\Python\\Python314\\python.exe';
+const VENV_PY = 'C:\\Users\\Administrator\\doc_venv\\Scripts\\python.exe';
+const PYPI = 'https://pypi.tuna.tsinghua.edu.cn/simple';
+
+function run(cmd, args, opts = {}) {
+  console.log(`> ${cmd} ${args.join(' ')}`);
+  const result = spawnSync(cmd, args, { stdio: 'inherit', ...opts });
+  if (result.status !== 0) {
+    console.error(`!! command failed (exit ${result.status})`);
+    process.exit(1);
+  }
+}
+
+// 1. base Python 3.14
+if (existsSync(BASE_PY)) {
+  console.log('[1/3] Global Python 3.14 found at ' + BASE_PY);
+} else {
+  console.error('!! Global Python 3.14 not found at ' + BASE_PY);
+  console.error('    Install Python 3.14, or edit BASE_PY in scripts/setup-doc-venv.mjs to your interpreter.');
+  process.exit(1);
+}
+
+// 2. venv
+if (!existsSync(VENV_PY)) {
+  console.log('[2/3] Creating doc_venv...');
+  mkdirSync(dirname(VENV_PY), { recursive: true });
+  run(BASE_PY, ['-m', 'venv', 'C:\\Users\\Administrator\\doc_venv']);
+} else {
+  console.log('[2/3] doc_venv found');
+}
+
+// 3. pymupdf
+const probe = spawnSync(VENV_PY, ['-c', 'import fitz; print(fitz.__doc__ or fitz.version)'], { encoding: 'utf8' });
+if (probe.status !== 0) {
+  console.log('[3/3] Installing pymupdf (Tsinghua mirror)...');
+  run(VENV_PY, ['-m', 'pip', 'install', '-i', PYPI, '--upgrade', 'pip']);
+  run(VENV_PY, ['-m', 'pip', 'install', '-i', PYPI, 'pymupdf']);
+} else {
+  console.log(`[3/3] pymupdf already installed (${probe.stdout.trim()})`);
+}
+
+console.log('\nDone. document_to_image can now call the doc_venv Python.');
+console.log('Verify: run document_to_image on a small pdf/docx and inspect the returned PNG list.');

package/scripts/setup-rapid.mjs

@@ -0,0 +1,85 @@
+/**
+ * Optional install helper for the RapidOCR engine (image_ocr engine="rapid").
+ * RapidOCR is an OPTIONAL engine — image_ocr degrades to the Windows engine
+ * when it is missing.
+ *
+ * RapidOCR uses the `rapidocr_onnxruntime` package with 3 bundled ONNX models
+ * (det/rec/cls), so no network model download happens on first run.
+ *
+ * What this does:
+ *  1. Ensures a base Python interpreter exists (default: the user Python314).
+ *  2. Creates/repairs the rapid_venv.
+ *  3. Installs rapidocr_onnxruntime from the Tsinghua PyPI mirror.
+ *  4. Warms up by running one recognition on the OCR test image.
+ *
+ * Usage: node scripts/setup-rapid.mjs
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const BASE_PYTHON = process.env.DSH_RAPID_BASE_PYTHON ?? 'C:\\Users\\Administrator\\AppData\\Local\\Programs\\Python\\Python314\\python.exe';
+const VENV = 'C:\\Users\\Administrator\\rapid_venv\\Scripts\\python.exe';
+const PYPI = 'https://pypi.tuna.tsinghua.edu.cn/simple';
+
+function run(cmd, args, opts = {}) {
+  console.log(`> ${cmd} ${args.join(' ')}`);
+  const result = spawnSync(cmd, args, { stdio: 'inherit', ...opts });
+  // pwsh can mis-report pip's Chinese output as exit 1; trust the actual status.
+  if (result.status !== 0) {
+    console.error(`!! command failed (exit ${result.status})`);
+    process.exit(1);
+  }
+}
+
+// 1. base Python
+if (!existsSync(BASE_PYTHON)) {
+  console.error('!! base Python not found at ' + BASE_PYTHON);
+  console.error('   Set DSH_RAPID_BASE_PYTHON to a valid python.exe (3.9+) and rerun.');
+  process.exit(1);
+}
+
+// 2. venv
+if (!existsSync(VENV)) {
+  console.log('[1/3] Creating rapid_venv...');
+  mkdirSync(dirname(VENV), { recursive: true });
+  run(BASE_PYTHON, ['-m', 'venv', 'C:\\Users\\Administrator\\rapid_venv']);
+} else {
+  console.log('[1/3] rapid_venv found');
+}
+
+// 3. rapidocr_onnxruntime
+const probe = spawnSync(VENV, ['-c', 'import rapidocr_onnxruntime; print(rapidocr_onnxruntime.__version__)'], { encoding: 'utf8' });
+if (probe.status !== 0) {
+  console.log('[2/3] Installing rapidocr_onnxruntime (Tsinghua mirror, ~1 min)...');
+  run(VENV, ['-m', 'pip', 'install', '-i', PYPI, '--upgrade', 'pip']);
+  run(VENV, ['-m', 'pip', 'install', '-i', PYPI, 'rapidocr_onnxruntime']);
+} else {
+  console.log(`[2/3] rapidocr_onnxruntime already installed (${probe.stdout.trim()})`);
+}
+
+// 4. warm-up with one recognition
+console.log('[3/3] Warming up RapidOCR (bundled ONNX models — no download)...');
+const testImage = join(dirname(fileURLToPath(import.meta.url)), '..', 'tests', 'fixtures-out', 'ocr-test.png');
+if (existsSync(testImage)) {
+  const warm = spawnSync(VENV, ['-c', [
+    'import json, sys',
+    'from rapidocr_onnxruntime import RapidOCR',
+    "_r, _ = RapidOCR()(sys.argv[1])",
+    'print("warm-up OCR ok, lines:", len(_r or []))'
+  ].join('; '), testImage.replaceAll('\\', '/')], {
+    env: { ...process.env, PYTHONIOENCODING: 'utf-8' },
+    encoding: 'utf8'
+  });
+  if (warm.status !== 0) {
+    console.error('!! warm-up failed — see output above; the engine may still work once models are present');
+    process.exit(1);
+  }
+  console.log(warm.stdout.trim());
+} else {
+  console.log('[3/3] test image missing — skip warm-up (first image_ocr rapid call loads models)');
+}
+
+console.log('\nDone. image_ocr engine="rapid" is now available.');
+console.log('Verify: ask the model to read an image with image_ocr(engine="rapid").');

package/src/bridge.js

@@ -0,0 +1,162 @@
+/**
+ * picturereader 图片桥 (bridge.js)
+ *
+ * DSH 原生支持粘贴图片：粘贴后即生成 image content block，并在输入框/会话里
+ * 渲染缩略图。但主模型一般是纯文本（如 deepseek-v4-flash），若直接把 image
+ * block 发给文本型适配器会 UNSUPPORTED_CONTENT 导致整轮失败。本桥负责把发给
+ * 文本模型的 image block 按当前使用模式降级为"本地图片理解引导"：
+ *
+ *  - agent/pre-step：把进入本轮的消息里的图片降级（privacy 只引导本地工具；
+ *    smart/strict 附带对应策略，并说明何时可考虑 vision_analyze 走外部 VLM）。
+ *  - llm/stream requestGuard：对仍带着 image block 的非多模态请求再兜底一次，
+ *    避免适配器抛错。
+ *
+ * 隐私模式为硬 gate：即使配置了外部 API，降级后的引导也明确"只用本地工具"，
+ * 绝不把图发给任何外部视觉端点。
+ *
+ * @module picturereader/bridge
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import os from 'node:os';
+import { getRuntimeConfig } from './runtime.js';
+import { routePolicyText, routeModeTag } from './routing.js';
+
+const EXT_BY_MEDIA = {
+  'image/png': '.png',
+  'image/jpeg': '.jpg',
+  'image/webp': '.webp',
+  'image/gif': '.gif',
+  'image/bmp': '.bmp',
+  'image/avif': '.avif',
+};
+
+/** 判断消息是否含 image content block。 */
+export function hasImageBlock(messages) {
+  return (messages ?? []).some(
+    (m) => Array.isArray(m?.content) && m.content.some((b) => b?.type === 'image'),
+  );
+}
+
+/** 深冻结（与 harness 对持久消息的冻结一致）。 */
+export function deepFreeze(value) {
+  if (value === null || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  if (Array.isArray(value)) {
+    for (const item of value) deepFreeze(item);
+    return Object.freeze(value);
+  }
+  for (const key of Object.keys(value)) deepFreeze(value[key]);
+  return Object.freeze(value);
+}
+
+/** 导出 attachment 到磁盘，返回路径（按 attachmentId 缓存，进程内复用）。 */
+const exportedPaths = new Map();
+export async function exportImage(attachment, ctx, dir) {
+  const cached = exportedPaths.get(attachment.attachmentId);
+  if (cached) return cached;
+  let data;
+  const attachments = ctx.get?.('attachments') ?? ctx.attachments;
+  try {
+    ({ data } = await attachments.readImage(attachment));
+  } catch (error) {
+    throw new Error(`picturereader: cannot read pasted image: ${String(error && error.message || error)}`);
+  }
+  await mkdir(dir, { recursive: true });
+  const ext = EXT_BY_MEDIA[attachment.mediaType] ?? '.img';
+  const safeName = attachment.name
+    ? attachment.name.replace(/\.[^.]+$/, '').replace(/[^\w\-]+/g, '_').slice(0, 40)
+    : '';
+  const base = (safeName ? `${safeName}_` : '') + attachment.attachmentId.slice(0, 12);
+  const path = join(dir, `${base}${ext}`);
+  await writeFile(path, data);
+  exportedPaths.set(attachment.attachmentId, path);
+  return path;
+}
+
+/**
+ * 把消息里的 image block 替换成文本引导。纯函数（可测）。
+ * 读取当前 runtime mode 生成对应策略。
+ * @param {Array} messages - 待处理消息。
+ * @param {object} ctx - 提供 ctx.attachments。
+ * @param {string} dir - 图片导出目录。
+ * @returns {Promise<Array>} 处理后消息（图片消息被替换成 fresh frozen 对象）。
+ */
+export async function bridgeMessages(messages, ctx, dir) {
+  const mode = getRuntimeConfig()?.mode ?? 'smart';
+  const policy = routePolicyText(mode, { vlmConfigured: true });
+  const next = [];
+  for (const message of messages) {
+    const content = message?.content;
+    if (!Array.isArray(content) || !content.some((b) => b?.type === 'image')) {
+      next.push(message);
+      continue;
+    }
+    const blocks = [];
+    for (const block of content) {
+      if (block?.type !== 'image') {
+        blocks.push(block);
+        continue;
+      }
+      let path;
+      try {
+        path = await exportImage(block.attachment, ctx, dir);
+      } catch {
+        // 导出失败时回退成纯提示，不让整轮崩。
+        blocks.push({ type: 'text', text: '[图片附件已粘贴，将尝试读取分析]' });
+        continue;
+      }
+      const name = block.attachment.name ? `（${block.attachment.name}）` : '';
+      blocks.push({
+        type: 'text',
+        text:
+          `用户粘贴了一张图片${name}，已导出到：${path}\n` +
+          `${routeModeTag(mode)}\n` +
+          policy +
+          `\n请先用 image_scan 分析 ${path}（如含文字再用 image_ocr）。`,
+      });
+    }
+    next.push(deepFreeze({ ...message, content: blocks }));
+  }
+  return next;
+}
+
+/**
+ * 注册图片桥（agent/pre-step 桥 + llm/stream 兜底）。
+ * @param {object} ctx - Cordis 上下文（inject: tools/llm/attachments）。
+ * @param {() => object} 未使用 getConfig —— mode 从 runtime 读，保持实时。
+ */
+export function attachImageBridge(ctx) {
+  // 注意：不在 agent/pre-step 读图降级 —— 该阶段图片 attachment 可能尚未落盘，
+  // readImage 读不到会报错。真正的图片降级/分析放在 llm/stream（适配器层，此时
+  // attachment 已保存）完成。
+
+  // llm/stream 兜底：还带着 image block 的非多模态请求，降级后放行。
+  ctx.on('llm/stream', (options, next) => {
+    console.log('[picturereader] llm/stream fired, model=', options?.model, 'hasImage=', hasImageBlock(options?.messages));
+    return (async function* () {
+      let downstream;
+      try {
+        const rt = getRuntimeConfig();
+        const guardOn = rt?.requestGuard !== false;
+        const multimodal = rt?.multimodalModels || [];
+        const model = options?.model || '';
+        const inWhitelist = multimodal.includes(model);
+        if (guardOn && !inWhitelist && hasImageBlock(options.messages)) {
+          const exportDir = (rt?.bridge?.exportDir || '').trim() || join(os.tmpdir(), 'picturereader-bridge');
+          const before = options.messages.reduce((n, m) => n + (Array.isArray(m?.content) ? m.content.filter(b => b?.type === 'image').length : 0), 0);
+          const messages = await bridgeMessages(options.messages, ctx, exportDir);
+          const after = messages.reduce((n, m) => n + (Array.isArray(m?.content) ? m.content.filter(b => b?.type === 'image').length : 0), 0);
+          const changed = messages.some((m, i) => m !== options.messages[i]);
+          console.log(`[picturereader] llm/stream images before=${before} after=${after} changed=${changed} model=${options.model}`);
+          if (changed) {
+            downstream = next({ ...options, messages });
+          }
+        }
+      } catch (error) {
+        console.log('[picturereader] llm/stream downgrade failed:', String(error && error.message || error));
+      }
+      yield* downstream ?? next();
+    })();
+  });
+}

package/src/config.js

@@ -0,0 +1,70 @@
+/**
+ * picturereader 设置命名空间 (config.js) — 纯逻辑部分
+ *
+ * schema（schemastery）在宿主侧 index.js 定义（DSH 运行时才可解析
+ * @deepseek-ai/schemastery）；本模块只保留可独立测试的解析纯函数。
+ *
+ * 字段采用扁平 key（与 dsh-tool-vision 一致），避免嵌套带来的 YAML 歧义：
+ *   mode            三模式（privacy / smart / strict）
+ *   vlm_base        OpenAI 兼容视觉端点 URL
+ *   vlm_model       视觉模型名
+ *   vlm_key         视觉 API key（role:'secret'，只写不读、保存可覆盖、不回显）
+ *   vlm_key_env     环境变量名（vlm_key 为空时回退读取）
+ *   ocr_engine      默认 OCR 引擎（windows / paddle / rapid）
+ * @module picturereader/config
+ */
+
+/** 本插件拥有的设置命名空间名。 */
+export const NS = 'picturereader';
+
+/** 合法模式（与 routing.MODE_KEYS 一致，避免循环依赖单独声明）。 */
+export const MODE_KEYS = ['privacy', 'smart', 'strict'];
+
+/** 合法 OCR 引擎。 */
+export const OCR_ENGINE_KEYS = ['windows', 'paddle', 'rapid'];
+
+/**
+ * 把扁平配置映射成稳定的模式值（容错非法输入）。
+ * @param {object} value - 原始配置对象。
+ * @returns {'privacy'|'smart'|'strict'}
+ */
+export function modeOf(value) {
+  const m = String(value?.mode ?? 'smart').trim();
+  return MODE_KEYS.includes(m) ? m : 'smart';
+}
+
+/**
+ * 从扁平配置解析 VLM 端点信息。
+ * @param {object} value
+ * @returns {{baseUrl:string, model:string, apiKey:string, apiKeyEnv:string}}
+ */
+export function vlmConfigOf(value) {
+  const v = value ?? {};
+  return {
+    baseUrl: String(v.vlm_base ?? ''),
+    model: String(v.vlm_model ?? ''),
+    apiKey: String(v.vlm_key ?? ''),
+    apiKeyEnv: String(v.vlm_key_env ?? ''),
+  };
+}
+
+/**
+ * 解析默认 OCR 引擎（容错）。
+ * @param {object} value
+ * @returns {'windows'|'paddle'|'rapid'}
+ */
+export function ocrEngineOf(value) {
+  const e = String(value?.ocr_engine ?? 'windows').trim();
+  return OCR_ENGINE_KEYS.includes(e) ? e : 'windows';
+}
+
+/** 读取 API key：优先 vlm_key，其次 环境变量 vlm_key_env，最后 ''。 */
+export function resolveVlmApiKey(vlm) {
+  if (vlm?.apiKey) return vlm.apiKey;
+  const envName = vlm?.apiKeyEnv;
+  if (envName) {
+    const fromEnv = process.env[envName];
+    if (fromEnv) return fromEnv;
+  }
+  return '';
+}