picturereader 2.0.0 → 3.0.0

package/src/picturereader-vision.mjs

@@ -0,0 +1,164 @@
+/**
+ * picturereader 视觉孪生 adapter
+ *
+ * 用 Proxy 把已注册的 adapter（如 PiAiAdapter，它服务 opencode-go / deepseek
+ * / xiaomi / qiu 等多个 provider）包装成"孪生"：
+ *
+ *  - listModels / resolveModel：将被勾选的模型标成 inputModalities:['text',
+ *    'image'] + 名称加「(视觉)」后缀 → DSH 原生缩略图/图片块进会话。
+ *  - stream：拦截请求里的 image block → 用 picturereader 本地工具链分析 → 替换
+ *    成文本 → 再转发给原始 adapter（pi-ai 收到纯文本，不会 UNSUPPORTED_CONTENT）。
+ *
+ * @module picturereader/picturereader-vision
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { contentHasImage } from '@deepseek-ai/dsh-llm';
+
+const DSH_HOME = process.env.DSH_HOME || join(homedir(), '.dsh');
+const IMAGE_DIR = join(DSH_HOME, 'picturereader-vision', 'images');
+
+/** 从配置读取被勾选的模型 Map<provider/id, entry>。 */
+function selectedMap(getConfig) {
+  try {
+    const cfg = getConfig?.();
+    const list = cfg?.vision_models;
+    if (!Array.isArray(list)) return new Map();
+    const map = new Map();
+    for (const m of list) {
+      const id = typeof m === 'string' ? m : m.id;
+      const provider = (typeof m === 'object' ? m.provider : '') || '';
+      if (id) map.set(provider + '/' + id, m);
+    }
+    return map;
+  } catch { return new Map(); }
+}
+
+function isSelected(getConfig, provider, id) {
+  const map = selectedMap(getConfig);
+  return map.has(provider + '/' + id);
+}
+
+function noteOf(getConfig, provider, id) {
+  const map = selectedMap(getConfig);
+  const entry = map.get(provider + '/' + id);
+  return entry && typeof entry === 'object' ? (entry.note || '') : '';
+}
+
+/** 给被勾选模型注入视觉元数据（inputModalities / pi-ai 的 input）。 */
+function applyVisionMeta(model, provider, getConfig) {
+  if (!model || !isSelected(getConfig, provider, model.id)) return model;
+  const note = noteOf(getConfig, provider, model.id);
+  const suffix = note ? ` (${note})` : ' (视觉)';
+  const out = { ...model, name: (model.name || model.id) + suffix, inputModalities: ['text', 'image'] };
+  // pi-ai 系列用 `input` 数组；一并注入，保证 resolveModel 也通过。
+  if ('input' in model) out.input = [...model.input, 'image'];
+  return out;
+}
+
+/** 把图片字节落盘为临时文件，返回路径。 */
+async function saveImageBytes(bytes, mediaType) {
+  await mkdir(IMAGE_DIR, { recursive: true });
+  const hash = createHash('sha1').update(bytes).digest('hex').slice(0, 24);
+  const ext = mediaType === 'image/jpeg' ? '.jpg'
+    : mediaType === 'image/webp' ? '.webp'
+      : mediaType === 'image/gif' ? '.gif' : '.png';
+  const path = join(IMAGE_DIR, hash + ext);
+  try { await writeFile(path, bytes, { flag: 'wx' }); } catch (e) { if (e?.code !== 'EEXIST') throw e; }
+  return path;
+}
+
+/** 读图（经 attachments）并做本地说明，返回一段文本证据（path 供工具续读）。 */
+async function analyzeImage(block, attachments) {
+  let data;
+  try {
+    ({ data } = await attachments.readImage(block.attachment));
+  } catch (e) {
+    return `[图片]（读取失败：${e?.message || e}），请用 image_scan 分析附件`;
+  }
+  const path = await saveImageBytes(data, block.attachment.mediaType);
+  return `[用户粘贴了一张图片]\n图片已导出到：${path}\n请先用 image_scan 分析该图片（如含文字再用 image_ocr），结合内容回答。`;
+}
+
+/** 把消息里的 image block 替换成分析文本。 */
+async function sanitizeImages(ctx, messages) {
+  const attachments = ctx.get?.('attachments') ?? ctx.attachments;
+  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; }
+      blocks.push({ type: 'text', text: await analyzeImage(block, attachments) });
+    }
+    next.push({ ...message, content: blocks });
+  }
+  return next;
+}
+
+/**
+ * 对被选中模型所属的 provider，用 Proxy 包装原始 adapter 成孪生并原位替换
+ * registration.adapter（避免 DUPLICATE_ADAPTER）。返回注册数；注册者用 ctx.effect
+ * 在卸载时恢复原 adapter。
+ */
+export function registerTwinAdapters(ctx, llm, getConfig) {
+  if (!llm || !getConfig) return 0;
+  const map = selectedMap(getConfig);
+  const providers = new Set();
+  for (const key of map.keys()) {
+    const prov = key.split('/')[0];
+    if (prov) providers.add(prov);
+  }
+
+  const restores = [];
+  let count = 0;
+  for (const provider of providers) {
+    let reg;
+    try { reg = llm.registration(provider); } catch { continue; }
+    if (!reg || !reg.adapter) continue;
+    const orig = reg.adapter;
+
+    const origList = orig.listModels.bind(orig);
+    const origResolve = orig.resolveModel.bind(orig);
+    const origStream = orig.stream.bind(orig);
+
+    const twin = new Proxy(orig, {
+      get(target, prop, receiver) {
+        if (prop === 'listModels') {
+          return async (p) => (await origList(p)).map((m) => applyVisionMeta(m, p, getConfig));
+        }
+        if (prop === 'resolveModel') {
+          return async (p, m, signal) => applyVisionMeta(await origResolve(p, m, signal), p, getConfig);
+        }
+        if (prop === 'stream') {
+          return async function* (options) {
+            if (options?.messages?.some((msg) => contentHasImage(msg?.content))) {
+              options = { ...options, messages: await sanitizeImages(ctx, options.messages) };
+            }
+            yield* origStream(options);
+          };
+        }
+        const value = Reflect.get(target, prop, receiver);
+        return typeof value === 'function' ? value.bind(target) : value;
+      },
+    });
+
+    reg.adapter = twin;
+    restores.push({ reg, orig });
+    count++;
+  }
+
+  if (count > 0) console.log(`[picturereader] vision twin active on provider(s): ${[...providers].join(', ')}`);
+
+  if (restores.length > 0) {
+    ctx.effect(
+      () => () => { for (const { reg, orig } of restores) reg.adapter = orig; },
+      'picturereader: vision twin restore',
+    );
+  }
+  return count;
+}

package/src/routing.js

@@ -0,0 +1,130 @@
+/**
+ * picturereader 三模式路由 (routing.js)
+ *
+ * 用户在设置卡里选择一个使用模式，控制"什么时候走外部 VLM API、什么时候
+ * 只用本地工具、要不要交叉验证"。这把语义集中在这里，供各工具 / 图片桥 /
+ * vision_analyze 共享，保证行为一致：
+ *
+ * - privacy（隐私）：无论是否配置了外部 API 一律不调用。所有路线只走本地
+ *   （image_scan / image_ocr / image_sample）。硬 gate，绝不外呼。
+ * - smart（智能）：让 LLM 先简单看图（image_scan），再自己选是走外部 API、
+ *   自己看细节、还是 OCR，目标是减少调用轮数与耗时。
+ * - strict（严谨）：LLM 自行选择路线，在必要时交叉验证（多证据对照），
+ *   可以仔细查看细节。
+ *
+ * @module picturereader/routing
+ */
+
+/** 三模式取值。 */
+export const MODES = Object.freeze({
+  privacy: 'privacy',
+  smart: 'smart',
+  strict: 'strict',
+});
+
+/** 三模式中文标签。 */
+export const MODE_LABELS = Object.freeze({
+  privacy: '隐私模式',
+  smart: '智能模式',
+  strict: '严谨模式',
+});
+
+/** 三模式英文标签。 */
+export const MODE_LABELS_EN = Object.freeze({
+  privacy: 'Privacy',
+  smart: 'Smart',
+  strict: 'Strict',
+});
+
+/** 合法模式集合。 */
+export const MODE_KEYS = Object.freeze(Object.keys(MODES));
+
+/** 归一化任意输入为一个合法模式值；非法值回退默认 'smart'。 */
+export function normalizeMode(raw) {
+  const v = String(raw ?? '').trim();
+  return MODE_KEYS.includes(v) ? v : MODES.smart;
+}
+
+/**
+ * 某模式下是否允许调用外部 VLM / 任何网络视觉 API。
+ * 隐私模式为硬门禁：即使配置了外部 API 也不调用。
+ * @param {string} mode - 归一化后的模式。
+ * @returns {boolean} true=允许外呼（smart/strict），false=禁用（privacy）。
+ */
+export function vlmAllowed(mode) {
+  return normalizeMode(mode) !== MODES.privacy;
+}
+
+/**
+ * 隐私模式下即使配置了外部 API 也要强制本地——这是对 vision_analyze /
+ * 图片桥的硬约束说明。
+ */
+export function isPrivacy(mode) {
+  return normalizeMode(mode) === MODES.privacy;
+}
+
+/**
+ * 某模式下 vision_analyze 的推荐证据默认。
+ * @param {string} mode
+ * @returns {{includeScan:boolean, includeOcr:boolean, includeVlm:boolean, allowLowInfo:boolean}}
+ */
+export function visionAnalyzeDefaults(mode) {
+  const m = normalizeMode(mode);
+  if (m === MODES.privacy) {
+    // 隐私：本地证据为主，VLM 永远归零。
+    return { includeScan: true, includeOcr: true, includeVlm: false, allowLowInfo: false };
+  }
+  if (m === MODES.smart) {
+    // 智能：先 scan，OCR 按需，能调外部 VLM（省轮数靠"值得才调"引导）。
+    return { includeScan: true, includeOcr: false, includeVlm: true, allowLowInfo: false };
+  }
+  // strict：全证据 + 允许多看细节，必要时交叉验证。
+  return { includeScan: true, includeOcr: true, includeVlm: true, allowLowInfo: false };
+}
+
+/**
+ * 把模式策略转成给纯文本 LLM 的中文行为引导（用于图片桥 hint、也用于
+ * vision_analyze 的描述构成，让模型据此决定路线）。
+ * @param {string} mode - 归一化后的模式。
+ * @param {{vlmConfigured: boolean}} [opts]
+ * @returns {string} 一段给模型的行为说明。
+ */
+export function routePolicyText(mode, opts = {}) {
+  const m = normalizeMode(mode);
+  const vlmConfigured = opts.vlmConfigured === undefined ? true : !!opts.vlmConfigured;
+  if (m === MODES.privacy) {
+    return (
+      '【当前模式：隐私模式】绝不调用任何外部视觉 API，也不访问网络看模型。' +
+      '对每张图只能使用本地工具：image_scan（看布局/颜色/结构）、image_ocr（读文字）、' +
+      'image_sample（细看材质纹理）。请用这些本地工具自行理解图片内容。'
+    );
+  }
+  if (m === MODES.smart) {
+    return (
+      '【当前模式：智能模式】先用 image_scan 快速看一眼图片（布局/颜色/是否含文字/是否照片）。' +
+      '然后自行判断：' +
+      '（1）若图片以文字为主 → 用 image_ocr 读文字即可，不必调 VLM；' +
+      '（2）若图片是普通图表/界面/简单内容 → 用 image_scan + image_sample 自己看就能说清，不必调 VLM；' +
+      '（3）仅当图片内容复杂、需要语义理解（如照片、抽象画面）' +
+      (vlmConfigured ? '且值得时，才调用 vision_analyze(include_vlm=true) 走外部 VLM' : '）时才尝试 VLM，但当前未配置外部 VLM，尽量用本地工具') +
+      '。目标是减少调用轮数与耗时，能本地就别外呼。'
+    );
+  }
+  return (
+    '【当前模式：严谨模式】自行选择路线并追求可靠：先用 image_scan 了解整体，' +
+    '必要时用 image_ocr 读文字、image_sample 细看细节。对关键判断采用交叉验证：' +
+    '把 image_scan / image_ocr ( / 外部 VLM) 多种证据相互对照，不轻易下结论。' +
+    (vlmConfigured ? '需要语义理解且值得时可用 vision_analyze(include_vlm=true) 走外部 VLM。' : '当前未配置外部 VLM，优先用本地工具自行理解。') +
+    '可以仔细查看细节，但要避免幻觉、给出有依据的描述。'
+  );
+}
+
+/**
+ * 渲染一条批量/桥接时用的简短模式说明（首行），供 hint 复用。
+ * @param {string} mode
+ * @returns {string}
+ */
+export function routeModeTag(mode) {
+  const m = normalizeMode(mode);
+  return `[模式:${MODE_LABELS[m]}]`;
+}

package/src/runtime.js

@@ -0,0 +1,127 @@
+/**
+ * picturereader 运行时配置快照 (runtime.js)
+ *
+ * host 侧（index.js）注册 picturereader 设置命名空间后，把每次读取到的
+ * 最新配置（mode + VLM 显式配置）注入本模块。各工具 / vlm.js /
+ * vision-analyze.js / 图片桥在 execute 时读 getRuntimeConfig() 得到当前
+ * 有效的模式与视觉端点，从而做到"改设置热生效 + privacy 硬 gate"。
+ *
+ * 两种注入方式：
+ *  - setRuntimeConfig(cfg)：直接替换快照（测试 / 手动）。
+ *  - setRuntimeSource(fn)：注册一个返回原始 config 的 getter（host 用
+ *    installSettingsSection 的 getConfig），读取时惰性缓存最新值，保证
+ *    mode / vlm 配置热更立即生效。
+ *
+ * 设计要点：vlm.js 顶部的静态 DEFAULT_BASE 等只是后盾（env / settings.yaml /
+ * GLM 默认），runtime 里显式填写的 vlm 配置优先级最高；而 `mode` 的快照使
+ * privacy 模式在任意调用点都能被识别，彻底拦截外部调用。
+ *
+ * @module picturereader/runtime
+ */
+
+import { normalizeMode } from './routing.js';
+
+let current = { mode: 'smart', vlm: { baseUrl: '', model: '', apiKey: '', apiKeyEnv: '' } };
+let sourceFn = null;
+
+/** 从原始扁平 config 构建快照。 */
+function build(raw) {
+  const v = raw || {};
+  return {
+    mode: normalizeMode(v.mode),
+    vlm: {
+      baseUrl: String(v.vlm_base ?? ''),
+      model: String(v.vlm_model ?? ''),
+      apiKey: String(v.vlm_key ?? ''),
+      apiKeyEnv: String(v.vlm_key_env ?? ''),
+      enabled: v.vlm_enabled === undefined ? Boolean(v.vlm_base) : v.vlm_enabled === true,
+      requestTimeoutMs: v.vlm_timeout_ms !== undefined ? Number(v.vlm_timeout_ms) : undefined,
+      maxTokens: v.vlm_max_tokens !== undefined ? Number(v.vlm_max_tokens) : undefined,
+    },
+    bridge: {
+      exportDir: String(v.bridge_export_dir ?? ''),
+    },
+    ocr: {
+      engine: String(v.ocr_engine ?? 'windows'),
+      language: String(v.ocr_language ?? ''),
+    },
+    scan: {
+      defaultSize: v.scan_default_size !== undefined ? Number(v.scan_default_size) : 32,
+      palette: String(v.scan_palette ?? 'auto'),
+      mode: String(v.scan_mode ?? 'auto'),
+    },
+    batch: {
+      probeFirst: v.batch_probe_first !== undefined ? Number(v.batch_probe_first) : 3,
+      ocrLimitChars: v.batch_ocr_limit_chars !== undefined ? Number(v.batch_ocr_limit_chars) : 800,
+    },
+    doc: {
+      dpi: v.doc_dpi !== undefined ? Number(v.doc_dpi) : 150,
+      maxPages: v.doc_max_pages !== undefined ? Number(v.doc_max_pages) : 50,
+    },
+    maxImageBytes: v.max_image_bytes !== undefined ? Number(v.max_image_bytes) : 52428800,
+    multimodalModels: String(v.multimodal_models ?? '').split(',').map(s => s.trim()).filter(Boolean),
+    requestGuard: v.request_guard !== undefined ? Boolean(v.request_guard) : true,
+    debug: v.debug === true,
+  };
+}
+
+/** 若注册了 source getter，则先同步一次最新值。 */
+function refresh() {
+  if (sourceFn) {
+    try {
+      const raw = sourceFn();
+      if (raw !== undefined && raw !== null) current = build(raw);
+    } catch {
+      // 读取失败则沿用上次快照。
+    }
+  }
+}
+
+/**
+ * 注册一个返回原始 config 的 getter（host：() => getConfig()）。
+ * @param {() => object|null} fn
+ */
+export function setRuntimeSource(fn) {
+  sourceFn = typeof fn === 'function' ? fn : null;
+  refresh();
+}
+
+/**
+ * 直接替换运行时快照（测试 / 手动）。
+ * @param {object} cfg - 支持 {mode, vlm:{...}} 结构，或扁平原始 config
+ *   （含 vlm_base/vlm_model/vlm_key/vlm_key_env）。
+ */
+export function setRuntimeConfig(cfg = {}) {
+  // 兼容扁平原始 config（含 vlm_base/vlm_key 等键）与 (mode, vlm) 结构两种形态。
+  if (cfg && cfg.vlm === undefined && (cfg.vlm_base !== undefined || cfg.mode !== undefined)) {
+    current = build(cfg);
+  } else {
+    const vlm = {
+      baseUrl: String(cfg?.vlm?.baseUrl ?? ''),
+      model: String(cfg?.vlm?.model ?? ''),
+      apiKey: String(cfg?.vlm?.apiKey ?? ''),
+      apiKeyEnv: String(cfg?.vlm?.apiKeyEnv ?? ''),
+      // 选配：显式给定则用之；未给定时向后兼容"配了 baseUrl 即视为启用"。
+      enabled: cfg?.vlm?.enabled ?? Boolean(cfg?.vlm?.baseUrl),
+    };
+    current = { mode: normalizeMode(cfg?.mode), vlm };
+  }
+}
+
+/** 读取运行时快照（返回内部引用；调用方不应修改）。 */
+export function getRuntimeConfig() {
+  refresh();
+  return current;
+}
+
+/** 当前有效模式（已归一化）。 */
+export function currentMode() {
+  refresh();
+  return current.mode;
+}
+
+/** 当前模式下是否允许外部 VLM（privacy 恒 false）。 */
+export function vlmAllowedByRuntime() {
+  refresh();
+  return current.mode !== 'privacy';
+}

package/src/settings-expose.js

@@ -0,0 +1,75 @@
+/**
+ * dsh-host-apiproxy exposes only namespaces listed in its hard-coded
+ * WEB_SETTINGS_NAMESPACES allowlist to the Web settings client. A namespace
+ * registered by a third-party plugin answers `settings-not-exposed` even
+ * though it is registered — upstream explicitly defers letting plugins
+ * expose their own configuration.
+ *
+ * This module idempotently patches that allowlist in the dsh installation
+ * actually loaded by the host process, so the plugin's settings section
+ * becomes visible in the Web UI without manual edits. A dsh update
+ * overwrites the file; the next plugin start re-patches it.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, sep } from "node:path";
+
+/**
+ * Ensure `nsName` is present in dsh-host-apiproxy's WEB_SETTINGS_NAMESPACES.
+ * No-op when already exposed or when the file cannot be located/patched.
+ * @param {import("cordis").Context} ctx
+ * @param {string} nsName - settings namespace short name (e.g. "tdai-memory").
+ * @param {{info?: Function, warn?: Function}} logger - dsh logger.
+ */
+export function ensureSettingsNamespaceExposed(ctx, nsName, logger) {
+  void ctx;
+  try {
+    const target = findApiproxyIndex();
+    if (!target) {
+      logger?.warn?.(`[settings-expose] could not locate dsh-host-apiproxy; add "${nsName}" to WEB_SETTINGS_NAMESPACES in dsh-host-apiproxy/lib/index.js to get a Web settings section`);
+      return;
+    }
+    let src;
+    try {
+      src = readFileSync(target, "utf8");
+    } catch (error) {
+      logger?.warn?.(`[settings-expose] cannot read ${target}: ${String(error)}`);
+      return;
+    }
+    const body = src.match(/const WEB_SETTINGS_NAMESPACES = \[([\s\S]*?)\];/)?.[1] ?? "";
+    if (body.includes(`"${nsName}"`)) return; // already exposed (manual or previous patch)
+    const patched = src.replace(/(const WEB_SETTINGS_NAMESPACES = \[[\s\S]*?)(\n\s*\];)/, (_, pre, post) => {
+      const trailingComma = /,\s*$/.test(pre) ? "" : ",";
+      const sep2 = pre.trimEnd().endsWith("[") ? "" : trailingComma;
+      return `${pre}${sep2}\n\t"${nsName}"${post}`;
+    });
+    if (patched === src) {
+      logger?.warn?.(`[settings-expose] allowlist pattern not found in ${target}; add "${nsName}" to WEB_SETTINGS_NAMESPACES manually`);
+      return;
+    }
+    writeFileSync(target, patched, "utf8");
+    logger?.info?.(`[settings-expose] added "${nsName}" to WEB_SETTINGS_NAMESPACES (${target}) — restart dsh web for the settings section to appear`);
+  } catch (error) {
+    logger?.warn?.(`[settings-expose] failed: ${String(error)}`);
+  }
+}
+
+function findApiproxyIndex() {
+  // 1) The host process has already loaded dsh-host-apiproxy: read the real
+  //    module path from the CommonJS module cache (any install layout).
+  try {
+    const Module = createRequire(import.meta.url)("module");
+    const cache = Module._cache ?? {};
+    for (const key of Object.keys(cache)) {
+      if (key.includes(`${sep}dsh-host-apiproxy${sep}`) && key.endsWith(`${sep}index.js`)) return key;
+    }
+  } catch { /* fall through */ }
+  // 2) Fallback: sibling of @deepseek-ai/dsh-settings (dsh's nested layout).
+  try {
+    const require = createRequire(import.meta.url);
+    const settingsEntry = require.resolve("@deepseek-ai/dsh-settings");
+    const candidate = join(dirname(dirname(dirname(settingsEntry))), "dsh-host-apiproxy", "lib", "index.js");
+    if (existsSync(candidate)) return candidate;
+  } catch { /* fall through */ }
+  return "";
+}

package/src/tool.js

@@ -255,9 +255,9 @@ export function createImageOcrTool(ctx) {
   return {
     name: 'image_ocr',
     description: [
-      'Recognize text in a local image. Two engines: engine="windows" (default) uses the Windows built-in OCR (no install, good for printed/UI text); engine="paddle" uses PaddleOCR via the local paddle_venv (much better for glowing, curved, stylized or game-rendered text and complex backgrounds, Chinese-friendly; ~2s model load per call).',
-      'Use it together with image_scan: when the pixel grid shows a dense, regular, high-contrast structure that looks like text (e.g. titles, labels, buttons, dialogs, glowing banners), call image_ocr on that region and read the actual characters. If the Windows engine returns nothing but text is expected, retry with engine="paddle".',
-      'Parameters: file_path (required), region: [x0, y0, x1, y1] (0..1 fractions) or focus: [row0, col0, row1, col1] (grid coordinates) to restrict recognition to an area, language (optional BCP-47 tag like "zh-Hans" or "en-US", Windows engine only), engine ("windows" default, "paddle").',
+      'Recognize text in a local image. Three engines: engine="windows" (default) uses the Windows built-in OCR (no install, good for printed/UI text); engine="paddle" uses PaddleOCR via the local paddle_venv (much better for glowing, curved, stylized or game-rendered text and complex backgrounds, Chinese-friendly; ~2s model load per call); engine="rapid" uses RapidOCR via the local rapid_venv (bundled ONNX models, no network download, fast).',
+      'Use it together with image_scan: when the pixel grid shows a dense, regular, high-contrast structure that looks like text (e.g. titles, labels, buttons, dialogs, glowing banners), call image_ocr on that region and read the actual characters. If the Windows engine returns nothing but text is expected, retry with engine="paddle" or engine="rapid".',
+      'Parameters: file_path (required), region: [x0, y0, x1, y1] (0..1 fractions) or focus: [row0, col0, row1, col1] (grid coordinates) to restrict recognition to an area, language (optional BCP-47 tag like "zh-Hans" or "en-US", Windows engine only), engine ("windows" default, "paddle", "rapid").',
       'The result lists each recognized line with its pixel bounding box and confidence score (paddle).'
     ].join(' '),
     parameters: {
@@ -284,8 +284,8 @@ export function createImageOcrTool(ctx) {
         },
         engine: {
           type: 'string',
-          enum: ['windows', 'paddle'],
-          description: '"windows" (default) = Windows built-in OCR; "paddle" = PaddleOCR via local paddle_venv (better for glowing/curved/game text).'
+          enum: ['windows', 'paddle', 'rapid'],
+          description: '"windows" (default) = Windows built-in OCR; "paddle" = PaddleOCR via local paddle_venv (better for glowing/curved/game text); "rapid" = RapidOCR via local rapid_venv (bundled ONNX models, fast).'
         }
       },
       required: ['file_path']
@@ -299,7 +299,7 @@ export function createImageOcrTool(ctx) {
           width: { type: 'integer' },
           height: { type: 'integer' },
           region: { type: 'string' },
-          engine: { type: 'string', enum: ['windows', 'paddle'] },
+          engine: { type: 'string', enum: ['windows', 'paddle', 'rapid'] },
           note: { type: 'string' },
           lines: {
             type: 'array',
@@ -349,8 +349,8 @@ export function createImageOcrTool(ctx) {
         throw new Error('image_ocr: language must be a non-empty BCP-47 tag');
       }
       const engine = args.engine === undefined ? 'windows' : String(args.engine);
-      if (engine !== 'windows' && engine !== 'paddle') {
-        throw new Error("image_ocr: engine must be 'windows' (default) or 'paddle'");
+      if (engine !== 'windows' && engine !== 'paddle' && engine !== 'rapid') {
+        throw new Error("image_ocr: engine must be 'windows' (default) or 'paddle' or 'rapid'");
       }
 
       const cwd = exec.agent?.session?.header?.cwd;
@@ -387,13 +387,18 @@ export function createImageOcrTool(ctx) {
         regionDisplay = 'full';
       }
 
-      // PaddleOCR is an optional engine: degrade gracefully to the Windows
-      // engine (with a note) when it is missing or fails — never crash.
+      // PaddleOCR / RapidOCR are optional engines: degrade gracefully to the
+      // Windows engine (with a note) when they are missing or fail — never crash.
+      const OPTIONAL = {
+        paddle: { available: () => core.paddleAvailable(), install: 'node scripts/setup-ocr.mjs' },
+        rapid: { available: () => core.rapidAvailable(), install: 'node scripts/setup-rapid.mjs' }
+      };
       let effectiveEngine = engine;
       let note;
-      if (engine === 'paddle' && !(await core.paddleAvailable())) {
+      const opt = OPTIONAL[engine];
+      if (opt !== undefined && !(await opt.available())) {
         effectiveEngine = 'windows';
-        note = 'PaddleOCR is not installed (engine="paddle" requested) — fell back to Windows OCR. To install it, run: node scripts/setup-ocr.mjs (see README).';
+        note = `${engine[0].toUpperCase()}${engine.slice(1)}OCR is not installed (engine="${engine}" requested) — fell back to Windows OCR. To install it, run: ${opt.install} (see README).`;
       }
       let result;
       try {
@@ -403,9 +408,9 @@ export function createImageOcrTool(ctx) {
           engine: effectiveEngine
         });
       } catch (error) {
-        if (engine === 'paddle' && effectiveEngine === 'paddle') {
+        if (opt !== undefined && effectiveEngine === engine) {
           effectiveEngine = 'windows';
-          note = `PaddleOCR failed (${error.message.slice(0, 140)}) — fell back to Windows OCR.`;
+          note = `${engine[0].toUpperCase()}${engine.slice(1)}OCR failed (${error.message.slice(0, 140)}) — fell back to Windows OCR.`;
           result = await core.ocrImage(data, ext, {
             region: regionArray,
             language: args.language === undefined ? undefined : String(args.language).trim(),

package/src/vision-analyze.js

@@ -21,7 +21,9 @@
 import { extname } from 'node:path';
 import { BYTE_CAP, MAX_PIXELS } from './tool.js';
 import { isLowInformationImage } from './guard.js';
-import { ensureServer, stopServer, sendVisionRequest, defaultVlmConfig, isVlmConfigured } from './vlm.js';
+import { ensureServer, stopServer, sendVisionRequest, defaultVlmConfig, isVlmConfigured, DEFAULT_BASE, DEFAULT_API_KEY } from './vlm.js';
+import { getRuntimeConfig } from './runtime.js';
+import { visionAnalyzeDefaults, isPrivacy, routePolicyText } from './routing.js';
 
 const CORE_URL = new URL('./core.js', import.meta.url).href;
 let coreCache = { url: null, mtime: -1, module: null };
@@ -94,8 +96,8 @@ export function createVisionAnalyzeTool(ctx) {
         },
         ocr_engine: {
           type: 'string',
-          enum: ['windows', 'paddle'],
-          description: 'OCR engine: windows (default) or paddle (better for glowing/curved/game text).'
+          enum: ['windows', 'paddle', 'rapid'],
+          description: 'OCR engine: windows (default), paddle or rapid (see image_ocr for details).'
         },
         include_vlm: {
           type: 'boolean',
@@ -168,15 +170,23 @@ export function createVisionAnalyzeTool(ctx) {
         );
       }
 
-      const includeScan = args.include_scan === undefined ? true : boolArg(args.include_scan, true);
-      const includeOcr = args.include_ocr === undefined ? false : boolArg(args.include_ocr, false);
-      const includeVlm = args.include_vlm === undefined ? true : boolArg(args.include_vlm, true);
+      const rt = getRuntimeConfig();
+      const mode = rt?.mode ?? 'smart';
+      const defaults = visionAnalyzeDefaults(mode);
+      const privacy = isPrivacy(mode);
+      const includeScan = args.include_scan === undefined ? defaults.includeScan : boolArg(args.include_scan, true);
+      const includeOcr = args.include_ocr === undefined ? defaults.includeOcr : boolArg(args.include_ocr, false);
+      // privacy 硬 gate：不管 include_vlm 传什么、外部是否配置，一律不调用 VLM。
+      const includeVlm = privacy ? false : (args.include_vlm === undefined ? defaults.includeVlm : boolArg(args.include_vlm, true));
       const allowLowInfo = boolArg(args.allow_low_info, false);
       const stopAfter = boolArg(args.stop_after, false);
       const prompt = args.prompt ?? 'Describe this image in detail.';
 
-      // Check if VLM is configured
-      const vlmAvailable = isVlmConfigured();
+      // 当前模式的调用策略，注入到返回文本里给主模型做路由引导。
+      const modePolicy = routePolicyText(mode, { vlmConfigured: isVlmConfigured() });
+
+      // Check if VLM is configured (privacy 下恒不可用)
+      const vlmAvailable = privacy ? false : isVlmConfigured();
       const shouldCallVlm = includeVlm && vlmAvailable;
 
       const lowInfo = isLowInformationImage(image.data, image.width, image.height);
@@ -194,11 +204,12 @@ export function createVisionAnalyzeTool(ctx) {
       }
 
       if (includeScan) {
+        const rtScan = rt?.scan || {};
         const analysis = core.analyzeImage(image.data, image.width, image.height, {
-          size: 32,
-          mode: 'auto',
+          size: rtScan.defaultSize || 32,
+          mode: rtScan.mode || 'auto',
           region: undefined,
-          palette: 'auto'
+          palette: rtScan.palette || 'auto'
         });
         scanText = core.renderImageScan({
           path: target.displayPath,
@@ -242,11 +253,22 @@ export function createVisionAnalyzeTool(ctx) {
           }
         }
       } else if (includeVlm && !vlmAvailable) {
-        blocks.push('[vlm] VLM 未配置（SEE_BASE 环境变量为空）');
+        const hasBase = DEFAULT_BASE.length > 0;
+        const hasKey = DEFAULT_API_KEY.length > 0;
+        if (hasBase && !hasKey) {
+          blocks.push('[vlm] VLM 未就绪：已配置端点但缺少 API key。\n' +
+            '要使用免费的 GLM-4V-Flash 视觉模型，请：\n' +
+            '1. 访问 https://open.bigmodel.cn 注册智谱账号\n' +
+            '2. 获取 API Key\n' +
+            '3. 设置环境变量：GLM_API_KEY=你的key 或 SEE_API_KEY=你的key\n' +
+            '4. 重启 DSH 生效');
+        } else {
+          blocks.push('[vlm] VLM 未配置（SEE_BASE 环境变量为空）');
+        }
       }
 
       ctx.emit('fs/observed', target, { kind: 'present', version: info.version }, exec);
-      const combined = blocks.join('\n\n---\n\n');
+      const combined = [modePolicy, ...blocks].join('\n\n---\n\n');
       return {
         path: target.displayPath,
         lowInformation: false,