co-Elly/dsh-plugin-vision

👁️ dsh-plugin-vision

为你的 DeepSeek Harness 装上眼睛

License: MIT
DeepSeek Harness
Stars

dsh-plugin-vision 是一个 DeepSeek Harness 插件，让纯文本大语言模型具备"看图"能力。

当你的底层模型不支持原生图片输入时（如 DeepSeek-V3 纯文本版），这个插件通过调用智谱 GLM-4V-Flash（免费视觉模型）来分析图片，返回文本描述。

用户粘贴图片 → Agent 调用 vision_analyze → GLM-4V-Flash 分析 → 返回文本描述

✨ 功能特性

- 🖼️ 分析本地图片文件（PNG/JPEG/WebP/GIF）
- 🌐 分析 HTTP(S) URL 图片
- 🔤 本地文件自动 base64 编码
- 🆓 使用智谱免费视觉模型，无需付费
- 🔌 遵循 DSH Capability Seam 架构
- 🧩 Cordis 插件，通过 cordis.yml 即可使用

📦 安装

方式一：克隆并链接

git clone https://github.com/co-Elly/dsh-plugin-vision.git
cd dsh-plugin-vision
pnpm install
pnpm build

然后在你的 DSH 项目的 cordis.yml 中引用：

plugins:
- name: /path/to/dsh-plugin-vision/dist/cordis.js
config:
apiKey: "你的智谱API Key"

方式二：npm（即将上线）

pnpm add dsh-plugin-vision

⚙️ 配置

获取免费 API Key

1. 访问智谱开放平台
2. 注册并登录
3. 在 API Keys 页面创建 Key
4. glm-4v-flash 模型免费，无需付费

环境变量

export ZHIPU_API_KEY="your-api-key"

cordis.yml 配置

plugins:
- name: dsh-plugin-vision/cordis
config:
apiKey: "your-api-key"           # 或使用 $ZHIPU_API_KEY 环境变量
baseUrl: "https://api.z.ai/api/paas/v4/chat/completions"  # 默认免费 API
model: "glm-4v-flash"            # 默认免费模型

🚀 使用

插件注册后，agent 会自动获得 vision_analyze 工具：

vision_analyze({
image_path: "/path/to/screenshot.png",
question: "这张图里有什么？"
})

参数

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| image_path | string | ✅ | 图片文件路径或 HTTP(S) URL |
| question | string | ❌ | 关于图片的问题，默认为"请描述这张图片的内容" |

返回

{
"description": "一张柱状图，显示了月度收入..."
}

🏗️ 架构

本插件遵循 DSH 的 Capability Seam 模式：

┌─────────────────────────────────────────────────┐
│                  dsh-plugin-vision               │
├─────────────┬─────────────────┬─────────────────┤
│  vision.ts  │  vision-glm.ts  │  tool-vision.ts │
│  (服务定义)  │  (服务提供者:    │  (消费者:       │
│             │  GLM-4V-Flash)  │  vision_analyze)│
├─────────────┼─────────────────┼─────────────────┤
│  定义        │  调用智谱 API   │  向模型暴露     │
│  ctx.vision │  分析图片        │  工具           │
│  接口        │                 │                 │
└─────────────┴─────────────────┴─────────────────┘

文件说明

| 文件 | 角色 | 说明 |
|---|---|---|
| src/vision.ts | 服务定义 | 视觉能力的类型和接口 |
| src/vision-glm.ts | 服务提供者 | GLM-4V-Flash 实现（智谱 AI） |
| src/tool-vision.ts | 消费者 | vision_analyze 工具注册 |
| src/cordis.ts | 插件入口 | Cordis 插件，串联所有组件 |
| src/index.ts | 导出 | 公共 API 导出 |

🗺️ 技术路线图

Phase 1 (v1.0.0) ✅ 已完成
├── 核心视觉能力（Service Definition / Provider / Consumer）
├── GLM-4V-Flash 提供者（免费）
├── 本地文件支持（base64 编码）
├── HTTP(S) URL 支持
└── Cordis 插件集成

Phase 2 (v1.1.0) 🔜 计划中
├── OpenAI 兼容提供者（GPT-4o、Claude 3 等）
├── 本地视觉模型支持（moondream2、LLaVA）
└── 批量图片分析

Phase 3 (v1.2.0) 🔮 未来
├── 图片语言检测与自动提示
├── 视频帧提取与分析
└── OCR 专用提供者（含版面分析）

🤝 贡献

欢迎贡献！请参阅 CONTRIBUTING.md。

📄 许可证

MIT

为 DeepSeek Harness 社区用心打造 ❤️