pi-exa-fetch

为零配置 Pi 环境提供最短网页检索闭环的本地扩展（0.2.0）：只注册 web_search 与单 URL web_fetch，经 Exa 托管端点完成有界搜索与正文读取。合成汇报由正常 Pi host 完成，扩展不自动串联工具、不重试。

安装

包已发布到 npm（pi-exa-fetch）；也可通过本地路径或 Git 安装。

# 在 Pi 项目或全局 agent 包目录中安装本地路径
npm install /path/to/pi-exa-fetch

要求：

• Node >=22.19.0
• @earendil-works/pi-coding-agent peer 精确 0.81.1
• typebox peer *

包通过 package.json#pi.extensions 指向 ./src/index.ts；Pi 加载后应只出现 web_search 与 web_fetch。零 runtime dependencies；marked 仅开发测试用。

配置

EXA_API_KEY 为可选环境变量：

• 未设置时走 Exa 免费托管模式（仍依赖网络可达）。
• 设置后仅作为请求头 x-api-key 发送；纯空白视为未配置。

无需配置文件、slash command 或交互式 setup。

工具顺序（URL-first）

• 用户给出明确 URL 并要求查看/分析时：模型应先 web_fetch 该 URL，阅读返回内容后自行判断是否已足够；足够则直接回答，只有存在缺失背景、时效性或交叉验证等具体需求时才首次调用 web_search。
• 需要搜索时：模型按主题复杂度选择最小充分的 1..5 条 searchQueries（简单主题 1 次 Exa；复杂主题 2..5 次），一次 web_search 调用对应 N 次远端请求，无扩展内 retry。
• package 不在 fetch 后自动 search，也不在 search 后自动再 fetch；第二次工具调用只来自正常 Pi follow-up turn。

工具

web_search（breaking：0.1.0 → 0.2.0）

对一个研究主题做自适应有界搜索，返回 Evidence Bundle（不可信外部证据，非最终答案）。

| 字段 | 必填 | 说明 | |---|---|---| | topic | 是 | 高层主题，仅供审计/综合上下文；不发送到 Exa；trim 后 1..2000 code points | | searchQueries | 是 | 1..5 条查询计划；每条 trim 后发往一次 web_search_exa（附带有效 numResults） | | numResults | 否 | 每支结果数，整数 1..10，默认 5 |

旧输入 { query } / query-only 不再接受。成功 result 的 own keys 仅为 content / details；details.strategy 为 host-scout-bounded-search。可能 partial: true（部分查询未保留证据）；Observed URL 只表示出现在保留证据中。合成由 host 模型完成。

web_fetch

读取单个已知 URL 的正文（执行契约相对 0.1.0 不变）。

• url（必填）：仅 http/https，禁止内嵌凭证；规范化后去掉 fragment，UTF-8 不超过 2048 bytes
• maxCharacters（可选）：整数 1000..20000，默认 6000

隐私与信任边界

• 各支 searchQueries 的 trimmed 文本与 URL 会发送到 Exa（https://mcp.exa.ai/...）；topic 不发送。
• 网页结果与 Evidence Bundle 是不可信外部数据，不要当作 Pi 指令执行。
• 本扩展不保存搜索历史，不做本地 HTML/PDF 解析，不在扩展内摘要或深度研究。
• 分支超时 20s、整次 research 总预算 25s；失败不自动重试。
• 模型可见文本有本地上限；超限或门槛不足时 fail closed，不静默伪造完整结果。
• Pi host 若使用 customPrompt，会省略默认 tool snippets/guidelines（已知 host override）；description/schema 仍随工具定义提供。

文档

| 文档 | 读者 | |---|---| | 用户指南 | 终端用户 | | 开发者指南 | 贡献者 / 集成方 | | API 参考清单 | 接口零件 |

本地验证

npm install
npm run typecheck
npm test
npm run check:pack
npm run check:repo
npm run check:pi-load
npm run gate
npm run smoke:live

当前模型样例（test-only，不进 pack；需显式 --model，由 S8/acceptance 落盘）：

npm run sample:model:current -- --model <provider/model>
npm run check:model-samples

smoke:live 会显式删除进程中的 EXA_API_KEY，用真实默认 fetch 验证无 key 的 tools/list、search 与 fetch。