@dshp-inx/tavily-search

用量与配额（对齐 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, search_usage, extract_usage, crawl_usage, map_usage, research_usage } }，其中 limit / plan_limit 为 null 表示不限量。
• 限流与缓存：官方限流 10 req / 10min（开发与生产一致）；服务端做 60 秒缓存，GET /ext/dshp-inx-tavily-search/usage 默认读缓存、?force=1 强制刷新；429 时返回 ok: false 并附带 stale 旧快照，设置页会明确标注“旧数据”。
• 本插件路由：GET /ext/dshp-inx-tavily-search/usage[?force=1]（同源校验）→ { ok, usage, cached, fetchedAt, takenMs }；state 另附 usageMeta { endpoint, cacheTtlMs, rateLimit, billing, hasCache, fetchedAt } 供设置页决定是否自动拉取。
• 错误语义：缺 Key 提示去设置页配置；401 表示 Key 无效；429 提示稍后“强制刷新”重试；未知响应与网络失败均透出原文便于排查。

配置密钥

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

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

配置（标准 settings 存储）

搜索行为持久化到 settings.yaml 的 dshp-inx-tavily-search 命名空间，设置页改完即时生效，外部编辑热重载（密钥仍走凭证库，不进 settings）：

dshp-inx-tavily-search:
  maxResults: 5      # 默认结果数 1–10
  searchDepth: basic # basic（1 credit/次）| advanced（2 credits/次）

v1：本命名空间曾有 projectId 字段（透传 X-Project-ID 按项目隔离用量）， v2 按次计费下无意义已移除。残留键会被 schema 忽略，无需手动清理。

cordis.patch.yml 的 config: 仍可覆盖默认值（settings 的 base 层）。单次搜索可传 maxResults 覆盖本次默认值。