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