dsh-aux-vision

DeepSeek Harness 辅助视觉插件：任意纯文本主模型 + 任意有识图能力的模型（默认 opencode-go/mimo-v2.5）。含图轮次自动让视觉模型看原图（像素级），并把描述以文本 注入当前轮供主模型使用；纯文本轮零视觉调用。主模型与路由保持完全不变。

核心优势

• 不换主模型：为任意文本模型补齐图片准入，再由独立视觉模型完成识图。
• 自动且保真：用户图片、历史图片和 read_image 结果都会按需转为像素级描述；会话 UI 仍保留原图。
• 成本可控：纯文本轮零视觉调用；同图描述按视觉模型和附件缓存，重复图不消耗批次名额。
• 稳定降级：视觉模型不可用、限流或超时时，可继续对话并注入可识别的占位文本。
• 可定向追问：vision_ask 能让主模型针对指定附件或本地图片再次提问，无须更换当前会话模型。

零运行时依赖（不 import 任何 @deepseek-ai 包，全部结构调用 ctx.llm / ctx.attachments）， 完整复用 DSH 的 llm 服务管线（resolveModelInfo / prepareCall / 流式协议），不重复实现 provider 适配。

工作原理

发图(prompt RPC) ── 准入守卫 ──┬─ 通过（① 能力申报：未声明 image 的模型补报 image）
                               └─ 拒绝（未安装插件时的现状）
        ↓ followup → inbox → 原图消息落日志（**UI 显示原图**）
        ↓ 请求构建（历史含图消息一并进入请求）
② llm/stream：请求含图 & 路由未声明 image
   ├─ 有图：视觉模型看原图 → 描述文本原位替换 image 块（改写请求副本）→ 主模型作答
   └─ 无图：直通（零视觉调用、零开销）

环节	说明
① 能力申报	补丁 llm.resolveModelInfo：凡原方法未声明 image 的模型，在返回副本中补入 image。prompt 准入守卫 / selectModel 守卫 / read_image 模态闸门因此对任意文本模型放行。pi-ai 适配器线路级检查读 pi-ai 目录，不受影响（最后一道安全网）。卸载/禁用即还原。
② 注入	llm/stream：LOOP 请求含图（用户发图 / read_image 工具结果 / 历史图片）且路由未声明 image 时，把图片块替换为视觉描述（缓存优先）或占位，改写请求副本放行。原图消息保留在会话日志——UI 显示原图，描述只出现在模型请求里。
视觉目标	配置候选链 visionChain 按序尝试（跳过无适配器/不声明 image 的候选）；链全不可用时 visionDiscovery 扫描所有已注册 provider 的目录取第一个 image 模型兜底；全不可用 → 按 onVisionFailure 降级。
缓存	描述按 `provider:model
纯文本轮	llm/stream 无图直通——不产生任何视觉调用（历史图片改写走缓存，零模型开销）。
原生视觉路由	会话/子代理运行在声明 image 的模型上时不重写、不注入，原生看图。

安装

方式一：dsh plugin（需要发布到 GitHub/npm 后）

dsh plugin --profile web add github:<owner>/dsh-aux-vision

方式二：手动（本仓库开发期）

1. 构建：npm install && npm run build（产物在 lib/）。

2. 复制到 profile 可解析位置：

   # 把 lib/、cordis.patch.yml、package.json 放入：
   # $DSH_HOME/profiles/web/node_modules/dsh-aux-vision/
   

3. 在 $DSH_HOME/profiles/web/cordis.patch.yml 追加：

   - insert:
       - id: aux-vision
         name: dsh-aux-vision
   

4. 保存后重启 DSH（HMR 不重载 profile node_modules 里的插件文件；config 热更新会重新 apply，但 lib 更新必须重启）。

卸载：移除 patch 条目（配置热更新即可卸载）；如需同时移除包，删除 node_modules 目录。

配置（cordis.patch.yml）

- insert:
    - id: aux-vision
      name: dsh-aux-vision
      config:
        enabled: true                  # 总开关
        declareImageCapability: true   # ① 能力申报补丁
        visionChain:                   # 视觉候选链（任意已注册 provider）
          - provider: opencode-go
            model: mimo-v2.5
        visionDiscovery: true          # 链不可用时自动扫描全部 provider 目录兜底
        maxTokens: 8192                # 视觉调用上限
        timeoutMs: 120000              # 视觉调用超时
        batchMaxImages: 4              # 每轮/每请求最多【调用视觉】的图片数；
                                       # 缓存命中/重复图不占名额（直接取缓存），
                                       # 名额优先给新图；超出部分占位
        onVisionFailure: marker        # marker | error（见降级）
        markerText: '[图片附件 {id}：辅助视觉模型暂不可用]'   # {id}=attachmentId
        descriptionFormat: '[用户附图 {id}（{model}）：{description}]'
        descriptionDetail: standard    # compact | standard(默认) | detailed 三档详细度
        visionPromptTemplate: '…'      # 显式配置时覆盖 descriptionDetail 档位
        cacheTtlSeconds: 3600          # 描述缓存 TTL
        cacheMaxEntries: 200
        debugLogPath: ''               # 调试日志文件（空=关；warn/info 同时追加写入）
        injectGuidance: true           # 向系统提示注入「辅助视觉引导」
        guidanceText: '…'              # 引导文本（{model} 替换为视觉模型名）
        guidanceOrder: 500             # 引导段落排序（不与内置段落冲突即可）
        visionAskEnabled: true         # 注册 vision_ask 追问工具（二次定向识图）

降级行为

场景	行为
视觉候选全部不可用 / 调用失败（网络/限流/超时/空输出）	onVisionFailure: marker（默认）→ 占位文本，轮次继续；error → 该轮报错
附件读取失败	同上游（marker / error）
主模型请求失败	不干预：走既有 llm-retry / agent/request-error
纯文本轮	零视觉调用、零重写
原生视觉路由（会话/子代理）	不重写、不注入
插件禁用/卸载	能力申报还原；守卫恢复原样；历史纯文本日志继续可用

开发检查

npm run typecheck
npm test
npm run build

已知边界

• UI 显示：原图消息保留在会话日志，会话记录显示原图；描述只出现在模型请求里 （v0.2）。历史含图消息在每次请求构建时走缓存改写（毫秒级，零视觉调用）。
• 切换边界：会话切到原生视觉模型后发图 → 原生看图（路由声明 image 直通）。
• 能力申报副作用：文本模型在 models 目录显示为支持图片（与「装了插件后的复合能力」一致）。
• mimo 偶发描述不准确：属视觉模型自身质量波动；可在 visionChain 配置更强模型或 多候选降级。

License

MIT