前言¶
在 DeepSeek Harness (DSH) 的生态中，纯文本主模型（如 DeepSeek 系列模型）无法直接处理图像。处理 UI 审查、OCR 或看图问答时，通常需要启动一个独立的视觉子代理，这带来了额外的上下文开销和状态管理的复杂性。
dsh-vision-resident 解决了这个问题。它是一个常驻在宿主进程里的视觉助手插件，不依赖额外的子代理进程，而是通过挂载钩子和组件，让纯文本主模型也能“看”图。
是什么¶
这是一个 DeepSeek Harness 的记忆类插件，由 AnnanRen 维护，采用 MIT 许可证。
它的核心价值在于：
1. 零子代理开销：视觉模型直连（通过 ctx.llm.stream），每次识别只是一次 LLM 推理，没有 agent 上下文初始化成本。
2. 常驻对话：视觉子代理拥有持续的上下文，记住看过的图与识别结果，追问时不需要重复发送图片。
3. 按会话隔离：每个 DSH 对话拥有独立的视觉历史、上下文与计数，互不串扰。
4. 持久化与清理：识别历史与转译缓存落盘，重启不丢失；支持归档联动与闲置清理。
核心功能¶
工具与钩子¶
插件提供了 describe_image 和 subagent_vision 两个工具，用于读取磁盘图片并转换为文字结果。同时，它通过 llm/stream 钩子实现了“粘贴图片自动转译”功能：当主模型不支持图片时，插件会自动调用视觉模型将图片转成文字注入请求。
状态胶囊与详情页¶
在输入框左侧有一个状态胶囊，实时显示视觉子代理的工作状态、模型名称及识别次数。点击胶囊可以打开折叠式的详情页，查看每张图的识别历史（指令、思考过程、输出），支持 Esc 或点击背景关闭。
会话管理¶
视觉历史按 DSH 对话隔离，默认保留最近 10 轮识别记录。会话上限为 40 条（LRU 策略），闲置超过 30 天的记录会被自动清理。
安装与启用¶
安装需要手动 clone 代码并挂载到 DSH 的 profile 中。
- Clone 仓库到本地：
git clone https://github.com/AnnanRen/dsh-vision-resident.git
- 创建软链接挂载到 node_modules：
ln -s "$PWD/dsh-vision-resident" ~/.dsh/profiles/node_modules/dsh-vision-resident
- 编辑
~/.dsh/profiles/web/cordis.patch.yml，在insert列表中添加：
- id: dsh-vision-resident
name: dsh-vision-resident
- 重启 DSH Web 服务。
配置¶
视觉模型设置¶
默认使用 opencode-go/mimo-v2.5 作为主模型，opencode-go/minimax-m3 作为回退。可以通过环境变量覆盖：
export VISION_PROVIDER=opencode-go
export VISION_MODEL=mimo-v2.5
export VISION_FALLBACK_MODELS=opencode-go/minimax-m3
纯文本主模型图片准入¶
Harness 会检查选中模型的 input 声明。要让纯文本模型（如 deepseek-v4-flash）支持粘贴图片，需在 ~/.dsh/settings.yaml 中声明：
input: [text, image]
对于内置在 force-convert 名单中的模型（如 deepseek-v4-flash / deepseek-v4-pro），插件会强制转译，不将原图直送上游。
使用方法¶
- 读取磁盘图片：
使用describe_image或subagent_vision工具，传入image_path参数。例如：
await ctx.callTool('describe_image', { image_path: '/path/to/screenshot.png' });
-
纯文字追问：
省略image_path参数，直接基于视觉子代理已知的上下文进行纯文本追问。 -
自定义模型：
通过上述环境变量切换视觉模型或配置回退链。
已知限制¶
- 模型切换限制：当会话中已有图片时，如果切换到不支持图片的模型，会被 Harness 拒绝（
model-unavailable），需要开新会话才能切换。 - 工具剥离：当前提示词中包含图片时，工具会被剥掉（为了防止弱模型反射性搜文件），建议分步操作。
- 历史上下文：历史上下文只包含文字，不包含历史图片。多图请求在部分端点上可能不稳定，且历史识别结果本身已是完整文字描述。
- 会话清理：主会话归档后，对应的视觉记录会在 30 秒内清除。
结语¶
dsh-vision-resident 通过将视觉能力集成到主进程流中，为 DSH 提供了一种轻量级的视觉增强方案。它适合需要频繁进行视觉任务但不想引入复杂多代理架构的场景。
更多细节与源码，请访问 GitHub 仓库。
