# dsh-vision

支持 OpenAI 协议的 **vision MCP 服务器**：为 dsh 及其他 harness 提供视觉理解工具。图片/视频/文档理解通过任意 OpenAI 兼容的 chat-completions 端点完成，默认指向智谱 GLM 视觉模型。

- 工具：`vision_analyze`（图片/图表问答）、`vision_ocr`（文字提取）、`vision_video`（视频理解）、`vision_document`（文档问答）
- 输入支持：http(s) URL、本地文件路径、`file://` URI、`data:...;base64,...` URI
- 传输：`stdio`（harness 默认）与 `streamable-http`（远程/Web 场景）
- 后端：OpenAI 协议 chat-completions；图片走标准 `image_url`，视频/文档/思考链为智谱扩展（见下方兼容性说明）

## 安装

```powershell
git clone <repo> dsh-vision
cd dsh-vision
uv sync                 # 建 .venv 并安装依赖
```

## 配置（环境变量）

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `VISION_API_KEY` | — | API Key（必填）。回退顺序：`VISION_API_KEY` → `OPENAI_API_KEY` → `ZHIPU_API_KEY` |
| `VISION_BASE_URL` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI 兼容端点 |
| `VISION_MODEL` | `glm-4v-plus` | 默认模型（图片/视频可用 `glm-4v-plus`；文档与 thinking 需 `glm-4.6v`+） |
| `VISION_TIMEOUT` | `300` | 请求超时（秒） |
| `VISION_MAX_IMAGE_BYTES` / `VISION_MAX_IMAGES` | `20 MiB` / `4` | 本地图片大小上限 / 单次图片数量 |
| `VISION_MAX_VIDEO_BYTES` / `VISION_MAX_VIDEOS` | `50 MiB` / `1` | 本地视频大小上限 / 单次视频数量 |
| `VISION_MAX_FILE_BYTES` / `VISION_MAX_FILES` | `20 MiB` / `4` | 本地文档大小上限 / 单次文档数量 |
| `VISION_DOC_TOOL_TYPE` | `lite` | 智谱文档解析工具：`lite`（免费）`expert`（PDF 表格/公式更准）`prime`（复杂排版） |
| `VISION_MAX_DOC_CHARS` | `500000` | 解析后的文档文本喂给模型的最大字符数 |
| `VISION_TRANSPORT` / `VISION_HOST` / `VISION_PORT` | `stdio` / `127.0.0.1` / `8000` | streamable-http 模式下的监听参数 |

## 运行

```powershell
# stdio（harness 用）
$env:VISION_API_KEY = "<你的智谱 API Key>"
uv run dsh-vision                          # 或 .venv\Scripts\dsh-vision.exe

# streamable-http
uv run dsh-vision --transport streamable-http --host 127.0.0.1 --port 8000
```

## 工具用法

### vision_analyze — 图片/图表问答

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `images` | `list[str]` | 图片引用：URL / 本地路径 / data URI（照片、截图、UI、图表、曲线图、原理图均可） |
| `prompt` | `str` | 给视觉模型的指令或问题，越具体越好 |
| `model` | `str?` | 可选模型覆盖（如 `glm-4.6v`） |
| `max_tokens` | `int?` | 可选回复长度上限 |
| `thinking` | `bool` | 开启推理链（智谱 `glm-4.6v`+，复杂图表/文档推荐开启） |
| `use_search` | `bool` | **搜索增强**（仅智谱端点）：① 提取图中可查证的关键信息与厂商标志/型号 → ② 多路搜索（含厂商官网定向 datasheet 查询，内置 TI/ADI/ST/NXP 等厂商映射）→ ③ 结合证据作答并**逐项交叉比对**，矛盾点标注来源。更准但慢（约 3-5 次 API 调用），适合冷门/专业内容 |

### vision_ocr — 文字提取

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `images` | `list[str]` | 同 `vision_analyze` |

### vision_video — 视频理解

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `videos` | `list[str]` | 视频引用：URL / 本地路径（mp4/mov/avi/mkv/webm 等）/ data URI |
| `prompt` | `str` | 问题或指令，如"总结这个视频"、"第几秒出现人物？" |
| `model` / `max_tokens` / `thinking` | — | 同 `vision_analyze` |

### vision_document — 文档问答

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `files` | `list[str]` | 文档引用：URL / 本地路径 / data URI（pdf/doc/docx/xls/xlsx/ppt/pptx/txt/md/csv） |
| `prompt` | `str` | 问题或指令，如"总结要点"、"第 2 页表格的最大值是多少？" |
| `model` / `max_tokens` / `thinking` | — | 同 `vision_analyze`（文档建议 `glm-4.6v`） |

智谱端点的文档走**文件解析服务**：本地/URL 文档先经解析器（`lite` 免费 / `expert` / `prime`，见配置）提取文本，再把文本与问题一起交给模型回答；扫描版 PDF 建议把 `VISION_DOC_TOOL_TYPE` 设为 `expert`（带 OCR）。其他 OpenAI 兼容端点使用通用 `file_url` 内容块直传。

失败时工具返回 `[vision error] ...` 文本而不是让 MCP 会话报错，方便模型自行修正重试。

### use_search 实战示例：芯片型号识别

对元件照片（PCB/IC 实物图）这类冷门专业内容，`use_search` 的价值最明显：

```json
{
  "images": ["OPA1612A-IC.webp"],
  "prompt": "图中是什么芯片？请给出完整型号和关键参数，并说明依据。",
  "use_search": true
}
```

实测（OPA1612A 音频运放，v0.4.0）：厂商定向查询与交叉比对生效——模型主动发现并正确裁决了噪声/供电/THD+N 三处来源矛盾（采信 TI 官方值 1.1nV/√Hz 等）；但通道数仍被一处错误搜索摘要带偏（说成单通道）。**结论：搜索增强显著提升参数查证能力，但搜索摘要本身可能含幻觉，专业场景请以官方 datasheet 为准**（后续改进见 `TODO.md`）。

## 兼容性说明

- ✅ **已实测**：智谱 GLM —— `glm-4v-plus`（图片/视频）、`glm-4.6v`（文档、复杂图表、thinking），均用真实图片、视频和数学建模竞赛 PDF 验证过。
- ⚠️ **尚未用其他供应商测试**：OpenAI、DeepSeek、Qwen/DashScope、本地 vLLM 等只是按 OpenAI 协议实现，没有实测。其中：
  - 图片理解（`vision_analyze`/`vision_ocr`）走标准 `image_url`，兼容性预期较好；
  - `video_url`、`file_url` 内容块、`thinking` 参数与 `use_search` 搜索增强都是**智谱对 OpenAI 协议的扩展**，其他供应商可能不支持或格式不同，使用前请先验证；
  - 智谱端点下 `vision_document` 使用智谱文件解析服务（非 OpenAI 协议），仅适用于 `bigmodel.cn` 的 base_url。
- 欢迎在其他供应商上测试后反馈结果（issue/PR）。

## 接入 dsh

在 harness 的 MCP 配置中注册 stdio 服务器：

```yaml
command: .venv\Scripts\dsh-vision.exe   # 或 uv run --directory <项目路径> dsh-vision
env:
  VISION_API_KEY: "<你的智谱 API Key>"
```

（具体写入位置按 `dsh-mcp-install` 技能 / harness 文档执行。）

## 开发

```powershell
uv run pytest            # 单元测试 + stdio 端到端冒烟
uv build                 # 打包 wheel
```

端到端脚本（需要智谱 API Key）：

```powershell
uv run python scripts/e2e_zhipu.py --mcp          # 图片链路
uv run python scripts/e2e_media.py                # 视频/文档/图表思考链路
uv run python scripts/e2e_doc.py <文件> <问题>     # 文档问答
uv run python scripts/e2e_search.py               # 搜索增强 vs 普通对比
```

## 测试智谱视觉模型

1. 到 [open.bigmodel.cn](https://open.bigmodel.cn) 创建 API Key
2. 设置 `VISION_API_KEY` 后启动服务器
3. 调用工具，例如：

```json
{"images": ["https://example.com/photo.png"], "prompt": "描述图片内容"}
{"videos": ["C:\\videos\\clip.mp4"], "prompt": "总结这个视频"}
{"files": ["https://example.com/report.pdf"], "prompt": "总结要点", "model": "glm-4.6v"}
```