sala003/dsh-tool-describe-image

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（0.1.0-rc.6+）。

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\ 下）：

全局安装（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 两个半区都要重新加载：

dsh web

配置

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

$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 中覆盖：

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

使用

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（按字节检测，不信扩展名） |

开发

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

测试见 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