dsh-web-search-enhanced 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -4,6 +4,39 @@
 
 ## [Unreleased]
 
+## [0.1.8] - 2026-10-12
+
+### 窄输入栏适配
+
+- 选择器只剩图标时同时去掉下拉箭头，改为与原生图标按钮一致的 28px 方形按钮；保存成功 / 错误标记改为角标，不再撑宽按钮。
+- 输入栏连图标都放不下、控件即将被挤到下一行时，选择器自动让出位置；空间足够时自动重新出现。判断基于实际渲染的控件是否同处一行，并先等待 DSH 收起模型名，不使用固定像素阈值；恢复前以同步探测确认放得下，同宽度下连续反复时需再放宽 4px 才重试，避免来回闪。
+- 出错、保存中、面板打开或所选连接不可用时始终显示选择器，宁可换行也不隐藏需要处理的状态；“关闭”属于主动选择，允许隐藏。
+- 新增 `/setup-search` 指令：在输入框中弹出当前会话的搜索连接与实时性选项，与选择器共用会话选择与缓存；选择器被隐藏时也能切换，切换后输入栏中的选择器同步刷新。
+- 新增 `showSelector` 配置（设置页“在输入栏显示搜索连接选择器”，默认开启），可完全隐藏输入栏中的选择器，改用 `/setup-search`。
+- 跟随 dsh-mobile 0.6.3+ 的 flex 工具栏，移除旧网格布局下的规则：分组换行和 44px 触控尺寸由 dsh-mobile 负责，宽度上限改到按钮本身，标签在 dsh-mobile 允许按钮换行时仍保持单行省略；手机页同样会在放不下时让出选择器位置。
+- 新增 `scripts/check-composer-fit.mjs` 隔离浏览器检查（桌面与 dsh-mobile 布局）及对应单元测试。
+
+### 升级说明
+
+- 包版本推进为 0.1.8；配置 version 2、会话 Storage Domain version 1、DSH 0.2.0-rc.2 基线和搜索行为均不变，无需迁移。新增的 `showSelector` 为可选字段，缺省等同开启。
+- 升级方式同前：备份后移除旧插件再安装新包，重载服务端插件并刷新 Web 页面。使用手机页时建议配合 dsh-mobile 0.6.3 及以上版本。
+
+## [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 兼容性

package/README.md

@@ -63,16 +63,16 @@
 - **DeepSeek Harness**：≥ `0.2.0-rc.2`
 - **Node.js**：`^22.19.0 || >=24.0.0`
 
-本版将 DSH 基线提升到 0.2.0-rc.2，保留动态配置、插件设置页和会话 projection 架构，无需新的配置或存储迁移。跟随模型仍要求 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 和旧设置。
+本版沿用 DSH 0.2.0-rc.2 基线，改进窄输入栏中的会话搜索选择器：空间不足时先收成 28px 图标，仍放不下时暂时让位，避免输入栏控件被挤到第二行（含 dsh-mobile 0.6.3+ 手机页）；新增 `/setup-search` 指令和“在输入栏显示搜索连接选择器”开关。配置格式、会话存储和搜索行为均不变（配置版本机制见[配置版本设计](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.6**，最低支持 **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` 自行构建。使用绝对路径安装：
+当前版本为 **0.1.8**，最低支持 **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.6.tgz
+dsh plugin --profile web add /path/to/dsh-web-search-enhanced-0.1.8.tgz
 ```
 
 **方式 B：通过 npm 在线安装**
@@ -80,10 +80,10 @@ dsh plugin --profile web add /path/to/dsh-web-search-enhanced-0.1.6.tgz
 该版本发布到 npm 后，也可直接安装：
 
 ```sh
-dsh plugin --profile web add dsh-web-search-enhanced@0.1.6
+dsh plugin --profile web add dsh-web-search-enhanced@0.1.8
 ```
 
-已安装旧版时，DSH rc.2 不支持直接自动升级：先备份配置和存储，再通过插件管理器移除旧版并安装 0.1.6，核对 profile 补丁与会话选择。Desktop profile 需先启动过一次桌面端。完整步骤见[升级指南](docs/migration.zh-CN.md)。
+已安装旧版时，DSH rc.2 不支持直接自动升级：先备份配置和存储，再通过插件管理器移除旧版并安装 0.1.8，核对 profile 补丁与会话选择。Desktop profile 需先启动过一次桌面端。完整步骤见[升级指南](docs/migration.zh-CN.md)。
 
 ### 步骤 2：生效与刷新
 
@@ -158,7 +158,7 @@ _注：实时抓取可能会稍微增加检索耗时与额度消耗；对于不
 <summary><b>Q1: 搜索时提示 <code>WEB_SEARCH_NOT_SELECTED</code>？</b></summary>
 
 **原因**：当前会话没有选定任何搜索连接。  
-**解决办法**：在输入框右侧工具栏点击搜索图标/胶囊，在弹出的菜单中勾选任意一个搜索服务（如 Exa 或 Firecrawl）；或者在插件设置中为“新会话默认连接”指定一个默认引擎。
+**解决办法**：在输入框右侧工具栏点击搜索图标/胶囊（或在输入框输入 `/setup-search`），在弹出的菜单中勾选任意一个搜索服务（如 Exa 或 Firecrawl）；或者在插件设置中为“新会话默认连接”指定一个默认引擎。
 </details>
 
 <details>
@@ -190,7 +190,14 @@ _注：实时抓取可能会稍微增加检索耗时与额度消耗；对于不
 </details>
 
 <details>
-<summary><b>Q5: 如何从 0.0.x 旧版本平滑升级？</b></summary>
+<summary><b>Q5: 窗口很窄时，输入框里的搜索图标不见了？</b></summary>
+
+**原因**：输入栏放不下所有控件时，插件会先把选择器收成图标；连图标也放不下时，为避免控件被挤到第二行，选择器会暂时隐藏（桌面与手机页相同）。若在设置中关闭了“在输入栏显示搜索连接选择器”（`showSelector: false`），选择器始终不显示。当前会话的搜索设置不受影响，照常生效。  
+**解决办法**：在输入框输入 `/setup-search`，即可切换当前会话的搜索连接与实时性；把窗口或侧栏拉宽一点，图标也会自动回来。出错、正在保存或所选连接不可用时，选择器始终显示。
+</details>
+
+<details>
+<summary><b>Q6: 如何从 0.0.x 旧版本平滑升级？</b></summary>
 
 升级后重新加载插件或重启 DSH，插件会在启动时自动检测并迁移旧版全局模型配置；迁移成功后映射为新版连接配置。若出现迁移错误，请检查宿主日志、DSH Credentials 权限和旧配置，再重启插件。详细注意事项请参阅 📖 [升级指南](docs/migration.zh-CN.md)。
 </details>

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,6 +1,8 @@
-# 0.1.6 配置参考
+# 0.1.8 配置参考
 
-本指南面向安装版插件。包版本为 **0.1.6**，配置格式的 `version` 为 **2**；两者不是同一版本号。快速开始见 [README](../README.md)，旧版用户先读[升级指南](migration.zh-CN.md)。
+本指南面向安装版插件。包版本为 **0.1.8**，配置格式的 `version` 为 **2**；两者不是同一版本号。快速开始见 [README](../README.md)，旧版用户先读[升级指南](migration.zh-CN.md)。
+
+配置版本判定、兼容策略和后续迁移开发方式见[配置版本设计](config-versioning.zh-CN.md)。`version: 1` 会自动迁移；高于当前版本或非法版本会被拒绝，绝不自动降级。
 
 ## 配置入口与作用范围
 
@@ -21,6 +23,7 @@
 | `version` | `2`；纯新配置可省略 | 显式标记当前配置格式；旧路由必须导入，不能只改版本绕过迁移 |
 | `defaultConnection` | 非空连接 ID；解析器不设默认 | 仅初始化没有持久选择的会话。安装补丁显式设为 `builtin:exa` |
 | `freshness` | `auto` / `fresh` / `realtime`；`auto` | 新会话默认实时性；旧记录缺少此字段时首次读取补入一次 |
+| `showSelector` | 布尔；`true` | 是否在输入栏显示会话搜索选择器。关闭只影响显示：搜索仍按会话选择执行，可在输入框用 `/setup-search` 切换当前会话的连接与实时性。开启时选择器在输入栏放不下时也会自动让位 |
 | `connections` | ID → 配置对象；空覆盖 | 内置连接的差异或完整自定义连接 |
 
 未设默认连接时，只有恰好一个本地可用连接才自动选中，否则保持未选择。不要依赖目录顺序。显式默认 ID 不会自动修复为其他连接；请确保它存在、未禁用且凭据可用。已有会话保存的连接（包括未选择）不随默认改变。

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

@@ -1,4 +1,4 @@
-# 0.1.6 当前架构与实现边界
+# 0.1.8 当前架构与实现边界
 
 本文描述已存在的源码契约，不是未来设计提案或历史验收记录。为避免外部链接失效，保留原文件名。用户配置见[配置参考](configuration.zh-CN.md)，验证方法见[开发验证指南](v2-implementation.zh-CN.md)。
 
@@ -41,12 +41,14 @@ tools/execute 的 exec.agent → 私有 AsyncLocalStorage → enhanced-search
 | [src/remote-contract.ts](../src/remote-contract.ts) | 严格 Remote 请求 / 响应 schema 与调用描述符 |
 | [src/client/V2Settings.tsx](../src/client/V2Settings.tsx) | ConfigForm hooks 注入、当前连接设置界面和稀疏操作 |
 | [src/client/SearchConnectionSelector.tsx](../src/client/SearchConnectionSelector.tsx) | 当前会话连接与实时性选择器 |
+| [src/client/crowded-row.ts](../src/client/crowded-row.ts) | 输入栏拥挤时让出选择器位置的布局观察（L3） |
+| [src/client/search-command.ts](../src/client/search-command.ts) | `/setup-search` 指令：当前会话连接与实时性的弹出选择 |
 
 `model-config.ts`、`provider.ts` 的 `createProvider` / `EnhancedSearchProvider` 是兼容固定配置辅助接口；安装版始终走 V2 bridge。旧辅助代码中的环境变量或 fallback 行为不能外推为安装版配置能力。
 
 ## 3. 配置和秘密分离
 
-当前设置格式为 version 2，包版本为 0.1.6。内置目录只做默认值；用户保存差异，不把目录整表复制到用户层。四种结构化内置连接默认 keyless，访问方式为显式选择，不根据已保存 Key 猜测。自定义连接只允许支持的 adapter 或固定模型协议；新 endpoint 需要信任确认。
+当前设置格式为 version 2，包版本为 0.1.8。内置目录只做默认值；用户保存差异，不把目录整表复制到用户层。四种结构化内置连接默认 keyless，访问方式为显式选择，不根据已保存 Key 猜测。自定义连接只允许支持的 adapter 或固定模型协议；新 endpoint 需要信任确认。
 
 内置结构化连接不能重定向地址或改变 adapter。自定义结构化连接只能使用个人 Key；固定模型总是需要显式信任。校验拒绝任意 headers/body、缓存参数、秘密字段等不受支持的 options。禁用连接也参与配置校验。
 
@@ -112,8 +114,12 @@ Firecrawl 的 fresh/realtime 映射为内联 scrapeOptions.maxAge（86400000 / 0
 
 ## 9. 客户端与非目标
 
-设置使用官方 `plugins.bundle.config` 槽（key 为包名）和 ConfigForms / ConfigForm 路径操作，`whileServed` 管理宿主表单上下线；只向渲染器传递 hooks source 和绑定回调，不直接传入服务对象。`mutate` 返回 false 时保留草稿，不显示保存成功；凭据使用宿主 Remote。会话选择器用标准 `useProjection("modelSelection")` 订阅模型变更，移除 sessions unknown / binding 猜测；通过 `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 / 模型槽，不读取输入内容。
 
 选择器只列本地可用连接并隐藏空组，但保留不可用的当前选择以供显式修复；使用原生 popover、键盘导航、Esc 与焦点恢复。主题使用宿主 `--dsw-alias-*` 令牌。空白会话首消息前没有独立选择器，靠默认连接初始化。
 
+窄宽度按级降级：先隐藏实时性，再随 DSH `data-model-compact` 只留图标；图标态去掉箭头，保持 28px 原生图标尺寸，状态标记改为角标（L2.5）。DSH 的输入栏在连图标都放不下时会让控件换行，dsh-mobile 也按设计分组换行；选择器在此之前让位（L3）：从稳定属性 `[data-composer-card]` 定位控制行，ResizeObserver 触发时检查行内已渲染按钮（排除弹层）是否同处一行，而不是按宽度相加——dsh-mobile 的伸展分组只报告填充后宽度。控制行尚未 compact 时先等宿主一帧。隐藏用 `hidden` 属性，宿主观察器据此重新测量；恢复前在同一同步任务内临时设置 `data-model-compact` 并取消隐藏，检查是否同处一行后立即撤销，不产生绘制。若刚恢复就在相同宽度再次换行，需再放宽 4px 才重试，防止来回切换。出错、保存中、面板打开或连接不可用时固定显示；activity 隐藏控件组时不处理。手机页沿用 dsh-mobile 0.6.3+ 的 flex 分组换行和 44px 触控尺寸，插件只限制按钮最大宽度并保持标签单行。
+
+`/setup-search` 通过可选注入的 `commandUi` 注册 popupSelect：选项与选择器面板一致（关闭、模型搜索、搜索服务；未关闭时追加实时性），经同一 SelectionClient 以观察到的 revision 写入，失败抛出让弹层显示错误；成功后 `announce` 通知同一会话的选择器从共享缓存重读。`showSelector: false` 时选择器条目渲染为空（加载中或设置不可用时仍显示），指令不受影响。
+
 本版本不修改 DSH 宿主、不新增任意 HTTP 路由、不维护用户自建密钥文件、不绕过上游限制、不保证匿名服务随时可用。隔离渲染和测试 harness 不等于运行中 GUI 已重新安装；发布 / 部署验证须另行执行并如实记录。

package/docs/migration.zh-CN.md

@@ -1,6 +1,6 @@
-# 升级到 0.1.6 / DSH 0.2.0-rc.2
+# 升级到 0.1.8 / DSH 0.2.0-rc.2
 
-0.1.6 将最低宿主版本提高为 **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.2.0-rc.2 影响评估](upstream-0.2.0-rc.2-assessment.zh-CN.md)。旧版已采用的**会话级搜索连接**保持不变：包版本 0.1.6、设置格式 version 2、会话 Storage Domain version 1 是三个不同概念。完整参数见[配置参考](configuration.zh-CN.md)。
+0.1.8 沿用最低宿主版本 **0.2.0-rc.2**，沿用 0.1.3 已完成的 Loader 动态配置、profile-backed SettingsForms、ConfigForms 客户端、惰性 Typert codec 和新版 PTC 适配，以及 0.1.7 的配置版本识别与逐版本迁移。从 0.1.3 – 0.1.7 的 V2 配置升级不需要新的配置或存储格式转换；本版改进客户端选择器的窄宽度布局与 dsh-mobile 适配，新增 `/setup-search` 指令与可选的 `showSelector` 配置（缺省开启）；详见 [0.2.0-rc.2 影响评估](upstream-0.2.0-rc.2-assessment.zh-CN.md)。旧版已采用的**会话级搜索连接**保持不变：包版本 0.1.8、设置格式 version 2、会话 Storage Domain version 1 是三个不同概念。完整参数见[配置参考](configuration.zh-CN.md)。
 
 ## 1. 升级前准备
 
@@ -16,26 +16,28 @@ DSH rc.2 对已安装插件不支持直接自动升级。先完成备份、停
 
 若跟随 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.6 构建包。使用绝对路径交给 DSH 插件管理器：
+从当前源码运行 `pnpm install --frozen-lockfile && pnpm run check && pnpm pack`，或使用 [Releases](https://github.com/Yurzi/dsh-web-search-enhanced/releases) 中实际发布的 0.1.8 构建包。使用绝对路径交给 DSH 插件管理器：
 
 ```sh
-dsh plugin --profile web add /absolute/path/to/dsh-web-search-enhanced-0.1.6.tgz
+dsh plugin --profile web add /absolute/path/to/dsh-web-search-enhanced-0.1.8.tgz
 ```
 
 若该版本已在 npm 发布，也可安装固定版本：
 
 ```sh
-dsh plugin --profile web add dsh-web-search-enhanced@0.1.6
+dsh plugin --profile web add dsh-web-search-enhanced@0.1.8
 ```
 
 发布附件中的构建 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，普通聊天不因此被替换或阻断。
 
 自动迁移覆盖以下旧字段：
@@ -88,6 +90,7 @@ dsh plugin --profile web add dsh-web-search-enhanced@0.1.6
 4. 在设置中确认实际访问方式和凭据引用，不以 UI“已配置”替代真实授权测试。
 5. 仅在你允许外发查询 / 可能产生费用时，使用一个公开、非敏感词进行搜索，核对返回来源和错误类型；不要把私有文档发送给新供应商做测试。
 6. 验证 web_fetch 仍由预期 provider 处理，普通对话模型没有被搜索设置替换。
+7. 逐步拉窄窗口或侧栏：选择器先收成无箭头的图标，再放不下时暂时隐藏，输入栏控件不换行；放宽后自动恢复。出错、保存中或所选连接不可用时选择器保持显示。手机页（dsh-mobile）行为相同。在输入框输入 `/setup-search`，确认能切换当前会话的连接与实时性，且输入栏中的选择器随之更新。
 
 详细故障表见[配置参考](configuration.zh-CN.md)。发布前自动测试通过不等于你的实例已安装，也不保证当前出口 IP 的匿名访问可用。
 

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

@@ -1,4 +1,4 @@
-# 0.1.6 开发与验证指南
+# 0.1.8 开发与验证指南
 
 本文件保留原路径以避免断链，内容改为可重复的开发、验证与交付方法。架构见[当前架构](design-v2.converged.zh-CN.md)，用户使用见[配置参考](configuration.zh-CN.md)，版本升级见[升级指南](migration.zh-CN.md)。测试存在、测试通过、供应商在线可用、运行实例完成部署是四种不同结论，不能互相替代。
 
@@ -6,7 +6,7 @@
 
 - Node.js：`^22.19.0 || >=24.0.0`；pnpm：按 packageManager 使用 `11.7.0`。
 - DSH：包要求 `>=0.2.0-rc.2`，源码以 0.2.0-rc.2 服务契约为基线。依赖声明与锁文件是构建依据，不修改宿主安装的依赖来让测试通过。
-- 当前开发主线为 `main`，旧版代码线为 `legacy/v0.0.x`。包版本 `0.1.6` 与 settings schema 的 `version: 2` 不同。
+- 当前开发主线为 `main`，旧版代码线为 `legacy/v0.0.x`。包版本 `0.1.8` 与 settings schema 的 `version: 2` 不同。
 
 在仓库根执行：
 
@@ -26,6 +26,7 @@ pnpm run check
 | `pnpm run build` | clean、声明 / TS 输出、服务端 ESM 与客户端 CJS bundle | 宿主已加载新 bundle |
 | `pnpm run verify:package` | 实际 pack 解包，必需产物及 patch 元数据 | npm 发布成功或线上安装成功 |
 | `node scripts/check-selector-ui.mjs` | 隔离 Chromium 中选择器交互和布局 | 运行中 DSH 会话 / Remote 的真实部署 |
+| `node scripts/check-composer-fit.mjs` | 隔离 Chromium 中按 DSH 输入栏结构的窄宽度降级（L2.5 / L3），桌面与 dsh-mobile 布局 | 真实 DSH 输入栏或其他插件组合的实际宽度 |
 | `node scripts/preview-ui.mjs` | 构建后生成设置组件静态 HTML | 交互、服务端或真实 GUI |
 
 verify-package 会临时打包并检查 `lib/index.js`、`lib/client.js`、`lib/types/index.d.ts`、`cordis.patch.yml`，随后删除临时包与解包目录。它内部优先 pnpm pack，失败才尝试 npm pack，不等于发布 registry。
@@ -58,6 +59,8 @@ node scripts/verify-package.mjs
 | [plugin.spec.ts](../tests/plugin.spec.ts)、[bundle.spec.ts](../tests/bundle.spec.ts)、[egress.spec.ts](../tests/egress.spec.ts) | 插件导出、bundle / patch 契约、fetchProvider 不受干扰、出站 transport |
 | [v2-client.spec.ts](../tests/v2-client.spec.ts) | 当前设置辅助逻辑、稀疏写入、凭据独立操作与多语言对齐 |
 | [settings-render.spec.ts](../tests/settings-render.spec.ts)、[selector-render.spec.ts](../tests/selector-render.spec.ts) | SSR 结构、折叠态、紧凑选择器、不可用项与状态 |
+| [crowded-row.spec.ts](../tests/crowded-row.spec.ts)、[selector-crowding.spec.ts](../tests/selector-crowding.spec.ts) | 拥挤输入栏让位：按渲染几何判断一行、等待宿主 compact、探测不残留属性、同宽反复的退避、固定显示状态、activity 不处理 |
+| [search-command.spec.ts](../tests/search-command.spec.ts)、[selector-display.spec.ts](../tests/selector-display.spec.ts) | `/setup-search` 选项与写入、跨视图刷新、`showSelector` 显示开关 |
 | [client-injection.spec.ts](../tests/client-injection.spec.ts) | Remote 命名空间注入顺序和生命周期 |
 
 修改某层时至少运行对应测试，并补负向用例。例如新增供应商不能只测成功响应，还需检查访问方式互斥、无付费回退、取消、限流、安全错误和设置冻结。修改 Remote 字段应一起更新服务端 schema、客户端调用与真实宿主测试，不能只让 SSR 通过。
@@ -71,6 +74,10 @@ CHROMIUM=/absolute/path/to/chromium node scripts/check-selector-ui.mjs
 # 仅在明确需要更新仓库预览资产时：
 node scripts/check-selector-ui.mjs --screenshots
 
+# 窄宽度降级与 dsh-mobile 布局（截图写到指定目录，不改仓库资产）：
+node scripts/check-composer-fit.mjs
+node scripts/check-composer-fit.mjs --screenshots .dsh-smoke-home/composer-fit
+
 # 先构建，再生成静态设置预览：
 node scripts/preview-ui.mjs
 node scripts/preview-ui.mjs --dark
@@ -78,6 +85,8 @@ node scripts/preview-ui.mjs --dark
 
 选择器脚本启动隔离 Chromium 和临时 profile，以模拟 Remote 运行组件；不连接或修改已有 DSH 会话。默认检查桌面、390px 窄屏、深色模式。`--screenshots` 会写预览图片，文档任务若未获资产修改范围不应使用。脚本使用本地 headless 浏览器参数，包括 `--no-sandbox`；仅在可信隔离开发环境运行。
 
+check-composer-fit 按 DSH `observeControlRow` 与 InputBar 样式搭建输入栏夹具，逐像素收窄 / 放宽，验证：可见选择器从不与换行同时出现、图标态为 28px 且无箭头、先 compact 再隐藏、隐藏 / 恢复各只切换一次且放得下即恢复、边界处无来回切换、错误 / 保存中 / 连接不可用时固定显示；再套用 dsh-mobile 0.6.4 工具栏样式重复收窄 / 放宽，验证手机页同样先让位、44px 触控尺寸与单行标签。夹具宽度不等于真实安装中其他插件的组合宽度。
+
 preview-ui 写 `.dsh-smoke-home/settings-preview.html`，不会启动第二个 DSH 服务。静态预览 / 截图仅供布局审阅，不能证明设置保存、服务端更新或用户机器的实际挂载。
 
 设置预览与选择器浏览器检查共用 `scripts/fixtures/dsh-theme.css`，其中记录 DSH 官方主题变量快照及来源提交。运行时仍直接继承宿主主题，不打包该快照；对齐新版主题时同步更新此文件，避免手写预览配色掩盖深色模式或按钮对比度问题。
@@ -101,7 +110,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.6.tgz` 安装 Release 构建附件。
+3. 用户可用 `dsh plugin --profile web add /absolute/path/to/dsh-web-search-enhanced-0.1.8.tgz` 安装 Release 构建附件。
 4. Git 操作、远端分支调整、标签、Release 和 npm 发布分别需要授权与结果核验；不要把本地构建当作已发布。主线为 main，旧代码保留 legacy/v0.0.x，不需要把历史文档反复改成当前成功记录。
 5. 标签触发发布流程后，单独确认 workflow 和 npm registry 的版本 / 包内容，再宣称 npm 可安装。