@xlight-oss/visionary-dsh 0.5.0

package/README.md

@@ -0,0 +1,85 @@
+# @xlight-oss/visionary-dsh
+
+[DeepSeek Visionary](https://github.com/xlight/deepseek-visionary) 的 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）原生插件：把 `deepseek_vision` / `deepseek_vision_status` / `deepseek_vision_login` / `deepseek_vision_logout` 注册为 DSH 原生工具，由 `visionary-server` CLI 支撑（DeepSeek 网页版视觉模型，**无需 API key**）。
+
+## 特性
+
+- **原生工具** — 结构化参数 schema 注册到 `ctx.tools`，模型直接调用，无 MCP 中间层
+- **复用 Rust 管道** — 每个工具 spawn `visionary-server`（PoW → 上传 → fork → HIF → SSE 全部在 Rust 侧），插件仅做参数映射与 JSON 解析
+- **宿主级权限** — 工具在 DSH 宿主进程执行（不经 bash 沙箱），会话续聊与浏览器登录不受 workspace-write 限制
+- **超时有界可取消** — 每个工具声明 `timeoutMs` 并转发 `exec.signal`（abort → kill 子进程）
+
+## 安装
+
+```bash
+# npm 包（发布后）
+dsh plugin --profile web add @xlight-oss/visionary-dsh
+
+# 本地路径（开发验证）
+dsh plugin --profile web add /path/to/packages/dsh-plugin
+```
+
+`dsh plugin` 会把包安装进 profile 并通过 `dsh.bundle` 声明自动追加到 `dsh.profile.bundles` 层叠——**无需手写任何配置**。重启 DSH 后 4 个工具出现在工具目录。
+
+验证：`dsh --profile web --dump-config` 应出现 `@xlight-oss/visionary-dsh` 层与 `visionary-vision` 插件行。
+
+> **本地路径（开发）安装**：`dsh plugin add <path>` 以 link 方式安装，Node 从包的真实位置解析其 peer 依赖，因此本地开发需先在包目录 `pnpm install`（peer 已镜像为 devDependencies，见 `package.json`），否则加载时报 `Cannot find package '@deepseek-ai/dsh-tools'`。已发布的 npm 包无此要求（DSH 的 `profiles/node_modules` 兜底解析）。
+
+## 前置要求
+
+`visionary-server` 二进制需可被找到（三者任一）：
+
+1. `Config.binaryPath`（插件配置，绝对路径）
+2. `DEEPSEEK_VISIONARY_BIN` 环境变量
+3. 在 PATH 中
+
+安装二进制见 [DeepSeek Visionary 安装章节](https://github.com/xlight/deepseek-visionary#安装)（install.sh / brew / npm）。未找到时工具返回含安装指引的错误。
+
+## 配置
+
+在 DSH profile 的 `cordis.patch.yml`（或 `$DSH_HOME/cordis.patch.yml`）给 `visionary-vision` 行补 `config`：
+
+```yaml
+- id: visionary-vision
+  config:
+    binaryPath: /usr/local/bin/visionary-server
+    loginTimeoutSeconds: 900        # 不设则读 DEEPSEEK_LOGIN_TIMEOUT env（默认 600）
+    visionTimeoutMs: 300000
+    statusTimeoutMs: 60000
+```
+
+> patch 层按 `id` 整行替换 `config`（不做键级深合并）：覆盖 `visionary-vision` 时，未写出的字段回退到下方表格中的 schema 默认值，而非保留插件包内的配置。
+
+| 字段 | 默认 | 说明 |
+|------|------|------|
+| `binaryPath` | `""`（env → PATH） | 二进制绝对路径 |
+| `loginTimeoutSeconds` | 600（`DEEPSEEK_LOGIN_TIMEOUT` env 优先） | 登录等待超时（秒） |
+| `visionTimeoutMs` | 300000 | `deepseek_vision` 单次超时 |
+| `statusTimeoutMs` | 60000 | status / logout 超时 |
+
+## 工具
+
+| 工具 | 说明 |
+|------|------|
+| `deepseek_vision` | 识图（路径 / base64 / data URI），支持 `prompt` / `thinking` / `continue_conversation` / `session_id` 多轮续聊 |
+| `deepseek_vision_status` | 登录状态检查（含真实 token 探针） |
+| `deepseek_vision_login` | 浏览器自动登录（阻塞，超时可配） |
+| `deepseek_vision_logout` | 清除保存的凭据 |
+
+## 与其他接入路径的关系
+
+| 路径 | 适用 |
+|------|------|
+| **本插件（推荐）** | DSH 用户：原生工具、结构化 schema、宿主级权限、续聊/登录不受沙箱限制 |
+| skill + CLI（`init dsh` / `skill install`） | 任何能执行 shell 的 agent：零安装配置，模型经 bash 调 `visionary-server vision <image> --json`；DSH 下续聊/登录受 bash 沙箱写限制 |
+| MCP（`mcp-stdio` + 各宿主配置） | 需要标准 MCP 工具面时（Zed / OpenCode / Codex / Claude Code 等） |
+
+三者共用同一二进制与同一份凭据（`~/.deepseek-visionary/config.json`），可并存。
+
+## 安全提示
+
+`deepseek_vision` 的 `image` 参数指向的文件会被**读取并上传**至 chat.deepseek.com——仅传用户有意分享的路径。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# @xlight-oss/visionary-dsh bundle patch.
+# Registers the DeepSeek Visionary native tools into the DSH composition.
+# Installed via: dsh plugin --profile <name> add @xlight-oss/visionary-dsh
+- insert:
+    - id: visionary-vision
+      name: '@xlight-oss/visionary-dsh'

package/lib/index.mjs

@@ -0,0 +1,400 @@
+// DeepSeek Visionary — DeepSeek Harness native plugin.
+//
+// Registers `deepseek_vision` / `deepseek_vision_status` / `deepseek_vision_login`
+// / `deepseek_vision_logout` as native tools on `ctx.tools`. Every tool spawns the
+// `visionary-server` binary (CLI; `--json` atomic output where the subcommand
+// supports it), so the heavy vision pipeline (PoW → upload → fork → HIF → SSE)
+// stays in Rust. Tools run in the DSH host process — not through the bash
+// sandbox — so session continuation and browser login are not restricted by the
+// workspace-write file sandbox.
+//
+// Tool-call timeout is declared per tool (`ToolDefinition.timeoutMs`); DSH's
+// timeout-policy enforces it cooperatively through `exec.signal`, which this
+// plugin forwards to the spawned child (abort → kill).
+
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import z from "@deepseek-ai/schemastery";
+import { spawn } from "node:child_process";
+import { statSync } from "node:fs";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const name = "visionary-vision";
+const inject = ["tools", "systemPrompt"];
+
+// 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.4";
+
+const Config = z.object({
+  binaryPath: z
+    .string()
+    .default("")
+    .description(
+      "Absolute path to the visionary-server binary. Empty resolves via DEEPSEEK_VISIONARY_BIN, then PATH."
+    ),
+  loginTimeoutSeconds: z
+    .number()
+    .default(600)
+    .description(
+      "Login wait timeout in seconds. DEEPSEEK_LOGIN_TIMEOUT env overrides when set (matching the CLI's own login deadline); schema default 600."
+    ),
+  visionTimeoutMs: z
+    .number()
+    .default(300000)
+    .description("Per deepseek_vision call timeout in ms."),
+  statusTimeoutMs: z
+    .number()
+    .default(60000)
+    .description("Per deepseek_vision_status / deepseek_vision_logout timeout in ms."),
+});
+
+// --- binary resolution -------------------------------------------------------
+
+function resolveBinaryPath(config) {
+  if (config.binaryPath) return config.binaryPath;
+  const fromEnv = process.env.DEEPSEEK_VISIONARY_BIN;
+  if (fromEnv) return fromEnv;
+  const exe = process.platform === "win32" ? "visionary-server.exe" : "visionary-server";
+  for (const dir of (process.env.PATH || "").split(path.delimiter).filter(Boolean)) {
+    const candidate = path.join(dir, exe);
+    try {
+      if (statSync(candidate).isFile()) return candidate;
+    } catch {
+      // keep looking
+    }
+  }
+  return null;
+}
+
+const binaryMissingHelp = () =>
+  [
+    "visionary-server binary not found. Install it and retry:",
+    "  - One-liner: curl -LsSf https://github.com/xlight/deepseek-visionary/releases/latest/download/visionary-server-installer.sh | sh",
+    "  - Homebrew: brew install <tap>/visionary-server",
+    "  - npm: npm install -g @xlight-oss/visionary-server",
+    "Or point the plugin at the binary via Config.binaryPath / DEEPSEEK_VISIONARY_BIN.",
+  ].join("\n");
+
+// --- subprocess --------------------------------------------------------------
+
+function runCli(binary, args, { timeoutMs, signal }) {
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawn(binary, args, { stdio: ["ignore", "pipe", "pipe"] });
+    } catch (err) {
+      reject(err);
+      return;
+    }
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let killed = false;
+    child.stdout?.on("data", (d) => (stdout += d));
+    child.stderr?.on("data", (d) => (stderr += d));
+
+    const kill = () => {
+      killed = true;
+      child.kill("SIGKILL");
+    };
+    const timer = setTimeout(kill, timeoutMs);
+    const onAbort = () => kill();
+    if (signal) {
+      if (signal.aborted) kill();
+      else signal.addEventListener("abort", onAbort, { once: true });
+    }
+
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      if (signal) signal.removeEventListener("abort", onAbort);
+      if (settled) return;
+      settled = true;
+      if (err.code === "ENOENT") reject(new Error(binaryMissingHelp()));
+      else reject(err);
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (signal) signal.removeEventListener("abort", onAbort);
+      if (settled) return;
+      settled = true;
+      resolve({ code: code ?? -1, stdout, stderr, killed });
+    });
+  });
+}
+
+// --- image input -------------------------------------------------------------
+
+// Mirror the CLI's read_image semantics: "-" (stdin) is not passed by this
+// plugin; "data:" prefixed input and long decodable base64 are materialized to
+// a temp file so the payload never travels as a giant argv entry (Linux caps a
+// single argument at 131072 bytes → E2BIG on real screenshots).
+async function materializeImage(image) {
+  let data = null;
+  if (image.startsWith("data:")) {
+    const comma = image.indexOf(",");
+    if (comma === -1) throw new Error("invalid data URI for image");
+    const meta = image.slice(0, comma);
+    const payload = image.slice(comma + 1);
+    data = /;base64$/i.test(meta)
+      ? Buffer.from(payload, "base64")
+      : Buffer.from(decodeURIComponent(payload), "utf8");
+  } else if (
+    image.length > 100 &&
+    image.length % 4 === 0 &&
+    /^[A-Za-z0-9+/=\r\n]+$/.test(image)
+  ) {
+    try {
+      data = Buffer.from(image, "base64");
+    } catch {
+      data = null;
+    }
+  }
+  if (data !== null) {
+    const tmp = path.join(
+      os.tmpdir(),
+      `visionary-${Date.now()}-${Math.random().toString(36).slice(2)}.img`
+    );
+    await fs.writeFile(tmp, data);
+    return { arg: tmp, cleanup: () => fs.rm(tmp, { force: true }).catch(() => {}) };
+  }
+  return { arg: image, cleanup: null };
+}
+
+// --- version probe (apply-time, fire-and-forget) -----------------------------
+
+function parseMinor(v) {
+  const m = /(\d+)\.(\d+)/.exec(v || "");
+  return m ? `${m[1]}.${m[2]}` : null;
+}
+
+// --- tools -------------------------------------------------------------------
+
+function apply(ctx, config) {
+  const binary = resolveBinaryPath(config);
+  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;
+  })();
+
+  let versionInfo = { known: false, compatible: true, version: "" };
+  if (binary) {
+    runCli(binary, ["--version"], { timeoutMs: 5000 })
+      .then((r) => {
+        const version = (r.stdout || r.stderr).trim();
+        versionInfo = {
+          known: true,
+          compatible: parseMinor(version) === COMPAT_MINOR,
+          version,
+        };
+      })
+      .catch(() => {
+        versionInfo = { known: true, compatible: false, version: "unknown" };
+      });
+  }
+
+  const withVersionWarning = (text) => {
+    if (!versionInfo.known || versionInfo.compatible) return text;
+    return `${text}\n\n[warning] visionary-server version "${versionInfo.version}" does not match the plugin's compatible version ${COMPAT_MINOR}.x — upgrade the binary or the plugin.`;
+  };
+
+  if (ctx.systemPrompt?.section) {
+    ctx.systemPrompt.section({
+      name: "visionary-vision",
+      order: 150,
+      text: () => [
+        "## Vision (DeepSeek Visionary)",
+        "",
+        "You have native vision tools backed by DeepSeek's web vision model (no API key):",
+        "- `deepseek_vision` — analyze an image (local path / base64 / data URI)",
+        "- `deepseek_vision_status` — check login state",
+        "- `deepseek_vision_login` — browser auto-login",
+        "- `deepseek_vision_logout` — clear saved credentials",
+        "",
+        "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` path passed to `deepseek_vision` is read and uploaded to the DeepSeek service — only pass paths the user intends to share.",
+      ].join("\n"),
+    });
+  }
+
+  const requireBinary = () => {
+    if (!binary) throw new Error(binaryMissingHelp());
+    return binary;
+  };
+
+  ctx.tools.register(
+    defineTool({
+      name: "deepseek_vision",
+      description:
+        "Analyze an image with DeepSeek's web vision model (local path / base64 / data URI). Use for screenshots, photos, or documents with images. Supports multi-turn conversation via continue_conversation / session_id.",
+      parameters: {
+        image: {
+          type: "string",
+          required: true,
+          description: "Image: local file path, base64, or data URI.",
+        },
+        prompt: {
+          type: "string",
+          description: "Question about the image (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).",
+        },
+        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 }],
+      },
+      timeoutMs: config.visionTimeoutMs,
+      async execute(args, exec) {
+        const bin = requireBinary();
+        const { arg, cleanup } = await materializeImage(args.image);
+        try {
+          const cliArgs = ["vision", 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");
+
+          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 {
+          if (cleanup) await cleanup();
+        }
+      },
+    })
+  );
+
+  ctx.tools.register(
+    defineTool({
+      name: "deepseek_vision_status",
+      description:
+        "Check DeepSeek Vision login state (authenticated, token validity). Run before deepseek_vision if unsure whether the user is logged in.",
+      parameters: {},
+      output: {
+        schema: { type: "string" },
+        render: (_args, value) => [{ type: "text", text: value }],
+      },
+      timeoutMs: config.statusTimeoutMs,
+      async execute(_args, exec) {
+        const bin = requireBinary();
+        const r = await runCli(bin, ["status", "--json"], {
+          timeoutMs: config.statusTimeoutMs,
+          signal: exec.signal,
+        });
+        if (r.killed) throw new Error("deepseek_vision_status was aborted or timed out");
+        // `status --json` prints a complete JSON document even when unauthenticated
+        // and exits non-zero — the JSON is authoritative, not the exit code.
+        let parsed = null;
+        try {
+          parsed = JSON.parse(r.stdout);
+        } catch {
+          parsed = null;
+        }
+        if (parsed) {
+          const state = parsed.token_valid
+            ? "authenticated, token valid"
+            : parsed.authenticated
+              ? "authenticated (live probe pending)"
+              : "not logged in";
+          const hint = parsed.token_valid
+            ? ""
+            : "\nRun `deepseek_vision_login` to auto-login, or set DEEPSEEK_USER_TOKEN.";
+          return withVersionWarning(`DeepSeek Vision status: ${state}${hint}`);
+        }
+        throw new Error(
+          `status failed (exit ${r.code}): ${(r.stderr || r.stdout).trim() || "unknown error"}`
+        );
+      },
+    })
+  );
+
+  ctx.tools.register(
+    defineTool({
+      name: "deepseek_vision_login",
+      description:
+        "Browser auto-login to chat.deepseek.com (opens a browser window and waits for the user to log in). Blocks until login completes or the timeout elapses; the browser stays open on timeout so the user can finish and retry.",
+      parameters: {},
+      output: {
+        schema: { type: "string" },
+        render: (_args, value) => [{ type: "text", text: value }],
+      },
+      timeoutMs: loginSeconds * 1000,
+      async execute(_args, exec) {
+        const bin = requireBinary();
+        const r = await runCli(bin, ["login"], {
+          timeoutMs: loginSeconds * 1000,
+          signal: exec.signal,
+        });
+        if (r.killed) {
+          throw new Error(
+            `deepseek_vision_login timed out after ${loginSeconds}s — the browser stays open; finish logging in and retry, or set DEEPSEEK_LOGIN_TIMEOUT for a longer wait.`
+          );
+        }
+        if (r.code !== 0) {
+          throw new Error(`login failed (exit ${r.code}): ${(r.stderr || r.stdout).trim()}`);
+        }
+        return withVersionWarning(r.stdout.trim() || "Logged in.");
+      },
+    })
+  );
+
+  ctx.tools.register(
+    defineTool({
+      name: "deepseek_vision_logout",
+      description: "Clear saved DeepSeek Vision credentials.",
+      parameters: {},
+      output: {
+        schema: { type: "string" },
+        render: (_args, value) => [{ type: "text", text: value }],
+      },
+      timeoutMs: config.statusTimeoutMs,
+      async execute(_args, exec) {
+        const bin = requireBinary();
+        const r = await runCli(bin, ["logout"], {
+          timeoutMs: config.statusTimeoutMs,
+          signal: exec.signal,
+        });
+        if (r.killed) throw new Error("deepseek_vision_logout was aborted or timed out");
+        if (r.code !== 0) {
+          throw new Error(`logout failed (exit ${r.code}): ${(r.stderr || r.stdout).trim()}`);
+        }
+        return withVersionWarning(r.stdout.trim() || "Logged out.");
+      },
+    })
+  );
+}
+
+export { name, inject, Config, apply };

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@xlight-oss/visionary-dsh",
+  "version": "0.5.0",
+  "description": "DeepSeek Visionary native plugin for DeepSeek Harness: deepseek_vision / status / login / logout native tools backed by the visionary-server CLI (DeepSeek web vision model, no API key).",
+  "type": "module",
+  "main": "lib/index.mjs",
+  "exports": {
+    ".": {
+      "default": "./lib/index.mjs"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.mjs",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xlight/deepseek-visionary.git"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "cordis",
+    "vision",
+    "image-analysis",
+    "mcp",
+    "plugin"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  }
+}