dsh-cyberdog-vision

DeepSeek Harness（dsh）视觉识别插件：多模态图片理解。走 dsh 自身的模型调用链路（ctx.llm / pi-ai provider），封装成 vision_analyze 工具给 agent 自主调用；同时提供浏览器端插件，让 text-only 主模型也能"收到"图片（发送时图片转文字标签，列表渲染仍显示缩略图）。

纯插件实现，不改 dsh 源码。

能力

| 能力 | 说明 | |---|---| | vision_analyze 工具 | 识别/描述图片内容，输入 attachmentId（dsh 附件）或 imagePath（本地文件） | | 图片转标签（client） | 用户拖图 → 发送时自动上传图片、消息转 [图片附件: sha256:xxx] 文字标签 → 主模型收到文字（绕过硬编码的"模型不支持图片就拒发"准入） | | 列表渲染缩略图（client） | 对话列表把 [图片附件: ...] 标签渲染成图片缩略图——给模型的是文字，给用户看的是图片 | | 模型发现 | 插件配置指定模型，或自动发现支持 image 的模型；未配置则报错引导 |

架构

[发送：text-only 主模型场景]
用户拖图 → composer 显示缩略图（dsh 原生）
点发送 → client 插件包装 sendSession → 上传图片（/vision-api/upload）
       → 消息文本追加 [图片附件: sha256:xxx (image/png)] → 纯文字发送
主模型看到标签 → 调 vision_analyze(attachmentId)
              → host 插件读图 → 视觉模型解析 → 返回描述
列表渲染 → client 插件接管 user 消息渲染
         → 正则匹配 [图片附件: ...] → <img src=/vision-api/attachment/:id> 缩略图

[通用场景]
agent 直接调 vision_analyze（attachmentId 或 imagePath）

dsh-cyberdog-vision/
├── index.mjs              # host 插件（Cordis）：工具注册 + HTTP 路由
├── core/index.js          # 平台无关核心（读附件、模型发现、analyze、ref 缓存）
├── client/index.ts        # 浏览器端插件（发送转标签 + 渲染接管）
├── client/dist/client.js  # 构建产物（esbuild + __ModuleLoader__.load）
├── cordis.bundle.yml      # dsh plugin add 安装配置
├── cordis.patch.yml       # --patch 开发加载示例
└── scripts/
    ├── verify-dsh.mjs     # 插件验证（契约/schema/端到端/报错）
    ├── build-client.mjs   # client bundle 构建
    └── dump-pi-models.mjs # 检查 settings.yaml 模型 input 声明

安装

方式一：bundle 安装（推荐）

dsh plugin --profile <name> add <dsh-cyberdog-vision 包或目录>

方式二：--patch 开发加载

cd <deepseek-harness 仓库>
pnpm dsh --profile web --patch C:\path\to\dsh-cyberdog-vision\cordis.patch.yml --port 3099

配置

1. 模型配置（dsh 侧，必需）

在 ~/.dsh/settings.yaml 的 llm-pi-ai.providers 里，给支持多模态的模型声明 input：

llm-pi-ai:
  providers:
    opencode-go:
      models:
        - id: mimo-v2.5
          name: MiMo V2.5
          input: ['text', 'image']   # ← 声明支持图片输入
          contextWindow: 1000000
          maxTokens: 128000

2. 插件配置（可选）

• 不配置：自动发现第一个 input 含 image 的模型
• 指定模型：插件 config 里设置：

- insert:
    - id: cyberdog-vision
      name: dsh-cyberdog-vision
      config:
        visionProvider: opencode-go   # 模型所在 provider（可选）
        visionModel: mimo-v2.5        # 模型 id（可选）

没配置且自动发现也找不到 → 工具报错："图片识别模型未配置"，引导去模型配置里声明 input: ['text','image']。

开发

npm run verify          # 插件契约 + schema + core 逻辑验证（不依赖 dsh 运行时）
npm run build:client    # 构建 client bundle
node scripts/dump-pi-models.mjs   # 检查 settings.yaml 里模型 input 声明

调试路由（插件加载后）：

• GET /vision-api/status — 模型发现结果（哪些模型支持 image）
• POST /vision-api/analyze — 直接调 analyze（body: {imagePath|attachmentId, prompt, model?, provider?}）
• POST /vision-api/upload — 上传图片 base64 → attachmentId（client 插件内部用）
• GET /vision-api/attachment/:id — 读图片字节（渲染层缩略图用）

发布

# 打 tag 触发 CI（.github/workflows/publish.yml：verify → build:client → npm publish）
git tag v0.1.0
git push origin v0.1.0

# 或本地直接发布（需 ~/.npmrc 配好 npm token）
npm publish

已知限制

• 图片格式限 png/jpeg/webp/gif（dsh attachment 支持范围）
• attachmentId 元数据缓存（refCache）是进程内的：dsh 重启后，仅凭裸 attachmentId 无法读取旧图（需重新上传）；新拖的图正常
• 渲染接管只处理 user 消息（用户发的），assistant 消息里的标签按纯文本显示
• 主模型是否主动调 vision_analyze 取决于模型对标签的响应；可在系统提示词里补充引导