dsh-vision-subagent

给 DeepSeek Harness 加上能力感知的视觉路由：当前多模态模型直接走 DSH 原生图片通道；纯文本模型才把读图任务交给运行在独立视觉路由（MiniMax / Kimi / 任意 OpenAI 兼容供应商）上的一次性子代理。在委托路径中，图片字节和视觉模型的中间上下文不会进入主会话，主模型只收到最终文字结论。

为什么是子代理

• 上下文隔离：大图 / 多图对比不再占用主模型窗口，只有蒸馏后的文本返回
• 多轮视觉推理：子代理可以自己调用 read_image 看更多工作区文件、反复比对后再给结论
• 成本与路由分离：视觉调用走 MiniMax/Kimi 路由单独结算，主模型只负责推理

快速开始

`sh

1. 安装到 web profile（本地 checkout / npm 包均可）

dsh plugin --profile web add /path/to/dsh-vision-subagent

或发布后：dsh plugin --profile web add dsh-vision-subagent

2. 配置视觉路由（编辑 ~/.dsh/profiles/web/cordis.patch.yml）

`

`yaml

• insert:
  • id: vision-subagent name: 'dsh-vision-subagent' config: provider: kimi-coding # 或 minimax-cn / 自定义路由 model: k3 # 或 MiniMax-M3 / MiniMax-VL-01

`

`sh

3. 重启 dsh web，开新会话后对模型说：

'看下 ~/Desktop/error.png 是什么报错'

模型会自主调用 vision_agent(images=[...], question=...)

`

效果展示

贴图提问	分析中	干净的气泡	灯箱详情

输入框直接粘贴图片（Codex 式）

DSH Web 本身已经支持原生图片块。插件默认使用能力感知的 pasteMode: auto：

• 当前模型支持图片 → 插件完全透明，调用 DSH 原始 sendSession(text, imageIds, mode, signal)；当前模型在完整对话上下文里直接看原图，不出现分析胶囊，也不生成预描述。
• 当前模型是纯文本 → 插件才启用视觉路由兜底：校验并保存图片，在隔离上下文中按消息意图完成一次分析，再把分析文字和原图持久引用交给主模型。

上方截图展示的是委托兜底路径。气泡只显示你的文字和缩略图；分析内容收在缩略图灯箱里。后续需要原图（图片编辑、像素级检查）时，vision_image_fetch 可把全保真文件物化到 .dsh-vision/。

可设 pasteMode: delegate，即使当前模型支持图片也强制隔离分析；或设 pasteMode: native，彻底绕过插件，把图片准入交给 DSH。委托分析失败时消息不会发送，输入框草稿原样保留。

MiniMax / Kimi 视觉模型速查

供应商	baseURL	视觉模型	key 环境变量
Kimi（月之暗面）	https://api.moonshot.cn/v1	k3 / kimi-k3 / moonshot-v1-8k-vision-preview	MOONSHOT_API_KEY
MiniMax	https://api.minimaxi.com/v1	MiniMax-VL-01	MINIMAX_API_KEY
MiniMax 国内	（llm-pi-ai 内置 minimax-cn 路由）	MiniMax-M3	MINIMAX_CN_API_KEY

两条路线：

• 已有 llm-pi-ai 路由（推荐）：在 Settings/Models 里已有 kimi-coding 或 minimax-cn 时，插件配置只需 provider + model，key 走该路由的凭据引用，插件自身永远不接触密钥。
• 手写声明路由：在 llm-pi-ai 配置里新增一条 OpenAI 兼容路由（api: openai-completions + baseURL + apiKeyEnv + models），然后把 provider/model 指过去。

配置项（全部有默认值）

字段	默认	说明
enabled	true	总开关；关闭后工具仍在但拒绝执行
provider / model	空（休眠）	视觉路由；两者必须成对设置
subagentProvider	spawn	ctx.subagents 提供方
maxDepth	1	子代理的绝对委托深度上限；1 = 视觉子代理可运行但禁止继续委托（0 会连子代理本身都拒绝——顶层 agent 的子代理深度即为 1）
maxImages	4	每次调用图片数上限
maxImageBytes	10 MiB	单图字节上限
maxPromptChars	8000	question 长度上限
maxOutputChars	32000	返回文本截断长度
maxTokens	4096	委托视觉调用的输出 token 上限；0 = 交给路由默认值
pasteMode	auto	auto：多模态当前模型走原生、纯文本才委托；delegate / native 强制指定路径
allowRemoteUrls	false	是否允许 http(s) 图片 URL（v0.1 保留字段，仅本地路径）
allowOutsideWorkspace	false	是否允许工作区外的本地图片
extraAllowedRoots	[]	额外允许的图片根目录
guidance	空	追加给子代理的额外指令

安全模型

• 密钥只存在于视觉路由的凭据引用（环境变量）中，插件配置不接受明文 key，也不会把 key 写进任何日志或会话
• 本地图片默认限制在会话工作区内；符号链接被拒绝；读取有字节上限（取配置与部署限额的较小值）
• 子代理默认 maxDepth: 1（可运行，但禁止继续委托）；指令中明确禁止修改文件与执行 shell
• vision_image_fetch 只在会话工作区的 .dsh-vision/ 下写入自生成的内容哈希文件名，任何调用方可控的路径片段都不会落盘

架构

主模型（纯文本） └─ vision_agent(images, question) ──┐ │ 1. 路径准入：扩展名/工作区包含/符号链接/字节上限 │ 2. ctx.attachments.saveImage → 内容寻址的持久引用 │ 3. ctx.subagents.start('spawn', { agentOptions: {provider, model} }) ▼ 一次性子代理（MiniMax/Kimi 视觉路由，独立上下文） └─ 最终文本 ──► 主会话（仅此一条消息进入主上下文）

插件对 harness 服务只做结构化解构（duck-typing），对 rc 版本不敏感；运行时依赖仅 @deepseek-ai/dsh-tools（defineTool）与 @deepseek-ai/schemastery（配置 schema）。

路线图

• Web 粘贴桥：composer 贴图自动触发视觉分析（v0.2）
• 贴图分析意图感知：消息草稿引导视觉聚焦；气泡保持干净（v0.3）
• vision_image_fetch：把贴图原图物化到 .dsh-vision/ 供编辑（v0.3）
• 能力感知贴图路由：多模态模型走原生 ImageBlock，纯文本才委托（v0.4）
• Settings 面板（可视化选择 provider/model）
• 远程图片 URL 支持（受控 fetch + 大小上限）
• 内嵌 SKILL.md：教主模型何时该委托读图

开发

sh npm install && npm run typecheck && npm test && npm run build

0.4.2 以 DSH 0.1.1-rc.2 开发并执行发布验证。Web 委托路径使用 rc.2 的原子批量图片准入，传递发送取消信号，返回原生 SubmitOutcome，并且只在 Host 确认接收成功后释放草稿图片。DSH 运行时包改为精确版本的可选 peer，不再让 profile 额外安装一套 Harness 运行时。

License

MIT