# 安装与升级

> 适用：`dsh-web-search-pool` ≥ 0.2.1；宿主 DeepSeek Harness 0.1.1-rc.x / 0.1.2+。
> 装配机制的源码依据见 [架构与机制](架构与机制.md)；机制结论均标注了调研日期。

## 1. 前置条件

- DeepSeek Harness 0.1.1-rc.x 或 0.1.2+（0.1.2 起 settings seam 与 Typert Remote 已适配）。
- `pnpm` 在 PATH 上：`dsh plugin` 是 pnpm 转发器，在 profile 目录执行 `pnpm add`。
- 至少一个搜索 key（Tavily / Exa）；Exa 也支持**匿名免费层**（不填 key 即可用，1 次/秒）。

## 2. 安装（官方方式）

### 2.1 tarball 安装（推荐）

```bash
# 项目目录打包
npm pack
# 装进 web profile（会把 dsh-web-search-pool 追加到 dsh.profile.bundles）
dsh plugin --profile web add ./dsh-web-search-pool-<version>.tgz
```

Windows PowerShell：

```powershell
dsh plugin --profile web add ".\dsh-web-search-pool-<version>.tgz"
```

### 2.2 开发期 link 安装

```bash
dsh plugin --profile web add link:<项目目录>
```

link 模式直接读源码，改完 `src/` 后必须**重启 DSH 进程**（刷新浏览器不加载新代码）；生产用 tarball。

## 3. 安装后验证

```bash
dsh --profile web --dump-config
# 期望（两处缺一不可）：
#   include:web                config.searchProvider: search-pool
#   include:web-search-pool    id: web-search-pool   name: dsh-web-search-pool
node -e "import('dsh-web-search-pool').then(m => console.log(m.name))"
```

## 4. 配置 API Key

设置 → 插件 → 「搜索 Key 池」卡片 → 添加 key（环境变量名 / 限流 RPM / 备注）→ 保存。

- 密钥只经 DSH credentials 服务保存，**不写入 settings.yaml 的非 secret 层**；也可用同名环境变量提供。
- Exa 的「环境变量名」留空即启用匿名免费层（全局 1 req/s，配置不可覆盖）。
- 卡片默认收起，已保存的 key 折叠为一行摘要（名称 / 额度 / 状态）。

## 5. 升级

### 5.1 升级前备份

```bash
cp $DSH_HOME/profiles/web/package.json   $DSH_HOME/profiles/web/package.json.bak
cp $DSH_HOME/profiles/web/pnpm-lock.yaml $DSH_HOME/profiles/web/pnpm-lock.yaml.bak
cp $DSH_HOME/profiles/web/settings.yaml  $DSH_HOME/profiles/web/settings.yaml.bak
```

### 5.2 升级步骤

1. 停掉 DSH Web 进程。
2. 检查 `$DSH_HOME/profiles/web/cordis.patch.yml`：**删除手工插入的 `web-search-pool` row**——插件自带的 Bundle 是 provider row 的唯一来源，重复会出现 duplicate provider。
3. 不要再运行 `node scripts/patch-api-proxy-namespace.mjs`：0.1.0-rc.7 起已注册的 settings namespace 由设置代理自动暴露（脚本仅作旧版诊断保留）。
4. 安装新包：`dsh plugin --profile web add <new>.tgz`。
5. 确认 `dsh.profile.bundles` 含 `dsh-web-search-pool`，且 profile patch 无重复 row。
6. `dsh --profile web --dump-config` 确认 `include:web` 的 `searchProvider: search-pool`。
7. 启动 DSH，刷新页面，确认设置页出现「搜索 Key 池」卡片（卡片 key = `web-search-pool`）。
8. 用真实 key 搜一次，并在卡片点「立即刷新」确认额度回写。

### 5.3 版本线说明

| 版本 | 宿主 | 关键变化 |
|---|---|---|
| 0.1.0-rc.7 | 0.1.0-rc.7 | 原生 Bundle（`cordis.patch.yml`）+ keyed slot（`key: web-search-pool`） |
| 0.2.0 | 0.1.2-rc.1 | `settings.installSection`、Typert Remote、`fetchProvider: http` 回补；旧符号动态导入回退 |
| 0.2.1 | 0.1.2-rc.1 | client 侧 `ctx.inject(["remote","remote.credentials"])` scoped 注入 |

同一份代码同时支持 0.1.1-rc.x 与 0.1.2+，升级宿主不必换插件版本。

## 6. 回滚

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

只想临时切回官方搜索：在 profile/home 用户 patch 覆盖 `web` row，不必卸载：

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

> 覆盖只改选择，provider 仍在注册表中；长期回滚请移除 Bundle 依赖。

## 7. 失败更新语义

- loader 对装配失败 **fail loud**，不会自动改 DSH 安装目录。
- 保留 profile 的 package.json / pnpm-lock.yaml 备份，按报错定位是 package resolve、client bundle、settings schema、slot 还是 provider apply 失败。
- 修复后重新 `npm pack` + 安装。

## 8. 卸载

```bash
dsh plugin --profile web remove dsh-web-search-pool
```

## 9. 故障排查

| 现象 | 判断 | 处理 |
|---|---|---|
| `Cannot find package dsh-web-search-pool` | profile 依赖未安装 | 重跑 `dsh plugin --profile web add` |
| 启动报 `does not provide an export named 'installSettingsSection'` | 0.1.2 移除了该符号，插件为 0.2.0 之前的版本 | 升级到 0.2.0+ |
| `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 发现 | 查 `exports`、`dsh.client` 与 Host loader 日志 |
| 仍走 `deepseek-official` | Bundle 未覆盖 `web` row | `dump-config` 检查 `include:web` |
| Web UI 报 `Failed to load plugins / dsh-web-search-pool` | client 未声明 `remote` 命名空间 inject | 升级到 0.2.1+ |
| 点击「立即刷新」无变化 | Host 未重启或 tick 未触发 | 重启 DSH，检查 `settings/updated` 与 `usageDiagnostic` |
| 刷新请求失败 | 凭据缺失 / 额度耗尽 | 检查 credentials 配置与 `usageDiagnostic` |