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 界面语言自动切换中文 / 英文

鲸鱼娘桌宠交互

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

工作原理

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 订阅

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

安装

需要已安装 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 或环境变量即可。

可配置项

在 ~/.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 工具返回账户可用状态与各币种剩余额度（含赠送/充值拆分）；也可双击鲸鱼娘，在设置面板点「查余额」按钮手动查看。余额不足时（账户不可用）会直接显示告警，避免用到一半才发现欠费。

常见问题

开发

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