dsh-tool-describe-image

Readme

# dsh-tool-describe-image（大肥鱼看世界）

让 DeepSeek 看懂图片的 DSH 插件 —— 通过**任意 OpenAI 兼容视觉端点**（百炼 qwen-vl、智谱 GLM-4V、OpenRouter、自建代理等），把图片转成文字或结构化 HTML，纯文本模型也能"看见"图片。

## 项目特点

- **悬浮鲸鱼娘桌宠**：Web 右下角的动画桌宠，支持拖动、表情切换、状态气泡、Agent 状态联动——是"大肥鱼看世界"的守护精灵
- **Agent 状态联动**：模型工作时鲸鱼娘切"专注"表情 + 气泡"我在认真工作呢…"，空闲时回待机 + "等你来聊～"
- **零配置可进 DSH**：不配 API key 也能正常启动，视觉功能随时可从设置窗补配
- **通用视觉通道**：baseURL + API key + 模型名自由填写，兼容任何 OpenAI 兼容视觉 API
- **自定义 Prompt + 输出格式**：Prompt 指令可编辑，输出可选文本描述或结构化 HTML
- **粘贴即识别（Web）**：`Ctrl+V` 粘贴图片，自动识别成文字/HTML 填入输入框
- **`describe_image` 工具**：模型按路径读取图片转成文字，任何 surface（Web / headless）都可用
- **DeepSeek 余额检测**：`check_balance` 工具 + 鲸鱼娘设置面板「查余额」按钮，实时查询 DeepSeek 账户余额（账户可用状态 + 各币种剩余额度，含赠送/充值拆分），余额不足时第一时间知道
- **零源码改动**：完全通过 DSH 公开扩展点实现（工具注册、RPC 通道、凭据服务、设置服务、客户端槽位），不改 Harness 任何代码
- **单包全包**：一个 npm 包 = host 半区 + 浏览器半区（鲸鱼娘桌宠 + 粘贴识别），`dsh plugin add` 即装即用
- **双语文案**：跟随 Web 界面语言自动切换中文 / 英文

## 鲸鱼娘桌宠交互

| 操作 | 行为 |
| --- | --- |
| **单击** | 随机表情反应 + 气泡"嘿嘿，戳我干嘛～" |
| **双击** | 打开**跟随鲸鱼娘的悬浮设置面板**（非全屏） |
| **按住拖动** | 拖动鲸鱼娘，松手落位 + 位置记忆（刷新后回到原位） |
| **Agent 工作** | 切"专注"表情 + 气泡"我在认真工作呢…" |
| **Agent 空闲** | 回待机（眨眼循环）+ 气泡"等你来聊～" |

表情动画用**交叉淡化 + 淡入覆盖**实现（无重影、无变淡），眨眼瞬时换帧保持利落。

## 工作原理

DeepSeek 官方适配器是纯文本路由，DSH 内置的 `read_image` 工具会在模型不支持 image 输入时拒绝。本插件绕开这道限制：

```
粘贴图片 / 指定路径
  → 图片字节交给用户配置的 OpenAI 兼容视觉端点
  → 返回文字描述或结构化 HTML（作为 tool result 或 draft 文本）
  → DeepSeek 基于文字/HTML 理解图片
```

- **工具模式**：`describe_image(file_path, question?)` 注册到 `ctx.tools`，schema 自动流入系统提示词
- **余额检测**：`check_balance` 注册到 `ctx.tools`，复用 Harness 的标准 `DEEPSEEK_API_KEY` 凭据，调用 DeepSeek 官方 `GET /user/balance` 返回账户可用状态与各币种剩余额度
- **粘贴模式**：浏览器半区在 document 上挂 capture 阶段 paste 监听，拦截图片 → base64 → host RPC（`/dsh-describe-image`）→ 文字填入输入框，带"正在识别…"提示与失败 toast
- **鲸鱼娘桌宠**：挂 `shell.overlay`（框架级悬浮层槽），表情帧由 host 静态路由 `/plugins-assets/...` 按需加载，Agent 状态经 `ctx.sessions` 订阅

## 用户配置（悬浮窗内全部可配）

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| API Base URL | `https://dashscope.aliyuncs.com/compatible-mode/v1` | 任意 OpenAI 兼容端点 |
| API Key | 无 | 存 DSH 凭据库；优先级：config > 环境变量 > 凭据库 > `.env` |
| 模型名称 | `qwen-vl-plus` | 自由输入 |
| 输出格式 | `text` | 文本描述 / HTML 结构化 |
| Prompt 指令 | 默认详细描述指令 | 用户可自定义 |
| 鲸鱼娘位置 | 右下角 | 拖动后自动记忆（`petX`/`petY`） |
| DeepSeek 余额 | — | 「查余额」按钮，查询 DeepSeek 账户剩余额度（key 复用 `DEEPSEEK_API_KEY`） |

## 安装

需要已安装 [DSH](https://github.com/deepseek-ai/deepseek-harness)（0.1.0-rc.6+）。

```sh
npm install -g dsh-tool-describe-image
dsh plugin --profile web add dsh-tool-describe-image
```

## 升级（从旧版）

> ⚠️ **0.5.0 存在打包缺陷（已由 0.5.1 修复）**：0.5.0 把 `@deepseek-ai/dsh-tools` 声明为普通 `dependencies`，npm 会按其 caret 范围装到**新版 rc**（如 `0.1.0-rc.8`），与 DSH 宿主自带的旧版 dsh-tools（如 `0.1.0-rc.6`）在进程里形成**两份模块实例**。两份实例的 `TOOL_RUNTIME_SCHEDULER` 是不同 `Symbol`，工具调度器按宿主 Symbol 挂载、再按另一份 Symbol 读取 → 取到 `undefined` → 每次调用工具都崩溃 `Cannot read properties of undefined (reading 'prepare')`。**如果你装过 0.5.0 且出现该错误：先 `dsh plugin --profile web remove dsh-tool-describe-image`，再装 0.5.1**（0.5.1 已将 dsh-tools/dsh-fs 移入 `peerDependencies`，与宿主共享同一实例，不再复制）。

先判断安装方式（`Get-Command dsh` 看 Source，或检查插件是否在 `~\.dsh\profiles\web\node_modules\` 下）：

```sh
# 全局安装（dsh 在 npm 全局目录）
npm install -g dsh-tool-describe-image@latest

# 或 profile 安装（插件在 ~/.dsh/profiles/web/node_modules 下）
dsh plugin --profile web update dsh-tool-describe-image
```

两种都执行也无害。**然后必须重启 dsh 并刷新浏览器（Ctrl+F5）**——host 与 client 两个半区都要重新加载：

```sh
dsh web
```

## 配置

视觉 API Key 可在**鲸鱼娘双击设置面板**里填写保存，或使用环境变量（推荐 `.env`）：

```powershell
$env:DASHSCOPE_API_KEY = "sk-你的key"
```

推荐写入 `~/.dsh/profiles/web/.env`，免去每次手动设置：

```
DASHSCOPE_API_KEY=sk-你的key
```

> 注意：环境变量优先级高于凭据库。若设置了 `DASHSCOPE_API_KEY` 环境变量，设置面板保存会提示"环境变量遮蔽"——直接改 `.env` 或环境变量即可。

### 可配置项

| 字段 | 默认值 | 说明 |
| --- | --- | --- |
| `apiKey` | 无（读 `DASHSCOPE_API_KEY`） | 视觉 API key |
| `model` | `qwen-vl-plus` | 视觉模型 id（自由输入） |
| `baseUrl` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI 兼容端点 |
| `prompt` | 详细描述指令 | 随图发送的指令文本 |
| `outputFormat` | `text` | 输出格式：`text` / `html` |
| `maxImageBytes` | 8 MiB | 单张图片读取上限 |
| `timeoutMs` | 60000 | HTTP 协作超时 |
| `deepseekApiKey` | 无（读 `DEEPSEEK_API_KEY`） | 余额查询用的 DeepSeek key（一般不配置，默认复用环境变量） |
| `deepseekBaseUrl` | 无（`$DEEPSEEK_BASE_URL` → `https://api.deepseek.com`） | 余额查询 API 端点（走中转可覆盖） |

在 `~/.dsh/profiles/web/cordis.patch.yml` 中覆盖：

```yaml
- insert:
    - id: describe-image
      name: 'dsh-tool-describe-image'
      config:
        model: qwen-vl-max
```

## 使用

```powershell
dsh web
```

**方式一：粘贴图片**（Web）

1. 任意截图 `Ctrl+C`
2. 输入框 `Ctrl+V`
3. 看到"正在识别图片…" → 文字描述自动填入输入框
4. 回车发送

**方式二：按路径描述**

对模型说：

```
描述一下 C:\Users\你的用户名\Pictures\image.png
```

模型会自动调用 `describe_image` 工具并基于描述回答。

**方式三：鲸鱼娘桌宠**

- 右下角鲸鱼娘待机眨眼；双击打开设置面板配置视觉 API
- 模型工作时鲸鱼娘切"专注"表情并冒泡提示；拖动可换位置并记忆

**方式四：DeepSeek 余额检测**

对模型说"查一下我的 DeepSeek 余额"，模型会自动调用 `check_balance` 工具返回账户可用状态与各币种剩余额度（含赠送/充值拆分）；也可双击鲸鱼娘，在设置面板点「查余额」按钮手动查看。余额不足时（账户不可用）会直接显示告警，避免用到一半才发现欠费。

## 常见问题

| 问题 | 解决 |
| --- | --- |
| 启动报 `DashScope API key missing` | 未配置 key，见「配置」 |
| 粘贴后没有反应 | 确认安装最新版、重启过 `dsh web` |
| 识别结果不理想 | patch 中把 `model` 换成 `qwen-vl-max` |
| 图片格式不支持 | 仅支持 PNG / JPG / WebP / GIF（按字节检测，不信扩展名） |

## 开发

```sh
npm install
npm run typecheck   # 类型检查（host + client）
npm run build       # host 构建
npm run bundle      # client bundle 构建
```

测试见 [TESTING.md](TESTING.md)。

## 技术架构

```
┌─────────────────────────── dsh-tool-describe-image ───────────────────────────┐
│ Host 半区 (lib/index.js)            Browser 半区 (lib/client.js)             │
│  ├ describe_image 工具 (ctx.tools)   └ paste 监听 → RPC → setDraft           │
│  └ /dsh-describe-image RPC 通道       (dsh.client 声明 → client-modules 发现) │
│        ↑ 共享 rpc-contract 契约                                                │
└──────────────────────────────────────────────────────────────────────────────┘
```

## 许可证

MIT

## 联系方式

- 作者：sala003
- 邮箱：841115144sala@gmail.com
- GitHub：https://github.com/sala003/dsh-tool-describe-image
- npm：https://www.npmjs.com/package/dsh-tool-describe-image