dsh-web-search-enhanced 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -4,6 +4,36 @@
 
 ## [Unreleased]
 
+## [0.1.7] - 2026-10-04
+
+### 配置版本与自动迁移
+
+- 沿用 `version` 作为配置 schema 版本，新增前后端共享的当前版本常量与严格判定；独立于插件包版本、宿主版本、并发 revision 和存储版本。
+- 新增逐版本纯迁移入口，显式 V1 和无版本旧模型配置自动执行 1 → 2；无版本连接配置固定兼容为 V2，未来版本及非法版本拒绝读取或提交，不自动降级。
+- 迁移保留已有连接、实时性偏好与显式默认连接；修复跟随会话模式迁移丢失连接配置的问题。
+- 迁移执行中收到配置修改会重新读取最新 revision，继续使用宿主 CAS 提交，避免丢失更新；保留先保存 Credentials、后提交配置的可重试顺序。
+- 客户端编辑与重置拒绝未迁移或未来版本，补充版本判定、输入不变、幂等、真实宿主重启及并发迁移回归。
+- 新增[配置版本设计](docs/config-versioning.zh-CN.md)，说明扩展步骤、失败恢复与跨服务事务边界。
+
+### 升级说明
+
+- 包版本推进为 0.1.7；配置 version 2、会话 Storage Domain version 1、DSH 0.2.0-rc.2 基线均不变。现有 V2 配置无需格式转换，旧配置自动迁移不影响已有会话选择。
+- 升级前备份 profile 和凭据；安装后重载服务端插件并刷新 Web 页面。
+
+## [0.1.6] - 2026-09-30
+
+### DSH 0.2.0-rc.2 兼容性
+
+- 最低宿主版本提升至 `0.2.0-rc.2`；所有 DSH peer 依赖下限改为 `^0.2.0-rc.2`，直接开发依赖固定到 rc.2，同步更新锁文件和预发布白名单。
+- Zod 最低版本保持与上游一致的 `^4.4.3`，开发依赖树统一锁定 `4.4.3`，增加跨包 schema 类型一致性和发行包契约检查，避免依赖漂移被误判为 API 破坏。Cordis / Schemastery 的上游版本未变。
+- 增加 pi-ai 新 DeepSeek Flash ID 的跟随模型回归，验证被移除的目录 ID 不会被自动改名，显式私有路由保持原模型 ID。新增 [rc.2 影响评估](docs/upstream-0.2.0-rc.2-assessment.zh-CN.md)。
+- 配置 version 2、会话 Storage Domain version 1 保持不变，无需新增迁移；升级指南明确先卸载旧插件再安装，并重载服务端、刷新 Web 页面。CI 和发布均显式使用冻结锁文件。
+
+### 会话搜索选择器
+
+- 新增“关闭”选项，按会话禁用 `web_search`；恢复连接后重新启用，不影响 `web_fetch`。
+- 对齐宿主输入区模型选择器的响应式边界，保留关闭搜索、连接选择和实时性控制的既有回归测试。
+
 ## [0.1.5] - 2026-09-29
 
 ### DSH 0.2.0-rc.1 兼容性

package/README.md

@@ -10,7 +10,7 @@
 
 [![Release](https://img.shields.io/github/v/release/Yurzi/dsh-web-search-enhanced?style=flat-square)](https://github.com/Yurzi/dsh-web-search-enhanced/releases)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
-[![DSH](https://img.shields.io/badge/DSH-0.2.0--rc.1%2B-536DFE?style=flat-square)](package.json)
+[![DSH](https://img.shields.io/badge/DSH-0.2.0--rc.2%2B-536DFE?style=flat-square)](package.json)
 [![Node.js](https://img.shields.io/badge/Node.js-22.19%2B%20%7C%2024%2B-green?style=flat-square)](package.json)
 
 [🚀 快速上手](#-快速上手) · [✨ 核心特性](#-核心特性) · [🔍 搜索引擎推荐](#-选哪种搜索服务) · [⚙️ 进阶配置](#️-进阶配置与个人-key) · [❓ 常见问题](#-常见问题-faq) · [📖 详细文档](#-想了解更多)
@@ -60,19 +60,19 @@
 
 ### 环境要求
 
-- **DeepSeek Harness**：≥ `0.2.0-rc.1`
+- **DeepSeek Harness**：≥ `0.2.0-rc.2`
 - **Node.js**：`^22.19.0 || >=24.0.0`
 
-本版将 DSH 基线提升到 0.2.0-rc.1，保留动态配置、插件设置页和会话 projection 架构，无需新的配置或存储迁移。原生搜索新增的 DeepSeek 账号认证不会自动用于本插件；跟随模型仍要求 API Key。详见[0.2.0-rc.1 影响评估](docs/upstream-0.2.0-rc.1-assessment.zh-CN.md)。升级前请备份 profile 和旧设置。
+本版沿用 DSH 0.2.0-rc.2 基线，完善配置版本判定与逐版本自动迁移；现有 V2 配置和会话存储格式不变，显式 V1 与无版本旧模型配置可自动升级。详见[配置版本设计](docs/config-versioning.zh-CN.md)。跟随模型仍要求 API Key；使用 pi-ai 内置 DeepSeek 目录时，请重新选择 `deepseek-flash` 并检查旧模型 overrides，本插件不会自动改名。详见[0.2.0-rc.2 影响评估](docs/upstream-0.2.0-rc.2-assessment.zh-CN.md)。升级前请备份 profile 和旧设置。
 
 ### 步骤 1：安装插件
 
 **方式 A：通过 GitHub Release 离线包安装（推荐）**
 
-当前版本为 **0.1.5**，最低支持 **DSH 0.2.0-rc.1**。发布后可从 [Releases](https://github.com/Yurzi/dsh-web-search-enhanced/releases) 下载对应版本安装包及 SHA256 校验文件；也可执行 `pnpm install --frozen-lockfile && pnpm run check && pnpm pack` 自行构建。使用绝对路径安装：
+当前版本为 **0.1.7**，最低支持 **DSH 0.2.0-rc.2**。发布后可从 [Releases](https://github.com/Yurzi/dsh-web-search-enhanced/releases) 下载对应版本安装包及 SHA256 校验文件；也可执行 `pnpm install --frozen-lockfile && pnpm run check && pnpm pack` 自行构建。使用绝对路径安装：
 
 ```sh
-dsh plugin --profile web add /path/to/dsh-web-search-enhanced-0.1.5.tgz
+dsh plugin --profile web add /path/to/dsh-web-search-enhanced-0.1.7.tgz
 ```
 
 **方式 B：通过 npm 在线安装**
@@ -80,9 +80,11 @@ dsh plugin --profile web add /path/to/dsh-web-search-enhanced-0.1.5.tgz
 该版本发布到 npm 后，也可直接安装：
 
 ```sh
-dsh plugin --profile web add dsh-web-search-enhanced@0.1.5
+dsh plugin --profile web add dsh-web-search-enhanced@0.1.7
 ```
 
+已安装旧版时，DSH rc.2 不支持直接自动升级：先备份配置和存储，再通过插件管理器移除旧版并安装 0.1.7，核对 profile 补丁与会话选择。Desktop profile 需先启动过一次桌面端。完整步骤见[升级指南](docs/migration.zh-CN.md)。
+
 ### 步骤 2：生效与刷新
 
 1. 重载插件或重启 DSH 服务端。
@@ -200,7 +202,7 @@ _注：实时抓取可能会稍微增加检索耗时与额度消耗；对于不
 | 文档                                                     | 适合谁读            | 主要内容                                                          |
 | :------------------------------------------------------- | :------------------ | :---------------------------------------------------------------- |
 | 📘 **[配置指南](docs/configuration.zh-CN.md)**           | 所有用户 / 进阶用户 | 完整参数列表、凭据机制、高级 options 白名单、自定义端点与排错字典 |
-| 📙 **[升级指南](docs/migration.zh-CN.md)**               | 从旧版升级的老用户  | 0.2.0-rc.1 宿主适配、旧版导入指引、升级踩坑预防                        |
+| 📙 **[升级指南](docs/migration.zh-CN.md)**               | 从旧版升级的老用户  | 0.2.0-rc.2 宿主适配、旧版导入指引、升级踩坑预防                        |
 | 📗 **[架构设计说明](docs/design-v2.converged.zh-CN.md)** | 开发者 / 架构爱好者 | 会话状态隔离、请求快照机制、多适配器与安全性设计                  |
 | 🛠️ **[开发与验证文档](docs/v2-implementation.zh-CN.md)** | 插件二次开发者      | 本地构建、单元测试、浏览器环境验证与打包发布                      |
 | 📝 **[更新日志](CHANGELOG.md)**                          | 所有人              | 版本演进记录与历史变更                                            |

package/docs/config-versioning.zh-CN.md

@@ -0,0 +1,50 @@
+# 插件配置版本与自动迁移设计
+
+## 决策
+
+需求合理。沿用已有顶层 `version` 作为 schema version，不另设 `schemaVersion`，避免双字段冲突。当前版本为整数 **2**，由共享的 `CURRENT_CONFIG_VERSION` 管理。它与 npm 包版本、宿主版本、SettingsForms revision（并发控制）、会话 Storage Domain version 相互独立。
+
+不因每次发布而递增；只有配置结构或解释语义发生不兼容变化时递增。新增兼容的可选字段一般不递增。
+
+## 版本判定
+
+| 输入 | 行为 |
+| --- | --- |
+| 无版本且包含历史模型字段 | 视为 V1，自动迁移 |
+| 显式 version: 1 | 自动执行 1 → 2，即使没有其他历史字段 |
+| 无版本的连接配置或空配置 | 固定视为历史 V2；不因启动写入版本覆盖 |
+| version: 2 | 校验后直接使用，无重复迁移 |
+| 高于当前版本 | 拒绝读取/提交，不尝试降级或重置 |
+| 非正安全整数、字符串、null | 拒绝，不猜测版本 |
+
+显式版本优先于字段启发式判定。无版本连接格式永久映射到 **2**，以后升级到 V3 也不能把它直接认作 V3。设置卡片实际写入新值时补齐当前版本；无操作或恢复继承不制造无意义覆盖。手工编写的配置建议始终声明版本。版本字段不能设置 schema 默认值，否则宿主合并默认值可能把旧配置伪装成新版。
+
+## 迁移流程
+
+1. Loader schema 接受数字版本，让已知旧版本能够进入迁移校验；插件负责严格的版本范围判定。
+2. `migrateConfig` 克隆输入，按注册表顺序执行 N → N+1 的纯转换，检查每一步输出版本，最后校验当前连接结构。失败不修改输入，不执行 I/O。
+3. V1 转换保留现有连接、freshness、显式 defaultConnection 等非历史字段；只有没有显式默认时才选择导入的连接。已有 custom:legacy 冲突则拒绝，而非覆盖。旧 fallbackModel 不再转为备用路由。
+4. 宿主启动完成及本插件设置更新后，读取该条目的实时 descriptor。仅需要升级时生成迁移结果。
+5. 对旧明文 Key，先验证无秘密的转换结果，再确保 Credentials 中已有相同值或完成写入；不同值不覆盖。配置版本判定在剥离 Key 前进行，避免仅有 apiKey 的旧配置被误认作 V2。
+6. 使用宿主 SettingsForms.replace(namespace, migrated, revision) 提交，只修改本插件条目。版本与转换结果一起提交，不先单独写版本。
+7. 单实例迁移串行执行，执行中收到更新会标记待处理；结束后重新读取最新 revision。CAS 冲突不会覆盖新配置。失败的相同 revision 不持续重试；配置更新、凭据服务重新挂载或插件重启可重试。
+8. 未迁移完成的旧配置不执行搜索；未来版本由配置校验拒绝。客户端设置编辑和重置也拒绝未迁移/未来版本。
+
+## 边界与恢复
+
+- 使用宿主已有的配置编辑与持久化契约，不直接写配置文件，不修改宿主源码。
+- Credentials 与 profile 不是跨服务事务：凭据可能已写入而 profile 提交失败。保留该凭据，重试复用；不回滚删除可能被其他操作引用的凭据。
+- 宿主 replace 会与继承层合并，不能保证清除 bundle 源码中的历史字段或秘密；继承层明文 Key 必须由部署者移走。旧配置备份也不由插件自动销毁。
+- 不自动改变已有会话选择，不探测供应商，不新增联网请求；正在运行的搜索仍使用冻结快照。
+- 不支持自动降级。恢复旧插件前应恢复与之匹配的配置备份，而非手工降低版本数字。
+- 对需要新授权、信息丢失或无法可靠推断的未来变更，迁移步骤应明确失败并提示人工处理；“无感”不是静默猜测的理由。
+
+## 后续新增 V3 的方式
+
+1. 将共享当前版本提升为 3，更新当前配置类型、校验器和客户端。
+2. 在迁移注册表加入 2 → 3 的纯转换，保留原有 1 → 2。历史步骤的输出版本必须固定，不得改成“当前版本”。
+3. 在需要时为历史输入保留 Loader schema 字段，不能让宿主在迁移前丢弃/拒绝这些字段。
+4. 添加 V2 → V3、V1 → V3、无版本历史 V2 → V3、幂等、输入不变、失败保留和 CAS 并发测试。
+5. 若需要新的外部副作用，显式设计执行顺序和可重试性，不把 I/O 放进纯迁移函数。
+
+当前只存在真实的 1 → 2 步骤，不为演示制造无业务意义的 V3。

package/docs/configuration.zh-CN.md

@@ -1,12 +1,14 @@
-# 0.1.5 配置参考
+# 0.1.7 配置参考
 
-本指南面向安装版插件。包版本为 **0.1.5**，配置格式的 `version` 为 **2**；两者不是同一版本号。快速开始见 [README](../README.md)，旧版用户先读[升级指南](migration.zh-CN.md)。
+本指南面向安装版插件。包版本为 **0.1.7**，配置格式的 `version` 为 **2**；两者不是同一版本号。快速开始见 [README](../README.md)，旧版用户先读[升级指南](migration.zh-CN.md)。
+
+配置版本判定、兼容策略和后续迁移开发方式见[配置版本设计](config-versioning.zh-CN.md)。`version: 1` 会自动迁移；高于当前版本或非法版本会被拒绝，绝不自动降级。
 
 ## 配置入口与作用范围
 
 在 DSH 设置的 Web Search Enhanced 卡片管理搜索连接、凭据引用与新会话默认值，在已有会话输入区选择搜索连接和内容实时性。搜索连接独立于对话模型。设置按宿主 ConfigForms / ConfigForm 保存 profile 稀疏覆盖，不复制整个内置目录；恢复继承设置、删除用户连接覆盖均不删除 Credentials。继承层中的连接在移除用户覆盖后仍可能存在。
 
-以下 YAML 均为 DSH 0.2.0-rc.1 的 profile patch 条目，`id: web-search-enhanced` 是安装补丁的固定条目 ID，字段置于 `config` 下。旧 `settings.yaml` 由宿主导入后不再作为实时配置源；优先使用插件管理器中的配置页，避免覆盖其他插件设置。专属客户端配置页绑定默认条目 ID，不支持任意改名或多个搜索插件实例。
+以下 YAML 均为 DSH 0.2.0-rc.2 的 profile patch 条目，`id: web-search-enhanced` 是安装补丁的固定条目 ID，字段置于 `config` 下。旧 `settings.yaml` 由宿主导入后不再作为实时配置源；优先使用插件管理器中的配置页，避免覆盖其他插件设置。专属客户端配置页绑定默认条目 ID，不支持任意改名或多个搜索插件实例。
 
 ```yaml
 - id: web-search-enhanced

package/docs/design-v2.converged.zh-CN.md

@@ -1,4 +1,4 @@
-# 0.1.5 当前架构与实现边界
+# 0.1.6 当前架构与实现边界
 
 本文描述已存在的源码契约，不是未来设计提案或历史验收记录。为避免外部链接失效，保留原文件名。用户配置见[配置参考](configuration.zh-CN.md)，验证方法见[开发验证指南](v2-implementation.zh-CN.md)。
 
@@ -46,7 +46,7 @@ tools/execute 的 exec.agent → 私有 AsyncLocalStorage → enhanced-search
 
 ## 3. 配置和秘密分离
 
-当前设置格式为 version 2，包版本为 0.1.5。内置目录只做默认值；用户保存差异，不把目录整表复制到用户层。四种结构化内置连接默认 keyless，访问方式为显式选择，不根据已保存 Key 猜测。自定义连接只允许支持的 adapter 或固定模型协议；新 endpoint 需要信任确认。
+当前设置格式为 version 2，包版本为 0.1.6。内置目录只做默认值；用户保存差异，不把目录整表复制到用户层。四种结构化内置连接默认 keyless，访问方式为显式选择，不根据已保存 Key 猜测。自定义连接只允许支持的 adapter 或固定模型协议；新 endpoint 需要信任确认。
 
 内置结构化连接不能重定向地址或改变 adapter。自定义结构化连接只能使用个人 Key；固定模型总是需要显式信任。校验拒绝任意 headers/body、缓存参数、秘密字段等不受支持的 options。禁用连接也参与配置校验。
 

package/docs/migration.zh-CN.md

@@ -1,10 +1,10 @@
-# 升级到 0.1.5 / DSH 0.2.0-rc.1
+# 升级到 0.1.7 / DSH 0.2.0-rc.2
 
-0.1.5 将最低宿主版本提高为 **0.2.0-rc.1**，沿用 0.1.3 已完成的 Loader 动态配置、profile-backed SettingsForms、ConfigForms 客户端、惰性 Typert codec 和新版 PTC 适配。从 0.1.3 / 0.1.4 升级不需要新的配置或存储迁移；详见 [0.2.0-rc.1 影响评估](upstream-0.2.0-rc.1-assessment.zh-CN.md)。旧版已采用的**会话级搜索连接**保持不变：包版本 0.1.5、设置格式 version 2、会话 Storage Domain version 1 是三个不同概念。完整参数见[配置参考](configuration.zh-CN.md)。
+0.1.7 沿用最低宿主版本 **0.2.0-rc.2**，沿用 0.1.3 已完成的 Loader 动态配置、profile-backed SettingsForms、ConfigForms 客户端、惰性 Typert codec 和新版 PTC 适配。从 0.1.3 / 0.1.4 / 0.1.5 / 0.1.6 的 V2 配置升级不需要新的配置或存储格式转换，本版增强旧配置迁移的版本识别和并发保护；详见 [0.2.0-rc.2 影响评估](upstream-0.2.0-rc.2-assessment.zh-CN.md)。旧版已采用的**会话级搜索连接**保持不变：包版本 0.1.7、设置格式 version 2、会话 Storage Domain version 1 是三个不同概念。完整参数见[配置参考](configuration.zh-CN.md)。
 
 ## 1. 升级前准备
 
-- 确认 DSH 满足 `>=0.2.0-rc.1`，Node 满足 `^22.19.0 || >=24.0.0`。实现基线是 0.2.0-rc.1 契约，不代表对所有未来宿主版本均完成验证。
+- 确认 DSH 满足 `>=0.2.0-rc.2`，Node 满足 `^22.19.0 || >=24.0.0`。实现基线是 0.2.0-rc.2 契约，不代表对所有未来宿主版本均完成验证。
 - 备份当前插件版本、Web profile / 插件配置和 DSH 持久存储。凭据使用宿主安全备份方式，不复制到公开 Issue 或仓库。
 - 记录旧 `modelMode`、协议、模型、endpoint、凭据引用，以及希望保留的会话选择。
 - 推荐升级前先将明文 `apiKey` 移到 DSH Credentials 并从配置来源删除。兼容导入仅允许旧格式短暂携带 Key：先验证转换结果，再写 Credentials，最后 CAS 替换 profile 配置。V2 配置仍拒绝明文 Key；已有不同值的同名凭据不会被自动覆盖。
@@ -12,26 +12,32 @@
 
 ## 2. 安装发行包
 
-从当前源码运行 `pnpm install --frozen-lockfile && pnpm run check && pnpm pack`，或使用 [Releases](https://github.com/Yurzi/dsh-web-search-enhanced/releases) 中实际发布的 0.1.5 构建包。使用绝对路径交给 DSH 插件管理器：
+DSH rc.2 对已安装插件不支持直接自动升级。先完成备份、停止相关任务，通过插件管理器卸载旧插件（CLI 使用 `dsh plugin --profile web remove dsh-web-search-enhanced`），再安装下述固定版本；卸载可能改变 profile 补丁，安装后核对原设置、凭据引用和会话选择，不要清空持久存储。使用 `--profile desktop` 时须先启动过一次 Desktop 初始化 profile，并完全退出 Desktop 后执行 CLI。
+
+若跟随 pi-ai 内置 DeepSeek 目录，升级宿主后重新选择 `deepseek-flash`，检查旧 `deepseek-v4-flash` / `deepseek-v4-flash-vision-exp` 及其 overrides、默认模型和子代理设置。只针对这条目录路由，不机械替换私有端点的 ID；本插件不会改写用户模型配置。
+
+从当前源码运行 `pnpm install --frozen-lockfile && pnpm run check && pnpm pack`，或使用 [Releases](https://github.com/Yurzi/dsh-web-search-enhanced/releases) 中实际发布的 0.1.7 构建包。使用绝对路径交给 DSH 插件管理器：
 
 ```sh
-dsh plugin --profile web add /absolute/path/to/dsh-web-search-enhanced-0.1.5.tgz
+dsh plugin --profile web add /absolute/path/to/dsh-web-search-enhanced-0.1.7.tgz
 ```
 
 若该版本已在 npm 发布，也可安装固定版本：
 
 ```sh
-dsh plugin --profile web add dsh-web-search-enhanced@0.1.5
+dsh plugin --profile web add dsh-web-search-enhanced@0.1.7
 ```
 
 发布附件中的构建 tgz 与 GitHub 自动生成的 Source code archive 不同：后者是源码，不能假定含 `lib/` 构建产物。npm 可用性须以 registry 实际发布结果为准，GitHub 标签 / Release 存在不代表 npm 已完成。
 
 安装补丁选择 enhanced-search、禁用默认 web-search-deepseek，并明确将新会话默认设为 Exa；不改 fetchProvider。已有部署请审阅插件管理器反馈和 Web profile，避免重复注册条目，不要用整份示例覆盖所有宿主配置。
 
-本次未改变插件前后端业务契约，但宿主依赖与构建产物已更新。重新加载插件或重启 DSH，**然后刷新 Web 页面**；只刷新浏览器不足以更新服务端。此操作可能影响运行中任务，应在合适时机进行。
+本次未改变搜索业务契约和宿主依赖基线，但配置迁移逻辑与前后端构建产物已更新。重新加载插件或重启 DSH，**然后刷新 Web 页面**；只刷新浏览器不足以更新服务端。此操作可能影响运行中任务，应在合适时机进行。
 
 ## 3. 启动时自动迁移旧配置
 
+配置版本机制沿用 `version`，现已统一到逐版本迁移入口：显式 `version: 1` 与无版本旧模型配置均可自动升级；无版本连接配置保持 V2 兼容，未来版本拒绝降级。迁移保留已有连接、freshness 与显式 defaultConnection，执行中收到并发编辑会在结束后重新读取最新 revision。完整设计与事务边界见[配置版本设计](config-versioning.zh-CN.md)。
+
 插件不再自行注册 Settings section 或直接改写 settings.yaml。DSH 0.1.7 在 Loader 就绪后将旧 settings.yaml 重命名为 settings.yaml.imported，并尝试导入到 profile 条目；插件监听该条目的表单 / volatile 更新，再迁移成 V2 连接结构。保存使用 revision CAS，不能覆盖并发编辑。新旧宿主的配置持久化架构不同，不应只修改版本号或复制整份旧 YAML 到 profile。未完成迁移时搜索 fail-closed，普通聊天不因此被替换或阻断。
 
 自动迁移覆盖以下旧字段：

package/docs/upstream-0.2.0-rc.2-assessment.zh-CN.md

@@ -0,0 +1,37 @@
+# DSH 0.2.0-rc.2 插件适配评估
+
+## 版本与范围
+
+本次对照上游标签 `dsh-v0.2.0-rc.1` 与 `dsh-v0.2.0-rc.2`（提交 `639ed015397290b3745d163aafe02ffee4aa3f84`），结合两份升级评估核查 Web Search Enhanced。插件发布版本为 **0.1.6**，最低宿主 **0.2.0-rc.2**。
+
+- engines.dsh：`>=0.2.0-rc.2`；全部 DSH peer：`^0.2.0-rc.2`；直接开发依赖精确固定 rc.2。
+- 更新 pnpm 锁文件与仅针对审阅版本的预发布白名单。开发安装统一 Zod **4.4.3**，运行依赖下限继续为 `^4.4.3`，与上游 rc.2 锁文件一致；不以类型断言规避跨包 schema 类型冲突。
+- Cordis **4.0.4**、Include **1.0.9**、Loader **1.0.5**、Schemastery **3.18.4** 在上游未变，不盲目升级。Node 下限保持 `^22.19.0 || >=24.0.0`。
+- pnpm overrides 只控制本仓库开发/CI 依赖树，不会强制修改已安装宿主的其他插件依赖。部署应整套对齐 DSH 包，不混装 rc.1 和 rc.2。
+
+## API 与行为结论
+
+| 上游变化 | 本插件影响 / 处理 |
+| --- | --- |
+| Tools、Web、Settings、LLM 核心实现 | 两标签间只有包版本变化；沿用 Provider、动态配置、会话 projection 与冻结请求快照。 |
+| pi-ai 0.87.1 模型目录 | 内置 DeepSeek 目录使用 deepseek-flash，旧 deepseek-v4-flash / deepseek-v4-flash-vision-exp 被移除。跟随目录模式要求当前 ID；回归验证缺失 ID 不自动重写，显式私有路由保留原 ID。 |
+| ui-commands 模糊搜索、分组、PopupState 必填字段 | 本插件不手工构造 PopupState，也不替换内置弹窗；现有会话搜索选择器无需新增 props。 |
+| TypertGateway.hasLiveClient() | 不实现自定义 Gateway；集成测试使用 rc.2 原生 Gateway，避免旧实现混装。 |
+| timed ask_user_question 与迟到回答 | 不提供问答替代 UI/answerer，不把 pending 当授权；无需改变搜索业务。 |
+| 定时消息 framing | 本插件不创建提醒或向其嵌入外部搜索结果；无需修改。 |
+| OpenInAppAction、侧栏、Client inspect、Shell/ACL | 不调用这些变化接口或脚本，不受直接影响。 |
+| 插件升级和 Desktop profile | 已安装插件先卸载再安装；Desktop 先启动一次初始化 profile，并完全退出后执行 CLI。 |
+
+**不自动改写模型配置。** 上游 pi-ai 内置目录的 ID 变化不是所有 Provider 的全局改名。用户需检查默认模型、会话模型、modelOverrides 和子代理配置；私有端点应显式声明实际模型。能聊天不代表搜索连接可用：跟随模式仍需要 API Key 引用，不自动透传 OAuth/账号认证。
+
+## 配置与部署
+
+设置格式仍为 version 2，会话 Storage Domain 仍为 version 1；从 0.1.3–0.1.5 无需新增迁移。不重写宿主 Session 日志，不清空已有凭据或会话搜索选择。备份后先移除旧插件，再安装固定版本，审阅 profile 补丁，重载服务端并刷新 Web 页面。详见[升级指南](migration.zh-CN.md)。
+
+## 验证范围
+
+发布检查使用冻结锁文件，执行 TypeScript Host/Client 类型检查、两端构建、完整 Vitest 测试与真实 tarball 契约校验。新增断言覆盖全部锁定 DSH 包版本、跨包 Zod 解析一致性和 Flash ID 边界；既有集成测试覆盖原生/PTC 请求、Gateway/SessionController、搜索关闭/恢复、设置持久化、fork 与会话隔离。
+
+本次本地执行 `pnpm install --frozen-lockfile && pnpm run check` 退出 0：类型检查、两端构建、21 个测试文件 / 336 项测试和真实安装包契约全部通过。测试使用模拟网络及目录 fixture，不宣称已运行真实 pi-ai 模型或供应商请求。
+
+这些验证不代表升级了用户正在运行的 DSH 实例，也不等于对真实供应商联网、付费认证或 Desktop 原生环境完成验收。上游报告中的 Fetch/Undici 问题属于其他插件，本插件不新增 Undici 依赖。

package/docs/v2-implementation.zh-CN.md

@@ -1,12 +1,12 @@
-# 0.1.5 开发与验证指南
+# 0.1.6 开发与验证指南
 
 本文件保留原路径以避免断链，内容改为可重复的开发、验证与交付方法。架构见[当前架构](design-v2.converged.zh-CN.md)，用户使用见[配置参考](configuration.zh-CN.md)，版本升级见[升级指南](migration.zh-CN.md)。测试存在、测试通过、供应商在线可用、运行实例完成部署是四种不同结论，不能互相替代。
 
 ## 环境与开发入口
 
 - Node.js：`^22.19.0 || >=24.0.0`；pnpm：按 packageManager 使用 `11.7.0`。
-- DSH：包要求 `>=0.2.0-rc.1`，源码以 0.2.0-rc.1 服务契约为基线。依赖声明与锁文件是构建依据，不修改宿主安装的依赖来让测试通过。
-- 当前开发主线为 `main`，旧版代码线为 `legacy/v0.0.x`。包版本 `0.1.5` 与 settings schema 的 `version: 2` 不同。
+- DSH：包要求 `>=0.2.0-rc.2`，源码以 0.2.0-rc.2 服务契约为基线。依赖声明与锁文件是构建依据，不修改宿主安装的依赖来让测试通过。
+- 当前开发主线为 `main`，旧版代码线为 `legacy/v0.0.x`。包版本 `0.1.6` 与 settings schema 的 `version: 2` 不同。
 
 在仓库根执行：
 
@@ -101,7 +101,7 @@ preview-ui 写 `.dsh-smoke-home/settings-preview.html`，不会启动第二个 D
 
 1. 对最终待发提交运行 check 和所需浏览器 / 网络验证，记录版本与退出状态。
 2. 使用 `pnpm pack` 生成构建包；检查包版本、入口、声明、patch、README 与 docs 完整性。GitHub 自动 Source code archive 不是含 lib 的发行 tgz。
-3. 用户可用 `dsh plugin --profile web add /absolute/path/to/dsh-web-search-enhanced-0.1.5.tgz` 安装 Release 构建附件。
+3. 用户可用 `dsh plugin --profile web add /absolute/path/to/dsh-web-search-enhanced-0.1.6.tgz` 安装 Release 构建附件。
 4. Git 操作、远端分支调整、标签、Release 和 npm 发布分别需要授权与结果核验；不要把本地构建当作已发布。主线为 main，旧代码保留 legacy/v0.0.x，不需要把历史文档反复改成当前成功记录。
 5. 标签触发发布流程后，单独确认 workflow 和 npm registry 的版本 / 包内容，再宣称 npm 可安装。
 

package/lib/client.js

@@ -6158,6 +6158,28 @@ window.__ModuleLoader__.load({
 			visit: () => visit$1,
 			visitAsync: () => visitAsync
 		});
+		const LEGACY_FIELDS = [
+			"modelMode",
+			"protocol",
+			"baseURL",
+			"model",
+			"fallbackModel",
+			"apiKey",
+			"apiKeyEnv",
+			"apiVersion",
+			"toolIdentifier",
+			"maxTokens",
+			"maxUses",
+			"chatSearchMode",
+			"searchContextSize"
+		];
+		function configVersion(raw) {
+			const version = raw.version;
+			if (version === void 0) return LEGACY_FIELDS.some((key) => raw[key] !== void 0) ? 1 : 2;
+			if (typeof version !== "number" || !Number.isSafeInteger(version) || version < 1) throw new Error("settings version must be a positive safe integer");
+			if (version > 2) throw new Error("unsupported settings version; upgrade the plugin (automatic downgrade is disabled)");
+			return version;
+		}
 		//#endregion
 		//#region lib/types/catalog.js
 		const CATALOG = Object.freeze({
@@ -6217,7 +6239,7 @@ window.__ModuleLoader__.load({
 		const selectorCss = `
 /* Match DSH ModelSelect trigger/menu metrics and semantic theme tokens. */
 .v2s-selector { display:inline-flex; align-items:center; flex:none; min-width:0; font:inherit; }
-.v2s-search-trigger { display:flex; align-items:center; gap:4px; min-width:0; max-width:min(280px,45cqw); height:28px; padding:0 4px 0 8px; border:none; border-radius:24px; outline:none; background:transparent; color:var(--dsw-alias-label-secondary); font:inherit; font-size:13px; font-weight:500; line-height:20px; cursor:pointer; white-space:nowrap; }
+.v2s-search-trigger { display:flex; align-items:center; gap:4px; min-width:0; max-width:220px; max-width:min(360px,45cqw); height:28px; padding:0 4px 0 8px; border:none; border-radius:24px; outline:none; background:transparent; color:var(--dsw-alias-label-secondary); font:inherit; font-size:13px; font-weight:500; line-height:20px; cursor:pointer; white-space:nowrap; }
 .v2s-search-trigger:hover,.v2s-search-trigger[aria-expanded=true] { background:var(--dsw-alias-interactive-bg-hover); }
 .v2s-search-trigger:focus-visible { box-shadow:0 0 0 2px var(--dsw-alias-border-l3); }
 .v2s-search-trigger svg { flex:none; }
@@ -6230,8 +6252,19 @@ window.__ModuleLoader__.load({
 .v2s-search-busy { animation:v2s-search-pulse 1s ease-in-out infinite alternate; }
 @keyframes v2s-search-pulse { to { opacity:.35; } }
 @media(prefers-reduced-motion:reduce) { .v2s-search-busy { animation:none; } .v2s-search-chevron { transition:none; } }
+/* Match DSH conversation.input.model content-driven collapse via row variables on desktop. */
+.v2s-search-label,.v2s-search-mode { display:var(--dsh-composer-model-text-display,block); }
+:where([data-model-compact]) .v2s-search-label,:where([data-model-compact]) .v2s-search-mode { display:none; }
+/* Responsive auto-scaling for narrow containers and mobile viewports. */
 @container(width<=420px) { .v2s-search-mode { display:none; } }
 @container(width<=360px) { .v2s-search-label { display:none; } }
+@media (max-width:420px) { .v2s-search-mode { display:none; } }
+@media (max-width:360px) { .v2s-search-label { display:none; } }
+/* Auto-scaling adaptation under dsh-mobile grid layout. */
+:where([data-dsh-mobile-composer-row]) .v2s-selector,:where([data-dsh-mobile-composer-trailing]) .v2s-selector { flex:0 1 auto; min-width:0; max-width:min(100%,180px); }
+:where([data-dsh-mobile-composer-row]) .v2s-search-trigger,:where([data-dsh-mobile-composer-trailing]) .v2s-search-trigger { min-width:0; max-width:100%; }
+:where([data-dsh-mobile-composer-row]) .v2s-search-mode,:where([data-dsh-mobile-composer-trailing]) .v2s-search-mode { display:none; }
+:where([data-dsh-mobile-composer-row]) .v2s-search-label,:where([data-dsh-mobile-composer-trailing]) .v2s-search-label { min-width:0; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
 .v2s-search-sr { position:absolute; width:1px; height:1px; padding:0; margin:-1px; overflow:hidden; clip-path:inset(50%); white-space:nowrap; border:0; }
 .v2s-selector-panel { position:fixed; inset:auto; margin:0; box-sizing:border-box; max-width:calc(100vw - 32px); padding:3px; overflow:auto; overscroll-behavior:contain; border:0; border-radius:16px; background:var(--dsw-specific-menu); backdrop-filter:var(--dsw-menu-backdrop-filter); color:var(--dsw-alias-label-primary); --dsw-elevation-stroke-color:var(--dsw-alias-border-l1); box-shadow:var(--dsw-elevation-prominent); --dsh-scrollbar-thumb:var(--dsw-alias-scrollbar-bg-l2); --dsh-scrollbar-thumb-hover:var(--dsw-alias-scrollbar-hover-l2); font-family:inherit; font-size:13px; line-height:20px; }
 .v2s-selector-panel:not(:popover-open) { display:none; }
@@ -6425,7 +6458,7 @@ window.__ModuleLoader__.load({
 			const [open, setOpen] = (0, react.useState)(false);
 			const selected = value?.selection.connectionId;
 			const current = connections.find((c) => c.id === selected);
-			const label = !value ? t("search") : current?.id === "builtin:session-model" ? t("followModel") : current?.label ?? (selected ? t("connectionUnavailable") : t("selectSearch"));
+			const label = !value ? t("search") : selected === null ? t("searchOff") : current?.id === "builtin:session-model" ? t("followModel") : current?.label ?? (selected ? t("connectionUnavailable") : t("selectSearch"));
 			(0, react.useEffect)(() => {
 				const node = panel.current;
 				if (!node) return;
@@ -6472,7 +6505,7 @@ window.__ModuleLoader__.load({
 						"aria-expanded": open,
 						"aria-controls": id,
 						"data-state": error ? "error" : pending ? "saving" : notice ? "saved" : "ready",
-						title: error || (pending ? t("saving") : notice || t("searchConnection") + (current?.label ?? t("notSelected"))),
+						title: error || (pending ? t("saving") : notice || (selected === null ? t("searchConnection") + t("searchOff") : t("searchConnection") + (current?.label ?? t("notSelected")))),
 						onClick: toggle,
 						children: [
 							(0, react_jsx_runtime.jsxs)("svg", {
@@ -6494,7 +6527,7 @@ window.__ModuleLoader__.load({
 								className: "v2s-search-label",
 								children: label
 							}),
-							value ? (0, react_jsx_runtime.jsx)("span", {
+							value && selected !== null ? (0, react_jsx_runtime.jsx)("span", {
 								className: "v2s-search-mode",
 								children: t(value.freshness === "auto" ? "freshnessAuto" : value.freshness === "fresh" ? "freshnessFreshShort" : "freshnessRealtimeShort")
 							}) : null,
@@ -6552,6 +6585,24 @@ window.__ModuleLoader__.load({
 							items[event.key === "Home" ? 0 : event.key === "End" ? items.length - 1 : (index + (event.key === "ArrowUp" ? -1 : 1) + items.length) % items.length]?.focus();
 						},
 						children: [
+							(0, react_jsx_runtime.jsx)("div", {
+								role: "group",
+								"aria-label": t("searchOff"),
+								children: (0, react_jsx_runtime.jsxs)("button", {
+									type: "button",
+									className: "v2s-search-option",
+									disabled: !value || pending,
+									"aria-pressed": selected === null,
+									onClick: () => {
+										if (selected !== null) onSelect(null);
+									},
+									children: [(0, react_jsx_runtime.jsx)("span", { children: t("searchOff") }), (0, react_jsx_runtime.jsx)("span", {
+										className: "v2s-search-option-check",
+										"aria-hidden": "true",
+										children: selected === null ? "✓" : ""
+									})]
+								})
+							}),
 							["model", "structured"].filter((kind) => connections.some((c) => c.kind === kind && c.configured)).map((kind) => (0, react_jsx_runtime.jsxs)("div", {
 								role: "group",
 								"aria-label": t(kind === "model" ? "modelSearch" : "searchServices"),
@@ -6589,7 +6640,7 @@ window.__ModuleLoader__.load({
 									].map((mode) => (0, react_jsx_runtime.jsx)("button", {
 										type: "button",
 										"aria-pressed": value?.freshness === mode,
-										disabled: !value || pending,
+										disabled: !value || pending || selected === null,
 										onClick: () => {
 											if (value?.freshness !== mode) onFreshness(mode);
 										},
@@ -7221,6 +7272,11 @@ window.__ModuleLoader__.load({
 		};
 		/** Update only the edited path; catalog defaults never materialize as settings. */
 		function sparseSettingOperations(snapshot, path, target, fallback) {
+			const effective = {
+				...object$1(snapshot.base),
+				...object$1(snapshot.user)
+			};
+			if (configVersion(effective) !== 2) throw new Error("settings migration required");
 			const at = (root) => path.reduce((v, key) => object$1(v)[key], root);
 			const inherited = at(snapshot.base) ?? fallback;
 			const user = at(snapshot.user);
@@ -7241,7 +7297,7 @@ window.__ModuleLoader__.load({
 				path,
 				value: sparse
 			});
-			if (ops.some((op) => op.op === "set") && object$1(snapshot.base).version !== 2 && object$1(snapshot.user).version !== 2) ops.push({
+			if (ops.some((op) => op.op === "set") && effective.version !== 2) ops.push({
 				op: "set",
 				path: ["version"],
 				value: 2
@@ -7249,6 +7305,10 @@ window.__ModuleLoader__.load({
 			return ops;
 		}
 		function resetSettingsOperations(snapshot) {
+			if (configVersion({
+				...object$1(snapshot.base),
+				...object$1(snapshot.user)
+			}) !== 2) throw new Error("settings migration required");
 			return [
 				"version",
 				"freshness",
@@ -12444,6 +12504,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 			followModel: "Follow model",
 			connectionUnavailable: "Connection unavailable",
 			selectSearch: "Select search",
+			searchOff: "Off",
 			searchConnection: "Search connection: ",
 			notSelected: "Not selected",
 			sessionSearchSettings: "Current session search settings",
@@ -12527,6 +12588,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 			followModel: "跟随模型",
 			connectionUnavailable: "连接失效",
 			selectSearch: "选择搜索",
+			searchOff: "关闭",
 			searchConnection: "搜索连接：",
 			notSelected: "未选择",
 			sessionSearchSettings: "当前会话搜索设置",