pi-search-hub

English

Pi 用的 Search Hub fork。通过多个搜索和内容读取 backend 提供统一的 web_search 与 web_read 工具。

本包也包含在 @zhcsyncer/pi-extensions 里。

安装

pi install npm:@zhcsyncer/pi-search-hub

或安装整个扩展 bundle：

pi install npm:@zhcsyncer/pi-extensions

工具

web_search

按配置的路由搜索网页。已启用 backend 会按顺序尝试，第一次成功即停止。combine=true 只由模型打开（默认关闭），最多合并三家有结果的来源，每条结果都带来源。配置不能把 combine 设成全局强制。

主要调用参数：

• query — 自然语言搜索词；
• numResults — 1 到 20 的目标结果数；
• combine — 用同一 query 合并多家已启用 provider（默认 false）；
• compact — 返回标题、来源与 URL 单行，而不是详细搜索正文。

受支持的搜索 backend 为 Exa、Tavily、Firecrawl、Parallel、OpenAI Codex 和 Grok。没有明确启用 backend 时，Firecrawl 是无需 key 的 fallback。Exa、Tavily 和 Parallel 需要 API key。Codex 和 Grok 走 Pi /login（在对应推理 API 上注入 hosted web search），不把 key 写进 Search Hub 配置。hosted backend 若订阅额度耗尽，会跳过 5 小时，避免每次搜索都重试。路由为 priority（已启用的有序名单）、random 或 best-latency。

web_read

读取 URL 并返回提取后的 Markdown。Reader 固定按 Firecrawl → Exa → Parallel 顺序尝试，只做顺序 fallback，不会并行查询或合并。Firecrawl 无需 key；Exa 和 Parallel 需要 key。

主要调用参数：

• url — 页面 URL。

工具行

Search Hub 自己画 Claude 风格的工具行，不再使用 pi-tool-display-intent。

• 调用行是 ● Web Search("query") 或 ● Read Web Page(url)，而不是通用 (N args)；
• 结果行显示 backend、条数、fallback 或提取长度。

语义化调用元数据包括：

| 工具 | Target | 元数据 | |---|---|---| | web_search | 搜索词 | combine、结果上限、compact 模式 | | web_read | 缩短后的 URL | 起始 reader |

搜索与读取进度通过当前 tool call 展示，不再写入常驻 footer 状态。语义化结果状态包括：

| 工具 | 状态 | |---|---| | web_search | 实际 backend、结果数、fallback 状态，以及组合搜索中可用/已尝试 backend 健康度 | | web_read | 实际 reader、提取字符数，以及展示内容是否被截断到 1 万字符上限 |

详细搜索输出在给模型的结果里仍以 ## Search Results: header 开头。发送给模型的内容仍由 Search Hub 负责，包括 backend 选择、结果数量、compact 结果生成和 backend 级截断。web_search.compact 会改变工具结果本身，不只是 TUI 行。

配置

Search Hub 从以下位置读取配置：

1. $PI_CODING_AGENT_DIR/extension-data/pi-search-hub/config.json：全局设置；
2. 受信任当前项目的 .pi/extension-data/pi-search-hub/config.json。

受信任项目的设置优先。backend map 会按单个 backend 合并，因此项目可以只覆盖一个 backend，无需重复全部全局条目。未受信任项目中的 Search Hub 配置不会被探测或读取。配置会在使用过程中刷新；交互式修改会留在草稿中，直到按 s 保存。

配置、凭据和 Exa 用量告警通过 Pi 原生通知去重展示，不再直接写终端。同一 backend 的搜索或读取连续失败时也会告警。这些本地调用结果不用于推算剩余配额。成功的工具结果也会在详情中保留告警，无 UI 运行同样保留。普通 provider 失败仍走原有工具错误与 fallback 路径。

首次使用时，Search Hub 会自动迁移旧的全局路径和受信任项目路径，升级可识别设置，丢弃无法映射的字段并发出 warning；只有新文件通过语义 round trip 后才删除旧文件。Exa 用量状态也会迁入 $PI_CODING_AGENT_DIR/extension-data/pi-search-hub/state/exa-usage.json，并使用串行化原子更新。

交互式配置

运行 /search-hub setup 可编辑全局路由和 compact 输出。/search-hub status 显示本地余量账（Tavily/Firecrawl 剩余、已禁用的 key 和解禁时间），打开时不打官方接口。按 r 或 /search-hub status refresh 刷新 Tavily/Firecrawl 用量。各家开关、key，以及 Codex/Grok 模型在二级 Providers 页。仅 priority 路由时，已启用尝试顺序在独立列表里改：Enter 选中，上下键移动。

修改留在草稿中。s 保存；干净时 Esc 直接关闭。有未保存修改时 Esc 只确认一次是丢弃还是继续编辑，确认框里没有保存。Key 用 ui.editor 编辑，一行一个引用，只有保存时才写盘。禁用 backend 会保留已存 key。受信任项目配置仍可覆盖全局文件；设置页只提示这一点，不编辑项目文件。

最小示例：

{
  "routing": "priority",
  "priority": ["exa", "firecrawl"],
  "backends": {
    "exa": { "enabled": true, "apiKeys": ["EXA_API_KEY"] },
    "firecrawl": { "enabled": true }
  }
}

可以复制 search.json.example 获取完整 backend 配置矩阵。credential 可以是 EXA_API_KEY 这样的环境变量名、以 ! 开头的 shell command，或直接保存在 apiKeys 中的 key 值。优先使用环境变量或 secret manager，绝不要提交凭据。旧的 apiKey 字符串会在存盘时迁入 apiKeys。多把 key 只在 429、402、432 或配额用尽时轮换。

上游 backend 专属参考见 UPSTREAM_README.md。对于 bundle fork，本 README 描述的本地行为优先。

上游来源

• 仓库：ronnieops/pi-search-hub
• 基线：v2.8.0 / 96ccf692123d35a3cf4b615d597a80fe9e9f6229
• 保留文档：UPSTREAM_README.md
• 保留版本历史：UPSTREAM_CHANGELOG.md

准确来源记录见 UPSTREAM_SOURCE.md。

开发

pnpm --filter @zhcsyncer/pi-search-hub check
pi --no-extensions -e ./packages/pi-search-hub --list-models __pi_search_hub_check__

许可证

上游 package.json 和 README 声明为 MIT，但 v2.8.0 tag 不包含独立许可证文件。保留声明见 UPSTREAM_NOTICE.md，本 fork 的合并许可条款见 LICENSE。