声明对 DSH 0.2.0-rc.2 的兼容性：已在 Web 与桌面版真实环境实测通过（对话增强、vision_analyze 工具、凭据读写、设置面板全链路正常）。0.2.0 起版本门禁同时检查 engines.dsh 与 peerDependencies，本插件两侧均为 >=0.1.2-rc.1 开下界声明，无需豁免直接通过。
修复官方模型对话报 Invalid schema for function 'vision_analyze' 的问题：工具参数声明改为标准 JSON Schema（type: "object" 根），与宿主 defineTool 编译产物同形态。宿主把工具参数原样透传给模型 API，DeepSeek 官方端严格校验 schema 必须以 object 为根，旧的属性映射写法会被拒绝；自定义模型不受影响。
修复桌面版设置面板 403 的问题：桌面形态下前端经 Electron 自定义协议加载且不带 Referer，同源校验新增对回环目标的放行分支（缺来源头，或来源为非 http/https 协议时放行回环请求）；浏览器恶意网页必带 http/https Origin，无法进入新分支，安全性不倒退。
前置条件更新：要求 DSH 0.1.2-rc.1 或更高版本，已实测至 0.2.0-rc.2。

1.5.2 更新

声明对 DSH 0.1.7-rc.2 的兼容性：已对 0.1.5-rc.2 → 0.1.7-rc.2 的宿主契约面做过完整比对（ctx.llm 适配器与路由、ctx.credentials、ctx.attachments.readImage、ctx.fs、ctx.remote.credentials RPC、webServer 路由注册、client 装配四注入点全部兼容），并在真实会话中运行验证通过。
修复 SSRF 防护的两个缺陷（vision/image-source.mjs）：① 移除 ::ffff:0:0/96 封锁规则——Node 的 BlockList 内部将所有 IPv4 地址以 IPv4-mapped 形式存储，该规则会误杀全部公网 IPv4 主机；IPv4 规则本身即可覆盖映射形式。② net.connect 自定义 lookup 回调改为 all: true 数组契约，并在解析结果全部命中封锁时显式回调错误——此前传单地址字符串会被 Node 静默丢弃、空结果传 undefined，均表现为 ERR_INVALID_IP_ADDRESS。
附件读取错误码附带原始 message（vision/analysis-core.mjs）：非 ATTACHMENT_* 故障（如 SSRF 守卫抛出的普通 Error）不再被折叠成裸 ATTACHMENT_READ_ERROR，保留稳定后缀供机器匹配的同时输出真实原因，便于诊断。
适配 0.1.7 新增宿主能力的说明：宿主持新增了 IMAGE_OFFLOAD_REQUIRED 图片预算机制与 text-only 模型图片投影工具，但桥接模型声明 image 输入能力，宿主会将图片原样转发给桥接适配器，由插件转换为视觉证据文本后再转发底层模型，与宿主持机制互不冲突。
GUI 模型选择器在 0.1.7 起按 catalog 成员资格过滤：插件的 listModels 会动态列出全部已启用路由的桥接模型，配置后即可在选择器中正常显示与选用。

1.5.1 更新

声明对 DSH 0.1.5-rc.2 的兼容性：已在真实会话中实测通过（对话增强 bridge 调用、凭据读写、设置与模型目录路由、附件读取全链路正常）。
新增 @deepseek-ai/dsh peer 依赖声明（>=0.1.2-rc.1），与既有的引擎声明一致，供 npm 安装解析时校验宿主版本。

1.5.0 更新

修复 DSH 0.1.2-rc.1 上设置页保存时“DSH 凭据服务暂不可用”的问题：凭据读写迁移到新的 ctx.remote.credentials 接口，并保留旧宿主的兼容路径。
“对话增强”模型选择器现在会置灰本身支持图片输入的模型（它们无需桥接），并标注“自带图片支持，无需增强”。
网关拒绝图片输入（如 Model do not support image input）或视觉模型返回空内容时，改为清晰的中文错误提示，不再把网关原始 JSON 注入对话。
修复持久化设置被 null 覆盖、模型目录响应无上限读取等问题。
完善重试路径诊断、空响应拦截、并发去重注释等稳定性细节。

1.4.0 更新

设置页的“对话视觉模型”列表改用 DSH 0.1.2-rc.1 的新模型目录接口读取，适配新版宿主。
插件最低宿主版本要求提升为 0.1.2-rc.1（dsh.plugin.json 与 package.json 的引擎声明同步收紧）。
客户端注入依赖精简：不再注入 @deepseek-ai/dsh-client-runtime。

1.3.0 更新

兼容新版 DSH 宿主（0.1.1-rc.8 及以上）的适配器接口。
会话辅助调用（标题生成、上下文压缩）不再触发重复的视觉分析，降低配额消耗与偶发失败。
相同图片与提示词的并发分析自动合并为一次上游请求。
新增“诊断日志”设置项（默认关闭），可输出插件运行日志便于排查。
连接测试改进：使用真实 token 预算，失败时错误信息包含上游返回摘要。
安装命令更新为 dsh 直令形式（需已全局安装 DSH）。

1.2.0 更新

重构设置页面的信息层级与连接流程：已完成配置时默认折叠，并在展开后提供完整编辑与“保存并测试连接”。
改进视觉模型选择、模型目录读取、手动模型 ID、连接状态与错误反馈。
优化多轮图片对话：无图片的后续轮次不再重复请求视觉模型；明确引用历史图片时可复用已缓存的视觉证据。
为图片内容的接口协议不兼容增加清晰、通用的错误提示。

功能

两个入口，共用同一条 vision_analyze 分析核心：显式工具调用与对话中的 [vision] 模型。
自动识别 11 类视觉任务：描述、对象清单、多主体、计数、定位、空间关系、比较、路径、拓扑、UI、文档视觉。
三档分析细节：brief、standard（默认）、verbose。
三种视觉原语策略：auto（默认）、on、off；原语使用 <ref>、<box>、<point>，坐标范围为 0–999。
仅为你选定的纯文本模型追加 [vision] 变体；原模型保留，不受影响。
会话级视觉证据缓存：追问仅在已有证据覆盖新问题时复用，否则重新读图。
原生设置页：安全密钥存储、连接测试、/models 搜索选择、手动模型 ID，以及按供应商折叠选择待增强模型（自带图片输入的模型自动置灰）。

工作方式

图片 + 用户问题
      │
      ▼
detectVisionMode() → shouldUsePrimitives() → buildVisionPrompt()
      │
      ▼
外部视觉模型（OpenAI 兼容 Chat Completions）
      │
      ▼
纯文本视觉证据（可含坐标化 primitives）
      │
      ▼
原始文本模型继续回答

Mode 与 Detail 是正交控制：Mode 决定任务，Detail 决定信息密度。Primitives 决定是否强制结构化的空间证据。

前置条件

已可运行的 DSH Web Profile（要求 DSH 0.1.2-rc.1 或更高版本，已实测至 0.2.0-rc.2）。
Node.js >= 20 与 pnpm。
一个可访问的视觉模型服务。默认使用 OpenAI 兼容端点：
- POST <Base URL>/chat/completions
- 可选模型目录：GET <Base URL>/models

视觉服务与被增强的文本模型可以来自不同供应商。

安装

npm 一键安装

在 PowerShell 或终端执行（以下 dsh 命令以已全局安装 DSH 为前提，即 npm install -g @deepseek-ai/dsh；未全局安装时，可将 dsh 替换为 npx @deepseek-ai/dsh）：

dsh plugin --profile web add dsh-tool-visual-primitives@latest

该命令调用 DSH 官方插件管理器，在 web Profile 中执行包安装。安装成功后，DSH 会识别本插件包内的 dsh.bundle.patch 声明，自动将插件加入 dsh.profile.bundles，并在启动时应用包内的 cordis.patch.yml。

该过程可重复执行，不会重复添加 bundle；它不会直接修改 Profile 自身的 cordis.patch.yml 或其他插件配置，因此可与 dsh-better-sidebar 等插件共存。

如使用的不是 web Profile，请将 --profile 改为对应的 Profile 名称：

dsh plugin --profile <你的 Profile 名称> add dsh-tool-visual-primitives@latest

安装后完整重启 DSH，并在“设置 → 视觉分析”中填写 API Key、Base URL 和视觉模型。

从 GitHub 源码本地挂载

这是当前已验证的安装方式。如使用其他目录，请同步调整 $source。

$source = 'D:\DSH\dsh-tool-visual-primitives'
git clone https://github.com/InkshadeWoods/dsh-tool-visual-primitives.git $source

Set-Location $source
pnpm install
pnpm run build

dsh plugin --profile web add $source

DSH 官方 CLI 会自动将本地包加入 Profile 依赖，并基于包内的 dsh.bundle.patch 声明维护 dsh.profile.bundles；无需手动编辑 Profile 的 package.json 或 cordis.patch.yml。

完整重启 DSH：

dsh web

首次更新客户端界面时，请在浏览器按 Ctrl+Shift+R 强制刷新。

卸载

如需清除已保存的 API Key，请先在插件设置页点击“清除 API Key”。然后执行 DSH 官方卸载命令：

dsh plugin --profile web remove dsh-tool-visual-primitives

DSH 会移除包依赖，并自动从 dsh.profile.bundles 清除对应 bundle。完成后重启 DSH。

首次配置

打开 DSH 设置 → 视觉分析，按顺序完成：

填写 API Key、Base URL 与视觉模型。
点击 加载模型：插件从 <Base URL>/models 获取可搜索列表。
若服务不提供模型目录，直接填写 自定义模型 ID。
点击 测试连接。
配置分析参数，并在“对话视觉模型”中勾选希望追加 [vision] 的纯文本模型。

已保存的 API Key 不会在重新打开页面时回显；填写新值会覆盖旧值，点击“清除 API Key”才会删除它。

API 与模型目录

项目	行为
视觉请求	`POST <Base URL>/chat/completions`，使用 `Authorization: Bearer <API Key>`
模型列表	`GET <Base URL>/models`，使用 `Accept: application/json` 与同一 API Key
模型列表失败	仍可直接填写自定义模型 ID，不影响视觉分析
小米 Mimo URL	自动改用 `api-key` 请求头

分析参数

设置	选项 / 默认值	作用
视觉原语	`auto` / `on` / `off`（默认 `auto`）	`auto` 根据 Mode 与 Detail 判断；`on` 强制坐标化证据；`off` 只要求纯文本证据。
分析细节	`brief` / `standard` / `verbose`（默认 `standard`）	控制输出密度，不改变任务类型。
重试模式	`off` / `on` / `format-only`（默认 `off`）	原语缺失时，`on` 重新读图；`format-only` 尽量保留结论，仅补齐格式。
最大图片大小	`10 MB`	本地、远程与对话附件均受上限约束。
超时	`180000 ms`	单次视觉模型请求的最长等待时间。
输出 Token 预算	`auto` 或手动值（默认 `auto`）	`auto` 跟随 Detail：brief `1024`、standard `2048`、verbose `4096`。
诊断日志	`off` / `on`（默认 `off`）	开启后向 DSH 控制台输出插件运行日志，便于排查问题。

11 种自动分析模式

Mode	适合的问题	证据重点
`caption`	“这张图是什么？”	整体摘要与关键对象
`object_inventory`	“图里有哪些物体？”	主要对象清单与位置
`multi_subject`	“从左到右有哪些人？”	主体编号、特征与位置
`counting`	“有几个按钮？”	候选对象、排除项与数量
`grounding`	“红色按钮在哪里？”	目标及候选位置
`spatial_relation`	“A 在 B 的哪边？”	上下左右、遮挡、包含等关系
`comparison`	“比较这两个区域”	比较维度与分别可见证据
`path_tracing`	“路线怎么走？”	起点、关键点、终点与不确定处
`topology`	“迷宫是否可达？”	连通性、阻断与结论
`ui_analysis`	“这个界面怎么操作？”	UI 元素、状态、位置与下一步建议
`document_visual`	“解读这张图表/海报”	标题、文本块、表格、阅读顺序

优先级最高的关键词决定 Mode；没有匹配时使用 caption。例如“这个界面有几个按钮？”会识别为 ui_analysis，再叠加所选 Detail。

使用方式

方式一：在对话中使用 `[vision]`

在插件设置的“对话视觉模型”中勾选一个纯文本模型。
重新打开对话模型列表，选择新增的 模型名 [vision]。
上传、粘贴或拖入图片，并直接提出问题。

插件仅将图像块替换为视觉证据文本；最终回答仍由所选的原文本模型生成。

对于明确指向当前会话最近图片的追问，插件会检查缓存证据是否覆盖新的任务、细节与关注对象/位置。覆盖不足时会重新分析图片，而不是把不充分的旧答案当作事实。

方式二：显式调用 `vision_analyze`

工具接收且只接收一个图片来源：本地绝对路径或 HTTP(S) URL。

{
  "image_path": "D:/images/dashboard.png",
  "prompt": "统计界面上可点击的主要按钮，并标出它们的位置"
}

{
  "url": "https://example.com/chart.png",
  "prompt": "解读图表的趋势，并说明读不清的标签"
}

远程 URL 不允许指向 localhost、私有网络地址或携带用户名/密码；重定向会被拒绝，以降低服务器端请求伪造风险。

视觉证据格式

启用视觉原语时，外部视觉模型会被要求按如下标题返回：

[Mode]
[Visual Primitives]
[Observations]
[Relations]
[Uncertainty]
[Answer]

定位信息示例：

<ref>submit_button</ref><box>[[742, 861, 900, 930]]</box>
<point>[[125, 430], [210, 430], [300, 510]]</point>

所有坐标均为相对 0–999，不是原图像素。

已验证的端到端场景

测试素材和结果均保存在 test/。

场景	已验证结果
对话图片理解	`[vision]` 模型成功读取 DSH 使用模式对比图，并向文本模型提供结构化图像说明。
截图驱动的 UI 复刻	`[vision]` 模型理解 Bilibili 首页截图后，文本模型据此生成了一个独立的 Bilibili 风格 HTML 页面。

图片理解结果

对话视觉入口成功读取图片