dsh-web-search-enhanced 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 记录 `dsh-web-search-enhanced` 的用户可见变化。历史条目描述对应版本，不代表当前行为。
 
+## [Unreleased]
+
+## [0.1.4] - 2026-09-24
+
+### DSH 0.1.7-rc.2 兼容性
+
+- 最低宿主版本提升至 `0.1.7-rc.2`；DSH peer 依赖下限、精确开发依赖、锁文件及预发布安装白名单同步对齐。
+- 核对动态工具更新、DeepSeek Provider 拆包、模型选择校验、Schedule 与审批变更；插件不调用 selectModel，不依赖被移除的 Schedule API，无需修改搜索运行时代码。
+- 跟随模型仍仅支持可解析的 API Key 路由，不因宿主支持官方账号而自动支持账号 / OAuth 搜索；固定连接及结构化搜索不受模型选择校验影响。
+- 设置格式 version 2、会话 Storage Domain version 1 保持不变；完整边界见 [rc.2 影响评估](docs/upstream-0.1.7-rc.2-assessment.zh-CN.md)。
+
+### 搜索选择器请求优化
+
+- 移除每 2 秒常驻轮询；首次加载、模型实际变化、展开菜单及页面恢复可见/焦点时按需读取，关闭菜单和普通重渲染不请求。
+- 增加按会话隔离的 30 秒客户端缓存与并发请求合并，最多保留 64 个空闲会话项；TTL 到期本身不会触发请求。
+- 写入成功直接复用返回值；手动重试和写入冲突刷新绕过缓存，模型/配置失效发生在请求期间时合并补读，防止旧响应覆盖新状态。
+- 插件配置变化及本插件保存凭据后使缓存失效；连接断开/重建与插件卸载清理缓存并隔离旧请求。
+- 本阶段不增加服务端推送：其他窗口的修改在后续缓存过期的按需刷新时同步，不再保证两秒内自动同步；版本冲突保护保留。
+
+## [0.1.3] - 2026-09-24
+
+### 界面细节对齐
+
+- 保留设置卡片、行内配置与会话搜索菜单布局，对齐 DSH 的中性色按钮、表单底色、细边框、状态标签和单色凭据图标。
+- 搜索菜单采用官方紧凑间距、圆角、背景模糊和浮层阴影；实时性分段选项跟随宿主主题。
+- 修复主按钮悬停时文字颜色被覆盖的问题，改善窄屏表单与操作按钮换行，并尊重减少动态效果偏好。
+- 设置与选择器预览共用官方浅色／深色主题变量快照，更新界面截图。
+
+### DSH 0.1.7-rc.1 适配
+
+- 最低宿主版本提升至 `0.1.7-rc.1`，开发依赖固定到该版本；Cordis / Schemastery 对齐 volatile 配置能力。
+- 服务端改用 Loader `Volatile<T>.get()` 与 `internal/config` 校验，SettingsForms 只负责 profile 投影与 CAS 保存；移除 installSection 和直接写 settings.yaml 的旧逻辑。
+- 保留旧配置导入：跟随宿主 settings.yaml → profile 时序，先迁凭据再替换配置，失败保留旧值并可重试，不覆盖已有不同凭据。
+- 客户端设置迁移至 ConfigForms 和 plugins.bundle.config，使用 hooks/回调注入与 whileServed 生命周期；修复保存拒绝仍显示成功的问题。
+- 会话选择器使用类型化 modelSelection projection；跟随模型按公开目录中的实例 namespace/path 读取设置，不扫描废弃 session 事件。
+- Typert strict codec 改惰性 create()；集成测试迁移 PtcRuntime.resolve/run，保留 native/PTC 请求快照与并发隔离。
+- 更新真实 profile、交互、模型目录与发布包契约测试，配置示例改为 profile patch。
+
+### 升级边界
+
+- 配置格式仍为 version 2，搜索选择 Storage Domain 仍为 version 1；不迁移或重写宿主 Session 日志。
+- 跟随模式仍有受限 adapter identity/catalog 兼容 shim，不自动扩大到 OAuth/订阅认证；无法证明绑定时拒绝搜索，可用固定连接。
+- 本版本需重新加载服务端插件并刷新 Web 页面；不支持旧版 settingsScope/settings.plugin.item 宿主。
+
 ## [0.1.2] - 2026-09-22
 
 ### 新增与修复

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.1.5--rc.2%2B-536DFE?style=flat-square)](package.json)
+[![DSH](https://img.shields.io/badge/DSH-0.1.7--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,25 +60,27 @@
 
 ### 环境要求
 
-- **DeepSeek Harness**：≥ `0.1.5-rc.2`
+- **DeepSeek Harness**：≥ `0.1.7-rc.2`
 - **Node.js**：`^22.19.0 || >=24.0.0`
 
+本版将 DSH 基线提升到 0.1.7-rc.2，保留动态配置、插件设置页和会话 projection 架构，详见[rc.2 影响评估](docs/upstream-0.1.7-rc.2-assessment.zh-CN.md)。升级前请备份 profile 和旧设置。
+
 ### 步骤 1：安装插件
 
 **方式 A：通过 GitHub Release 离线包安装（推荐）**
 
-从 [v0.1.2 Release](https://github.com/Yurzi/dsh-web-search-enhanced/releases/tag/v0.1.2) 下载预构建包 `dsh-web-search-enhanced-0.1.2.tgz`，执行绝对路径安装命令：
+当前版本为 **0.1.4**，最低支持 **DSH 0.1.7-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.2.tgz
+dsh plugin --profile web add /path/to/dsh-web-search-enhanced-0.1.4.tgz
 ```
 
 **方式 B：通过 npm 在线安装**
 
-在版本已发布到 npm 仓库后，也可直接安装：
+该版本发布到 npm 后，也可直接安装：
 
 ```sh
-dsh plugin --profile web add dsh-web-search-enhanced@0.1.2
+dsh plugin --profile web add dsh-web-search-enhanced@0.1.4
 ```
 
 ### 步骤 2：生效与刷新
@@ -181,7 +183,7 @@ _注：实时抓取可能会稍微增加检索耗时与额度消耗；对于不
 **不会**。Web Search Enhanced 是完全**会话隔离**的：
 
 - 修改当前会话的搜索连接，不会影响已经存在的其他会话。
-- Fork（分支）出的新会话会继承分支那一刻的搜索设置，之后两者独立变更，互不干扰。
+- Fork（分支）出的新会话在首次初始化时继承父会话当前搜索设置，之后两者独立变更；不重建历史 fork 切点的搜索设置。
 
 </details>
 
@@ -198,7 +200,7 @@ _注：实时抓取可能会稍微增加检索耗时与额度消耗；对于不
 | 文档                                                     | 适合谁读            | 主要内容                                                          |
 | :------------------------------------------------------- | :------------------ | :---------------------------------------------------------------- |
 | 📘 **[配置指南](docs/configuration.zh-CN.md)**           | 所有用户 / 进阶用户 | 完整参数列表、凭据机制、高级 options 白名单、自定义端点与排错字典 |
-| 📙 **[升级指南](docs/migration.zh-CN.md)**               | 从旧版升级的老用户  | 0.1.0 架构变化、旧版导入指引、升级踩坑预防                        |
+| 📙 **[升级指南](docs/migration.zh-CN.md)**               | 从旧版升级的老用户  | 0.1.7 宿主适配、旧版导入指引、升级踩坑预防                        |
 | 📗 **[架构设计说明](docs/design-v2.converged.zh-CN.md)** | 开发者 / 架构爱好者 | 会话状态隔离、请求快照机制、多适配器与安全性设计                  |
 | 🛠️ **[开发与验证文档](docs/v2-implementation.zh-CN.md)** | 插件二次开发者      | 本地构建、单元测试、浏览器环境验证与打包发布                      |
 | 📝 **[更新日志](CHANGELOG.md)**                          | 所有人              | 版本演进记录与历史变更                                            |

package/docs/configuration.zh-CN.md

@@ -1,18 +1,19 @@
-# 0.1.2 配置参考
+# 0.1.4 配置参考
 
-本指南面向安装版插件。包版本为 **0.1.2**，配置格式的 `version` 为 **2**；两者不是同一版本号。快速开始见 [README](../README.md)，旧版用户先读[升级指南](migration.zh-CN.md)。
+本指南面向安装版插件。包版本为 **0.1.4**，配置格式的 `version` 为 **2**；两者不是同一版本号。快速开始见 [README](../README.md)，旧版用户先读[升级指南](migration.zh-CN.md)。
 
 ## 配置入口与作用范围
 
-在 DSH 设置的 Web Search Enhanced 卡片管理搜索连接、凭据引用与新会话默认值，在已有会话输入区选择搜索连接和内容实时性。搜索连接独立于对话模型。设置按宿主 SettingsScope 保存稀疏覆盖，不复制整个内置目录；恢复继承设置、删除用户连接覆盖均不删除 Credentials。继承层中的连接在移除用户覆盖后仍可能存在。
+在 DSH 设置的 Web Search Enhanced 卡片管理搜索连接、凭据引用与新会话默认值，在已有会话输入区选择搜索连接和内容实时性。搜索连接独立于对话模型。设置按宿主 ConfigForms / ConfigForm 保存 profile 稀疏覆盖，不复制整个内置目录；恢复继承设置、删除用户连接覆盖均不删除 Credentials。继承层中的连接在移除用户覆盖后仍可能存在。
 
-以下 YAML 的 `web-search-enhanced` 是 Settings 命名空间。若编辑 Cordis 插件条目的 `config`，仅放该命名空间下的字段，不能原样把整个示例作为 Cordis 根配置。优先使用设置 UI，避免覆盖其他插件设置。
+以下 YAML 均为 DSH 0.1.7 的 profile patch 条目，`id: web-search-enhanced` 是安装补丁的固定条目 ID，字段置于 `config` 下。旧 `settings.yaml` 由宿主导入后不再作为实时配置源；优先使用插件管理器中的配置页，避免覆盖其他插件设置。专属客户端配置页绑定默认条目 ID，不支持任意改名或多个搜索插件实例。
 
 ```yaml
-web-search-enhanced:
-  version: 2
-  defaultConnection: builtin:exa
-  freshness: auto
+- id: web-search-enhanced
+  config:
+    version: 2
+    defaultConnection: builtin:exa
+    freshness: auto
 ```
 
 | 顶层字段 | 类型 / 默认 | 含义 |
@@ -50,16 +51,17 @@ web-search-enhanced:
 内置结构化连接只允许覆盖 `label`（非空）、`disabled`（布尔，默认 false）、`credentialRef`、`access`、`options`。不能改其 `kind`、`adapter`、`endpoint` 或添加任意请求字段。
 
 ```yaml
-web-search-enhanced:
-  version: 2
-  connections:
-    builtin:exa:
-      access: api-key
-      credentialRef: EXA_API_KEY
-      options:
-        type: fast
-    builtin:firecrawl:
-      disabled: true
+- id: web-search-enhanced
+  config:
+    version: 2
+    connections:
+      builtin:exa:
+        access: api-key
+        credentialRef: EXA_API_KEY
+        options:
+          type: fast
+      builtin:firecrawl:
+        disabled: true
 ```
 
 ### 结构化 options 白名单
@@ -109,16 +111,17 @@ Firecrawl 非 auto 会请求内联 Markdown 正文，正文缺失时不拿旧搜
 ID 格式为 `custom:` 加 1–100 个字符，首字符为字母或数字，后续可含字母、数字、点、下划线、连字符。必需 `label`、`kind: structured`、已支持的 `adapter`、`credentialRef`；可用 `disabled`、`endpoint`、`trustedEndpoint`、`options`。省略 endpoint 使用该 adapter 的官方 REST 地址；不同地址必须显式 `trustedEndpoint: true`。自定义结构化连接**只用个人 Key**，不接受 `access`、任意 headers 或任意 body。
 
 ```yaml
-web-search-enhanced:
-  version: 2
-  connections:
-    custom:team-tavily:
-      label: 团队 Tavily
-      kind: structured
-      adapter: tavily
-      credentialRef: TEAM_TAVILY_API_KEY
-      options:
-        topic: news
+- id: web-search-enhanced
+  config:
+    version: 2
+    connections:
+      custom:team-tavily:
+        label: 团队 Tavily
+        kind: structured
+        adapter: tavily
+        credentialRef: TEAM_TAVILY_API_KEY
+        options:
+          topic: news
 ```
 
 自定义地址必须为绝对 HTTP(S) URL，不含内嵌账号密码、查询或片段。信任标志意味着你同意向该地址发送搜索词与所选凭据，不是自动安全检测；建议使用 HTTPS。
@@ -128,22 +131,23 @@ web-search-enhanced:
 自定义模型必须为 `kind: model`，含 `label`、`trustedEndpoint: true` 和完整 `binding`。`disabled` 默认 false，`options` 默认空对象。
 
 ```yaml
-web-search-enhanced:
-  version: 2
-  connections:
-    custom:search-model:
-      label: 专用搜索模型
-      kind: model
-      trustedEndpoint: true
-      binding:
-        mode: fixed
-        protocol: openai-responses
-        model: YOUR_SEARCH_CAPABLE_MODEL
-        baseURL: https://api.openai.com/v1
-        credentialRef: SEARCH_MODEL_API_KEY
-      options:
-        maxTokens: 4096
-        searchContextSize: medium
+- id: web-search-enhanced
+  config:
+    version: 2
+    connections:
+      custom:search-model:
+        label: 专用搜索模型
+        kind: model
+        trustedEndpoint: true
+        binding:
+          mode: fixed
+          protocol: openai-responses
+          model: YOUR_SEARCH_CAPABLE_MODEL
+          baseURL: https://api.openai.com/v1
+          credentialRef: SEARCH_MODEL_API_KEY
+        options:
+          maxTokens: 4096
+          searchContextSize: medium
 ```
 
 `model` 必须非空；示例占位值需替换为实际支持服务端搜索的模型。`baseURL` 遵守上述 URL 约束。支持协议和路径：
@@ -172,16 +176,17 @@ web-search-enhanced:
 `builtin:session-model` 仅允许 `disabled` 和 `optionsByProtocol` 覆盖，不能重命名或设置固定 binding。每个协议单独保存上述模型 options：
 
 ```yaml
-web-search-enhanced:
-  version: 2
-  defaultConnection: builtin:session-model
-  connections:
-    builtin:session-model:
-      optionsByProtocol:
-        anthropic-messages:
-          maxUses: 3
-        openai-responses:
-          searchContextSize: low
+- id: web-search-enhanced
+  config:
+    version: 2
+    defaultConnection: builtin:session-model
+    connections:
+      builtin:session-model:
+        optionsByProtocol:
+          anthropic-messages:
+            maxUses: 3
+          openai-responses:
+            searchContextSize: low
 ```
 
 实际 agent 请求头必须有完整 provider/model；仅无请求头时才读同一 agent options，不混拼不完整字段。插件读取 `llm-pi-ai.providers[provider]` 的 `api`、`baseURL`、`apiKeyEnv`；协议也识别宿主的 `openai-completions` 为 Chat Completions。只在缺省协议 / 地址时尝试只读模型目录补齐。

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

@@ -1,4 +1,4 @@
-# 0.1.2 当前架构与实现边界
+# 0.1.4 当前架构与实现边界
 
 本文描述已存在的源码契约，不是未来设计提案或历史验收记录。为避免外部链接失效，保留原文件名。用户配置见[配置参考](configuration.zh-CN.md)，验证方法见[开发验证指南](v2-implementation.zh-CN.md)。
 
@@ -7,7 +7,7 @@
 插件为 DSH 原生 `web_search` 注册 `enhanced-search` provider。模型工具签名、结果结构和宿主访问控制不变；原生调用与 PTC 调用经过同一工具执行链。它不是第二套模型工具，不接管 `web_fetch`，不替换对话模型。
 
 ```text
-Settings + 内置 Catalog ── resolveSettings ───────────────┐
+Volatile Config + 内置 Catalog ── resolveSettings ───────────────┐
 DSH Storage Domain ── SessionSelections ────────────────┤
 实际 agent/request ── 按 agent + turn + step 捕获快照 ──┤
                                                        ↓
@@ -26,7 +26,7 @@ tools/execute 的 exec.agent → 私有 AsyncLocalStorage → enhanced-search
 
 | 模块 | 职责 |
 | --- | --- |
-| [src/index.ts](../src/index.ts) | 插件 schema、Settings 注册、显式迁移门禁、安装 bridge |
+| [src/index.ts](../src/index.ts) | volatile Config、profile SettingsForms 展示策略、迁移门禁、安装 bridge |
 | [src/catalog.ts](../src/catalog.ts) | 无秘密的稳定内置 ID、地址、默认引用和能力 |
 | [src/config.ts](../src/config.ts) | 稀疏合并、字段白名单、URL / 引用 / options 校验 |
 | [src/migration.ts](../src/migration.ts) | 纯旧配置转换，不读 Key、不写 Settings、不执行 fallback |
@@ -39,14 +39,14 @@ tools/execute 的 exec.agent → 私有 AsyncLocalStorage → enhanced-search
 | [src/adapters/mcp.ts](../src/adapters/mcp.ts) | 私有 keyless MCP 传输与结果解析 |
 | [src/protocols.ts](../src/protocols.ts) | 三种模型协议的请求构造和响应归一化 |
 | [src/remote-contract.ts](../src/remote-contract.ts) | 严格 Remote 请求 / 响应 schema 与调用描述符 |
-| [src/client/V2Settings.tsx](../src/client/V2Settings.tsx) | 当前连接设置界面、稀疏操作和显式导入 |
+| [src/client/V2Settings.tsx](../src/client/V2Settings.tsx) | ConfigForm hooks 注入、当前连接设置界面和稀疏操作 |
 | [src/client/SearchConnectionSelector.tsx](../src/client/SearchConnectionSelector.tsx) | 当前会话连接与实时性选择器 |
 
 `model-config.ts`、`provider.ts` 的 `createProvider` / `EnhancedSearchProvider` 是兼容固定配置辅助接口；安装版始终走 V2 bridge。旧辅助代码中的环境变量或 fallback 行为不能外推为安装版配置能力。
 
 ## 3. 配置和秘密分离
 
-当前设置格式为 version 2，包版本为 0.1.2。内置目录只做默认值；用户保存差异，不把目录整表复制到用户层。四种结构化内置连接默认 keyless，访问方式为显式选择，不根据已保存 Key 猜测。自定义连接只允许支持的 adapter 或固定模型协议；新 endpoint 需要信任确认。
+当前设置格式为 version 2，包版本为 0.1.4。内置目录只做默认值；用户保存差异，不把目录整表复制到用户层。四种结构化内置连接默认 keyless，访问方式为显式选择，不根据已保存 Key 猜测。自定义连接只允许支持的 adapter 或固定模型协议；新 endpoint 需要信任确认。
 
 内置结构化连接不能重定向地址或改变 adapter。自定义结构化连接只能使用个人 Key；固定模型总是需要显式信任。校验拒绝任意 headers/body、缓存参数、秘密字段等不受支持的 options。禁用连接也参与配置校验。
 
@@ -100,9 +100,9 @@ REST 共享 fetchJson，MCP 使用私有 Streamable HTTP 客户端；均有 90
 
 跟随模式并非自动复用宿主所有认证机制。优先读取实际 agent 请求头的完整 provider/model；仅请求头不存在才读同一 agent options，不补拼不完整路由。
 
-每个请求捕获 `llm-pi-ai.providers` 中的非秘密 api/baseURL/apiKeyEnv 及只读目录；只有协议 / 地址缺省才从经过形状检查的 adapter 目录补齐。显式配置不依赖该可选兼容入口。FollowRequest 按 provider/model 缓存解析结果，执行时核对 adapter 身份，替换后拒绝旧请求。实际模型选择在工具执行时解析，而 provider 设置保持请求时快照；不能把它简化成全局固定模型。
+每个请求通过公开 `llm.listConfigurableProviders()` 的 `settingsNs/settingsPath` 定位具体实例的 `settings.describe()` 值，捕获非秘密 api/baseURL/apiKeyEnv；不再调用已移除的 settings.get，也不固定假设实例名为 llm-pi-ai。公开目录未导出完整搜索 wire binding，因此仍保留受限的非公开 adapter identity/catalog 兼容 shim：只有协议 / 地址缺省才使用 catalog 补齐；任何路由都必须通过 adapter identity guard，shim 形状变化即拒绝跟随搜索，可改用显式固定连接。FollowRequest 按 provider/model 缓存解析结果，执行时核对 adapter 身份，替换后拒绝旧请求。实际模型选择在工具执行时解析，而 provider 设置保持请求时快照；不能把它简化成全局固定模型。
 
-不重建 scoped credential records，不读取 OAuth / 订阅秘密，不透传自定义 headers，不虚构 rc.2 不支持的 model 级 endpoint/API/凭据覆盖。协议受支持也不代表模型有服务端搜索能力。
+不重建 scoped credential records，不读取 OAuth / 订阅秘密，不透传自定义 headers，不透传 model 级 endpoint/API/凭据覆盖。协议受支持也不代表模型有服务端搜索能力。
 
 ## 8. 实时性和诊断
 
@@ -112,7 +112,7 @@ Firecrawl 的 fresh/realtime 映射为内联 scrapeOptions.maxAge（86400000 / 0
 
 ## 9. 客户端与非目标
 
-设置使用官方 `settings.plugin.item` 槽和 SettingsScope 路径操作；凭据使用宿主 Remote。会话选择器通过 `conversation.input.right` 追加槽，Remote 挂载后在独立注入作用域注册，不替换 composer / 模型槽，不抓取 DOM。
+设置使用官方 `plugins.bundle.config` 槽（key 为包名）和 ConfigForms / ConfigForm 路径操作，`whileServed` 管理宿主表单上下线；只向渲染器传递 hooks source 和绑定回调，不直接传入服务对象。`mutate` 返回 false 时保留草稿，不显示保存成功；凭据使用宿主 Remote。会话选择器用标准 `useProjection("modelSelection")` 订阅模型变更，移除 sessions unknown / binding 猜测；通过 `conversation.input.right` 追加槽，Remote 挂载后在独立注入作用域注册，不替换 composer / 模型槽，不抓取 DOM。
 
 选择器只列本地可用连接并隐藏空组，但保留不可用的当前选择以供显式修复；使用原生 popover、键盘导航、Esc 与焦点恢复。主题使用宿主 `--dsw-alias-*` 令牌。空白会话首消息前没有独立选择器，靠默认连接初始化。
 

package/docs/migration.zh-CN.md

@@ -1,27 +1,27 @@
-# 升级到 0.1.0
+# 升级到 0.1.4 / DSH 0.1.7-rc.2
 
-0.1.0 将旧版全局搜索模型配置重构为**会话级搜索连接**。包版本 0.1.0、设置格式 version 2、会话 Storage Domain version 1 是三个不同概念。完整参数见[配置参考](configuration.zh-CN.md)。
+0.1.4 将最低宿主版本提高为 **0.1.7-rc.2**，沿用 0.1.3 已完成的 Loader 动态配置、profile-backed SettingsForms、ConfigForms 客户端、惰性 Typert codec 和新版 PTC 适配。从 0.1.3 升级不需要新的配置或存储迁移；详见 [rc.2 影响评估](upstream-0.1.7-rc.2-assessment.zh-CN.md)。旧版已采用的**会话级搜索连接**保持不变：包版本 0.1.4、设置格式 version 2、会话 Storage Domain version 1 是三个不同概念。完整参数见[配置参考](configuration.zh-CN.md)。
 
 ## 1. 升级前准备
 
-- 确认 DSH 满足 `>=0.1.5-rc.2`，Node 满足 `^22.19.0 || >=24.0.0`。实现基线是 rc.2 契约，不代表对所有未来宿主版本均完成验证。
+- 确认 DSH 满足 `>=0.1.7-rc.2`，Node 满足 `^22.19.0 || >=24.0.0`。实现基线是 0.1.7-rc.2 契约，不代表对所有未来宿主版本均完成验证。
 - 备份当前插件版本、Web profile / 插件配置和 DSH 持久存储。凭据使用宿主安全备份方式，不复制到公开 Issue 或仓库。
 - 记录旧 `modelMode`、协议、模型、endpoint、凭据引用，以及希望保留的会话选择。
-- 如旧配置存在非空明文 `apiKey`，**先移到 DSH Credentials，并从配置来源删除**。新插件验证阶段即拒绝明文 Key；如果因此无法挂载设置页，需先在原配置来源处理，不能指望导入按钮替你搬运秘密。
+- 推荐升级前先将明文 `apiKey` 移到 DSH Credentials 并从配置来源删除。兼容导入仅允许旧格式短暂携带 Key：先验证转换结果，再写 Credentials，最后 CAS 替换 profile 配置。V2 配置仍拒绝明文 Key；已有不同值的同名凭据不会被自动覆盖。
 - 自定义 `providerId` 不再支持；安装版固定为 `enhanced-search`。检查旧 Web profile 的 searchProvider 配置和重复安装。
 
 ## 2. 安装发行包
 
-从 [v0.1.0 Release](https://github.com/Yurzi/dsh-web-search-enhanced/releases/tag/v0.1.0) 下载构建好的 `dsh-web-search-enhanced-0.1.0.tgz`，使用绝对路径交给 DSH 插件管理器：
+从当前源码运行 `pnpm install --frozen-lockfile && pnpm run check && pnpm pack`，或使用 [Releases](https://github.com/Yurzi/dsh-web-search-enhanced/releases) 中实际发布的 0.1.4 构建包。使用绝对路径交给 DSH 插件管理器：
 
 ```sh
-dsh plugin --profile web add /absolute/path/to/dsh-web-search-enhanced-0.1.0.tgz
+dsh plugin --profile web add /absolute/path/to/dsh-web-search-enhanced-0.1.4.tgz
 ```
 
 若该版本已在 npm 发布，也可安装固定版本：
 
 ```sh
-dsh plugin --profile web add dsh-web-search-enhanced@0.1.0
+dsh plugin --profile web add dsh-web-search-enhanced@0.1.4
 ```
 
 发布附件中的构建 tgz 与 GitHub 自动生成的 Source code archive 不同：后者是源码，不能假定含 `lib/` 构建产物。npm 可用性须以 registry 实际发布结果为准，GitHub 标签 / Release 存在不代表 npm 已完成。
@@ -32,7 +32,7 @@ dsh plugin --profile web add dsh-web-search-enhanced@0.1.0
 
 ## 3. 启动时自动迁移旧配置
 
-插件现在只保留启动时自动迁移，不再提供命令行迁移脚本或设置页手动导入入口。检测到旧版配置后，插件会在设置注册阶段尝试迁移；迁移成功后写入 V2 连接结构，搜索请求仍会对未完成迁移的配置 fail-closed，并提示检查设置。
+插件不再自行注册 Settings section 或直接改写 settings.yaml。DSH 0.1.7 在 Loader 就绪后将旧 settings.yaml 重命名为 settings.yaml.imported，并尝试导入到 profile 条目；插件监听该条目的表单 / volatile 更新，再迁移成 V2 连接结构。保存使用 revision CAS，不能覆盖并发编辑。新旧宿主的配置持久化架构不同，不应只修改版本号或复制整份旧 YAML 到 profile。未完成迁移时搜索 fail-closed，普通聊天不因此被替换或阻断。
 
 自动迁移覆盖以下旧字段：
 
@@ -53,7 +53,7 @@ dsh plugin --profile web add dsh-web-search-enhanced@0.1.0
 
 自动迁移不会覆盖已有会话的搜索选择，也不会自动切换新连接。迁移完成后请重新加载插件或重启 DSH，再刷新 Web 页面；已有会话如需使用迁移后的连接，应在会话搜索选择器中显式选择。
 
-如果迁移失败，请先将明文 Key 移入 DSH Credentials，并检查旧配置中的 endpoint、模型协议和 credential 引用。插件不会提供独立迁移命令，也不会创建配置文件备份；进行升级前请由宿主或部署系统负责备份 `settings.yaml`。
+如果迁移失败，请检查 Credentials、endpoint、协议和引用，并保留 profile 与 settings.yaml.imported。已成功进入 profile 的旧值会在插件重启后重试；凭据服务重新挂载也会触发重试。宿主拒绝导入的 section 可能只留在 settings.yaml.imported，宿主不会再次自动导入：需修正该 section 后通过宿主 profile 配置编辑器恢复到对应条目的 config，再重启。不要把含 Key 的备份上传 Issue。插件不删除 .imported 备份，也不能清除继承 bundle 中的秘密，请在确认迁移后自行安全处理原始配置/备份。升级前由部署系统备份 settings.yaml、profile patch 与持久存储。
 
 ## 4. 从重构预览版升级
 

package/docs/upstream-0.1.7-adaptation.zh-CN.md

@@ -0,0 +1,49 @@
+# DSH 0.1.7-rc.1 适配记录
+
+## 基线与交付版本
+
+- 插件版本：**0.1.3**。
+- 最低宿主版本：**0.1.7-rc.1**；所有直接 DSH 开发依赖精确固定为该版本，peer 下限同步提升。
+- 对比上游：
+  - dsh-v0.1.5-rc.2：fb2c4b9e698e30edb738bca4cf0618587db7d203。
+  - dsh-v0.1.7-rc.1：46a7f68b0922371ce7144b668b90e377d8e799f4。
+- 使用用户提供的上游源码只读审查；未修改上游 checkout，未修改运行中的 DSH 安装。
+
+## 变更对照
+
+以下上游链接固定到目标 tag，不依赖 main 分支漂移。
+
+| 上游变化 / 依据 | 插件适配 |
+| --- | --- |
+| [SettingsForms](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.7-rc.1/packages/settings/settings/src/index.ts#L223-L277) 替代 SettingsProvider / installSection，按 profile entry 投影 volatile 字段 | [src/index.ts](../src/index.ts) 使用 Volatile Config、get()、internal/config 跨字段校验；configure({auto:false}) 避免重复生成设置页。动态更新不重挂载插件，搜索仍按 agent/request 冻结快照。 |
+| [原生搜索 provider 的 volatile 用法](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.7-rc.1/packages/web/web-search-deepseek/src/index.ts#L46-L74)；settings.yaml 导入改为 Loader 就绪后写 profile | 删除插件直接改写 YAML 文件的逻辑；监听表单/volatile 更新，先验证、再迁凭据、最后 revision CAS 替换配置。缺凭据时保留旧值，重启或凭据重新挂载后重试。 |
+| [ConfigForm / ConfigForms](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.7-rc.1/packages/client/ui-settings/src/client/config-form-types.ts) 替代 SettingsScope | [bindings.ts](../src/client/bindings.ts) 使用 hooks compartment + InjectFace，将服务限制在 apply 层；组件只接收框架 hook 与操作回调。mutate 返回 false 时保留草稿、不虚报成功。 |
+| [第三方 bundle 配置槽](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.7-rc.1/packages/client/ui-plugin-manager/src/client/slot-contract.ts#L80-L102) | [client/index.tsx](../src/client/index.tsx) 使用 plugins.bundle.config，key 为插件包名，whileServed 管理设置服务可用性；保留先挂载 Remote 再注入 namespace 的生命周期。 |
+| [会话 UI 的 projection hook](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.7-rc.1/packages/client/ui-session/src/client/index.ts#L163-L178) | 选择器改为 useProjection('modelSelection')；删除 sessions unknown 与内部 binding/faceOf 探测。保留跨会话迟到响应隔离、读写竞争保护及轮询/focus 兜底。 |
+| [可配置模型目录](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.7-rc.1/packages/llm/llm/src/index.ts#L473-L546) 使用具体实例 settingsNs/settingsPath | [session-model.ts](../src/dsh/session-model.ts) 从公开目录和 settings.describe() 定位 profile，不再调用 settings.get 或假定 llm-pi-ai 是固定实例名。执行仍使用 committed requestHeader，不能被下一轮 pending 模型选择覆盖。 |
+| [Typert strict codec 惰性 create](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.7-rc.1/packages/typert/protocol/src/types.ts#L272) | [remote-contract.ts](../src/remote-contract.ts) 将 schema 属性迁移到 create()，保持严格请求/响应验证；没有为纯 JSON 结果虚构 binary 编码需求。 |
+| [PtcRuntime](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.7-rc.1/packages/ptc-runtime/ptc-runtime/src/index.ts) 取代 CodeRuntime，resolve/run 分离 | 移除旧开发依赖；真实 Tools 的 native/PTC 集成测试使用新运行时 seam，覆盖 resolved cwd/timeout、会话隔离、请求冻结、取消与授权。代码执行基底和网络是测试 fixture，不等同真实进程沙箱验收。 |
+| snapshotEvents 已废弃；Web provider / Credentials / Storage Domain 在此版本范围内接口未发生对应破坏 | 模型配对不再扫描旧 Session 事件；保留官方 Web provider 接口、Credentials、Storage Domain。配置 version 2、选择 domain version 1 不变，不重写宿主 Session 数据。 |
+
+## 验证结果
+
+在本仓库、Node v26.9.0 / pnpm 11.7.0 环境执行：
+
+- CI=true pnpm install --frozen-lockfile：通过，锁文件与目标依赖可复现。
+- pnpm run check：通过，依次 typecheck → build → test → verify:package。
+- Vitest：**20 文件、295 测试通过，无跳过**。包括真实 Loader + profile + ConfigEditor + SettingsForms 的配置更新、CAS、迁移与重启恢复。
+- node scripts/check-selector-ui.mjs：桌面、390px 窄屏、深色模式各 **14 项检查通过**；使用隔离 Chromium / 临时 profile，不连接当前 DSH 会话。
+- 安装包验证：宿主/客户端 bundle、类型声明、profile patch、最低版本与客户端依赖契约通过。
+- git diff --check：通过；上游 checkout 仍 clean。
+
+完整检查先构建再测试，避免客户端 bundle 用例验证陈旧产物或因缺少构建产物而跳过。测试中的损坏缓存恢复场景会输出预期 warning，不是测试失败。
+
+## 限制与升级注意
+
+1. 公开模型目录仍未暴露完整 endpoint/protocol/credential 与 adapter 身份。现有跟随模式保留一个明确标注的非公开 adapter identity/catalog 兼容 shim，目标版本已测；shape 不符则 fail-closed，不静默取消身份保护。固定搜索连接不依赖该兼容层。不扩展 OAuth/订阅认证、不透传自定义 headers。
+2. 专属 bundle 设置页绑定默认 entry id web-search-enhanced；上游 bundle 槽不提供实例 ID，未增加猜测式多实例/任意别名 UI 支持。
+3. 宿主拒绝导入的旧 section 可能只保留在 settings.yaml.imported。请按[升级指南](migration.zh-CN.md)修复并恢复到 profile，保留安全备份；不会删除含秘密的原始备份或修改继承 bundle。
+4. 未安装到当前运行的 DSH、未重启服务、未执行付费/真实供应商网络搜索。隔离测试不能代表生产 GUI 已更新。
+5. Fork 仍在初始化时继承父会话当前搜索选择，不声称能恢复任意历史切点的插件选择。
+
+安装本地构建包后，需重新加载服务端插件或重启 DSH，再刷新 Web 页面。源码、安装包与校验文件见 [v0.1.3 Release](https://github.com/Yurzi/dsh-web-search-enhanced/releases/tag/v0.1.3)。

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

@@ -0,0 +1,35 @@
+# DSH 0.1.7-rc.2 对插件 0.1.4 的影响评估
+
+## 范围与结论
+
+根据上游 rc.1 → rc.2 版本分析，逐项核对本插件实际调用路径，并将开发依赖切换到发布的 rc.2 包验证。上游范围为 [dsh-v0.1.7-rc.1 … dsh-v0.1.7-rc.2](https://github.com/deepseek-ai/deepseek-harness/compare/dsh-v0.1.7-rc.1...dsh-v0.1.7-rc.2)。本文不是对上游全部提交的重新审计。
+
+结论：升级风险低，未发现需要修改本插件运行时代码的直接破坏性变更；跟随模型存在原有认证与私有 adapter 兼容边界，不能据此承诺所有 Provider 均可搜索。
+
+- 插件：`0.1.3` → `0.1.4`（patch）。
+- 最低 DSH：`>=0.1.7-rc.2`；DSH peer 范围：`^0.1.7-rc.2`；直接 DSH 开发依赖：精确 `0.1.7-rc.2`。
+- 设置格式仍为 version 2，Storage Domain 仍为 version 1，不重写宿主会话历史。
+- 原 Unreleased 中的选择器按需刷新、缓存与并发合并优化一并归入 0.1.4。
+
+## 逐项影响
+
+| 上游变化 | 插件实际依赖与结论 |
+| --- | --- |
+| 动态工具增删、ToolHistory 与历史投影 | [bridge](../src/dsh/bridge.ts) 只注册 `enhanced-search` Web provider，使用 `agent/request` 和 `tools/execute` 捕获请求上下文；不构造工具增删消息、不重写历史。继续由宿主原生 `web_search` 和 PTC 链执行，无需自行接入投影协议。 |
+| DeepSeek Provider 拆分为 API Key / Account 插件 | 依赖、测试和 [安装补丁](../cordis.patch.yml) 均不把旧 `dsh-llm-deepseek` 作为 Cordis 插件加载。补丁中的 `web-search-deepseek` 是原生搜索插件条目，不是被拆分的 LLM 插件，不能误改成新 Provider 包名。用户自行维护的宿主 profile 仍需按上游规则迁移。 |
+| `selectModel` 严格校验 `listModels` | 插件不调用 `selectModel`，也不通过切换聊天模型执行辅助搜索。[跟随模型](../src/dsh/session-model.ts) 读取实际请求头与公开配置目录；固定模型直接使用显式 binding。因此不是所有固定搜索模型都要注册到宿主。用户切换聊天模型时则须确保模型在宿主目录中，否则会先被宿主拒绝。 |
+| Schedule 存储导出删除、默认禁用 schedule/time-context | 插件不依赖 Schedule 或时间上下文服务。自身选择存储通过 Storage Domain，不涉及计划任务存储；实时性参数是缓存年龄偏好，也不依赖注入时钟。 |
+| `PreToolDecision.displayReason`、Auto Review 调整 | 插件不构造该准入决策，不接管审批；`tools/execute` 钩子继续调用 next，保留宿主授权与审批链。新增可选展示字段无需适配。 |
+| 快捷键中心、代码语言与系统提示词调整 | 插件不导入旧快捷键内部 API、不使用代码语言内部模块、不解析系统提示词。设置页、会话 projection 与插件配置槽的类型和构建由 rc.2 依赖验证；不能以编译通过替代真实 GUI 验收。 |
+
+## 跟随模型边界
+
+[session-model.ts](../src/dsh/session-model.ts) 仍通过 `listConfigurableProviders()` 的 settings namespace/path 获取非秘密路由信息，要求受支持的 HTTP 协议、endpoint 和显式 `apiKeyEnv`。官方账号、OAuth、订阅凭据不会被重建或借用。新官方 API Key Provider 也不能仅因包名包含 API Key 就视为自动兼容，仍须满足这些路由条件。
+
+adapter identity 的 `registration()` 及可选 pi-ai catalog 是原有兼容 shim，并非稳定公共契约；缺失或发生替换时保持 fail-closed，不隐式改用其他连接或凭据。遇到跟随不可用可显式选择内置结构化连接或受支持的固定搜索连接。
+
+## 升级与验收
+
+先升级 DSH，再安装 0.1.4，重新加载服务端插件并刷新 Web 页面。从 0.1.3 升级应保留连接选择、凭据和实时性偏好，无需清空存储。选择器不再常驻两秒轮询；跨窗口修改在后续缓存过期的按需刷新时同步。
+
+本次验证通过：冻结锁文件安装、TypeScript 类型检查、服务端 / 客户端构建、22 个测试文件共 339 项测试，以及 0.1.4 实际打包契约检查。执行命令为 `PNPM_HOME="$PWD/.pnpm-home" pnpm install --frozen-lockfile` 与 `PNPM_HOME="$PWD/.pnpm-home" pnpm run check`；显式设置工作区 PNPM_HOME 是为解决本机默认 pnpm 状态数据库打开失败，不是插件运行要求。自动测试使用模拟网络，不证明外部搜索服务实时可用；本次版本更新不等于 npm/GitHub 发布，也不等于运行中的 DSH 已安装新版本。

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

@@ -1,12 +1,12 @@
-# 0.1.2 开发与验证指南
+# 0.1.4 开发与验证指南
 
 本文件保留原路径以避免断链，内容改为可重复的开发、验证与交付方法。架构见[当前架构](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.1.5-rc.2`，源码以 rc.2 服务契约为基线。依赖声明与锁文件是构建依据，不修改宿主安装的依赖来让测试通过。
-- 当前开发主线为 `main`，旧版代码线为 `legacy/v0.0.x`。包版本 `0.1.2` 与 settings schema 的 `version: 2` 不同。
+- DSH：包要求 `>=0.1.7-rc.2`，源码以 0.1.7-rc.2 服务契约为基线。依赖声明与锁文件是构建依据，不修改宿主安装的依赖来让测试通过。
+- 当前开发主线为 `main`，旧版代码线为 `legacy/v0.0.x`。包版本 `0.1.4` 与 settings schema 的 `version: 2` 不同。
 
 在仓库根执行：
 
@@ -15,7 +15,7 @@ pnpm install --frozen-lockfile
 pnpm run check
 ```
 
-`check` 顺序为 typecheck → test → build → verify:package。任一步失败都不应宣称整个检查完成。安装依赖或构建可能写 node_modules / lib；纯文档工作不必重复构建来制造“验证记录”。
+`check` 顺序为 typecheck → build → test → verify:package（先构建，确保 bundle 测试验证当前产物而非旧文件或跳过）。任一步失败都不应宣称整个检查完成。安装依赖或构建可能写 node_modules / lib；纯文档工作不必重复构建来制造“验证记录”。
 
 ## 检查层级
 
@@ -80,6 +80,8 @@ node scripts/preview-ui.mjs --dark
 
 preview-ui 写 `.dsh-smoke-home/settings-preview.html`，不会启动第二个 DSH 服务。静态预览 / 截图仅供布局审阅，不能证明设置保存、服务端更新或用户机器的实际挂载。
 
+设置预览与选择器浏览器检查共用 `scripts/fixtures/dsh-theme.css`，其中记录 DSH 官方主题变量快照及来源提交。运行时仍直接继承宿主主题，不打包该快照；对齐新版主题时同步更新此文件，避免手写预览配色掩盖深色模式或按钮对比度问题。
+
 真实宿主验收需另外安装构建包，重载插件或重启 DSH 并刷新 Web 页，再检查：
 
 - 官方设置槽和已有会话输入区出现组件，主题 / 窄屏 / 键盘导航正常。
@@ -99,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.2.tgz` 安装 Release 构建附件。
+3. 用户可用 `dsh plugin --profile web add /absolute/path/to/dsh-web-search-enhanced-0.1.4.tgz` 安装 Release 构建附件。
 4. Git 操作、远端分支调整、标签、Release 和 npm 发布分别需要授权与结果核验；不要把本地构建当作已发布。主线为 main，旧代码保留 legacy/v0.0.x，不需要把历史文档反复改成当前成功记录。
 5. 标签触发发布流程后，单独确认 workflow 和 npm registry 的版本 / 包内容，再宣称 npm 可安装。