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，视频/文档/思考链为智谱扩展（见下方兼容性说明）

安装

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 模式下的监听参数

运行

# 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+，复杂图表/文档推荐开启）

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 会话报错，方便模型自行修正重试。

兼容性说明

• ✅ 已实测：智谱 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 参数是智谱对 OpenAI 协议的扩展，其他供应商可能不支持或格式不同，使用前请先验证；
  • 智谱端点下 vision_document 使用智谱文件解析服务（非 OpenAI 协议），仅适用于 bigmodel.cn 的 base_url。
• 欢迎在其他供应商上测试后反馈结果（issue/PR）。

接入 dsh

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

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

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

开发

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

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

uv run python scripts/e2e_zhipu.py --mcp          # 图片链路
uv run python scripts/e2e_media.py                # 视频/文档/图表思考链路

测试智谱视觉模型

1. 到 open.bigmodel.cn 创建 API Key
2. 设置 VISION_API_KEY 后启动服务器
3. 调用工具，例如：

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