dsh-web-search-enhanced 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -2,13 +2,55 @@
 
 记录 `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
+
+### 新增与修复
+
+- 新增 OpenAlex 与 Semantic Scholar 学术检索连接，支持摘要、作者、引用计数与开放获取链接。
+- 修复 OpenAlex 个人 API Key 认证：使用 api_key 查询参数，免 Key 模式不发送凭据；支持配置 mailto 联系邮箱。
+- 模型切换时，尚未手动修改选择的非 fork 会话（revision 为 0）动态更新搜索连接；客户端订阅模型选择变化。
+- 内置及自定义连接的 Key、OpenAlex 邮箱和已有连接编辑统一在对应行下展开，避免共享凭据引用导致重复展开。
+- 移除独立迁移脚本和手动导入入口，仅保留启动自动迁移；统一旧字段检测，验证转换结果后顺序写入凭据与设置，失败时保留旧配置并输出脱敏提示。
+- 更新配置、升级指南及安装示例，补充认证、稀疏旧配置迁移与设置渲染回归测试。
+
+### 升级注意
+
+- 升级前自行备份 settings.yaml；重新加载插件或重启 DSH 后刷新 Web 页面。
+- 不再提供 pnpm run migrate 命令。自动迁移失败时，检查宿主日志、旧配置和 Credentials 写权限后重启插件。
+- 保存 Key 不会自动切换访问模式；个人 Key 仍需显式选择。
+
 ## [0.1.1] - 2026-09-21
 
 ### 新增与优化
 
 - **模型与搜索连接智能记忆联动**：引入 `ModelPairingStore` 状态缓存机制（持久化于 `$DSH_HOME/cache/web-search-enhanced/model-connections.json`），实现不同对话模型与其最近一次选择的搜索连接自动绑定与恢复；新会话自动恢复该模型最近一次使用的搜索连接偏好，未记录模型平滑回退至全局默认配置。
 - **自定义连接配置全面采用 DSH 原生 YAML 规范**：设置页自定义连接编辑器升级为 DSH 原生 YAML 块级缩进格式（替代原 JSON 格式），大幅提升阅读与手动编辑体验，并保持完全向后兼容。
-- **配置自动迁移与静默自愈**：提供命令行配置迁移脚本 `scripts/migrate-config.mjs` (`pnpm run migrate`)，支持自动定位配置、安全创建 `.bak` 备份，并将旧版 JSON flow-style 自动修复转换为标准 YAML 块级缩进；同时支持插件启动时静默自愈。
+- **配置自动迁移与静默自愈**：该版本提供命令行配置迁移脚本及启动时自动迁移；独立脚本在 0.1.2 中移除。
 - **文档与应用市场体验优化**：优化 README 用户安装与上手指引，补充更友好的安装与使用说明及截图清单 `screenshots.json`。
 
 ## [0.1.0] - 2026-09-21 🎉

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.1 Release](https://github.com/Yurzi/dsh-web-search-enhanced/releases/tag/v0.1.1) 下载预构建包 `dsh-web-search-enhanced-0.1.1.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.1.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.1
+dsh plugin --profile web add dsh-web-search-enhanced@0.1.3
 ```
 
 ### 步骤 2：生效与刷新
@@ -106,6 +108,8 @@ Web Search Enhanced 内置了多种主流检索服务与模型搜索能力，你
 | **Firecrawl**    | 📰 新闻资讯、深度文章抓取       | 免 Key (开箱即用) / 个人 Key   | 擅长清洗和抓取干净的 Markdown 网页正文；支持优先获取最新页面                      |
 | **Tavily**       | 🔍 事实核查、行业调研、综合检索 | 免 Key (开箱即用) / 个人 Key   | 专为大语言模型打造的搜索服务，支持自定义搜索深度（快速/进阶）与新闻主题           |
 | **Tinyfish**     | 🌍 跨语言搜索、地域本地化资讯   | 免 Key (开箱即用) / 个人 Key   | 支持按国家地区、特定语言和搜索用途精准过滤检索范围                                |
+| **OpenAlex**     | 📚 学术论文、开源文献、引用检索 | 免 Key (开箱即用) / 个人 Key   | 全球开放学术图谱，自动解析摘要倒排索引、作者、OA PDF 与引用数；支持 mailto 礼貌池 |
+| **Semantic Scholar** | 🔬 深度学术、论文速读、AI 论文 | 需配置个人 API Key             | 专为学术科研打造，内置 TL;DR 速读总结、引用计数与 ArXiv/OA 论文直链               |
 | **专用搜索模型** | 🤖 统一使用特定支持联网的模型   | Anthropic / OpenAI 协议        | 通过服务端搜索能力（如 OpenAI Responses、Anthropic Messages）直接返回带引用的回答 |
 | **跟随会话模型** | 🔄 懒人模式，搜索使用当前模型   | 需配置 provider 的 `apiKeyEnv` | 自动沿用当前会话选定的模型与端点发起联网搜索                                      |
 
@@ -133,11 +137,13 @@ _注：实时抓取可能会稍微增加检索耗时与额度消耗；对于不
 
 1. **绑定个人 API Key**：
    - 找到目标连接（例如 Firecrawl 或 Tavily）。
-   - 在凭据输入框填入你的 API Key，点击保存（将自动存入 DSH Credentials，安全可靠）。
-   - 将“访问方式”从“免 Key”切换为“个人 Key”。
-2. **设置新会话默认连接**：
+   - 点击目标连接行上的“配置 Key”，在行内展开的输入框中填写 API Key 并保存（将自动存入 DSH Credentials，安全可靠）。
+   - 将“访问方式”从“免 Key”切换为“个人 Key”。OpenAlex 的个人 Key 会按官方要求通过 api_key 查询参数发送。
+2. **配置 OpenAlex 礼貌邮箱（可选）**：
+   - 在 OpenAlex 连接行点击“礼貌邮箱”，行内填写联系邮箱；清空后保存即可恢复默认公共标识。
+3. **设置新会话默认连接**：
    - 在“新会话默认连接”下拉框中选择你最常用的引擎，新创建的对话将自动应用该偏好。
-3. **添加自定义模型或端点**：
+4. **添加自定义模型或端点**：
    - 支持添加任意兼容 OpenAI 或 Anthropic 服务端搜索协议的模型端点。
 
 完整配置语法与高级参数白名单，请参阅 📖 [详细配置指南](docs/configuration.zh-CN.md)。
@@ -177,14 +183,14 @@ _注：实时抓取可能会稍微增加检索耗时与额度消耗；对于不
 **不会**。Web Search Enhanced 是完全**会话隔离**的：
 
 - 修改当前会话的搜索连接，不会影响已经存在的其他会话。
-- Fork（分支）出的新会话会继承分支那一刻的搜索设置，之后两者独立变更，互不干扰。
+- Fork（分支）出的新会话在首次初始化时继承父会话当前搜索设置，之后两者独立变更；不重建历史 fork 切点的搜索设置。
 
 </details>
 
 <details>
 <summary><b>Q5: 如何从 0.0.x 旧版本平滑升级？</b></summary>
 
-进入 **设置 → 插件 → Web Search Enhanced**，系统会自动检测旧版全局模型配置并弹出“导入旧配置”提示，一键点击即可无缝映射为新版连接配置。详细注意事项请参阅 📖 [升级指南](docs/migration.zh-CN.md)。
+升级后重新加载插件或重启 DSH，插件会在启动时自动检测并迁移旧版全局模型配置；迁移成功后映射为新版连接配置。若出现迁移错误，请检查宿主日志、DSH Credentials 权限和旧配置，再重启插件。详细注意事项请参阅 📖 [升级指南](docs/migration.zh-CN.md)。
 </details>
 
 ---
@@ -194,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.1 配置参考
+# 0.1.3 配置参考
 
-本指南面向安装版插件。包版本为 **0.1.1**，配置格式的 `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
 ```
 
 | 顶层字段 | 类型 / 默认 | 含义 |
@@ -41,6 +42,8 @@ web-search-enhanced:
 | `builtin:firecrawl` | `https://api.firecrawl.dev/v2/search`，不发 Authorization | 同址 REST；`FIRECRAWL_API_KEY` |
 | `builtin:tavily` | `https://api.tavily.com/search`，`X-Tavily-Access-Mode: keyless` | 同址 REST；`TAVILY_API_KEY` |
 | `builtin:tinyfish` | `https://agent.tinyfish.ai/mcp`，`search`，`X-TinyFish-Access-Mode: keyless` | `https://api.search.tinyfish.ai`，GET；`TINYFISH_API_KEY` |
+| `builtin:openalex` | `https://api.openalex.org/works`，GET，不发 Authorization | 同址 REST，Bearer Token；`OPENALEX_API_KEY` |
+| `builtin:semanticscholar` | 不支持匿名（公共 IP 限流）；须配置 API Key | `https://api.semanticscholar.org/graph/v1/paper/search`，GET，`x-api-key`；`SEMANTIC_SCHOLAR_API_KEY` |
 | `builtin:session-model` | 不支持匿名；跟随当前实际 agent 模型 | `llm-pi-ai` 对应 provider 的显式 `apiKeyEnv` |
 
 免 Key 是上游公共访问能力，不是无限额度、服务可用性或永久免登录承诺。IP、地区、额度、服务策略均可能导致拒绝。设置页显示“已配置 / 免 Key”仅说明本地条件满足，不会发网络请求测试供应商。
@@ -48,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 白名单
@@ -74,6 +78,13 @@ web-search-enhanced:
 | Tinyfish | `language` | 2–3 个英文字母，可带连字符及 2–4 个字母后缀 |
 | Tinyfish | `purpose` | 1–2000 字符，不含 U+0000–U+001F |
 | Tinyfish | `domain_type` | `web`、`news`；个人 Key 另可用 `research_paper` |
+| OpenAlex | `sort` | 单个或逗号分隔的多个 `字段:asc` 或 `字段:desc`，如 `cited_by_count:desc` 或 `publication_year:desc,cited_by_count:desc` |
+| OpenAlex | `filter` | 1–500 字符，如 `publication_year:2024` |
+| OpenAlex | `is_oa` | 布尔（自动合并至 filter，如 `is_oa:true`） |
+| OpenAlex | `mailto` | 合法电子邮箱，用于加入 OpenAlex 礼貌池（Polite Pool）享受更快更稳定的响应，缺省使用插件公共标识邮箱 |
+| Semantic Scholar | `year` | 年份或年份范围，如 `2024` 或 `2020-2024` |
+| Semantic Scholar | `fieldsOfStudy` | 学科分类，如 `Computer Science,Physics` |
+| Semantic Scholar | `publicationTypes` | 出版类型，如 `JournalArticle,Conference` |
 
 Exa 免 Key 仅接收查询与数量，非空 options 会被拒绝。Tinyfish 免 Key 查询上限 2000 字符，不能使用 `research_paper`。Firecrawl 查询上限 500 字符，其他结构化 REST 查询上限 10000 字符。数量由工具请求和适配器控制，不能在 options 设置 `limit`、`numResults`、分页或缓存字段。Tavily 请求数量上限 20，Firecrawl/Exa REST 上限 100；Tinyfish 使用单页结果，本地按请求数量裁剪。不自动重试或翻页。
 
@@ -81,7 +92,7 @@ Exa 免 Key 仅接收查询与数量，非空 options 会被拒绝。Tinyfish
 
 实时性指**内容缓存 / 抓取偏好**，不是发布日期过滤，也不证明页面内容确实最新。它在当前会话持久保存，切换连接保留，fork 复制父会话当前值后独立。连接和实时性共用 revision，多标签页冲突需刷新后重试。请求开始后修改设置不改变该请求已冻结的路由与偏好。
 
-| 模式 | Firecrawl（两种访问方式） | Exa 个人 Key | Exa 免 Key、Tavily、Tinyfish、模型 |
+| 模式 | Firecrawl（两种访问方式） | Exa 个人 Key | Exa 免 Key、Tavily、Tinyfish、OpenAlex、Semantic Scholar、模型 |
 | --- | --- | --- | --- |
 | `auto` 自动 | 默认搜索策略 | 默认内容策略 | 默认行为 |
 | `fresh` 优先新鲜 | `scrapeOptions.maxAge=86400000` 毫秒 | `contents.maxAgeHours=24` 小时 | 忽略该偏好，不猜测上游参数 |
@@ -100,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。
@@ -119,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 约束。支持协议和路径：
@@ -163,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。只在缺省协议 / 地址时尝试只读模型目录补齐。
@@ -191,7 +205,7 @@ web-search-enhanced:
 | `WEB_PROVIDER_ACCESS_ERROR` | 上游访问 / 计费限制（如 HTTP 402），检查账户 |
 | `WEB_PROVIDER_RATE_LIMITED` | HTTP 429 等限流；等待并检查额度，不自动重试或转付费 |
 | `WEB_SEARCH_FOLLOW_UNSUPPORTED` | 检查 provider 协议、地址、显式 apiKeyEnv、模型能力；必要时用固定连接 |
-| `WEB_SEARCH_MIGRATION_REQUIRED` | 按升级指南显式导入旧配置 |
+| `WEB_SEARCH_MIGRATION_REQUIRED` | 自动迁移未完成；检查宿主日志、旧配置与 DSH Credentials 权限后重启插件 |
 | `WEB_SEARCH_CONFIG_INVALID` | 检查未知字段、options、信任确认及引用格式；禁用连接也必须配置合法 |
 | `WEB_SEARCH_STORAGE_UNAVAILABLE` | 检查 DSH storage-domain 及持久后端；恢复后下一请求会重试 |
 | `WEB_SEARCH_CONTEXT_UNAVAILABLE` | 缺少真实请求执行上下文；发起新的模型请求，不在工具参数伪造 Session |

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

@@ -1,4 +1,4 @@
-# 0.1.1 当前架构与实现边界
+# 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.1。内置目录只做默认值；用户保存差异，不把目录整表复制到用户层。四种结构化内置连接默认 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 已完成。
@@ -30,51 +30,30 @@ dsh plugin --profile web add dsh-web-search-enhanced@0.1.0
 
 升级含服务端与客户端契约变更。重新加载插件或重启 DSH，**然后刷新 Web 页面**；只刷新浏览器不足以更新服务端。此操作可能影响运行中任务，应在合适时机进行。
 
-## 3. 显式导入旧配置与自动迁移脚本
+## 3. 启动时自动迁移旧配置
 
-针对老用户的历史配置，插件提供两种迁移方式：**Web 设置页导入**与**命令行自动迁移脚本**。
+插件不再自行注册 Settings section 或直接改写 settings.yaml。DSH 0.1.7 在 Loader 就绪后将旧 settings.yaml 重命名为 settings.yaml.imported，并尝试导入到 profile 条目；插件监听该条目的表单 / volatile 更新，再迁移成 V2 连接结构。保存使用 revision CAS，不能覆盖并发编辑。新旧宿主的配置持久化架构不同，不应只修改版本号或复制整份旧 YAML 到 profile。未完成迁移时搜索 fail-closed，普通聊天不因此被替换或阻断。
 
-### 方式一：命令行自动迁移脚本（推荐）
+自动迁移覆盖以下旧字段：
 
-针对已有部署或自动化环境，插件提供了针对老用户的自动迁移脚本。该脚本会自动检测 DSH `settings.yaml`，备份原文件，将遗留的 JSON / flow-style 格式转换为标准 DSH YAML 块级缩进格式，并完成 v1 到 v2 模型的无缝迁移：
+- 固定路由字段：`modelMode`、`protocol`、`baseURL`、`model`、`apiKeyEnv`；
+- 旧模型与搜索选项：`fallbackModel`、`apiVersion`、`toolIdentifier`、`maxTokens`、`maxUses`、`chatSearchMode`、`searchContextSize`；
+- 明文 `apiKey` 会先尝试写入 DSH Credentials，随后从配置迁移数据中剥离。
 
-```sh
-# 预览迁移效果（不修改文件）
-node scripts/migrate-config.mjs --dry-run
-
-# 执行自动迁移（自动备份原文件为 .bak）
-pnpm run migrate
-# 或
-node scripts/migrate-config.mjs
-```
-
-脚本特性：
-- **安全备份**：在对配置文件做任何修改前，自动创建 `.bak` 备份文件。
-- **YAML 格式规范化**：自动修复此前设置页或外部写入产生的 JSON 行内花括号 (`flow-style`)，统一输出为符合 DSH 原生规范的标准块级 YAML。
-- **旧版路由迁移**：自动将旧版 `modelMode: configured` 转换为 `custom:legacy`，或将 `modelMode: current-session` 转换为 `builtin:session-model`。
-- **凭据安全保护**：若旧配置存在明文 `apiKey`，脚本会明确告警并将其从公开配置中剥离，提示移入 DSH Credentials。
+迁移规则：
 
-### 方式二：Web 界面显式导入
-
-打开设置 → 插件 → Web Search Enhanced。检测到旧 `modelMode/protocol/baseURL/model/apiKeyEnv` 且未标记 version 2 时，显示导入入口。搜索返回 `WEB_SEARCH_MIGRATION_REQUIRED` 是保护措施，不会静默选新默认替代旧路由。
-
-导入前核对 endpoint 与凭据归属，点击“导入旧配置（不迁移或删除 Key）”：
-
-| 旧配置 | 0.1.0 结果 |
+| 旧配置 | V2 结果 |
 | --- | --- |
-| `modelMode: configured` 或固定配置 | 新增 `custom:legacy` 固定模型，设为新会话默认 |
+| `modelMode: configured` 或固定配置 | 新增 `custom:legacy` 固定模型连接并设为默认 |
 | `modelMode: current-session` | 新会话默认设为 `builtin:session-model` |
-| `protocol/model/baseURL/apiKeyEnv` | 转为固定连接 binding 的 `protocol/model/baseURL/credentialRef` |
-| 模型高级选项 | 固定模式导入到 options；跟随模式按需重新配置 optionsByProtocol |
-| `fallbackModel` | 不执行，不变成备用连接 |
-| 非空 `apiKey` | 拒绝导入，须先移入 Credentials |
-| 已有 `custom:legacy` | 固定模式拒绝覆盖；先重命名已有连接或手动选择其他 ID |
-
-固定模式缺省值沿用旧导入器约定：`anthropic-messages`、`deepseek-flash`、`https://api.deepseek.com/anthropic/v1`、`WEB_SEARCH_ENHANCED_API`。它们不是新的自动 fallback；必须确认目标真实支持搜索。导入器将旧地址标为 trustedEndpoint，因此点击前应检查目标，不能把导入当作安全认证。
+| `protocol/model/baseURL/apiKeyEnv` | 转为固定连接 binding 的对应字段 |
+| 模型高级选项 | 固定模式导入到连接 `options` |
+| `fallbackModel` | 不执行，不转换为备用连接 |
+| 非空 `apiKey` | 仅在 Credentials 写入成功后继续迁移；失败则保持 fail-closed |
 
-UI 以 Settings revision 写入转换结果，并清理用户层的旧路由字段；继承层原配置可能仍保留。导入函数本身只生成对象，不写配置或读取秘密。不要手工仅补 `version: 2` 来“消除错误”，那不会转换旧路由。
+自动迁移不会覆盖已有会话的搜索选择，也不会自动切换新连接。迁移完成后请重新加载插件或重启 DSH，再刷新 Web 页面；已有会话如需使用迁移后的连接，应在会话搜索选择器中显式选择。
 
-**导入只改新会话默认，不覆盖已有会话选择。** 导入后请在已有会话里显式选 `custom:legacy` 或跟随会话模型；新建会话检查默认是否符合预期。多窗口编辑冲突时刷新后重试。
+如果迁移失败，请检查 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)。