@xlight-oss/visionary-dsh 0.6.1 → 0.7.0

package/lib/index.mjs

@@ -14,6 +14,7 @@
 
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import z from "@deepseek-ai/schemastery";
+import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
 import { spawn } from "node:child_process";
 import { statSync, readFileSync } from "node:fs";
 import { promises as fs } from "node:fs";
@@ -23,9 +24,12 @@ import path from "node:path";
 const name = "visionary-vision";
 const inject = ["tools", "systemPrompt"];
 
+/** Settings namespace（面板 / settings.yaml 双入口，规范：dsh-plugin 设置面板上传路径配置）。 */
+const SETTINGS_NAMESPACE = settingsNamespace("visionary-vision");
+
 // Keep in lockstep with the Rust binary's minor version: tools rely on the
 // CLI's `--json` output shape. Bump when the binary's contract changes.
-const COMPAT_MINOR = "0.6";
+const COMPAT_MINOR = "0.7";
 
 const Config = z.object({
   binaryPath: z
@@ -43,11 +47,17 @@ const Config = z.object({
   visionTimeoutMs: z
     .number()
     .default(300000)
-    .description("Per deepseek_vision call timeout in ms."),
+    .description("Per deepseek_vision / deepseek_ocr call timeout in ms."),
   statusTimeoutMs: z
     .number()
     .default(60000)
     .description("Per deepseek_vision_status / deepseek_vision_logout timeout in ms."),
+  modelType: z
+    .union([z.const("vision"), z.const("ocr")])
+    .default("vision")
+    .description(
+      "上传管道：vision（默认，完整多模态图像理解，携带 x-model-type: vision）| ocr（文本提取，不携带 x-model-type，走服务端 OCR 管道）。deepseek_vision 按此上传；deepseek_ocr 恒为 ocr。覆盖 CLI 默认配置，修改后即时生效。"
+    ),
 });
 
 // --- binary resolution -------------------------------------------------------
@@ -222,6 +232,56 @@ async function materializeImage(image) {
   return { arg: image, cleanup: null };
 }
 
+// --- CLI 参数构建 --------------------------------------------------------------
+
+// 构建 vision / ocr 子命令的 argv（纯函数，便于测试）。
+// 选项一律等号传参（`--prompt=<v>`），避免 clap 把 `-` 开头的空格形式值当 flag 拒绝。
+// `modelType` 仅对 vision 子命令生效：ocr 时追加 `--model-type=ocr`（其余情况不追加，
+// CLI 默认即 vision）；`ocr` 子命令不暴露 `--model-type`（恒为 ocr）。
+function buildImageCliArgs(subcommand, images, opts) {
+  const cliArgs = [subcommand, ...images, "--json"];
+  if (opts?.prompt) cliArgs.push(`--prompt=${opts.prompt}`);
+  if (opts?.thinking) cliArgs.push("--thinking");
+  if (opts?.sessionId) cliArgs.push(`--session-id=${opts.sessionId}`);
+  else if (opts?.continueConversation) cliArgs.push("--continue-conversation");
+  if (subcommand === "vision" && opts?.modelType === "ocr") cliArgs.push("--model-type=ocr");
+  return cliArgs;
+}
+
+// deepseek_vision / deepseek_ocr 共用参数 schema（原生工具面，规范对齐对应 MCP 工具）。
+const imageToolParams = {
+  images: {
+    type: "array",
+    items: { type: "string" },
+    description: "One or more images: local file paths, base64, or data URIs. The model analyzes all of them together.",
+  },
+  image: {
+    type: "string",
+    description: "Single image (local path, base64, or data URI) — convenience form of `images` with one entry.",
+  },
+  prompt: {
+    type: "string",
+    description: "Question about the image(s) (default: detailed description in Chinese).",
+  },
+  thinking: {
+    type: "boolean",
+    description: "Enable DeepThink deep reasoning.",
+  },
+  continue_conversation: {
+    type: "boolean",
+    description: "Continue the previous session (multi-image comparison across turns).",
+  },
+  session_id: {
+    type: "string",
+    description: "Reuse an explicit session thread (takes precedence over continue_conversation).",
+  },
+};
+
+const imageToolOutput = {
+  schema: { type: "string" },
+  render: (_args, value) => [{ type: "text", text: value }],
+};
+
 // --- version probe (apply-time, fire-and-forget) -----------------------------
 
 function parseMinor(v) {
@@ -232,18 +292,32 @@ function parseMinor(v) {
 // --- tools -------------------------------------------------------------------
 
 function apply(ctx, config) {
+  // 运行态配置：settings 面板 / settings.yaml 写入经 source() 即时生效（热重载），
+  // 无 settings 服务时回退到插件行 entry config。所有工具调用都从 runtime 读取，
+  // 而不是冻结的 config —— 设置面板切换 modelType（vision|ocr）无需重启 DSH。
+  let runtime = { ...config };
+  let source = () => config;
+  installSettingsSection(ctx, SETTINGS_NAMESPACE, Config, config, {
+    setSource: (thunk) => {
+      source = thunk;
+    },
+    onChange: () => {
+      runtime = { ...source() };
+    },
+  });
+
   const loginSeconds = (() => {
     const raw = Number(process.env.DEEPSEEK_LOGIN_TIMEOUT);
     if (Number.isFinite(raw) && raw > 0) return raw;
-    return config.loginTimeoutSeconds > 0 ? config.loginTimeoutSeconds : 600;
+    return runtime.loginTimeoutSeconds > 0 ? runtime.loginTimeoutSeconds : 600;
   })();
 
   // 版本探测：apply 时 fire-and-forget（仅用于结果附带版本警告）。
   // 注意：二进制路径【不在此缓存】——每次工具调用经 requireBinary()
-  // 重新 resolveBinaryPath(config)，用户修改 PATH / DEEPSEEK_VISIONARY_BIN
+  // 重新 resolveBinaryPath(runtime)，用户修改 PATH / DEEPSEEK_VISIONARY_BIN
   // 后无需重启 DSH 即生效（懒解析，成本为数次 statSync）。
   let versionInfo = { known: false, compatible: true, version: "" };
-  const probeBinary = resolveBinaryPath(config);
+  const probeBinary = resolveBinaryPath(runtime);
   if (probeBinary) {
     runCli(probeBinary, ["--version"], { timeoutMs: 5000 })
       .then((r) => {
@@ -273,10 +347,12 @@ function apply(ctx, config) {
         "",
         "You have native vision tools backed by DeepSeek's web vision model (no API key):",
         "- `deepseek_vision` — analyze one or more images (local path / base64 / data URI; use `images` for multiple)",
+        "- `deepseek_ocr` — extract raw text from an image (text extraction, not interpretation): document/PDF/terminal screenshots, code, signs",
         "- `deepseek_vision_status` — check login state",
         "- `deepseek_vision_login` — browser auto-login",
         "- `deepseek_vision_logout` — clear saved credentials",
         "",
+        "Use `deepseek_vision` for understanding an image; use `deepseek_ocr` when the user wants the text content of an image verbatim.",
         "Prefer these native tools over invoking `visionary-server` through the shell: native tools run in the host process, so session continuation and login are not restricted by the bash sandbox.",
         "The `image`/`images` paths passed to `deepseek_vision` are read and uploaded to the DeepSeek service — only pass paths the user intends to share.",
       ].join("\n"),
@@ -285,95 +361,110 @@ function apply(ctx, config) {
 
   // 懒解析：每次工具调用重新定位二进制（PATH / 环境变量改动即时生效）。
   const requireBinary = () => {
-    const binary = resolveBinaryPath(config);
+    const binary = resolveBinaryPath(runtime);
     if (!binary) throw new Error(binaryMissingHelp());
     return binary;
   };
 
+  // deepseek_vision / deepseek_ocr 共享执行（materialize → spawn → 原子 JSON 解析）。
+  // `subcommand`：本轮 spawn 的 CLI 子命令；`modelType` 仅 vision 生效（见
+  // buildImageCliArgs）。ocr 工具恒为 ocr 子命令，不受 config.modelType 影响。
+  async function runImageAnalysis({ subcommand, name, imageInputs, args, exec }) {
+    const bin = requireBinary();
+    if (imageInputs.length === 0) {
+      throw new Error(`${name}: at least one image is required (\`images\` or \`image\`)`);
+    }
+    const materialized = [];
+    try {
+      for (const image of imageInputs) {
+        materialized.push(await materializeImage(image));
+      }
+      const cliArgs = buildImageCliArgs(
+        subcommand,
+        materialized.map((m) => m.arg),
+        {
+          prompt: args.prompt,
+          thinking: args.thinking,
+          sessionId: args.session_id,
+          continueConversation: args.continue_conversation,
+          modelType: subcommand === "vision" ? runtime.modelType : undefined,
+        },
+      );
+
+      const r = await runCli(bin, cliArgs, {
+        timeoutMs: runtime.visionTimeoutMs,
+        signal: exec.signal,
+      });
+      if (r.killed) throw new Error(`${name} was aborted or timed out`);
+      let parsed = null;
+      try {
+        parsed = JSON.parse(r.stdout);
+      } catch {
+        parsed = null;
+      }
+      if (parsed && typeof parsed.error === "string") {
+        throw new Error(parsed.error);
+      }
+      if (parsed && typeof parsed.text === "string") {
+        const meta = [`session_id: ${parsed.session_id}`, `parent_message_id: ${parsed.parent_message_id}`]
+          .filter((s) => !s.endsWith(": null") && !s.endsWith(": undefined"))
+          .join(", ");
+        return withVersionWarning(meta ? `${parsed.text}\n\n[${meta}]` : parsed.text);
+      }
+      throw new Error(
+        `${name} failed (exit ${r.code}): ${(r.stderr || r.stdout).trim() || "unknown error"}`
+      );
+    } finally {
+      for (const m of materialized) if (m.cleanup) await m.cleanup();
+    }
+  }
+
   ctx.tools.register(
     defineTool({
       name: "deepseek_vision",
       description:
         "Analyze one or more images with DeepSeek's web vision model (local path / base64 / data URI). Pass multiple images via `images` to have the model analyze them together in one call (like the DeepSeek website). Use for screenshots, photos, or documents with images. Supports multi-turn conversation via continue_conversation / session_id.",
-      parameters: {
-        images: {
-          type: "array",
-          items: { type: "string" },
-          description: "One or more images: local file paths, base64, or data URIs. The model analyzes all of them together.",
-        },
-        image: {
-          type: "string",
-          description: "Single image (local path, base64, or data URI) — convenience form of `images` with one entry.",
-        },
-        prompt: {
-          type: "string",
-          description: "Question about the image(s) (default: detailed description in Chinese).",
-        },
-        thinking: {
-          type: "boolean",
-          description: "Enable DeepThink deep reasoning.",
-        },
-        continue_conversation: {
-          type: "boolean",
-          description: "Continue the previous session (multi-image comparison across turns).",
-        },
-        session_id: {
-          type: "string",
-          description: "Reuse an explicit session thread (takes precedence over continue_conversation).",
-        },
-      },
-      output: {
-        schema: { type: "string" },
-        render: (_args, value) => [{ type: "text", text: value }],
+      parameters: imageToolParams,
+      output: imageToolOutput,
+      timeoutMs: runtime.visionTimeoutMs,
+      async execute(args, exec) {
+        const imageInputs = Array.isArray(args.images) && args.images.length > 0
+          ? args.images
+          : args.image
+            ? [args.image]
+            : [];
+        return runImageAnalysis({
+          subcommand: "vision",
+          name: "deepseek_vision",
+          imageInputs,
+          args,
+          exec,
+        });
       },
-      timeoutMs: config.visionTimeoutMs,
+    })
+  );
+
+  ctx.tools.register(
+    defineTool({
+      name: "deepseek_ocr",
+      description:
+        "Extract raw text from one or more images with DeepSeek's OCR pipeline (local path / base64 / data URI), equivalent to `visionary-server ocr`. Use for the text content of a screenshot or document — document/PDF screenshots, code, signs, tables (not interpretation). Text is extracted verbatim by default. Supports multi-turn conversation via continue_conversation / session_id.",
+      parameters: imageToolParams,
+      output: imageToolOutput,
+      timeoutMs: runtime.visionTimeoutMs,
       async execute(args, exec) {
-        const bin = requireBinary();
         const imageInputs = Array.isArray(args.images) && args.images.length > 0
           ? args.images
           : args.image
             ? [args.image]
             : [];
-        if (imageInputs.length === 0) {
-          throw new Error("deepseek_vision: at least one image is required (`images` or `image`)");
-        }
-        const materialized = [];
-        try {
-          for (const image of imageInputs) {
-            materialized.push(await materializeImage(image));
-          }
-          const cliArgs = ["vision", ...materialized.map((m) => m.arg), "--json"];
-          if (args.prompt) cliArgs.push(`--prompt=${args.prompt}`);
-          if (args.thinking) cliArgs.push("--thinking");
-          if (args.session_id) cliArgs.push(`--session-id=${args.session_id}`);
-          else if (args.continue_conversation) cliArgs.push("--continue-conversation");
-
-          const r = await runCli(bin, cliArgs, {
-            timeoutMs: config.visionTimeoutMs,
-            signal: exec.signal,
-          });
-          if (r.killed) throw new Error("deepseek_vision was aborted or timed out");
-          let parsed = null;
-          try {
-            parsed = JSON.parse(r.stdout);
-          } catch {
-            parsed = null;
-          }
-          if (parsed && typeof parsed.error === "string") {
-            throw new Error(parsed.error);
-          }
-          if (parsed && typeof parsed.text === "string") {
-            const meta = [`session_id: ${parsed.session_id}`, `parent_message_id: ${parsed.parent_message_id}`]
-              .filter((s) => !s.endsWith(": null") && !s.endsWith(": undefined"))
-              .join(", ");
-            return withVersionWarning(meta ? `${parsed.text}\n\n[${meta}]` : parsed.text);
-          }
-          throw new Error(
-            `vision failed (exit ${r.code}): ${(r.stderr || r.stdout).trim() || "unknown error"}`
-          );
-        } finally {
-          for (const m of materialized) if (m.cleanup) await m.cleanup();
-        }
+        return runImageAnalysis({
+          subcommand: "ocr",
+          name: "deepseek_ocr",
+          imageInputs,
+          args,
+          exec,
+        });
       },
     })
   );
@@ -388,11 +479,11 @@ function apply(ctx, config) {
         schema: { type: "string" },
         render: (_args, value) => [{ type: "text", text: value }],
       },
-      timeoutMs: config.statusTimeoutMs,
+      timeoutMs: runtime.statusTimeoutMs,
       async execute(_args, exec) {
         const bin = requireBinary();
         const r = await runCli(bin, ["status", "--json"], {
-          timeoutMs: config.statusTimeoutMs,
+          timeoutMs: runtime.statusTimeoutMs,
           signal: exec.signal,
         });
         if (r.killed) throw new Error("deepseek_vision_status was aborted or timed out");
@@ -461,11 +552,11 @@ function apply(ctx, config) {
         schema: { type: "string" },
         render: (_args, value) => [{ type: "text", text: value }],
       },
-      timeoutMs: config.statusTimeoutMs,
+      timeoutMs: runtime.statusTimeoutMs,
       async execute(_args, exec) {
         const bin = requireBinary();
         const r = await runCli(bin, ["logout"], {
-          timeoutMs: config.statusTimeoutMs,
+          timeoutMs: runtime.statusTimeoutMs,
           signal: exec.signal,
         });
         if (r.killed) throw new Error("deepseek_vision_logout was aborted or timed out");
@@ -478,4 +569,19 @@ function apply(ctx, config) {
   );
 }
 
-export { name, inject, Config, apply, resolveBinaryPath, resolveFromNpmShim };
+export {
+  name,
+  inject,
+  Config,
+  apply,
+  SETTINGS_NAMESPACE,
+  buildImageCliArgs,
+  resolveBinaryPath,
+  resolveFromNpmShim,
+};
+
+// Internal reuse: the image-bridge plugin runs in the same package but is a
+// separate plugin row; it needs the same binary resolution + subprocess
+// plumbing to drive deterministic-mode analysis. Export the two pieces it
+// reuses (not the public plugin surface).
+export { runCli, binaryMissingHelp };