dsh-web-tavily

中文 · English

为 dsh-TUI 构建。

dsh host 平面 cordis 插件：为 dsh 的 web 能力 seam（ctx.web）注册搜索提供商 tavily，让 web_search 工具默认走 Tavily Search API（POST https://api.tavily.com/search）。

• 不替换 web_search 工具本身：工具、系统提示、展示卡片均保持原样，只有搜索后端换成 Tavily。
• 保留 DeepSeek 原生搜索（web-search-deepseek）为可切换备选；想切回只需把 web.searchProvider 改为 deepseek-official 或删掉该键。
• key 按以下顺序解析：配置里的字面 apiKey 最优先，其次凭证服务 （~/.dsh/.credentials.yaml 的 refs:，引用名默认 TAVILY_API_KEY），最后是启动 环境变量。provider 不保留 key。

工作原理

1. 注册 provider（id = tavily）到 ctx.web；web.searchProvider: tavily 使其成为默认选择。
2. web_search 被调用时，seam 把 { query, maxResults } 交给本 provider。
3. provider 解析 key（每次操作时快照，一次搜索不会混用两个配置版本）→ 请求 {baseURL}/search。
4. 响应映射：results[] → sources[]（title / url / content→snippet，若有 published_date → publishedAt），顶层 answer（Tavily 的 AI 总结）→ 工具的可选 content 摘要。
5. 取消（信号）→ WEB_ABORTED；HTTP 失败 / 不可解析 → WEB_PROVIDER_ERROR；缺 key → WEB_PROVIDER_CREDENTIAL_MISSING（错误信息带配置指引）。

默认配置

| 字段 | 默认值 | 说明 | | --- | --- | --- | | apiKeyEnv | TAVILY_API_KEY | 凭证引用（环境变量名） | | apiKey | （无） | 字面 key，仅当不想走引用时使用 | | baseURL | https://api.tavily.com | 可用环境变量 TAVILY_BASE_URL 覆盖 | | searchDepth | basic | basic / advanced（advanced 更深度、额度消耗更高） | | topic | general | general / news | | includeAnswer | true | 是否请求 Tavily 的 AI 总结（映射为 content） | | maxResults | 10 | 兜底结果数上限（web_search 每次实际传 8，Tavily 上限 20） |

安装

1. 先注册 Tavily 账号并创建 API key。 到 https://tavily.com/ 注册，在控制台创建 key，然后放进 ~/.dsh/.credentials.yaml 的 refs: 下，或在启动 dsh 的环境里导出 TAVILY_API_KEY（详见下文「key 存放」）。不要把 key 提交进仓库，也不要写进设置 文档。

2. 装进 profile —— 它以 dsh-web-tavily 发布在 npm 上：

   dsh plugin --profile dsh-tui add dsh-web-tavily
   # 从本仓库本地安装（开发）：
   # dsh plugin --profile dsh-tui add file:<本包路径>

3. 先 /restart 重启一次，让插件行载入。dsh plugin add 只改写 profile 的 bundles 清单，不会把插件加载进运行中的会话；先重启，下一步保存补丁时 tavily provider 才已经注册好。

4. 把 web 服务默认搜索改为 tavily（必须写在 profile 用户补丁层，settings.yaml 的 web: 段对服务配置无效）—— 编辑 ~/.dsh/profiles/dsh-tui/cordis.patch.yml 追加：

   - id: web
     name: '@deepseek-ai/dsh-web'
     config:
       searchProvider: tavily
       fetchProvider: http-trusted

   ⚠️ 保存该文件会立即热重载运行中的会话，不是「重启后才生效」。 profile 补丁层被 文件监听器盯着，落盘那一刻当前会话就会被重新配置。若插件此时尚未加载（跳过了第 3 步），web 行立刻指向一个还没注册的 provider，当前会话的 web_search/联网能力当场报 WEB_PROVIDER_CONFIGURED_MISSING。重启即恢复：启动时插件与补丁一起读入。先改 补丁、稍后再重启对启动同样安全，只是当前会话的联网能力要等到那次重启才可用。

   web 行由基座 dsh-base 提供，不要用 insert: 新增同 id 行——那会撞 id 直接崩 duplicate loader entry id: web；这里要按 id 覆盖既有行，且覆盖是整行重写，需写全 fetchProvider。

配置

插件自身的设置段放 ~/.dsh/settings.yaml（设置页「Plugin configuration」里也会出现「Web search Tavily」类）：

dsh-web-tavily:
  apiKeyEnv: TAVILY_API_KEY
  searchDepth: basic
  topic: general
  includeAnswer: true
  maxResults: 10

可用环境变量覆盖：TAVILY_BASE_URL（API 源），凭证引用键默认 TAVILY_API_KEY。

设置页把这个命名空间渲染成一张中英双语卡片（「联网搜索（Tavily）」/ Web search (Tavily)），每个字段都有说明；日常只需要改「凭证引用」那一项。密钥本身永远不进设置文档。

key 存放（本机，不进代码库）

在 ~/.dsh/.credentials.yaml 的 refs: 下添加（该文件属于本机凭证，不要提交/外发）：

refs:
  TAVILY_API_KEY: 'tvly-...'

也可以在启动 dsh 的环境里导出 TAVILY_API_KEY：解析时先查凭证服务、再查启动环境。 配置里的字面 dsh-web-tavily.apiKey 同样可用，且优先于以上两者，但它等于把密钥写进 设置文档，只建议作为最后手段。

切回 DeepSeek 原生搜索

把 web.searchProvider 改为 deepseek-official（或删除该键、让 seam 用唯一可用 provider）。注意 seam 不支持自动回退：Tavily 配置失效时搜索会明确报错，而不会悄悄走 DeepSeek。

代理兼容 fetch（http-trusted）

本插件同时注册 http-trusted fetch provider，解决 fake-IP 代理环境（Clash 等把域名解析为 198.18.0.0/15 假地址）下 web_fetch 被官方 http provider 的安全预检拒绝的问题（WEB_BLOCKED_URL: resolves to a non-public IP address）。

• 复用官方 @deepseek-ai/dsh-web-fetch-http 传输层：仅放宽「解析结果必须是公网 IP」这一预检——额外放行 198.18.0.0/15（代理 fake-IP 段），其余全部照旧：内网/环回/保留段照常拒绝（WEB_BLOCKED_URL）、IPv6 答案一律丢弃、地址 pinning、同源重定向、内容类型白名单、字节/字符上限、无凭证 cookie 等防护原封未动。
• ⚠️ 安全边界：SSRF 防护从「宿主内强校验」退化为「信任本机代理的 DNS 决策」，网络的最终裁决权移交代理分流规则。仅适用于单用户本机 + 自制可信代理；多人共用/公网服务请回退官方 http（见下）。
• IP 来源特殊（http://192.168.x.x/ 之类）仍会被拒绝。

# ~/.dsh/profiles/dsh-tui/cordis.patch.yml 的 web 行
config:
  searchProvider: tavily
  fetchProvider: http-trusted

回退官方 http：把 fetchProvider 改回 http（代价：fake-IP 代理环境下 web_fetch 将再次被拒，但安全预检完整）。

加载失败排查

• 插件启动报 duplicate loader entry id: web：profile cordis.patch.yml 误用 insert: 新增同 id 行，按上文改写为直接行。
• web_search 报 WEB_PROVIDER_CONFIGURED_MISSING：web 行指向的 provider 尚未注册 ——要么插件没加载（检查 bundles 清单），要么 cordis.patch.yml 在插件加载前就被保存 （保存即热重载，见「安装」）；/restart 即可恢复。
• web_fetch 报 WEB_BLOCKED_URL ... non-public IP：代理假 IP 预检拒绝，改用 http-trusted 或关闭代理 fake-IP 模式。

限制说明

• Tavily key 缺失或失效 → web_search 报错（WEB_PROVIDER_CREDENTIAL_MISSING / WEB_PROVIDER_ERROR），按错误信息指引配置即可。
• max_results 会被钳制到 Tavily 上限 20。
• searchDepth / topic 非法值会直接报错，不会悄悄回退默认。

发布

• 仓库：https://github.com/VviLliAm-qwq/dsh-web-tavily（公开）
• 发布方式：v* tag 驱动 .github/workflows/release.yml，经 npm **可信发布（OIDC）**上传——仓库内不存放任何令牌。

使用

装好并配置 key 后，照常让模型调用 web_search 即可；工具返回的 Sources: 列表与可选总结即来自 Tavily。

许可

MIT — 见 LICENSE。