1HelloMan1/dsh-vision-fallback

English | 中文

为 DeepSeek Harness (dsh) 提供全局静默视觉增强：你继续在会话顶部直接选择真实主模型（如 deepseek-v4-flash），聊天框里拖入、粘贴、引用的图片会自动交给固定视觉模型，转成事实性文字观察后作为隐藏上下文交给主模型。界面始终显示你的原始图片——不新增"视觉回退"模型分组、不切换模型、不调用额外工具。

为什么需要

• DeepSeek V4 Flash/Pro 等强编码模型是纯文本的：聊天框发图会直接报"模型不支持图片输入"。
• 已有的"视觉工具"类插件需要你把图存成文件再调 see_image(path)——笨重，而且主模型依然收不到聊天框附件。
• 本插件在请求层架桥：聊天框发图就像原生支持一样，无论你在模型选择器里选哪个主模型。

工作方式

拖图/粘贴 ──► 聊天附件（UI 始终显示原图）
        │
        ▼
agent/pre-step ──► 图片 + 当前问题 + 最近上下文
        │                    │
        │                    ▼
        │          固定视觉模型（OpenAI 兼容 /chat/completions）
        │                    │  事实性文字观察
        │                    ▼
        └──► model-only surface replacement ──► 主模型（纯文本）

1. 插件覆盖发送前的图片能力检查，让文本主模型也能接收带图消息。
2. agent/pre-step 检测本轮图片，把图片、最新用户问题和最近对话上下文发给配置的视觉模型。
3. 你的原始图片作为正常聊天附件保留在界面。
4. 仅模型可见的 surface replacement 把图片换成视觉观察后再交给主模型。
5. 切换主模型（DeepSeek、Kimi、MiniMax……）不会改变固定视觉模型。

完整调用线路

• 普通对话：agent/pre-step 在主模型请求前处理图片，并把视觉观察投影到模型视图。
• 上下文压缩：llm/stream 的 purpose: "compaction" 线路会先复用已有观察；只有确实没有观察的图片才补一次识别。
• 工具结果图片：tool/result 中的图片也会进入模型投影，界面仍保留原始图片，不把工具结果改成用户不可追溯的纯文本。
• 会话重载 / 重启：观察结果持久化到 observations.json，重启后同一会话、同一消息位置不会再次调用视觉模型。
• 模型能力判断：auto 模式会读取主模型的真实 inputModalities；主模型原生支持图片时不重复接管，纯文本主模型才走视觉桥。

安装

npm / 本地检出

# npm 发布后（或本地检出目录）
dsh plugin --profile web add dsh-vision-fallback
# 或：dsh plugin --profile web add /path/to/dsh-vision-fallback

从源码

git clone https://github.com/1HelloMan1/dsh-vision-fallback.git
cd dsh-vision-fallback
pnpm install --config.minimumReleaseAge=0   # rc.6 peer 依赖需绕过发布年龄策略
pnpm test                                    # 22 个单元测试
dsh plugin --profile web add "$PWD"

然后验证并重启：

dsh --profile web --dump-config   # 应出现 "# == dsh-vision-fallback" 层
# 重启 `dsh web`（patch/bundle 层不支持热加载）

插件注册在 host 平面，headless / TUI 等其他 profile 同样兼容。

配置

两种方式都实时生效（保存后无需重启）：

Web 设置页

打开 DSH Web 设置 → 视觉增强，只暴露这些项：

字段	默认值	说明
启用	true	总开关
视觉模型	mimo-v2.5	OpenAI 兼容 model
API 地址	https://opencode.ai/zen/go/v1	插件自动拼 /chat/completions
凭据引用	OPENCODE_GO_API_KEY	从 DSH 凭证系统解析（不写入环境变量）
输出上限 / 超时 / 图片上限	1536 / 60000 / 15MB	视觉请求限制
最近上下文	includeRecentContext: true、contextMessages: 6、contextMaxChars: 6000	附带多少最近对话给视觉模型
提示词	（中文详细分析）	分析指令；用户问题自动追加
结果标注	true	观察前加 【视觉观察：<model>】

settings.yaml

vision-fallback:
  enabled: true
  model: mimo-v2.5
  baseURL: https://opencode.ai/zen/go/v1
  apiKeyRef: OPENCODE_GO_API_KEY
  maxTokens: 1536
  timeoutMs: 60000
  maxBytes: 15728640
  includeRecentContext: true
  contextMessages: 6
  contextMaxChars: 6000
  prompt: "请分析这张图片..."
  tagResult: true

API key 通过 DSH 凭证系统（~/.dsh/.credentials.yaml）解析，process.env[apiKeyRef] 作为兜底——插件不会把 key 写入 shell 环境文件。

安全与隐私

• 配置路由仅限本机回环 + 同源校验，请求体限大小并做 schema 校验。
• 视觉模型没有工具权限、没有 system prompt、没有执行权限——只拿到图片、问题和最近文字上下文。
• 观察结果以 model-only surface replacement 交付，界面中的原始图片永不被改写。
• 图片读取走 DSH 附件服务（遵守沙箱与观察策略）；视觉请求携带官方 attributionHeaders()。

用量记录（usage.jsonl）

开启 recordUsage 后，每次真实视觉调用（成功或失败）追加一行 JSON 到 <dshHome>/vision-fallback/usage.jsonl（可在设置页改 usageLogPath），供 usage-dashboard 统计。 字段：

字段	含义
ts	调用发起时刻（毫秒时间戳）
durationMs	本次调用响应耗时（毫秒）
kind	固定 "vision"
status	"ok" 成功 / "error" 失败
model	视觉模型名
inputTokens / outputTokens	输入 / 输出 token 数
cacheReadTokens	命中缓存读取的 token 数
error	失败时的错误信息（仅失败条目）
imageName / mediaType / imageBytes	图片文件名 / 媒体类型 / 字节数
imageIndex / imageTotal	该图在本次请求中的第几张 / 总张数

复用已记忆的观察结果（observations.json）不会产生新条目——该文件统计的是真实外部视觉调用次数。

观察缓存语义

观察结果按图片在某次会话中的出现位置（会话 id + 消息 id）记录：

• 同一图片在同一消息位置被重复处理（重启恢复、重放、压缩）→ 直接复用，不重新识别；
• 同一图片在会话的新位置再次出现（新轮次、主模型"再仔细看看"）→ 重新识别，生成贴合当前上下文的新观察；
• 不同会话之间不共享观察结果。

缓存上限 256 条（LRU 淘汰），失败结果不入缓存。

缓存文件位置：如果设置了 usageLogPath，缓存写在同一目录的 observations.json；否则使用 <dshHome>/vision-fallback/observations.json。因此压缩、事件回放和服务重启都可以复用已经成功得到的观察。

压缩、工具结果与重启

主模型能看图时，视觉桥不会重复调用视觉模型；但如果后续使用纯文本压缩模型，压缩线路可能再次遇到原始图片。插件会优先复用主模型已有的视觉投影和持久化观察，再处理真正没有结果的图片。这样可以避免“每次压缩重新识别整段历史图片”，同时保留新消息位置重新识别的能力。

默认视觉路由

• 模型：mimo-v2.5 · 端点：https://opencode.ai/zen/go/v1/chat/completions · 凭据：OPENCODE_GO_API_KEY

任何 OpenAI 兼容视觉端点都可用（智谱 GLM-4V-Flash、SiliconFlow Qwen-VL、vLLM、Ollama……），在设置页改 model、baseURL、apiKeyRef 即可。

与 OpenCode 方案的关系

OpenCode 社区的 opencode-see-image 把 filePath 和针对当前任务的 question 交给固定视觉模型，再把文字结果返回当前主模型。DSH 比 OpenCode 多了一层发送前的图片能力校验，因此这里同时覆盖该校验，并用 DSH 官方的 agent/pre-step 与 model-only surface replacement 保持界面静默。

开发

pnpm test    # node --test test/*.test.mjs — 22 个测试

目录结构：

dsh-vision-fallback/
├── package.json        # dsh.bundle + dsh.client 声明
├── cordis.patch.yml    # 插入 vision-fallback 行
├── lib/index.js        # host 插件（pre-step 桥、配置路由、控制器）
├── lib/client.js       # Web 设置页（"视觉增强"）
└── test/               # 单元测试

许可证

MIT