@floatingsk/dsh-vision 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 floatingsk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+# dsh-vision
+
+> 给 DeepSeek Harness（dsh）补上视觉能力的插件：**本地 OCR + 云端 VLM 图片理解**。
+
+DeepSeek 的模型 API 目前不支持图像输入，`read_image` 因此无法使用。本插件提供两个工具绕过这个限制：
+
+| 工具 | 能力 | 成本 |
+|---|---|---|
+| `read_image_text` | 识别图片中的**文字**（macOS 本地 Vision 引擎，免费离线，中英文） | 免费 |
+| `describe_image` | 理解图片的**画面内容**（云端 VLM，OpenAI 兼容端点） | 按量付费 |
+
+## 特性
+
+- 🔒 **本地 OCR**：基于 macOS Vision.framework，图片不出本机，隐私安全
+- ☁️ **云端 VLM**：默认阿里云百炼 `qwen3-vl-flash`（快且便宜），OpenAI 兼容接口，可换成任意提供商
+- 🖼️ **自动压缩**：VLM 调用前用 `sips` 把大图压到 2048px / JPEG 85%，省钱省流量
+- 🔑 **灵活取 Key**：环境变量或 `~/.dsh/.credentials.yaml`
+- 🧪 **零依赖单测**：核心逻辑用 Node 内置 `node:test` 覆盖（13 用例）
+- 🌏 **多供应商 VLM**：内置百炼 / 硅基流动 / 智谱 / 火山方舟，OpenAI 兼容可加任意家
+- 🪟 **Windows 支持**：附 PowerShell OCR 后端（Windows.Media.Ocr），VLM 通道跨平台
+
+## 安装
+
+### 方式 A：从 npm 安装（发布后推荐）
+
+```sh
+dsh plugin --profile web add @floatingsk/dsh-vision
+```
+
+### 方式 B：从源码拷贝
+
+```sh
+# 把本仓库拷贝到你的 dsh profile 插件目录
+cp -R dsh-vision ~/.dsh/profiles/node_modules/dsh-vision
+```
+
+### 方式 C：从 GitHub Release 下载预编译二进制（免编译，推荐）
+
+维护者在打 `v*` tag 时，GitHub Actions 会自动在两种 macOS 架构上编译并附到 Release：
+
+1. 打开本仓库的 **Releases** 页面，选择最新版本
+2. 按你的 Mac 架构下载：
+   - Apple Silicon（M 系列）：`vision-ocr-arm64`
+   - Intel Mac：`vision-ocr-x86_64`
+3. 放到插件目录并加执行权限：
+
+```sh
+cp vision-ocr-arm64 ~/.dsh/profiles/node_modules/dsh-vision/bin/vision-ocr
+chmod +x ~/.dsh/profiles/node_modules/dsh-vision/bin/vision-ocr
+```
+
+### 编译 OCR 二进制（macOS 需要 Xcode Command Line Tools）
+
+```sh
+cd ~/.dsh/profiles/node_modules/dsh-vision
+# 显式指定 clang 模块缓存目录（沙箱/受限环境下必需）
+swiftc -Xcc -fmodules-cache-path="$PWD/.cache" -O bin/vision-ocr.swift -o bin/vision-ocr
+```
+
+### 在 profile patch 中启用插件
+
+编辑 `~/.dsh/profiles/web/cordis.patch.yml`（你的 profile 对应文件），追加：
+
+```yaml
+- insert:
+    - id: dsh-vision
+      name: 'dsh-vision'
+```
+
+### 配置 VLM API Key（`describe_image` 需要）
+
+任选其一：
+
+```sh
+# 方式 A：环境变量
+export DASHSCOPE_API_KEY=sk-xxx
+
+# 方式 B：写入 dsh 凭据文件
+echo 'DASHSCOPE_API_KEY: sk-xxx' >> ~/.dsh/.credentials.yaml
+```
+
+Key 从你的 VLM 提供商控制台获取（默认阿里云百炼：[bailian.console.aliyun.com](https://bailian.console.aliyun.com)）。
+
+### 重启 dsh
+
+重启后工具即可用。**注意：需要新开一个对话**，工具列表在会话开始时注入。
+
+## 使用
+
+在对话中把图片保存到磁盘，告诉 agent 路径即可：
+
+```
+看下 /path/to/image.png 里有什么
+读取 /path/to/截图.png 中的文字
+```
+
+Agent 会自动选择合适的工具（读文字走 OCR，看画面走 VLM）。想指定 VLM 供应商时，可让 agent 传 `provider` 参数（如 `bailian` / `siliconflow` / `zhipu` / `volcengine`）。
+
+## 配置
+
+通过 `cordis.patch.yml` 中 `dsh-vision` 节点的 `config` 覆盖默认值。
+
+### 多供应商 VLM
+
+内置四家国内供应商，`describe_image` 可传 `provider` 参数选择（留空用 `defaultProvider`）：
+
+```yaml
+- insert:
+    - id: dsh-vision
+      name: 'dsh-vision'
+      config:
+        defaultProvider: 'bailian'          # 默认供应商
+        providers:
+          bailian:                          # 阿里云百炼
+            baseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1'
+            model: 'qwen3-vl-flash'         # 或 qwen3-vl-plus / qwen-vl-ocr
+            apiKeyEnv: 'DASHSCOPE_API_KEY'
+          siliconflow:                      # 硅基流动
+            baseUrl: 'https://api.siliconflow.cn/v1'
+            model: 'Qwen/Qwen2.5-VL-7B-Instruct'
+            apiKeyEnv: 'SILICONFLOW_API_KEY'
+          zhipu:                            # 智谱
+            baseUrl: 'https://open.bigmodel.cn/api/paas/v4'
+            model: 'glm-4v-flash'
+            apiKeyEnv: 'ZHIPU_API_KEY'
+          volcengine:                       # 火山方舟（豆包）
+            baseUrl: 'https://ark.cn-beijing.volces.com/api/v3'
+            model: 'doubao-seed-1.6-vision'
+            apiKeyEnv: 'ARK_API_KEY'
+        # 自定义 OCR 二进制路径（默认插件 bin/vision-ocr）
+        ocrBin: ''
+        # 上传前压缩最长边（像素）
+        vlmMaxImageDim: 2048
+```
+
+换供应商：改 `defaultProvider`，或在调用时指定 `provider` 参数；加新供应商：在 `providers` 下加任意键名（任何 OpenAI 兼容端点都行）。
+
+### 推荐的视觉模型（阿里云百炼）
+
+| 模型 | 特点 |
+|---|---|
+| `qwen3-vl-flash`（默认） | 快、便宜，日常够用 |
+| `qwen3-vl-plus` | 质量更高，稍慢稍贵 |
+| `qwen-vl-ocr` | 纯文字识别专用，比本地 OCR 更强（需联网） |
+
+## 开发
+
+```sh
+# 运行单元测试
+node --test test/
+
+# 重新编译 OCR 二进制
+swiftc -Xcc -fmodules-cache-path="$PWD/.cache" -O bin/vision-ocr.swift -o bin/vision-ocr
+```
+
+## 平台支持
+
+| 能力 | macOS (Apple Silicon) | macOS (Intel) | Windows |
+|---|---|---|---|
+| 本地 OCR | ✅ 已编译 | ✅ 自编译或用 Release 二进制 | ✅ PowerShell 后端（Windows.Media.Ocr，未实测） |
+| 云端 VLM | ✅ | ✅ | ✅（纯 Node） |
+
+- **macOS OCR**：依赖 Vision.framework。仓库不含编译产物（见 `.gitignore`）：
+  - Apple Silicon：`npm run build:ocr` 自编译，或下载 GitHub Release 的 `vision-ocr-arm64`
+  - Intel：`npm run build:ocr` 自编译，或下载 Release 的 `vision-ocr-x86_64`
+  - 打 `v*` tag 推 GitHub 时，Actions 自动在两种架构编译并附到 Release
+- **Windows OCR**：`bin/vision-ocr.ps1`（Windows 10/11 内置 OCR 引擎，需装中文 OCR 语言包），插件 `ocrBin` 指向它即可：
+  ```powershell
+  powershell -ExecutionPolicy Bypass -File bin/vision-ocr.ps1 <image> -Json
+  ```
+  > 注：该脚本在 macOS 上开发，未在 Windows 实测，欢迎提交 issue/PR。
+- **VLM 通道**：Node >= 18（内置 `fetch`），全平台可用。
+
+## 许可证
+
+[MIT](./LICENSE)

package/bin/vision-ocr.ps1

@@ -0,0 +1,99 @@
+# vision-ocr.ps1 — Windows OCR 后端（Windows.Media.Ocr）
+#
+# 与 macOS 版 vision-ocr 输出相同 JSON 格式的 OCR 命令行工具。
+# 使用 Windows 10/11 内置 OCR 引擎（Windows.Media.Ocr），免费、离线、支持中文。
+#
+# 用法:
+#   powershell -ExecutionPolicy Bypass -File vision-ocr.ps1 <image-path> [-Json]
+#
+# 注意:
+#   - 需要 Windows 10 1803+ / Windows 11
+#   - 需要安装对应语言的 OCR 语言包（设置 → 时间和语言 → 语言 → 可选功能 → 光学字符识别(OCR)）
+#   - 作者在 macOS 上开发，此脚本未在 Windows 上实测，欢迎提交 issue/PR
+#   - 坐标单位为 DIP（与 macOS 版归一化坐标不同，但文本内容一致）
+
+param(
+    [Parameter(Mandatory = $true, Position = 0)]
+    [string]$ImagePath,
+
+    [switch]$Json
+)
+
+$ErrorActionPreference = "Stop"
+
+if (-not (Test-Path -LiteralPath $ImagePath)) {
+    Write-Error "cannot load image: $ImagePath"
+    exit 2
+}
+
+# ── 加载 WinRT 类型 ───────────────────────────────────────────────────────────
+[Windows.Media.Ocr.OcrEngine, Windows.Foundation, ContentType = WindowsRuntime] | Out-Null
+[Windows.Storage.StorageFile, Windows.Storage, ContentType = WindowsRuntime] | Out-Null
+[Windows.Graphics.Imaging.BitmapDecoder, Windows.Graphics, ContentType = WindowsRuntime] | Out-Null
+
+Add-Type -AssemblyName System.Runtime.WindowsRuntime -ErrorAction SilentlyContinue
+
+# ── Await helper：把 WinRT IAsyncOperation 转成 .NET Task（PowerShell 5.1 兼容）──
+$asTaskGeneric = ([System.WindowsRuntimeSystemExtensions].GetMethods() |
+    Where-Object { $_.Name -eq 'AsTask' -and $_.GetParameters().Count -eq 1 -and $_.GetParameters()[0].ParameterType.Name -eq 'IAsyncOperation`1' })[0]
+
+function Await($WinRtTask, $ResultType) {
+    $asTask = $asTaskGeneric.MakeGenericMethod($ResultType)
+    $netTask = $asTask.Invoke($null, @($WinRtTask))
+    $netTask.Wait(-1) | Out-Null
+    return $netTask.Result
+}
+
+# ── 打开并解码图片 ────────────────────────────────────────────────────────────
+try {
+    $file = Await ([Windows.Storage.StorageFile]::GetFileFromPathAsync($ImagePath)) ([Windows.Storage.StorageFile])
+} catch {
+    Write-Error "cannot open image: $ImagePath ($_)"
+    exit 3
+}
+
+$stream = Await ($file.OpenAsync([Windows.Storage.FileAccessMode]::Read)) ([Windows.Storage.Streams.IRandomAccessStream])
+$decoder = Await ([Windows.Graphics.Imaging.BitmapDecoder]::CreateAsync($stream)) ([Windows.Graphics.Imaging.BitmapDecoder])
+$bitmap = Await ($decoder.GetSoftwareBitmapAsync()) ([Windows.Graphics.Imaging.SoftwareBitmap])
+
+# ── OCR 引擎（优先中文） ──────────────────────────────────────────────────────
+$engine = [Windows.Media.Ocr.OcrEngine]::TryCreateFromUserProfileLanguages()
+if ($null -eq $engine) {
+    Write-Error "no OCR language pack available; install OCR language packs in Settings"
+    exit 4
+}
+
+$result = Await ($engine.RecognizeAsync($bitmap)) ([Windows.Media.Ocr.OcrResult])
+
+# ── 组装输出（与 macOS vision-ocr 的 --json 格式一致） ───────────────────────
+$lines = @()
+foreach ($line in $result.Lines) {
+    $words = @($line.Words)
+    if ($words.Count -eq 0) { continue }
+    $first = $words[0].BoundingRect
+    $last = $words[$words.Count - 1].BoundingRect
+    $lines += [PSCustomObject]@{
+        text       = $line.Text
+        confidence = 1.0
+        x          = [math]::Round($first.X, 3)
+        y          = [math]::Round($first.Y, 3)
+    }
+}
+
+$resultObj = [PSCustomObject]@{
+    width  = $decoder.PixelWidth
+    height = $decoder.PixelHeight
+    lines  = $lines
+}
+
+if ($Json) {
+    $resultObj | ConvertTo-Json -Depth 5
+} else {
+    Write-Host "image: $ImagePath  size: $($decoder.PixelWidth)x$($decoder.PixelHeight)"
+    Write-Host "--- OCR ---"
+    if ($lines.Count -eq 0) { Write-Host "(no text detected)" }
+    foreach ($l in $lines) { Write-Host $l.text }
+}
+
+$stream.Dispose()
+exit 0

package/bin/vision-ocr.swift

@@ -0,0 +1,103 @@
+// vision-ocr.swift — macOS Vision.framework OCR 命令行工具
+// 用法: vision-ocr <image-path> [--lang zh-Hans] [--json]
+// 输出: 图片元信息 + 按阅读顺序排序的识别文本行
+import Foundation
+import Vision
+import AppKit
+
+func fail(_ msg: String, code: Int32) -> Never {
+    FileHandle.standardError.write((msg + "\n").data(using: .utf8)!)
+    exit(code)
+}
+
+let args = CommandLine.arguments
+guard args.count >= 2 else {
+    fail("usage: vision-ocr <image> [--lang zh-Hans] [--json]", code: 1)
+}
+let imagePath = args[1]
+var language = "zh-Hans"
+var wantsJSON = false
+if let idx = args.firstIndex(of: "--lang"), idx + 1 < args.count { language = args[idx + 1] }
+if args.contains("--json") { wantsJSON = true }
+
+guard let image = NSImage(contentsOfFile: imagePath) else {
+    fail("cannot load image: \(imagePath)", code: 2)
+}
+guard let cgImage = image.cgImage(forProposedRect: nil, context: nil, hints: nil) else {
+    fail("cannot convert image to CGImage: \(imagePath)", code: 3)
+}
+
+let width = cgImage.width
+let height = cgImage.height
+
+let request = VNRecognizeTextRequest()
+request.recognitionLevel = .accurate
+request.recognitionLanguages = [language, "en-US"]
+request.usesLanguageCorrection = true
+
+let handler = VNImageRequestHandler(cgImage: cgImage, options: [:])
+do {
+    try handler.perform([request])
+} catch {
+    fail("Vision request failed: \(error)", code: 4)
+}
+
+struct Line {
+    let text: String
+    let y: Double   // Vision 坐标 (0-1, 底部为 0)
+    let x: Double
+    let confidence: Float
+}
+
+var lines: [Line] = []
+for obs in request.results ?? [] {
+    guard let cand = obs.topCandidates(1).first else { continue }
+    let box = obs.boundingBox
+    lines.append(Line(text: cand.string, y: Double(box.midY), x: Double(box.minX), confidence: cand.confidence))
+}
+
+// 按阅读顺序：从顶到底，同行内从左到右
+lines.sort { a, b in
+    if abs(a.y - b.y) > 0.02 { return a.y > b.y }
+    return a.x < b.x
+}
+
+if wantsJSON {
+    let rows = lines.map { l in
+        "{\"text\": \(jsonEscape(l.text)), \"confidence\": \(String(format: "%.3f", l.confidence)), \"x\": \(String(format: "%.3f", l.x)), \"y\": \(String(format: "%.3f", l.y))}"
+    }
+    let payload = """
+    {"width": \(width), "height": \(height), "lines": [\(rows.joined(separator: ","))]}
+    """
+    print(payload)
+} else {
+    print("image: \(imagePath)  size: \(width)x\(height)")
+    print("--- OCR (\(language)) ---")
+    if lines.isEmpty {
+        print("(no text detected)")
+    }
+    for l in lines {
+        print(l.text)
+    }
+}
+
+func jsonEscape(_ s: String) -> String {
+    var out = "\""
+    for ch in s.unicodeScalars {
+        switch ch {
+        case "\"": out += "\\\""
+        case "\\": out += "\\\\"
+        case "\n": out += "\\n"
+        case "\r": out += "\\r"
+        case "\t": out += "\\t"
+        default:
+            if ch.value < 0x20 {
+                out += String(format: "\\u%04x", ch.value)
+            } else {
+                out.append(Character(ch))
+            }
+        }
+    }
+    out += "\""
+    return out
+}

package/lib/core.js

@@ -0,0 +1,102 @@
+// dsh-vision 核心纯逻辑（无 Cordis 依赖，可独立单元测试）
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+/** VLM 请求超时（毫秒） */
+export const VLM_TIMEOUT_MS = 120_000;
+/** VLM 输出 token 上限 */
+export const VLM_MAX_TOKENS = 1024;
+/** 上传前图片压缩的最长边（像素） */
+export const VLM_MAX_IMAGE_DIM = 2048;
+/** 压缩 JPEG 质量（0-100） */
+export const JPEG_QUALITY = 85;
+/** 本地 OCR 单次执行超时（毫秒） */
+export const OCR_TIMEOUT_MS = 60_000;
+
+/** 默认的画面理解提问（当用户未提供具体问题时使用） */
+export const DEFAULT_DESCRIBE_PROMPT =
+	"请详细描述这张图片的内容：画面主体、场景、人物、构图、颜色、光线、以及任何值得注意的细节。";
+
+/**
+ * 从环境变量或 ~/.dsh/.credentials.yaml 解析 API Key。
+ * 优先读环境变量；其次读 DSH 凭据文件中的同名条目。
+ * @param {string} envName - 环境变量名（如 DASHSCOPE_API_KEY）
+ * @returns {string|null} 解析到的 Key，未配置返回 null
+ */
+export function resolveApiKey(envName) {
+	if (process.env[envName]) return process.env[envName];
+	try {
+		const credPath = join(homedir(), ".dsh", ".credentials.yaml");
+		if (!existsSync(credPath)) return null;
+		const content = readFileSync(credPath, "utf8");
+		const re = new RegExp(`^${envName}\\s*[:=]\\s*(.+)$`, "m");
+		const m = content.match(re);
+		if (!m) return null;
+		return m[1].trim().replace(/^["']|["']$/g, "");
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * 从 OpenAI 兼容 chat/completions 响应中提取助手文本。
+ * @param {unknown} data - API 返回的 JSON
+ * @returns {string} 提取到的文本；缺失时返回空字符串
+ */
+export function extractDescription(data) {
+	const content = data?.choices?.[0]?.message?.content;
+	if (typeof content === "string") return content;
+	if (Array.isArray(content)) {
+		// 部分模型返回 content 数组（Anthropic 风格块）
+		return content
+			.map((b) => (b?.type === "text" ? b.text : ""))
+			.join("")
+			.trim();
+	}
+	return "";
+}
+
+/**
+ * 构建 OpenAI 兼容的 VLM 请求体。
+ * @param {object} opts - { model, prompt, imageBase64, mimeType }
+ * @returns {object} chat/completions 请求体
+ */
+export function buildVLMRequestBody({ model, prompt, imageBase64, mimeType }) {
+	return {
+		model,
+		messages: [{
+			role: "user",
+			content: [
+				{ type: "text", text: prompt },
+				{ type: "image_url", image_url: { url: `data:${mimeType};base64,${imageBase64}` } },
+			],
+		}],
+		max_tokens: VLM_MAX_TOKENS,
+	};
+}
+
+/** 根据文件扩展名推断图片 MIME 类型（未知按 jpeg 兜底） */
+export function mimeTypeForPath(filePath) {
+	return filePath.toLowerCase().endsWith(".png") ? "image/png" : "image/jpeg";
+}
+
+/**
+ * 从多供应商配置中解析指定供应商。
+ * @param {object} config - 插件 Config（含 providers 与 defaultProvider）
+ * @param {string} [providerId] - 指定供应商 id；缺省用 defaultProvider
+ * @returns {{id: string, baseUrl: string, model: string, apiKeyEnv: string}} 供应商配置
+ * @throws {Error} 供应商不存在时
+ */
+export function resolveProvider(config, providerId) {
+	const id = providerId || config.defaultProvider || "bailian";
+	const provider = config.providers?.[id];
+	if (!provider) {
+		const available = Object.keys(config.providers ?? {}).join(", ");
+		throw new Error(
+			`未知的 VLM 供应商 "${id}"。可用：${available || "（未配置任何供应商）"}。` +
+			"可在 cordis.patch.yml 中 dsh-vision 节点的 config.providers 下添加。"
+		);
+	}
+	return { id, baseUrl: provider.baseUrl, model: provider.model, apiKeyEnv: provider.apiKeyEnv };
+}

package/lib/index.js

@@ -0,0 +1,230 @@
+// dsh-vision 插件：给模型提供图片理解能力
+// - read_image_text : 本地 OCR（macOS Vision），免费离线，识别图中文字
+// - describe_image  : 云端 VLM（OpenAI 兼容端点，默认阿里云百炼 qwen3-vl-flash），理解画面内容
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readFile, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import z from "@deepseek-ai/schemastery";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import {
+	VLM_TIMEOUT_MS,
+	VLM_MAX_IMAGE_DIM,
+	JPEG_QUALITY,
+	OCR_TIMEOUT_MS,
+	DEFAULT_DESCRIBE_PROMPT,
+	resolveApiKey,
+	extractDescription,
+	buildVLMRequestBody,
+	mimeTypeForPath,
+	resolveProvider,
+} from "./core.js";
+
+const execFileAsync = promisify(execFile);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export const name = "dsh-vision";
+export const inject = ["tools"];
+
+const providerSchema = z.object({
+	baseUrl: z.string(),
+	model: z.string(),
+	apiKeyEnv: z.string(),
+});
+
+export const Config = z.object({
+	/** 本地 OCR 可执行文件路径（默认指向插件 bin/vision-ocr） */
+	ocrBin: z.string().default(""),
+	/** 默认 VLM 供应商 id（对应 providers 的键名） */
+	defaultProvider: z.string().default("bailian"),
+	/** 多供应商 VLM 配置：每个供应商为 OpenAI 兼容端点 */
+	providers: z.object({
+		bailian: providerSchema.default({
+			baseUrl: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+			model: "qwen3-vl-flash",
+			apiKeyEnv: "DASHSCOPE_API_KEY",
+		}),
+		siliconflow: providerSchema.default({
+			baseUrl: "https://api.siliconflow.cn/v1",
+			model: "Qwen/Qwen2.5-VL-7B-Instruct",
+			apiKeyEnv: "SILICONFLOW_API_KEY",
+		}),
+		zhipu: providerSchema.default({
+			baseUrl: "https://open.bigmodel.cn/api/paas/v4",
+			model: "glm-4v-flash",
+			apiKeyEnv: "ZHIPU_API_KEY",
+		}),
+		volcengine: providerSchema.default({
+			baseUrl: "https://ark.cn-beijing.volces.com/api/v3",
+			model: "doubao-seed-1.6-vision",
+			apiKeyEnv: "ARK_API_KEY",
+		}),
+	}),
+	/** 上传前压缩图片的最长边（像素） */
+	vlmMaxImageDim: z.number().default(VLM_MAX_IMAGE_DIM),
+});
+
+/** 用 sips 把图片压到最长边 <= maxDim 的 JPEG；失败时退回原图（不落盘） */
+async function prepareImage(filePath, maxDim) {
+	const tmpOut = join(__dirname, "..", ".cache", `vlm_${Date.now()}_${Math.random().toString(36).slice(2, 8)}.jpg`);
+	try {
+		await execFileAsync("sips", [
+			"-Z", String(maxDim),
+			"-s", "format", "jpeg",
+			"-s", "formatOptions", String(JPEG_QUALITY),
+			filePath, "--out", tmpOut,
+		]);
+		return { path: tmpOut, cleanup: () => void unlink(tmpOut).catch(() => {}) };
+	} catch {
+		return { path: filePath, cleanup: () => {} };
+	}
+}
+
+/** 调用 OpenAI 兼容 VLM 端点，返回描述文本 */
+async function callVLM({ baseUrl, model, apiKey, imagePath, question }) {
+	const { path, cleanup } = await prepareImage(imagePath, VLM_MAX_IMAGE_DIM);
+	try {
+		const imageBytes = await readFile(path);
+		const imageBase64 = imageBytes.toString("base64");
+		const prompt = question && question.trim().length > 0 ? question : DEFAULT_DESCRIBE_PROMPT;
+		const body = buildVLMRequestBody({
+			model,
+			prompt,
+			imageBase64,
+			mimeType: mimeTypeForPath(path),
+		});
+
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), VLM_TIMEOUT_MS);
+		let res;
+		try {
+			res = await fetch(`${baseUrl}/chat/completions`, {
+				method: "POST",
+				headers: { "Content-Type": "application/json", "Authorization": `Bearer ${apiKey}` },
+				body: JSON.stringify(body),
+				signal: controller.signal,
+			});
+		} finally {
+			clearTimeout(timer);
+		}
+
+		if (!res.ok) {
+			const detail = (await res.text()).slice(0, 500);
+			throw new Error(`VLM HTTP ${res.status}: ${detail}`);
+		}
+		const description = extractDescription(await res.json());
+		return description || "(空回复)";
+	} finally {
+		cleanup();
+	}
+}
+
+export function apply(ctx, config) {
+	const resolved = config;
+	const ocrBin = resolved.ocrBin && resolved.ocrBin.length > 0
+		? resolved.ocrBin
+		: join(__dirname, "..", "bin", "vision-ocr");
+
+	// ── 工具1：本地 OCR ────────────────────────────────────────────────
+	ctx.tools.register(defineTool({
+		name: "read_image_text",
+		description: "识别图片中的文字（OCR）。使用 macOS 本地 Vision 引擎，免费、离线、隐私安全，支持中英文。返回按阅读顺序排列的文本行与图片尺寸。",
+		parameters: {
+			file_path: {
+				type: "string",
+				required: true,
+				description: "图片文件路径（PNG/JPEG 等）",
+			},
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					path: { type: "string", required: true },
+					width: { type: "integer", required: true },
+					height: { type: "integer", required: true },
+					text: { type: "string", required: true },
+					lines: { type: "array", items: { type: "string" } },
+				},
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: `【图片文字识别】 ${value.path} (${value.width}x${value.height})\n${value.text}`,
+			}],
+		},
+		async execute(args) {
+			const { stdout } = await execFileAsync(ocrBin, [args.file_path, "--json"], { timeout: OCR_TIMEOUT_MS });
+			const parsed = JSON.parse(stdout);
+			const lines = parsed.lines.map((l) => l.text);
+			return {
+				path: args.file_path,
+				width: parsed.width,
+				height: parsed.height,
+				text: lines.length > 0 ? lines.join("\n") : "(未检测到文字)",
+				lines,
+			};
+		},
+	}));
+
+	// ── 工具2：云端 VLM 画面理解 ──────────────────────────────────────
+	ctx.tools.register(defineTool({
+		name: "describe_image",
+		description: "理解图片的画面内容（视觉语言模型 VLM）。调用可配置的云端视觉模型（默认阿里云百炼 qwen3-vl-flash），返回对图片内容的自然语言描述或对指定问题的回答。需要先配置 API Key（环境变量或 ~/.dsh/.credentials.yaml）。",
+		parameters: {
+			file_path: {
+				type: "string",
+				required: true,
+				description: "图片文件路径（PNG/JPEG）",
+			},
+			question: {
+				type: "string",
+				required: false,
+				description: "可选的具体问题；留空则描述整体画面内容",
+			},
+			provider: {
+				type: "string",
+				required: false,
+				description: "可选：VLM 供应商 id（bailian / siliconflow / zhipu / volcengine，或自定义）。留空用默认供应商。",
+			},
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					path: { type: "string", required: true },
+					model: { type: "string", required: true },
+					description: { type: "string", required: true },
+				},
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: `【图片理解·${value.model}】 ${value.path}\n${value.description}`,
+			}],
+		},
+		async execute(args) {
+			const provider = resolveProvider(resolved, args.provider);
+			const apiKey = resolveApiKey(provider.apiKeyEnv);
+			if (!apiKey) {
+				throw new Error(
+					`describe_image (${provider.id}) 需要 API Key：请设置环境变量 ${provider.apiKeyEnv}，` +
+					`或添加到 ~/.dsh/.credentials.yaml（例如：${provider.apiKeyEnv}: sk-xxx）。`
+				);
+			}
+			const description = await callVLM({
+				baseUrl: provider.baseUrl,
+				model: provider.model,
+				apiKey,
+				imagePath: args.file_path,
+				question: args.question,
+			});
+			return {
+				path: args.file_path,
+				model: `${provider.id}:${provider.model}`,
+				description,
+			};
+		},
+	}));
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@floatingsk/dsh-vision",
+  "version": "0.1.0",
+  "description": "dsh 视觉插件：本地 OCR（macOS Vision）+ 云端 VLM 图片理解（OpenAI 兼容）",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "lib",
+    "bin/vision-ocr.swift",
+    "bin/vision-ocr.ps1",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test \"test/*.test.js\"",
+    "build:ocr": "swiftc -Xcc -fmodules-cache-path=\"$PWD/.cache\" -O bin/vision-ocr.swift -o bin/vision-ocr"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "cordis",
+    "plugin",
+    "vision",
+    "vlm",
+    "ocr",
+    "image"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/dsh-tools": "*",
+    "@deepseek-ai/schemastery": "*"
+  }
+}