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）

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

方式二：按路径描述

对模型说：

描述一下 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
• 邮箱：[e-mail]
• GitHub：https://github.com/sala003/dsh-tool-describe-image
• npm：https://www.npmjs.com/package/dsh-tool-describe-image