# opencode-vision-mcp

给**不支持多模态的模型**（如 DeepSeek）提供"看图"能力的完整解决方案：**vision MCP server + opencode 粘贴落盘插件**。

让 DeepSeek 等纯文本模型也能直接看懂你粘贴/引用的图片：

```
你在对话框粘贴图片
  ↓ 插件 vision-paste.js 拦截（chat.message hook）
图片自动落盘到本地文件
  ↓ 插件把图片 part 改写为"仅模型可见"的路径指引
模型读到路径 → 调用 vision_analyze_image 工具
  ↓ vision MCP server 读取图片 → 转发给多模态后端
通义千问 Qwen-VL / 豆包 / GLM-4V 返回文字描述
  ↓
模型把识别结果转达给你
```

**图片字节全程不进入主模型上下文**——主模型只接触"路径字符串"和"文字描述"，不会被 base64 污染。

---

## 功能特性

- 🖼️ **粘贴即识别**：opencode 对话框直接粘贴图片，自动落盘并识别，无需手动保存路径
- 🔄 **多后端可切换**：通义千问 Qwen-VL / 豆包 / GLM-4V，环境变量切换或单次调用覆盖
- 🧮 **结果缓存**：同图同参数重复识别直接命中缓存，节省 API 费用（默认 128 条 / 1 小时）
- 🔁 **自动重试**：429 限流 / 5xx 服务端错误指数退避重试（默认 2 次）
- 🖼️ **多图对比**：一次传入多张图片做对比分析
- 🔒 **Key 安全**：API key 仅存本地 `.env`，不进入代码库

---

## 目录结构

```
opencode-vision-mcp/
├── server.py              # vision MCP server 主程序（stdio 传输）
├── plugins/
│   └── vision-paste.js    # opencode 插件：粘贴图片自动落盘
├── requirements.txt       # Python 依赖
├── .env.example           # 环境变量模板
├── README.md              # 本文件
└── LICENSE                # MIT
```

---

## 安装

### 1. 环境要求

- Python >= 3.10
- opencode（仅插件需要）
- 至少一个多模态后端的 API key（见下表）

### 2. 克隆并安装 MCP server

```bash
git clone https://github.com/Jsliu28/opencode-vision-mcp.git
cd opencode-vision-mcp

# 创建虚拟环境并安装依赖
python -m venv .venv
# Windows:
.\.venv\Scripts\Activate.ps1
# macOS/Linux:
source .venv/bin/activate

pip install -r requirements.txt

# 配置 API key
cp .env.example .env
# 编辑 .env，填入你的 key（见下节）
```

### 3. 配置 API key

复制 `.env.example` 为 `.env` 后填写。**至少配置一个后端**即可；配置多个后可用 `provider` 参数切换。

| 标识 | 名称 | API key 环境变量 | 默认模型 |
|------|------|-----------------|----------|
| `qwen` | 通义千问 Qwen-VL | `DASHSCOPE_API_KEY` | qwen-vl-max |
| `doubao` | 火山方舟豆包 | `ARK_API_KEY` | doubao-1-5-vision-pro-32k-250115 |
| `zhipu` | 智谱 GLM-4V | `ZHIPU_API_KEY` | glm-4v-plus |

Key 申请地址：
- 通义千问：<https://bailian.console.aliyun.com/>
- 火山方舟：<https://console.volcengine.com/ark>
- 智谱：<https://open.bigmodel.cn/>

### 4. 安装 opencode 插件

把 `plugins/vision-paste.js` 复制到 opencode 插件目录：

```bash
# Windows
copy plugins\vision-paste.js %USERPROFILE%\.config\opencode\plugins\

# macOS/Linux
cp plugins/vision-paste.js ~/.config/opencode/plugins/
```

重启 opencode 生效。

---

## 配置到 opencode

编辑 `~/.config/opencode/opencode.json`：

```json
{
  "mcp": {
    "vision": {
      "type": "local",
      "command": ["python", "C:/你的路径/opencode-vision-mcp/server.py"],
      "enabled": true,
      "environment": {
        "VISION_DEFAULT_PROVIDER": "qwen"
      }
    }
  }
}
```

> 说明：API key 在 `.env` 中，server 启动时会自动读取，无需重复配置在 `environment` 里（如同时存在，`environment` 优先）。
> 如果 `python` 不在 PATH 中，使用虚拟环境解释器绝对路径，如 `C:/你的路径/opencode-vision-mcp/.venv/Scripts/python.exe`。

---

## 使用示例

### 在 opencode 对话框中

```
你：粘贴一张图片（或拖拽文件生成 @ 路径）
    "这张图里有什么？"

opencode：自动识别并返回图片描述
```

```
你：粘贴两张图片
    "对比这两张截图有什么不同？"

opencode：多图对比分析
```

### 直接传路径 / URL

```
你：分析 C:/Users/me/photo.png
你：识别 https://example.com/cat.jpg
```

### 指定后端 / 模型

```
你：用豆包分析这张图 C:/Users/me/photo.png
```

---

## 工具说明

### vision_analyze_image
分析一张或多张图片，返回文字描述。参数：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `images` | `string[]` | ✅ | 图片引用**列表**（1 张或多张），每项为本地**绝对路径**或 http(s) URL |
| `prompt` | `string` | ❌ | 对图片的问题/指令，默认"详细描述图片内容，多张时对比分析" |
| `provider` | `string` | ❌ | `qwen` / `doubao` / `zhipu`，覆盖默认后端 |
| `model` | `string` | ❌ | 具体模型名，留空用该后端默认模型 |
| `temperature` | `number` | ❌ | 0~2，默认 0.3 |

### vision_list_providers
列出当前各后端配置状态（是否已填 API key）与可用模型。

---

## 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `VISION_DEFAULT_PROVIDER` | `qwen` | 默认后端：qwen / doubao / zhipu |
| `DASHSCOPE_API_KEY` | - | 通义千问 key |
| `ARK_API_KEY` | - | 火山方舟 key |
| `ZHIPU_API_KEY` | - | 智谱 key |
| `VISION_CACHE_ENABLED` | `true` | 是否启用结果缓存 |
| `VISION_CACHE_SIZE` | `128` | 缓存最大条数 |
| `VISION_CACHE_TTL` | `3600` | 缓存有效期（秒） |
| `VISION_MAX_RETRIES` | `2` | 失败重试次数 |
| `VISION_RETRY_BASE_DELAY` | `1.0` | 首次重试等待秒数（之后指数翻倍，上限 10s） |

---

## 常见问题

**Q: 粘贴图片后没有任何反应？**
A: 确认插件已放入 `~/.config/opencode/plugins/` 并重启 opencode；确认 vision MCP 已启用（`/mcp` 查看）。

**Q: 提示"后端未配置"？**
A: 检查 `.env` 中对应 key 是否填写正确，`vision_list_providers` 可查看配置状态。

**Q: 图片能上传但识别失败？**
A: 单张图片限制 20MB；本地路径必须是绝对路径；URL 需可公开访问（部分网站有防盗链）。

**Q: 识别结果能缓存吗？**
A: 默认开启。同图同参数（含 prompt/temperature）重复调用直接命中缓存。

**Q: API key 会泄露到代码库吗？**
A: 不会。`.env` 已被 `.gitignore` 排除，key 仅存本地。

---

## License

[MIT](./LICENSE)