@kbpoyo/dsh-image-bridge

Readme

# dsh-image-bridge

DSH（DeepSeek Harness）Web 插件：为**不支持原生图片输入**的纯文本模型提供图片桥接能力，让纯文本模型也能"看图"。

纯文本模型无法直接接收图片（DSH 原生会以 `MODEL_DOES_NOT_SUPPORT_IMAGES` 拒绝）。本插件把图片落盘到会话工作区，以文本标记把图片路径与处理指引注入对话，由模型**自主发现并调用**其技能（skill）/工具（tool）目录中的视觉类能力（通用视觉问答 / OCR / grounding）来查看图片。**插件不绑定任何具体技能或工具**——能力发现完全由模型自行完成。

## 功能

- **一键桥接**：纯文本模型下，输入框粘贴图片后出现「桥接发送图片」按钮，点击即可发送，模型能读到图片。
- **回车兜底**：不点按钮、直接回车发送图片，也会在发送入口自动改写为桥接标记发送，与按钮等效。
- **多模态直通**：多模态模型下按钮自动隐藏、图片原生发送，插件零干预。
- **即时感知**：会话中切换模型，按钮立即显隐，不闪烁、不跳动。
- **自动清理**：桥接产生的临时图片定时自动清理，无需手动管理。

## 安装

DSH 插件通过 `dsh plugin` 命令安装进 **profile**（`dsh web` 对应 `web` profile）。

### 方式一：从 npm 安装（推荐）

```sh
dsh plugin --profile web add @kbpoyo/dsh-image-bridge@0.1.0
```

装完重启 `dsh web` 即可生效。该命令会在 profile 中安装插件并自动挂载为配置层，**无需手动编辑任何配置文件**。

验证：重启后，纯文本模型会话中粘贴图片出现「桥接发送图片」按钮即生效；也可用 `dsh --profile web --dump-config` 确认插件配置层已挂载。

### 方式二：手动安装（本地调试用）

1. 将本包放置到 DSH profile 的 `node_modules/` 下（如 `~/.dsh/profiles/web/node_modules/@kbpoyo/dsh-image-bridge/`）；
2. 在 profile 的 `cordis.patch.yml` 的 `- insert:` 列表追加：

```yaml
    - id: dsh-image-bridge
      name: '@kbpoyo/dsh-image-bridge'
      config: {}
```

3. 重启 DSH（插件为启动期扫描加载）。

## 卸载

- **npm 安装的**：`dsh plugin --profile web remove @kbpoyo/dsh-image-bridge`，然后重启 `dsh web`。
- **手动安装的**：删除 `node_modules/@kbpoyo/dsh-image-bridge/` 目录，并移除 `cordis.patch.yml` 中对应的 `@kbpoyo/dsh-image-bridge` 行，然后重启。

## 使用说明

1. 在会话中选择纯文本模型（如 deepseek-v4-flash）；
2. 粘贴或拖入图片，点击「桥接发送图片」按钮发送（直接回车发送也会自动桥接）；
3. 模型会自主调用其视觉类技能/工具（通用视觉问答 / OCR / grounding）查看图片并回答，无需你手动指定工具；
4. 需要 OCR 时请在提问中明确说明（如「识别图中文字」），否则默认走通用视觉问答；
5. 切换到多模态模型（如 mimo-v2.5）后按钮自动消失，图片原生直通。

## 工作原理

- **落盘**：图片写入会话工作区的**隐藏目录** `<cwd>/.dsh-image-bridge/`（点号开头，常规文件管理器不显示；文件名 `img-<时间戳>-<序号>.<ext>`），发送前校验 `attachments.imageLimits`（数量 / 类型 / 单张与总大小）。
- **文本化注入**：原生图片被替换为三段文本标记：`[图片附件]`（路径 / 尺寸 / 类型）+ `[用户提问]` + `[处理指引]`（默认优先通用视觉问答，OCR 仅在用户明确要求或文字不清晰时使用）。
- **发送入口自动改写**：宿主侧包装 `session.prompt`，纯文本模型下含图消息在原生门禁（`MODEL_DOES_NOT_SUPPORT_IMAGES`）之前改写为桥接标记；多模态模型直通；改写失败（如桥接目录不可写）回退原生行为，与按钮流程等效。
- **零技能绑定**：插件不调用、不绑定任何具体技能/工具，由模型从自身目录自主发现视觉能力。
- **能力判定与切换感知**：判定来源为客户端上报当前模型（与官方模型选择器同通路，最新鲜）→ 会话最近一次请求 → 默认模型；模型切换由**事件驱动即时感知**（订阅官方模型目录 store），另有图片挂载期间每 1s 的兜底轮询覆盖事件漏网场景（如跨标签页切换）。
- **自动清理**：TTL 24 小时；总大小超过 512MB 时按最旧优先清理；每 6 小时巡检，插件卸载时清理超龄文件。

## 常见问题

**1. 按钮没出现？**
当前模型被上报为支持图片（多模态模型），按钮按设计隐藏；或 Host 端点不可用（安全降级）。请确认会话当前模型。

**2. 直接回车发送图片会怎样？**
会自动桥接，与点击按钮等效；仅当桥接失败（如磁盘不可写）时才回退原生行为并报错。

**3. 模型真的能"看到"图片吗？**
取决于模型自身的视觉技能/工具目录——插件只负责把图片送达，不保证所有模型都具备视觉能力；模型无可用视觉能力时会如实告知。

**4. 图片会一直留在磁盘吗？**
不会。桥接目录为隐藏目录 `<cwd>/.dsh-image-bridge/`，图片 24 小时自动清理；总大小超过 512MB 时按最旧优先清理。如需手动清理，直接删除该目录即可（插件会在下次桥接时自动重建）。

**5. 自定义供应商模型下按钮一直显示？**
配置层未声明 `input: ['text','image']` 时，适配器一律将模型上报为纯文本，插件忠实读取——需在模型声明中补 `input` 字段，见「已知限制」。

**6. 发图后切不回纯文本模型？**
这是 DSH 原生限制（会话日志含原生图片后禁止切回），需 `/compact` 或开新会话，插件不绕过。

**7. 切换模型后按钮没反应？**
刷新页面后重试；正常情况下切换瞬间生效（事件驱动 + 轮询双通道）。

## 已知限制

- **自定义供应商模型的能力上报**：凡经 settings 配置的自定义供应商（provider），其模型声明未包含 `input: ['text','image']`（或适配器未上报 image 能力）时，适配器一律将其上报为 `inputModalities=['text']`。此类模型下桥接按钮会**如实显示**（插件忠实读取适配器上报，无法判定其为视觉模型）——这是配置层事实，与插件无关。要让这类模型正确隐藏按钮，需在模型声明中补 `input` 字段，或改用适配器托管目录、正确上报能力的模型。
- **原生门禁不绕过**：DSH 原生"会话日志含原生图片后禁止切回纯文本模型"的限制保持不变（切回需 `/compact` 或新会话）。
- **subagent 传图不在覆盖范围**：父代理向子代理发送的含图消息不经 `session.prompt`，仍走原生门禁。

## License

MIT