xingling80/dsh-zhipu-vision

dsh-zhipu-vision — 视觉理解插件（DSH 原生插件）

基于官方 NPM SDK（dsh-tools / dsh-host-webserver / dsh-system-prompt / schemastery）实现的
DSH 原生插件，不修改 DSH 源码。核心体验：聊天框粘贴图片 → 自动识别 → DeepSeek 回答
（视觉识别由智谱 GLM-4V 负责，回答由 DeepSeek 负责，全程不切换模型）。

界面显示名统一为「视觉」：侧边栏入口、面板标题、设置卡片均显示「视觉」；
包名 / 工具名 / 路由仍为 dsh-zhipu-vision / zhipu_vision / /api/dsh-zhipu-vision/。

能力

| 能力 | 说明 |
| --- | --- |
| 粘贴识图（核心） | 聊天框 Ctrl+V 粘贴图片 → 自动保存到 ~/.dsh/pastes/ → 识别指令插入输入框（官方 conversation input 通道，立即可见）→ 你继续输入自己的需求 → 一次回车发送 → DeepSeek 调用 zhipu_vision 结合图片回答你的需求 |
| 视觉侧边栏 | 侧边栏「视觉」入口 → 面板：粘贴/拖图 + 缩略图 + 需求输入框 + 「发送给 DeepSeek」（图片+问题一条消息入会话）+ 面板内快速识别 + 已保存图片画廊 + 清空历史 |
| 视觉理解工具 | zhipu_vision：本地图片绝对路径 或 http(s) URL + 提问 → 返回模型回答（图片描述 / OCR / 截图分析 / 图表文档解读） |
| 设置入口 | GUI 设置 → 插件 → 插件配置 →「视觉」卡片：API Key（只写不回显）、模型、接口、超时、大小上限、粘贴拦截、自动发送、保留天数 |
| 图片保留 | 默认保留 7 天自动清理（keepPastesDays 可调，0 = 永久）；面板可一键清空 |
| 零运行时依赖 | host 使用 Node ≥22 内置 fetch；浏览器端仅依赖 React |

粘贴识图怎么用（推荐）

1. 复制任意图片（截图用 Win+Shift+S）
2. 在聊天输入框 Ctrl+V
3. 插件自动：保存图片，并在输入框插入「识别这张图片：」
4. 在它后面输入你的需求（如：这个报错怎么解决？这段代码有什么问题？）
5. 回车发送 → DeepSeek 调用 zhipu_vision 看图并针对你的需求回答

另一条路：侧边栏「视觉」面板 → 粘贴图片 → 输入需求 → 「发送给 DeepSeek」，效果相同。
可关选项（设置卡片）：interceptPaste（不拦截粘贴）、autoSendOnPaste（开启后粘贴即自动发送纯识别消息，不等你输入需求）。

架构

浏览器（web GUI）                          host 进程
┌────────────────────────────┐        ┌──────────────────────────────────┐
│ 聊天框粘贴图片（拦截）        │ base64 │ /api/dsh-zhipu-vision/paste       │
│   ↓ 保存后自动发送           │ ─────► │  保存到 ~/.dsh/pastes/，返回路径    │
│ sessions.driver.prompt     │        │                                  │
│ 「识别这张图片：」入会话  │ ─────► │  当前会话 agent（DeepSeek）        │
│   ↓                        │        │   调用 zhipu_vision 工具           │
│ 聊天流显示识别回答            │ ◄───── │ ZhipuVisionEngine（GLM-4V 推理）  │
│ 侧边栏面板：画廊/识别/清空     │ ─────► │ /pastes /paste-file /analyze     │
│ 设置→插件→插件配置 卡片       │ ─────► │ /config                         │
└────────────────────────────┘        └──────────────────────────────────┘

自动发送走官方 sessions driver 通道（与任务看板插件同款 API），消息以用户消息形式进入
当前会话，agent 正常处理。设置表单与面板不经过 dsh settings 服务，直接读写插件自己的
配置路由（与 dsh-ssh 同构）；API Key 永不离开宿主进程。

安装

当前 GUI 使用 web profile（~/.dsh/profiles/web）。三种方式任选其一：

方式一：一键脚本（最简单）

仓库内 scripts/ 目录提供两个通用脚本（不依赖本机特定路径，任何机器 clone 后可直接用）：

| 脚本 | 作用 |
| --- | --- |
| scripts/install.cmd | 双击即装（幂等：已装则跳过）；自动定位 node 与插件目录 |
| scripts/uninstall.cmd | 双击即卸 |

脚本会自动定位插件目录：脚本与插件目录平级（flat 布局），或脚本在插件目录的
scripts/ 子目录内（仓库布局）均可。脚本内部就是方式二的那一条官方 CLI 命令。

方式二：官方 CLI 一条命令

dsh CLI 位于 ~/.dsh/profiles/node_modules/@deepseek-ai/dsh/lib/bin.js（不在 PATH 上，用 node 调用）：

安装（file: 复制真实文件，依赖解析正常）
node "$env:USERPROFILE\.dsh\profiles\node_modules\@deepseek-ai\dsh\lib\bin.js" plugin --profile web add file:

卸载
node "$env:USERPROFILE\.dsh\profiles\node_modules\@deepseek-ai\dsh\lib\bin.js" plugin --profile web remove dsh-zhipu-vision

方式三：手动（不推荐，仅作原理说明）

1. 复制插件包到 profile 的 node_modules
Copy-Item -Recurse  "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-zhipu-vision"

2. 在 ~/.dsh/profiles/web/cordis.patch.yml 追加注册行：
- insert:
- id: zhipu-vision
name: dsh-zhipu-vision

安装后

重启 DeepSeek Harness 应用。生效后：
- 聊天框粘贴图片 → 自动识别
- 侧边栏出现「视觉」入口
- 设置 → 插件 → 插件配置 出现「视觉」卡片

注意事项

- CLI 会自动把包写入 profile 的 package.json（dependencies + dsh.profile.bundles），
无需手改任何配置文件。
- 用 file: 而非 link:：Windows 上 link: 建立的是 Junction 链接，Node 会按
真实路径（源目录）解析插件内部依赖，找不到 @deepseek-ai/ 包导致加载失败
（--preserve-symlinks 下才正常，而桌面宿主未启用）。file: 复制真实文件进
profile，与 pnpm 装的其它插件一致。
- 改完插件源码后需要重新执行安装（file: 是快照复制，不会自动同步源目录）。

配置

插件不内置任何 API Key。配置方式（优先级从高到低）：GUI 设置卡片 → 配置文件
~/.dsh/dsh-zhipu-vision.json → 环境变量 DSH_ZHIPU_API_KEY。

| 字段 | 默认值 | 说明 |
| --- | --- | --- |
| apiKey | 无（留空） | 智谱 API Key（Bearer）；设置页只写不回显 |
| model | glm-4v-flash | 视觉模型（免费）/ glm-4v-plus / glm-4.1v-thinking |
| baseUrl | https://open.bigmodel.cn/api/paas/v4 | 接口地址 |
| timeoutMs | 60000 | 请求超时（毫秒） |
| maxImageBytes | 10485760 (10MB) | 本地图片大小上限 |
| interceptPaste | true | 聊天框图片粘贴拦截 |
| autoSendOnPaste | false | 粘贴后自动发送识别请求（默认插入输入框等你输入需求） |
| keepPastesDays | 7 | 已保存图片保留天数（0=永久） |
| announceToAgent / enabled | true | 通告 / 总开关（需重载完全生效） |

验证安装

插件目录自带测试脚本（需已安装到 profile）：

1) 加载测试：验证插件模块、路由、工具、通告都能注册
node ".\load-test.mjs"

2) 冒烟测试：真实调用智谱 API 识别 test-image.png（需已配置 API Key）
$env:DSH_ZHIPU_API_KEY = (Get-Content "$HOME\.dsh\dsh-zhipu-vision.json" -Raw | ConvertFrom-Json).apiKey
node ".\smoke-test.mjs"

安全模型

- 请勿把真实 API Key 提交到公开仓库——本插件不内置 Key（默认值为空），避免泄露导致
额度被盗用或 Key 被平台自动失效
- 图片会上传至智谱开放平台（open.bigmodel.cn）推理，敏感图片请勿使用
- API Key 明文存于 ~/.dsh/dsh-zhipu-vision.json（与 dsh-ssh 同信任模型）；配置 GET 只返回
「已设置」标志，Key 永不进入浏览器
- 所有路由仅限 loopback 访问（含同源校验）；paste-file 有文件名白名单与路径穿越防护
- 粘贴的图片保存在 ~/.dsh/pastes/（默认 7 天自动清理，可手动清空）

常见问题（FAQ）

| 现象 | 原因 / 处理 |
| --- | --- |
| 粘贴图片没反应 | 检查设置卡片「粘贴拦截」是否开启；确认焦点在聊天输入框而非侧边栏面板 |
| 粘贴后输入框没有出现「识别这张图片」 | autoSendOnPaste 开启时会直接自动发送；关闭（默认）才会插入输入框 |
| 报「Zhipu API key is not configured」 | 设置卡片或 ~/.dsh/dsh-zhipu-vision.json 里未填 API Key |
| 报「image file not found」 | 传入的图片路径不存在或不是绝对路径；粘贴保存的图片在 ~/.dsh/pastes/ |
| 插件入口没出现 | 安装后需重启应用；确认 profile package.json 的 bundles 含 dsh-zhipu-vision |
| 双击桌面脚本报「不是内部或外部命令」 | 旧版脚本的编码问题；请使用当前随插件配套的 ASCII 版脚本 |

已知限制

- 单张图片/单次请求（glm-4v-flash 不支持多图）
- 自动发送在当前会话进行（sessions driver 通道）；若无可用会话则退回剪贴板模式
- announceToAgent / enabled 改动需重载完全生效
- 调用消耗智谱 API 额度（glm-4v-flash 免费）