ankye/dsh-client-vision

dsh-client-vision

给你的 DeepSeek Harness agent 装上眼睛。dsh-client-vision 是面向 DeepSeek Harness 的截图 + 外部图像识别插件：agent 按需截图（或指定任意图片），通过可插拔通道交给具备视觉能力的模型，拿回纯文本描述后继续干活——完全不需要多模态模型。

兼容性

本修订要求 DeepSeek Harness core 为 0.1.2-alpha.5 或以上的 0.1.x 版本；它使用该 core 版本引入的 Settings 服务 API。

为什么值得装

- deepseek 看不到？现在能了。 harness 模型没有图像输入。本插件把「看图」整个过程放在模型之外，返回 agent 能直接推理的文本——和 Codex 的语义识图工具一个思路。
- 想截什么、怎么截都行。 fullscreen 全屏 / window 指定窗口（实时窗口枚举）/ region 指定区域 / interactive 手动框选——抓浏览器、抓游戏窗口、抓屏幕一角。
- 多通道架构，天生可扩展。 工具入口与识别后端完全解耦。gpt 通道开箱即用；加 Claude / Gemini / 本地模型 = 一个 analyze() 实现 + 一行注册，三个工具契约永远不用改。
- 密钥安全。 API Key 存在 harness credentials 服务里（VISION_GPT_API_KEY）——绝不进设置文件、日志或会话记录。
- 所有 preset 开箱即用。 host 层全局挂载，code / standard / cordis / minimal 任何 preset 的 agent 都能调用，无需切换。
- 开箱可分发。 附构建产物；三种安装路径（拖入 monorepo / pnpm publish / tarball）。
- 智能压缩。 大图自动降采样重编码（≤1568px JPEG q80）后再发出去，控制网关 payload。

能力说明

工具

| 工具 | 作用 |
|---|---|
| take_screenshot | 截图：fullscreen（主屏）/ window（配合 list_windows 的 id）/ region（x, y, w, h）/ interactive（用户框选）/ android（adb 设备或模拟器）/ ios（已启动的模拟器）。返回 PNG 路径 + 尺寸。 |
| list_windows | 枚举屏幕上的窗口（id、app、title）——macOS CGWindowList、Windows Get-Process 主窗口句柄、Linux X11（wmctrl/xprop），挑出要截的浏览器或游戏窗口。 |
| analyze_image | 把图片（指定路径，或最近一次截图）交给当前配置的视觉通道，返回纯文本描述。 |
| view_image | 一步「看一下」：截屏（或传入 image_path）并经活动通道识别。截图会在 Web 对话中渲染为图片卡片，而模型上下文只拿到文字描述——图片字节从不进入模型上下文。 |

平台

| 平台 | 截图后端 | 窗口枚举 | 额外要求 |
|---|---|---|---|
| macOS | 系统 screencapture | Swift CGWindowList | 首次使用授予屏幕录制权限 |
| Windows | PowerShell System.Drawing | Get-Process 主窗口句柄 | PowerShell System.Drawing |
| Linux | ImageMagick import | wmctrl + xprop | ImageMagick（convert/identify）、wmctrl、x11-utils |

interactive 手动框选只支持 macOS；Windows 和 Linux 请使用带坐标的 region。

设备截图

| 模式 | 截什么 | 要求 |
|---|---|---|
| android | 已连接的 Android 设备或模拟器屏幕 | PATH 里有 adb 且 adb devices 有在线设备；任意宿主系统可用。多个设备在线时传 device= |
| ios | 已启动的 iOS 模拟器 | macOS 宿主 + Xcode（xcrun simctl） |

设置（vision 命名空间）

配置入口：设置 → 插件 → 插件配置 →「图像识别」

| 字段 | 含义 |
|---|---|
| 接口地址（baseUrl） | 域名 + 可选路径前缀；自动拼接 /chat/completions。例：https://api.example.com/v1 |
| 识别通道 | 当前生效的视觉后端（目前为 gpt） |
| 模型 | gpt-5.5 / gpt-5.6-sol / gpt-5.6-terra |
| API Key | 通过 harness credentials 服务存储为 VISION_GPT_API_KEY；明文永远不离开你的机器 |

多通道架构

模型 → analyze_image(image, prompt)
│  读取 vision.channel
▼
channels//analyze()         ← 每个后端一个实现
│
gpt:    POST {baseUrl}/chat/completions   （image_url data URL）
claude / gemini / 本地模型: …   ← 在这里加你的

加一个通道，小到不能再小：

// src/channels//index.ts
export async function myAnalyze(ctx, call): Promise {
// call.imageB64 / call.mime / call.prompt / call.config / call.signal
return await fetchYourVisionApi(...)
}

// src/channels/index.ts —— 一行注册
export const channels = {
gpt: { label: 'GPT', analyze: gptAnalyze },
myChannel: { label: 'My Channel', analyze: myAnalyze },
}

take_screenshot / list_windows / analyze_image 三个工具及其 schema 永远不用改。

安装方式（官方部署，不改仓库）

dsh plugin add 把包装进 profile；每个包都声明了 dsh.bundle，挂载自动完成——不需要手写 patch 行、不需要改官方工程。

前置条件

- DeepSeek Harness core 0.1.2-alpha.5 或以上的 0.1.x 版本，且 dsh 与 pnpm 在 PATH。

1. 取包（三选一）

a. 从本仓库（发布前推荐）：

dsh plugin --profile web add \
file:/path/to/dsh-client-vision/packages/tool-vision \
file:/path/to/dsh-client-vision/packages/ui-vision

b. Tarball：

cd packages/tool-vision && npm pack
cd packages/ui-vision   && npm pack
dsh plugin --profile web add file:/path/to/deepseek-ai-dsh-tool-vision-0.1.0-rc.7.tgz \
file:/path/to/deepseek-ai-dsh-client-ui-vision-0.1.0-rc.7.tgz

c. npm registry（发布后）：

dsh plugin --profile web add @deepseek-ai/dsh-tool-vision @deepseek-ai/dsh-client-ui-vision

安装时的 [WARN] Issues with peer dependencies 是正常的，可忽略——peer 由部署自身的 bundle 在运行时提供。

2. 验证安装

node -e "console.log(JSON.stringify(require(process.env.HOME + '/.dsh/profiles/web/package.json').dsh.profile.bundles))"
应包含 dsh-tool-vision 与 dsh-client-ui-vision

3. 重启 + 配置

重启 harness，打开 设置 → 插件 → 插件配置 →「图像识别」：填接口地址、模型和你自己的 API Key（VISION_GPT_API_KEY），保存。

4. 功能验证

让 agent「看一下屏幕」——它会调用 take_screenshot → analyze_image 并描述看到的内容。

卸载

dsh plugin --profile web remove @deepseek-ai/dsh-tool-vision @deepseek-ai/dsh-client-ui-vision

备选：在 harness 分支内构建

如果你运行的是 deepseek-harness 的分支（而非官方部署），也可以把包拖进 monorepo：

cp -R packages/tool-vision /packages/vision/tool-vision
cp -R packages/ui-vision   /packages/client/ui-vision

然后在 harness 仓库内：apps/cli/package.json 加两个依赖（workspace:^）、tsconfig.host.json/tsconfig.client.json 加引用、pnpm install、构建（tsdown host + client），重启。

快速上手

1. 重启 harness。
2. 工具目录出现 take_screenshot / list_windows / analyze_image。
3. 打开 设置 → 插件 → 插件配置 →「图像识别」，填接口地址、模型和你自己的 API Key，保存。
4. 让 agent「看一下屏幕」——它会截图并描述看到的内容。

开发说明

- 本仓库是源码分发形态：peer 依赖（@deepseek-ai/dsh-tools 等）来自你的部署；lib/ 已附构建产物，npm pack 立即可用。
- tsconfig.json 已适配独立目录；harness monorepo 内的构建管线（含 client bundle 的 tsdown.config.ts）在方式 A 下生效。
- 绝不提交密钥：API Key 只存在每台机器的 .credentials.yaml 里。

License

MIT