pi-web-access：安装、搜索降级、PDF 与 YouTube

概览

pi-web-access 为 Pi 添加 web_search、fetch_content 和后续内容读取工具。使用下方安装命令，重启 Pi 后，先读取公开网址或做一次小范围搜索。

零配置指免 Key 的 Exa MCP 搜索路径，不代表所有供应商都免费、可以离线使用，或无需后端即可读取登录网站和分析 YouTube。

搜索如何降级

自动搜索先尝试已配置的 SearXNG。当前模型为 openai-codex 时，优先尝试已授权 OpenAI；否则 Exa 先于 OpenAI。有 Exa Key 使用直接 API，无 Key 使用 MCP。

此提交之后的可用来源顺序为 Brave → Parallel → TinyFish → Search1API → Searchinfinity → Querit → Tavily → Firecrawl → Jina → SERPdive → Kagi → Bocha → Ollama → Perplexity → Gemini API/Web。未配置的服务会跳过；依赖 Cookie 的 Gemini Web 需显式开启。

DuckDuckGo 需显式选择。指定单个 provider 时严格使用该来源；searchRouting.providers 可定义顺序，fallbackOn 决定哪些错误可以继续下一来源，不应假定所有错误都会自动降级。

网址提取的另一条路径

GitHub 仓库可克隆后本地读取。普通 HTML 先使用直接 HTTP、Readability 及 RSC 解析；之后可尝试配置好的自托管 Firecrawl 或 Crawl4AI。远程 HTTP(S) 目标若要用第三方托管提取器，需配置 fetchRouting.allowRemoteHostedProviders: true。

开启后，远程服务会收到目标网址并自行抓取；这与搜索 API 配置分别控制。降级链或“智能提取”都不保证读取登录页、付费墙或反爬页面。

PDF 的依赖与数据路径

PDF 按已配置的 Datalab、已配置的 Gemini、最后本地 unpdf/pdf.js 的顺序提取。本地路径不需要 pdftotext、浏览器或 Key，但只能读取内嵌文字，没有 OCR；远程 PDF 路径会收到文件内容。

设置 pdf.provider 为 unpdf 可选择本地提取；扫描件可能读不到有效文字。默认限制 20 MB、前 100 页。远程普通错误可回退本地，但取消及凭据/配置错误不会被当作普通可恢复错误。

{
  "pdf": { "provider": "unpdf", "maxSizeMB": 20, "maxPages": 100 }
}

区分 YouTube 理解与抽帧

YouTube 理解先尝试明确允许浏览器 Cookie 的 Gemini Web，再尝试 Gemini API、Perplexity。需要至少一个可用并已授权的后端；私密及年龄限制视频可能在整条链上失败。

ffmpeg 和 yt-dlp 是将 YouTube 帧提取为图片时的可选系统程序，并非远程转录/画面描述的前置条件。本地视频抽帧需要 ffmpeg；视频理解可能将文件上传到 Gemini。

配置并验证

可选供应商配置位于 ~/.pi/agent/web-search.json。例如 braveApiKey 可写成 "$BRAVE_API_KEY"，从该环境变量解析凭据。需要时将上面的 PDF 设置合并到同一个 JSON 对象。

重启 Pi 后请求下面的搜索与抓取，检查来源链接及供应商元数据，再试一份已知的文本 PDF。这是可复现的验证方法，不代表本项目已调用所有上游服务或测量提取准确度。

web_search({ query: "Pi coding agent documentation", numResults: 3 })
fetch_content({ url: "https://pi.dev/" })