# dsh-web-search-pool 升级与回滚指南

> 本文档描述从 0.2.x（rc.6 时代）升级到 0.1.0-rc.7（rc.7 Bundle 原生）的过程。

## 从 0.2.x 升级到 0.1.0-rc.7

### 升级前备份

```bash
# 备份 profile 关键文件
cp $DSH_HOME/profiles/web/package.json $DSH_HOME/profiles/web/package.json.bak
cp $DSH_HOME/profiles/web/cordis.patch.yml $DSH_HOME/profiles/web/cordis.patch.yml.bak
cp $DSH_HOME/profiles/web/settings.yaml $DSH_HOME/profiles/web/settings.yaml.bak
```

### 升级步骤

1. **停止当前 DSH Web 进程**

2. **删除旧 profile patch 中手工插入的 web-search-pool row**
   - 检查 `$DSH_HOME/profiles/web/cordis.patch.yml`
   - 删除其中 `web-search-pool` 相关的 insert 行
   - 0.1.0-rc.7 Bundle 是唯一 provider row 来源

3. **删除旧的 WEB_SETTINGS_NAMESPACES patch 逻辑**
   - 不再运行 `node scripts/patch-api-proxy-namespace.mjs`
   - rc.7 自动暴露已注册的 Settings namespace

4. **安装 0.1.0-rc.7 tarball**

```bash
dsh plugin --profile web add <path>/dsh-web-search-pool-0.1.0-rc.7.tgz
```

5. **检查 `dsh.profile.bundles` 是否出现 `dsh-web-search-pool`**

6. **检查用户 patch 没有重复 `web-search-pool`**
   - 若存在重复 entry，删除旧手工 row

7. **执行配置验证**

```bash
dsh --profile web --dump-config
```

   期望看到 `include:web` 的 `searchProvider = search-pool`

8. **启动 DSH Web**

9. **刷新页面并确认插件卡片**
   - 设置页出现「搜索 Key 池」卡片
   - 卡片 key 为 `web-search-pool`

10. **使用测试 key 执行一次真实搜索**

## 重复挂载防护

Bundle patch 和用户手工 patch 同时存在时，可能导致：

- duplicate provider id
- duplicate Settings namespace
- keyed slot 重复 key

**规则**：

- 0.1.0-rc.7 Bundle 是唯一 provider row 来源
- profile `cordis.patch.yml` 只保存用户配置覆盖，不再 insert 同名 provider
- 如果用户保留旧手工 row，启动应 fail loud，文档提供删除旧 row 的步骤

## 回滚

### 方式一：回退 npm 包版本

```bash
dsh plugin --profile web remove dsh-web-search-pool
dsh plugin --profile web add <old-package.tgz>
```

### 方式二：暂时禁用 Bundle row

不推荐直接编辑 shipped patch；可在 profile/home 用户 patch 中覆盖：

```yaml
- id: web
  config:
    searchProvider: deepseek-official
```

> 注意：如果 provider Bundle 仍注册，未使用的 provider 仍可能出现在注册表中；长期回滚应移除 Bundle dependency。

## 失败更新语义

如果新版本启动失败：

- DSH loader 应 fail loud
- 不自动修改旧 DSH 安装目录
- 保留 profile package/lock 备份
- 根据错误判断是 package resolve、client bundle、Settings schema、slot 或 provider apply 失败
- 修复后重新 pack 安装

## 故障排查

| 现象 | 判断 | 处理 |
|---|---|---|
| Cannot find package dsh-web-search-pool | profile 依赖未安装 | 重新运行 `dsh plugin --profile web add` |
| dsh.bundle.patch 未识别 | package metadata 或 files 缺失 | 检查 package.json、重新 pack |
| provider duplicate | 旧 profile patch 仍 insert provider | 删除旧手工 row |
| keyed slot requires options.key | client 仍使用 id | 改为 `key: web-search-pool`，重启 DSH |
| 设置页没有卡片 | client 未构建/未被 graph 发现 | 查 package exports、dsh.client、Host loader 日志 |
| 仍走 deepseek-official | Bundle 未覆盖 web row | dump-config 检查 `include:web` |
| 点击刷新无变化 | Host 未重启或 tick 未触发 | 重启 DSH，检查 settings/updated 和 usageDiagnostic |