dsh-tavily-resilient-search: A Resilient Tavily Web Search Plugin for DSH

前言¶

在 DeepSeek Harness (DSH) 的生态中，联网能力通常通过插件实现。当使用 Tavily API 时，开发者常面临密钥限流（429）、配额耗尽（432/433）或密钥被吊销（401）的问题。如果处理不当，这些错误会直接中断 Agent 循环，导致任务失败。dsh-tavily-resilient-search 旨在解决这一痛点，通过原子级密钥轮换和 Keyless 降级模式，保证 Agent 循环的连续性。

这是什么¶

dsh-tavily-resilient-search 是一个独立的 Cordis 插件，由用户 frederico-kluser 维护。它通过 Tavily API 提供实时网络搜索，核心能力包括：

原子级密钥轮换：当一组密钥中某个遇到限流或错误时，自动切换到下一个可用密钥，而不中断 Agent 循环。
Keyless 降级：当所有密钥失效或未配置时，自动切换到 Keyless 模式（限制更严），并给出明确提示。
密钥管理面板：提供 Web 界面进行密钥的增删改查及测试。
安全审计：记录关键操作和拒绝的请求。

该插件遵循 MIT 许可证。

安装与启用¶

安装该插件需要 Node.js 环境版本大于等于 24。安装过程通过 DSH 的包管理器完成，插件声明了 dsh.bundle.patch，因此安装后会自动激活。

dsh plugin --profile web add dsh-tavily-resilient-search

安装后，相关配置会自动注入到 DSH 的 Bundle 层。

配置与密钥管理¶

环境变量配置¶

密钥必须通过环境变量设置，绝不能以明文形式硬编码在配置文件中。插件会按顺序读取环境变量。

export TAVILY_API_KEY_A="tvly-..."
export TAVILY_API_KEY_B="tvly-..."
export TAVILY_API_KEY_C="tvly-..."

Web 界面管理¶

插件提供了一个管理面板用于维护密钥池。

访问面板：在 DSH 界面的“Settings”中，只有当没有有效密钥时才会显示“Tavily Keys”入口。
CRUD 操作：支持添加、列出、编辑、删除和测试密钥。编辑和删除操作需要二次确认（nonce）。
管理员令牌：首次启动时，系统会生成一个 CSPRNG 令牌，保存在 ~/.dsh/dsh-tavily-resilient-search/admin-token.txt（权限 0600）。
- 如果忘记令牌，可通过环境变量 DSH_TAVILY_ADMIN_RESET=1 重置。
- 也可以直接设置 DSH_TAVILY_ADMIN_TOKEN。
安全策略：默认仅允许 Loopback 访问。如果需要绑定公网地址（0.0.0.0），必须在配置中显式开启 admin.allowPublicBind: true，否则面板拒绝启动。

配置参数¶

配置通过 Profile、Home 或 CLI 覆盖层进行，注意插件采用整条目替换策略，而非深度合并。

字段	类型	默认值	说明
`apiKeys`	`string[]`	`[]`	密钥数组，按顺序轮询。空数组表示 Keyless 模式。
`searchDepth`	`ultra-fast\\|fast\\|basic\\|advanced`	`basic`	搜索深度。
`maxResults`	`1..100`	`5`	最大结果数，会自动钳制在 10 以内。
`includeAnswer`	`boolean`	`true`	是否包含 Tavily 的摘要答案。
`timeoutMs`	`number`	`15000`	单次 HTTP 请求超时时间。
`callTimeoutMs`	`number`	`120000`	整个调用（包括轮换）的总超时时间。
`projectId`	`string`	—	用于项目隔离的 ID。
`admin.enabled`	`boolean`	`true`	是否启用管理面板。
`admin.trustedRemotes`	`string[]`	`loopback`	信任的远程源。
`admin.allowedHosts`	`string[]`	`127.0.0.1`, `localhost`, `::1`	允许的 Host 名。
`securityProfile`	`{sandbox, approval}`	必填	安全策略，通常为 `sandbox: 'workspace-write', approval: 'ask'`。

工具用法¶

安装并激活后，插件会暴露 web_search 工具。

调用方式：

web_search(query, search_depth, max_results, topic)

参数：

query (string, 必填)：搜索词，推荐小于 1500 字符，硬限制 4000 字符。
search_depth (enum, 可选)：ultra-fast、fast、basic、advanced。
max_results (integer, 可选)：1 到 10。
topic (enum, 可选)：general 或 news。

返回值：

返回包含 ok、query、answer、sources、responseTime、keylessFallbackUsed、error、detail、suggestion 的结构化数据。即使出错，也会返回结构化信息，而非抛出异常中断进程。

错误处理机制¶

插件针对不同的 HTTP 状态码有明确的处理逻辑：

429 (限流) / 432 (配额) / 433 (配额)：标记当前密钥为不可用，立即重试下一个密钥，保持 payload 不变。
401 (未授权/吊销)：密钥失效，从池中移除并重试。
400 (参数错误)：不轮换密钥，直接返回错误并附带修正建议。
超时或网络错误：尝试轮换密钥；若所有密钥均失败，则触发 Keyless 模式或返回错误。

注意事项¶

Node 版本：必须使用 Node.js 24 或更高版本。
权限：插件以当前 DSH 进程的权限运行，需确保环境变量已正确设置。
源码审查：虽然许可证为 MIT，但在生产环境使用前，建议审查源码以确保符合安全规范。
配置方式：配置时直接覆盖配置项，注意不要试图深度合并覆盖 apiKeys 等数组字段。

总结¶

dsh-tavily-resilient-search 是一个为追求高可用性而设计的 DSH 插件。它通过自动化的密钥管理和容错机制，解决了 Tavily API 在实际使用中常见的限流和配额问题，确保 Agent 在联网任务中不会因 API 错误而意外终止。