# 更新日志

本项目的所有重要变更都记录在此文件。格式参考 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。

英文版见 [CHANGELOG_EN.md](CHANGELOG_EN.md)。

## [1.5.4] — 2026-10-24

### 兼容性

- 声明对 DSH `0.2.1-rc.2` 的兼容性，已在真实环境实测通过三条链路：`[vision]` 模型被桥接器正常接管、`vision_analyze` 工具调用成功、非 `[vision]` 模型调用该工具时正确返回拒绝提示。
- 相较 1.5.3 声明的 `0.2.0-rc.2`，`0.2.1-rc.2` 的宿主契约面无破坏性变更，无需新增版本豁免，两侧声明的 `>=0.1.2-rc.1` 开下界继续有效。

### 变更

- **`vision_analyze` 工具收紧为 `[vision]` 模型专用。** 在非 `[vision]` 模型下调用该工具现在会被明确拒绝，并返回可操作的拒绝原因（当前 provider 是什么、应改用模型自身能力、如何切换到 `[vision]` 模型）。此前该工具对所有模型开放，会与自带图片能力的模型形成两条竞争通路。闸门安装在宿主 `tools/pre-execute` 阶段，在工具主体执行前就拦截，不产生上游调用。
- 未配置对话视觉模型（桥接器关闭）时不安装该闸门，工具保持原有行为——此时不存在 `[vision]` 模型可选。
- 路由判定优先读取会话折叠后的请求上下文（`session.requestContext().provider`），仅在访问器缺失时回退到 `agent.options.provider`。原因是桥接模型在 `agent.options` 中保留的是基础 provider（如 `omniroute`），并不反映实际路由。

### 修复

- **图片 URL 现在支持 302 等跳转。** 此前重定向被直接拒绝，导致所有返回 302 的短链图床（如 `picsum.photos`）必然读取失败。改为手动逐跳跟随，每一跳都重新执行 SSRF 校验（`redirect: "follow"` 会让跳转绕过首跳已通过的检查），最多 5 跳。
- **图片抓取失败的错误信息带上底层原因。** `fetch` 把有效信息藏在 `cause` 里，裸 `fetch failed` 无法诊断。现在错误会附带 `cause` 的 code 或 message，例如 `ATTACHMENT_READ_ERROR: fetch failed — cause: UND_ERR_CONNECT_TIMEOUT`，可直接区分 DNS 失败、连接超时与 TLS 错误。

### 稳定性

- 连接超时从 undici 默认的 10 秒收紧到 5 秒。实测健康边缘 0.07–1.4 秒响应、较慢但可用的约 4 秒，5 秒留有足够余量，同时让黑洞地址失败得更快。
- 远程图片抓取改为每次尝试使用独立连接池（原为模块级单例），避免重试复用刚失败的那条连接与 DNS 结果。
- 抓取失败增加一次 400ms 退避的有限重试，仅针对连接类瞬时错误（`UND_ERR_CONNECT_TIMEOUT`、`ECONNRESET`、`ETIMEDOUT` 等）。HTTP 状态错误、超出大小限制、SSRF 拒绝与用户取消一律立即失败，不重试。

### 已知限制

- 部分网络到 CDN 边缘节点存在**持续数十秒的连续不可达**（实测可达率约 53%，最长连续失败约 20 秒）。此类中断无法通过秒级重试跨越，抓取会在约 13 秒后失败并给出原因。遇到时请更换图源，或让 Node 走代理。这属于网络侧问题，非插件缺陷。

## [1.5.3] — 2026-09-30

### 修复

- 声明对 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] — 2026-09-28

### 修复

- 声明对 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] — 2026-09-11

### 新增

- 新增 `@deepseek-ai/dsh` peer 依赖声明（`>=0.1.2-rc.1`），与既有的引擎声明一致，供 npm 安装解析时校验宿主版本。

### 修复

- 声明对 DSH `0.1.5-rc.2` 的兼容性：已在真实会话中实测通过（对话增强 bridge 调用、凭据读写、设置与模型目录路由、附件读取全链路正常）。

## [1.5.0] — 2026-09-07

### 修复

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

### 变更

- “对话增强”模型选择器现在会置灰本身支持图片输入的模型（它们无需桥接），并标注“自带图片支持，无需增强”。

## [1.4.0] — 2026-09-05

### 变更

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

## [1.3.0] — 2026-08-22

### 新增

- 新增“诊断日志”设置项（默认关闭），可输出插件运行日志便于排查。
- 相同图片与提示词的并发分析自动合并为一次上游请求。
- 安装命令更新为 `dsh` 直令形式（需已全局安装 DSH）。

### 修复

- 兼容新版 DSH 宿主（0.1.1-rc.8 及以上）的适配器接口。
- 会话辅助调用（标题生成、上下文压缩）不再触发重复的视觉分析，降低配额消耗与偶发失败。
- 连接测试改进：使用真实 token 预算，失败时错误信息包含上游返回摘要。

## [1.2.0] — 2026-08-20

### 新增

- 重构设置页面的信息层级与连接流程：已完成配置时默认折叠，并在展开后提供完整编辑与“保存并测试连接”。

### 变更

- 改进视觉模型选择、模型目录读取、手动模型 ID、连接状态与错误反馈。
- 优化多轮图片对话：无图片的后续轮次不再重复请求视觉模型；明确引用历史图片时可复用已缓存的视觉证据。

### 修复

- 为图片内容的接口协议不兼容增加清晰、通用的错误提示。