dsh-web-search-enhanced 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 记录 `dsh-web-search-enhanced` 的用户可见变化。历史条目描述对应版本，不代表当前行为。
 
+## [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.1%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.1`
 - **Node.js**：`^22.19.0 || >=24.0.0`
 
+本版已对齐 DSH 0.1.7-rc.1 的动态配置、插件设置页和会话 projection 架构，详见[上游适配记录](docs/upstream-0.1.7-adaptation.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.3**，最低支持 **DSH 0.1.7-rc.1**。从 [v0.1.3 Release](https://github.com/Yurzi/dsh-web-search-enhanced/releases/tag/v0.1.3) 下载安装包及 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.3.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.3
 ```
 
 ### 步骤 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.3 配置参考
 
-本指南面向安装版插件。包版本为 **0.1.2**，配置格式的 `version` 为 **2**；两者不是同一版本号。快速开始见 [README](../README.md)，旧版用户先读[升级指南](migration.zh-CN.md)。
+本指南面向安装版插件。包版本为 **0.1.3**，配置格式的 `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.3 当前架构与实现边界
 
 本文描述已存在的源码契约，不是未来设计提案或历史验收记录。为避免外部链接失效，保留原文件名。用户配置见[配置参考](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.3。内置目录只做默认值；用户保存差异，不把目录整表复制到用户层。四种结构化内置连接默认 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.3 / DSH 0.1.7-rc.1
 
-0.1.0 将旧版全局搜索模型配置重构为**会话级搜索连接**。包版本 0.1.0、设置格式 version 2、会话 Storage Domain version 1 是三个不同概念。完整参数见[配置参考](configuration.zh-CN.md)。
+0.1.3 将最低宿主版本提高为 **0.1.7-rc.1**，对齐 Loader 动态配置、profile-backed SettingsForms、ConfigForms 客户端、惰性 Typert codec 和新版 PTC。旧版已采用的**会话级搜索连接**保持不变：包版本 0.1.3、设置格式 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.1`，Node 满足 `^22.19.0 || >=24.0.0`。实现基线是 0.1.7-rc.1 契约，不代表对所有未来宿主版本均完成验证。
 - 备份当前插件版本、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.3 构建包。使用绝对路径交给 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.3.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.3
 ```
 
 发布附件中的构建 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/v2-implementation.zh-CN.md

@@ -1,12 +1,12 @@
-# 0.1.2 开发与验证指南
+# 0.1.3 开发与验证指南
 
 本文件保留原路径以避免断链，内容改为可重复的开发、验证与交付方法。架构见[当前架构](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.1`，源码以 0.1.7-rc.1 服务契约为基线。依赖声明与锁文件是构建依据，不修改宿主安装的依赖来让测试通过。
+- 当前开发主线为 `main`，旧版代码线为 `legacy/v0.0.x`。包版本 `0.1.3` 与 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.3.tgz` 安装 Release 构建附件。
 4. Git 操作、远端分支调整、标签、Release 和 npm 发布分别需要授权与结果核验；不要把本地构建当作已发布。主线为 main，旧代码保留 legacy/v0.0.x，不需要把历史文档反复改成当前成功记录。
 5. 标签触发发布流程后，单独确认 workflow 和 npm registry 的版本 / 包内容，再宣称 npm 可安装。