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免费）