Pi Web Access 介绍

July 06, 2026

这是什么

pi-web-access 是 Pi 生态里最常用的第三方 package，给 Pi 接入网络。本质上是把 web_search、网页抓取、GitHub 仓库、YouTube/本地视频分析、PDF 提取等能力，封装成 Pi 的 extension + skill，安装后 Pi 可以直接上网查资料。

作者是 Nico Bailon，仓库在 github.com/nicobailon/pi-web-access。

安装

pi install npm:pi-web-access

安装后放在 ~/.pi/agent/npm/node_modules/pi-web-access/，不是 ~/.pi/agent/extensions/ 目录。它作为 Pi Package 安装，不需要手动管理扩展文件。

零配置可用： 不需要任何 API key。默认走 Exa MCP（免费），如果你恰好有 Codex 订阅，OpenAI 搜索也能复用认证。

如果觉得不如意，可以给别的搜索提供商配 API key。

三个工具

安装后 Pi 会多出三个 LLM 可调用的工具。

1. web_search — 联网搜索

最常用。支持单条 query 或批量 queries（推荐一次搜 2-4 条不同角度，覆盖面更宽）：

web_search({ query: "rust async programming" })
web_search({ queries: ["react 性能优化 2025", "react concurrent mode 原理"] })
web_search({ query: "...", numResults: 10, recencyFilter: "week" })
web_search({ query: "...", domainFilter: ["github.com", "-reddit.com"] })
web_search({ query: "...", provider: "openai" })
web_search({ query: "...", includeContent: true })

工作流选项：

summary-review（默认）：打开 curator 摘要页，你可以手动挑选结果后批准
auto-summary：自动生成摘要，不弹 curator
none：直接返回原始搜索结果

2. fetch_content — 抓取内容

万能抓取器，会根据 URL 类型自动分派：

// 普通网页 → 提取为 markdown
fetch_content({ url: "https://docs.example.com/guide" })

// 批量抓取
fetch_content({ urls: ["url1", "url2", "url3"] })

// GitHub 仓库 → 克隆到本地，返回文件内容和路径
fetch_content({ url: "https://github.com/owner/repo" })

// YouTube 视频 → 转录 + 视觉描述
fetch_content({ url: "https://youtube.com/watch?v=abc", prompt: "里面提到什么库？" })

// 本地视频 → 分析画面内容
fetch_content({ url: "/path/to/recording.mp4", prompt: "屏幕上显示了什么错误？" })

// 提取视频帧
fetch_content({ url: "...", timestamp: "23:41-25:00", frames: 4 })

// PDF → 提取文本保存到 ~/Downloads/
fetch_content({ url: "https://example.com/paper.pdf" })

3. get_search_content — 取完整内容

web_search 和 fetch_content 的返回结果可能被截断到 30,000 字符。完整内容被后台存了起来，用这个工具取出：

get_search_content({ responseId: "abc123", urlIndex: 0 })
get_search_content({ responseId: "abc123", url: "https://..." })

搜索提供商 & Fallback

Auto 模式的默认搜索链路：

OpenAI → Exa → Brave → Parallel → Tavily → Perplexity → Gemini API → Gemini Web

Exa：默认走 Exa MCP 代理，零配置。如果配了 Exa API key，就走直连 API，有更高的调用额度
OpenAI：如果 Pi 已 /login 订阅 Codex，可复用认证；没订阅就自动跳过
其他几个（Brave、Perplexity、Gemini 等）需要各自 API key

fetch_content 的 fallback 更复杂，分不同场景：

YouTube: Gemini Web → Gemini API → Perplexity
本地视频: Gemini API → Gemini Web
网页抓取: Readability → RSC parser → Jina Reader → Gemini URL Context → Gemini Web

反爬/JS 页面打不开的时候，Jina Reader 会服务端渲染后重试。

特色能力

GitHub 仓库

GitHub URL 不抓 HTML，而是直接 git clone 到本地。Pi 拿到的是真实的文件系统路径，可以用 read 和 bash 操作源码。超过 350MB 的仓库用 API 轻量查看（可以用 forceClone: true 强制克隆）。private 仓库需要本机有 gh CLI 认证。

YouTube 视频

识别所有格式（/watch?v=、youtu.be/、/shorts/、/live/ 等），输出带时间戳的转录文字、画面视觉描述、章节标记。配上 prompt，可以让 Pi 回答视频里的具体问题。

本地视频

支持 MP4/MOV/WebM/AVI，最大 50MB。配上 prompt，可以用 Gemini 分析画面内容。装了 ffmpeg 后还会附带缩略图。

视频帧提取

用 timestamp（单个时间点或时间段）+ frames（帧数）从 YouTube 或本地视频摘画面帧。需要 ffmpeg（和 YouTube 还要 yt-dlp）。

PDF

文本提取到 ~/Downloads/ 保存为 markdown，Pi 之后可以 read 特定片段，避免把整篇论文塞进上下文。

捆绑技能：librarian

skills/librarian/ 是一个研究开源库的技能。结合 GitHub 克隆、web 搜索、git blame/log，给出带源码引用和 GitHub permalink 的证据型回答。适合问"这个库的实现细节是什么"这类需要看源码的问题。

命令 & 快捷键

命令	作用
`/websearch`	打开搜索 curator，手动输入搜索词
`/websearch react hooks`	带关键词打开 curator
`/curator`	切换 curator 开关
`/curator off`	关闭 curator，搜索直接返原始结果
`/search`	浏览当前 session 存过的所有搜索结果
`/google-account`	查看 Gemini Web 当前用的 Google 账号

快捷键	作用
`Ctrl+Shift+W`	打开 Activity Monitor，看实时请求/响应
`Ctrl+Shift+S`	打开 curator

配置文件

~/.pi/web-search.json，所有字段都是可选的：

{
  "openaiApiKey": "sk-...",
  "braveApiKey": "BSA_...",
  "exaApiKey": "exa-...",
  "perplexityApiKey": "pplx-...",
  "geminiApiKey": "AIza...",
  "provider": "auto",
  "workflow": "summary-review",
  "allowBrowserCookies": false,
  "chromeProfile": "Profile 2",
  "searchModel": "gemini-2.5-flash",
  "summaryModel": "anthropic/claude-haiku-4-5",
  "curatorTimeoutSeconds": 20,
  "ssrf": {
    "allowRanges": ["198.18.0.0/15"]
  }
}

对应的环境变量（OPENAI_API_KEY、BRAVE_API_KEY 等）优先级高于配置文件。

工作流

搜索流程：

LLM 调用 web_search
根据 workflow 决定行为：none 直接返结结果；auto-summary 调模型生成摘要；summary-review（默认）打开浏览器 curator
curator 是一个本地 HTTP 服务的网页，你可以浏览结果、增删、手动摘选
你批准后，摘要（或选中的结果）会注入到 Pi 对话

如果在 Docker/WSL/SSH 等无图形环境跑，curator 打不开浏览器，会在工具输出里显示 URL，需要手动复制到本机浏览器。