从 dsh-tavily-search 迁移（手工，插件不自动采用配置）

旧插件（@dshp-inx/tavily-search）与本插件互斥：两者都注册 tavily 提供方，id 冲突会触发 WEB_DUPLICATE_PROVIDER（本插件会打印中文告警提示）。两步：

安装本插件（见上）并重启确认生效；
移除旧插件：dsh plugin --profile web remove "@dshp-inx/tavily-search"，删除 ~/.dsh/plugins/dsh-tavily-search 目录。

配置不自动迁移：本插件只读自己的 dshp-search-provider 分节。如需沿用旧插件设置，请手工把值抄到新分节（旧分节 dshp-inx-tavily-search 之后可自行删除）：


## 配置（标准 settings 存储）

以下配置写入 `settings.yaml` 顶层 `dshp-search-provider` 命名空间（设置页可改，外部编辑热重载；schema 默认值 → composition base → 用户层三级继承）。密钥**不**进 settings.yaml，走 credentials 服务。

| 键                   | 类型                 | 默认     | 说明                                                                                                          |
| -------------------- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `provider`           | string               | `tavily` | 设置页聚焦的提供方；真正生效者由 profile patch 的 `web.searchProvider` 决定（state 接口会在不一致时给出提示） |
| `maxResults`         | int 1–10             | `5`      | 单次搜索默认返回条数；调用方显式传 maxResults 时以调用方为准                                                  |
| `tavily.searchDepth` | `basic` / `advanced` | `basic`  | 搜索深度；按次计费 basic 1 credit/次、advanced 2 credits/次                                                   |

### 计费与用量（Tavily，对齐 [官方文档](https://docs.tavily.com/documentation/api-reference/endpoint/usage)）

- **端点**：`GET https://api.tavily.com/usage`，鉴权为 `Authorization: Bearer `（注意与 `/search` 的 `body.api_key` 不同）。
- **返回**（仅透传文档声明的叶子标量）：`{ key: { usage, limit, search_usage, extract_usage, crawl_usage, map_usage, research_usage }, account: { current_plan, plan_usage, plan_limit, paygo_usage, paygo_limit, ... } }`，`limit / plan_limit` 为 `null` 表示不限量。
- **限流与缓存**：官方限流 `10 req / 10min`；服务端做 `60 秒`缓存，`GET /ext/dshp-search-provider/tavily/usage` 默认读缓存、`?force=1` 强制刷新；`429` 时返回 `ok:false` 并附带 `stale` 旧快照，设置页会明确标注“旧数据”。

### 计费与用量（Tavily，对齐 [官方文档](https://docs.tavily.com/documentation/api-reference/endpoint/usage)）

- **端点**：`GET https://api.tavily.com/usage`，鉴权为 `Authorization: Bearer `（注意与 `/search` 的 `body.api_key` 不同）。
- **返回**（仅透传文档声明的叶子标量）：`{ key: { usage, limit, search_usage, extract_usage, crawl_usage, map_usage, research_usage }, account: { current_plan, plan_usage, plan_limit, paygo_usage, paygo_limit, ... } }`，`limit / plan_limit` 为 `null` 表示不限量。
- **限流与缓存**：官方限流 `10 req / 10min`；服务端做 `60 秒`缓存，`GET /ext/dshp-search-provider/tavily/usage` 默认读缓存、`?force=1` 强制刷新；`429` 时返回 `ok:false` 并附带 `stale` 旧快照，设置页会明确标注“旧数据”。

## 配置密钥

1. 注册 [tavily.com](https://tavily.com)（有免费额度），取 `tvly-…` 格式的 API Key；
2. 设置 → AI 搜索 → 粘贴密钥 → 保存密钥。「密钥状态」行变绿（已配置）、「搜索引擎」行显示「Tavily · 当前生效」即接管完成；
3. 在连接测试框输入任意查询点「运行测试」，返回结果列表即全链路通。

密钥通过 DSH credentials 服务持久化到 `~/.dsh/.credentials.yaml`，**不回显、不进模型上下文**；写入/清除即时生效，无需重启。

@dshp/search-provider

安装

说明文档

从 dsh-tavily-search 迁移（手工，插件不自动采用配置）