dsh-bundle-vision

Readme

# dsh-bundle-vision

给 DeepSeek Harness 提供**零核心改动的视觉能力**，以一个可安装的 npm 包同时充当 profile bundle 与插件：

- 插件注册面向模型的 **`describe_image`** 工具；
- bundle patch 把该插件挂载到任意 profile。

工具读取本地 PNG/JPEG/WebP/GIF 文件，把字节经随附的附件服务落盘，再用**一次直接的 LLM 请求**询问**调用参数指定的**多模态路由（`provider` / `model` 是工具参数）。结果只有文本——图像块绝不进入调用会话，因此纯文本主模型无需对 dsh 做任何改动即可获得视觉能力。

## 工作原理（全部走随附的公开 seam）

工具用到的一切都随每个 dsh profile 发布：

- `ctx.fs`（有界字节读取、按会话工作区解析）——文件系统能力；
- `ctx.attachments`（`saveImage`、图像限额、魔数校验）——持久图像存储；
- `ctx.llm`（`resolveModelInfo` + `stream`）配合 pi-ai 多提供方适配器——多模态请求本身。

唯一的逐部署前提与 dsh 的任何视觉用法相同：多模态模型必须在 `llm-pi-ai` 设置段声明图像输入，例如：

```yaml
llm-pi-ai:
  providers:
    my-vision:
      apiKeyEnv: MY_VISION_API_KEY
      api: openai-completions
      baseURL: https://example.invalid/v1
      models:
        - id: my-vision-model
          input: [text, image]
```

（在 Models 页已有输入模态控件的发布版上，这一声明就是一个下拉选择。）

## 安装（已装 dsh、非源码用户）

从 npm registry：

```sh
dsh plugin --profile <name> add dsh-bundle-vision
```

或从打包好的 tarball（例如首次发布前、或需要固定版本时）：

```sh
dsh plugin --profile <name> add ./dsh-bundle-vision-0.1.0.tgz
```

`dsh plugin` 会把参数转发给 profile 目录里的 pnpm，并自动调和 profile 的 bundle 层列表——声明了 `dsh.bundle` 的依赖自动加入层栈。重启 `dsh <name>`；工具对每个 agent 可见（profile 根作用域的注册对所有 preset 作用域可见）。

## 使用

让主模型带上路由调用：

> 用 describe_image，file_path 填 `/path/to/photo.jpg`，provider 填 `my-vision`，model 填 `my-vision-model`，prompt 填"OCR 图片中的文字"。

主模型按次指定 provider/model——配置多条多模态路由即可按次切换，无需改 profile。每种拒绝都会点名具体门禁（未知扩展名、部署媒体类型、模型未声明图像输入、文件缺失、类型不匹配、流错误）。

## 版本下限

包对 dsh seam 包声明 `>=0.1.0-rc.6` 的 peer 依赖。若后续发布版本有要求，请同步抬升下限。

## 开发

```sh
npm install          # 开发依赖从 npm registry 解析 seam 包
npm run typecheck    # tsc --noEmit(src + tests)
npm test             # vitest
npm run build        # tsdown(lib/index.js)+ tsc 声明(lib/types)
npm pack             # 生成可安装 tarball
```