给文本模型装眼睛（deepseek-eyes / dsh-eyes）

以 DeepSeek 纯文本模型为例的完整范式：文本模型本身不具备视觉能力 → 用桥做翻译 → 把图片交给外部视觉大模型（Qwen-VL / DeepSeek-VL2 / DeepSeek-OCR）→ 拿回文字描述喂给主模型。 图片进来，文字出去。

用户截图到剪贴板 / 拖图进聊天框 / 本地图片文件
   ↓
┌─ 形态 A：MCP 桥 deepseek-eyes（mcp-bridge/，80 分，零框架改动）
│     analyze_clipboard / analyze_image / analyze_latest_screenshots
│     校验(扩展名/20MB/魔数) → 裁剪(可选) → 降采样1600px → JPEG q=88 → base64
│     → OpenAI 兼容视觉端点；429/408/5xx 指数退避(1s→2s→4s)，主模型挂→备用模型
│
└─ 形态 B：dsh-eyes 插件（dsh-plugin/，100 分，翻译点前移到输入框）
      paste/drop/导入图片 捕获拦截 → 极简浮层预览 → 输入框写提问 + 回车
      → host.call('eyes.analyzeWith') → one_shot.py（mcp-bridge/.venv）
      → 文字自动发送（消息体只有文字，准入闸门不触发）
   ↓
文字结果 → 主模型拿到"眼睛看到的"

为什么需要它

• DeepSeek 等纯文本模型声明 inputModalities: ['text']，消息带图会在 DSH 准入闸门被拒 （MODEL_DOES_NOT_SUPPORT_IMAGES），连工具都触发不了。
• 解决思路：在"图"和"文本模型"之间插一层翻译。不跟闸门对抗——在闸门之外把图消化掉。

目录

路径	内容
mcp-bridge/	Python stdio MCP 服务器（通用：DSH / opencode / 任意 MCP 客户端）
mcp-bridge/launchers/	自愈启动器（修复"配置路径腐烂"）
dsh-plugin/	DSH 动态 Cordis 插件（host.js + client.js + 装载手册）
src/	bundle 形态插件源码（官方 npm 包格式，host + client 双半包）
package.json / cordis.patch.yml	bundle 清单与插件行（dsh plugin add 安装用）
composition/	DSH host composition 接入示例（MCP 行）
AGENTS.md	给智能体的使用纪律

文档导航

文档	内容
docs/ARCHITECTURE.md	项目架构：双形态数据流、模块职责、与 DSH 框架对应点
docs/BUILD-GUIDE.md	从零构建指南：环境核实 → Python 桥 → 挂载 → 插件开发 → 验证清单
docs/DESIGN.md	设计决策记录（为什么这么做）

快速开始：MCP 桥（推荐先跑这个）

cd mcp-bridge
uv venv .venv
uv pip install -e .
copy eyes.toml.example eyes.toml   # 填 base_url / model / api_key
.\launchers\run-eyes.ps1           # 启动器先做配置体检，再起 stdio 服务器

挂进 DSH：把 composition/eyes.mcp.cordis.yml 的 insert 行合入 host composition （挂载前按 editing-cordis-compositions 技能核对行格式）。之后智能体就能调 mcp__deepseek-eyes__analyze_clipboard 等四个工具。

快速开始：dsh-eyes 插件（极简浮层 + 回车翻译）

1. 不需要视觉路由也能用：翻译走 mcp-bridge/.venv 的 one_shot.py， 模型/Key 由 ⚙ 配置 管理（持久化到 .eyes-config.json，默认从 eyes.toml 预填）。
2. 按 dsh-plugin/DEFINE.md 用 cordis_define + cordis_run 装载 host.js / client.js （首次运行需在 UI 批准）。
3. 效果：输入框出现 ⚙ 配置（选视觉模型/填 API Key/默认模式，保存后自动使用） 和 🖼 导入图片（多选）两个按钮；粘贴/拖入/导入图片 → 非模态极简浮层 展示缩略图（可删单张、可追加）→ 在输入框写提问 → 回车直接翻译并自动发送； 当前模型自带视觉时会放行原生贴图，不拦截。

内置预设：opencode GO（mimo-v2.5，https://opencode.ai/zen/go/v1）、 Qwen3.5-397B-A17B（ModelScope）、Qwen3-VL-30B-A3B（ModelScope）、 DeepSeek-VL2（SiliconFlow / 本地 vLLM）、自定义端点。 注意：opencode GO 的模型 ID 必须用裸 ID（如 mimo-v2.5）， 带 opencode-go/ 前缀会被 Zen API 拒绝（401）。

安装：bundle 形态（官方插件，跨会话持久）

本仓库同时提供官方 bundle 包（package.json 声明 dsh.bundle + dsh.client）， 任意 DSH 用户可一键安装（需 dsh CLI）：

dsh plugin --profile <name> add github:qing9835/plug#<commit>

1. pnpm ≥10 首次会拒绝 git 依赖的构建脚本：按提示把包 key 加入 profile 的 pnpm-workspace.yaml 的 allowBuilds（本包无构建脚本，允许即安全）， 重新 add；

2. 准备视觉桥环境（随包分发在 node_modules/dsh-eyes/mcp-bridge/）：

   cd node_modules/dsh-eyes/mcp-bridge
   uv venv .venv && uv pip install -e .
   

3. 配置视觉模型：输入框旁 ⚙ 配置（保存到 .eyes-config.json），或编辑 mcp-bridge/eyes.toml（环境变量 EYES_* 优先）；

4. 重启 DSH 后生效：粘贴/拖入/导入图片 → 输入框写提问 → 回车翻译并自动发送。

两种形态对比：动态插件（dsh-plugin/）会话级、需要每次 define； bundle（src/）官方标准、dsh plugin add 一条命令安装、跨重启持久。 功能一致，按使用场景二选一。

关键设计点（可复用经验）

维度	做法	原因
交互入口	剪贴板优先 + 输入框 paste/drop 拦截 + 文件路径	"复制截图→说一句"零摩擦
性能	1600px 降采样、统一 JPEG q=88、多图并发	base64 体积与串行耗时是 MCP 超时头号杀手
容错	只重试 429/408/5xx/超时，4xx 直接失败；备用模型降级；失败返回文字不阻断	省配额、保可用
防幻觉	只报告可见事实、P0/P1/P2 分级、数值标"约"、文本逐字引用	视觉模型会编造布局问题
安全	扩展名白名单 + 20MB + 魔数 + 完整解码 + 像素上限	拒绝伪造图片与解压炸弹
配置	启动器自动发现解释器 + 启动前 --check 体检	修复 venv 路径腐烂故障

配置参考（环境变量优先于 eyes.toml）

变量	说明	示例
EYES_BASE_URL	OpenAI 兼容端点	https://api-inference.modelscope.cn/v1 / https://api.siliconflow.cn/v1 / https://opencode.ai/zen/go/v1 / http://localhost:8000/v1
EYES_MODEL	视觉模型 id	Qwen/Qwen3-VL-30B-A3B-Instruct / Qwen/Qwen3.5-397B-A17B / mimo-v2.5 / deepseek-ai/deepseek-vl2
EYES_API_KEY	凭据（本机端点免）	—
EYES_BACKUP_MODELS	降级备用模型，逗号分隔	deepseek-ai/deepseek-vl2
EYES_MODE	describe / inspect / ocr	describe

限制与边界

• MCP 桥救不了"图已经在聊天框消息里"的场景——消息里的图在工具触发前就被宿主拒绝； 这正是插件形态（拦截点在输入框）存在的意义。
• 视觉结论对"布局错位"类判断不可信：必须 OCR + 源码交叉验证（见 AGENTS.md 纪律 4）。
• 插件形态依赖动态插件机制：会话内有效，进程重启后需重新 define（持久化走静态插件变体，见 docs/DESIGN.md）。

License

MIT（见 LICENSE）。