# @jpa957/dsh-web-search-anysearch

[English](README.md) | [中文]

[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的 [AnySearch](https://api.anysearch.com) 搜索提供方插件，注册到 `ctx.web` 接缝（`web-search-anysearch`）。

与内置提供方一样，插件带两半：

- **宿主半**：向 `ctx.web` 注册 `anysearch` 搜索提供方（round-robin 密钥轮换 + 按 key 冷却故障切换），并安装设置节（settings section），使配置可以在 web 应用里修改。
- **浏览器半**：在设置导航里有**独立的 AnySearch 标签页**（**设置 → AnySearch 搜索**），直接在界面里填 API 密钥、接口地址、结果数——不用再改 patch 文件。

## 安装

```sh
dsh plugin --profile web add @jpa957/dsh-web-search-anysearch
```

（或从本地检出版安装：`dsh plugin --profile web add /path/to/dsh-web-search-anysearch`）

bundle 的 patch 层会自动注册提供方。要把它设为 web 接缝的**默认**搜索后端，请在你自己的 patch 层（须应用在 bundle 层之后）加一行 pin：

```yaml
- id: web
  config:
    searchProvider: anysearch
    fetchProvider: http
```

> **从手动挂载的旧版迁移？** 先从你的 profile patch 里删掉指向插件文件的旧 `- insert:` 行——bundle 现在自带注册，重复 id 会导致组合失败。保留 `searchProvider: anysearch` 的 pin 即可。

## 在设置标签页里配置

打开 web 应用的 **设置 → AnySearch 搜索** 标签页：

- **API 密钥** —— 保存在宿主凭据库中（引用名见下）；明文不会再回传浏览器（卡片只显示"已配置/未设置"）。
- **密钥引用名** —— 提供方每次搜索按此名称解析密钥；默认 `ANYSEARCH_API_KEY`。值可以是逗号分隔的多个 key 组成密钥池。
- **接口地址** —— 留空默认 `https://api.anysearch.com`。
- **最大结果数** —— 每次搜索请求的结果条数（1-10）。

修改先暂存，点**保存**才写入；**放弃**则还原。设置命名空间为 `web-search-anysearch`（卡片编辑的 section），同一份配置也可以通过 settings 文档管理。

### 密钥池行为

密钥来源：凭据引用的值（可逗号分隔多个）、加上组合配置里的 `apiKey`/`apiKeys` 字面量，去重合并。搜索在池上轮转；key 级失败——限流（HTTP 429 / "retry after N seconds"，并尊重 API 的 `retry-after` 响应头）、配额耗尽、鉴权拒绝（401/403）——会把该 key 放入冷却（默认 60 秒，鉴权/配额 10 分钟），并在**同一次搜索内**换下一把 key 重试，最多尝试六次。池子全部耗尽时聚合为一个 `WEB_PROVIDER_ERROR`，写明池子大小、掩码后的 key 和 API 的 `request_id`。空池匿名搜索。

## Key 安全

密钥只通过凭据域进入（设置页或 `$ANYSEARCH_API_KEY`），除非你显式写进组合配置。本仓库不含任何机密；测试使用明显的假 key（`as_sk_unit-*`）。诊断信息只显示 key 的前十位。

## 行为说明

- **轮转**：round-robin 游标在每次成功搜索后前进。
- **故障切换**：key 级失败会冷却该 key 并在同一次搜索内换下一把；非 key 级失败（网络、5xx、无法解析的响应体）立即抛出。
- **自我纠正**：当所有 key 都在冷却时，按最早到期时间重试，冷却误判可自愈。
- **中止**在 fetch、响应体解析、信号三个阶段都呈现为 `WEB_ABORTED`。
- **结果映射**：无 URL 的条目丢弃、重复 URL 去重、`content` 优先于 `snippet`；`truncated` 恒为 `false`——最终截断由 web 服务负责（`maxResults` 会钳制到 API 文档的 1-10）。

## 开发

```sh
node tests/unit.mjs           # 离线单元测试（纯 node，无测试框架）
node tests/client-bundle.mjs  # client bundle 契约冒烟测试
node tests/live.mjs           # 真实端点的匿名冒烟测试
```

浏览器半（`lib/client.js`）是免构建、手工维护的 client-module 工厂格式 bundle——不需要构建步骤。从 git URL 或 npm 安装时，web 应用直接使用仓库里已提交的 `lib/client.js`。

## 许可证

[MIT](LICENSE)