deepseek-harness-vision-plugin

给 Agent 增加视觉输入能力的 DeepSeek Harness 插件。作者：edison。

本插件支持两种使用方式：

1. 在 DeepSeek Harness 对话框中直接发送“文字 + 图片”，自动切换到视觉模型；纯文字请求继续使用默认的 DeepSeek 模型。
2. 向 Agent 注册 vision_analyze 工具，让 Agent 主动读取工作区中的本地图片，用于描述、OCR 或 UI 分析。

底层请求使用 OpenAI-compatible POST /chat/completions，因此可以接入 Sub2API、DashScope 兼容接口或其他支持视觉输入的网关。

工作方式

Harness 对话框：文字 + 图片
        │
        ├─ 没有图片 → 默认 DeepSeek 模型
        │
        └─ 有图片 → vision-auto → OpenAI-compatible 视觉模型
                         │
                         └─ 返回结果后，Agent 继续处理文字和工具调用

图片会作为当前消息的一部分发送，不需要手动切换模型。一个会话一旦包含过图片，后续步骤也会继续使用视觉路由以保留图片上下文；要回到纯文字路由时，新建一个会话即可。

安装到 DeepSeek Harness

前置条件：已安装可运行的 DeepSeek Harness 和 Node.js 20+。

git clone https://github.com/edison-land/deepseek-harness-vision-plugin.git
cd deepseek-harness-vision-plugin

# 将本地插件加入 web profile
dsh plugin --profile web add .

然后在启动 DSH 的同一个终端设置配置并启动：

export VISION_API_KEY='你的视觉网关用户 API Key'
export VISION_BASE_URL='http://127.0.0.1:8080/v1'
export VISION_MODEL='gpt-4o'

dsh web

打开 Harness Web 对话框，在同一条消息中输入文字，再点击 + 上传图片并发送即可。

如果你使用的是其他 DSH profile，把上面的 --profile web 换成实际 profile 名称。环境变量必须在启动 DSH 前设置；修改后需要重启 DSH。

API Key 和模型设置

插件只从运行时环境变量读取密钥，不会把密钥写进 cordis.patch.yml、日志或工具 schema。

优先级如下：

配置	作用	默认值
VISION_API_KEY	通用视觉服务 API Key	无
VISION_BASE_URL	OpenAI-compatible 服务的 /v1 根地址	https://dashscope.aliyuncs.com/compatible-mode/v1
VISION_MODEL	视觉模型 ID，必须是网关实际暴露的名称	qwen3-vl-plus
VISION_MAX_IMAGE_BYTES	单张图片最大字节数	10485760
VISION_MAX_TOKENS	视觉请求最大输出 token	自动路由 8192，工具 2048
VISION_TIMEOUT_MS	请求超时时间	120000

也可以复制配置模板：

cp .env.example .env

.env 不会被 Git 跟踪，但 DSH 不会自动读取它；请把变量 export 到启动 DSH 的 shell 中，或使用你自己的环境变量加载器。

使用 Sub2API 反代 GPT

这是本地 Sub2API 的典型配置：

export VISION_API_KEY='Sub2API 生成的用户/客户端 API Key'
export VISION_BASE_URL='http://127.0.0.1:8080/v1'
export VISION_MODEL='gpt-4o'

注意：

• VISION_API_KEY 必须是 Sub2API 给 API 客户端使用的用户 API Key。
• 不要把 Sub2API 管理员登录密码、管理员 JWT 或 x-api-key 管理密钥填到这里。
• VISION_MODEL 必须填写 Sub2API 账号/分组实际暴露的模型 ID，例如 gpt-4o；具体名称以你的 Sub2API 管理页或 /v1/models 返回结果为准。
• Sub2API 服务必须先启动并监听 127.0.0.1:8080。如果它部署在其他机器，把 127.0.0.1 换成网关所在主机地址。

可以先只检查模型列表，不发送图片请求：

curl -sS "${VISION_BASE_URL%/}/models" \
  -H "Authorization: Bearer ${VISION_API_KEY}"

使用 DashScope

export DASHSCOPE_API_KEY='你的 DashScope API Key'
export VISION_BASE_URL='https://dashscope.aliyuncs.com/compatible-mode/v1'
export VISION_MODEL='qwen3-vl-plus'

VISION_API_KEY 优先于 DASHSCOPE_API_KEY。如果两者都设置，插件使用 VISION_API_KEY。

使用其他 OpenAI-compatible 网关

只要服务支持视觉消息格式，就可以这样配置：

export VISION_API_KEY='your-client-api-key'
export VISION_BASE_URL='https://your-gateway.example.com/v1'
export VISION_MODEL='your-vision-model-id'

其中 VISION_BASE_URL 是 API 的 /v1 根地址，不要重复拼接 /chat/completions。插件会自动请求：

POST ${VISION_BASE_URL}/chat/completions
Authorization: Bearer ${VISION_API_KEY}

vision_analyze 工具

当 Agent 需要显式调用工具时，会看到 vision_analyze。参数如下：

{
  "image_path": "screenshots/login.png",
  "task": "ui",
  "instruction": "列出登录按钮、输入框及其大致位置",
  "language": "zh-CN"
}

参数说明：

• image_path：当前 Harness 工作区内的本地图片路径。
• task：describe、ocr、ui 或 custom。
• instruction：可选的具体问题或额外要求。
• language：可选的回答语言，例如 zh-CN 或 en-US。

插件只读取 Harness ctx.fs 能访问的文件，不接受远程 URL；支持 PNG、JPEG、WebP 和 GIF，并按文件魔数确认真实 MIME 类型。

Codex、Claude Code 和其他 Agent 接入

这个仓库本身是 DeepSeek Harness 插件，但视觉请求遵循通用的 OpenAI-compatible 协议。因此其他 Agent 有两种接入方式。

方式 A：直接使用 Agent 自带的图片输入

如果 Codex、Claude Code 或其他 Agent 的对话界面本身支持图片附件，直接附加图片并提问即可。把它们的模型服务配置到同一个视觉网关，并使用：

Base URL: ${VISION_BASE_URL}
API Key:  ${VISION_API_KEY}
Model:    ${VISION_MODEL}

这类 Agent 不需要安装本仓库的 DSH 插件；本仓库主要负责给 DeepSeek Harness 增加自动路由和 vision_analyze 工具。

方式 B：通过 OpenAI-compatible API 或自定义工具调用

任何能发送 OpenAI-compatible 请求的 Agent、MCP server、脚本或工作流都可以复用同一个网关配置。仓库提供了一个最小示例：

export VISION_API_KEY='your-client-api-key'
export VISION_BASE_URL='http://127.0.0.1:8080/v1'
export VISION_MODEL='gpt-4o'

./examples/vision-request.sh screenshots/login.png '识别这张图中的文字，并列出所有按钮'

等价的请求结构是：

{
  "model": "gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "识别这张图中的文字"},
        {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
      ]
    }
  ]
}

这样，Claude Code、Codex CLI、Python/Node Agent、MCP 工具或其他编排器都可以把本地图片转成 Data URL 后调用同一接口。

安全与限制

• 不要把真实 API Key 写进源码、README、cordis.patch.yml 或提交记录。
• 不要把 Sub2API 管理凭据发到公共仓库；公开接入只使用客户端 API Key。
• 默认单张图片上限为 10 MiB，代码上限为 50 MiB。
• 图片会编码为 Base64 后发送到你配置的视觉网关；请确认该网关的隐私和计费策略。
• 本插件不会替你充值、创建账号或执行管理员操作。

本地开发与测试

npm test
node --check src/index.mjs

测试使用本地模拟的 OpenAI-compatible HTTP 服务，不需要 API Key，也不会产生模型费用。

License

MIT © 2026 edison