README · 中文参考版

Pi Web Access

为 Pi 智能体提供网页搜索、内容提取和视频理解能力。支持零配置搜索，也可以连接 OpenAI、Brave、Parallel、Tavily、Firecrawl、Jina、Kagi、SearXNG、DuckDuckGo、Exa、Perplexity、Gemini 等多种提供商。

为什么选择它

零配置：安装后即可通过 Exa MCP 搜索，无需 API 密钥。如果 Pi 已通过 /login 登录 Codex 订阅，OpenAI 网页搜索也可以复用该认证。需要更多控制时，再按需添加其他提供商的密钥或端点。

视频理解：可以向 YouTube 视频或本地屏幕录制提问，获取完整字幕、画面描述，并按精确时间戳提取帧。

智能回退：搜索、内容提取和视频分析都有回退链。某个提供商不可用时，会按配置自动尝试其他可用方式。

GitHub 克隆：遇到 GitHub 仓库 URL 时，会把仓库克隆到本地，而不是抓取渲染后的网页。智能体可以读取真实文件并获得可继续探索的本地路径。

安装

pi install npm:pi-web-access

无需 API 密钥即可立即使用 Exa MCP 搜索。若要使用更多提供商或直连 API，可将密钥写入 ~/.pi/web-search.json：

{
  "openaiApiKey": "sk-...",
  "braveApiKey": "BSA_...",
  "exaApiKey": "exa-...",
  "jinaApiKey": "jina_...",
  "perplexityApiKey": "pplx-...",
  "geminiApiKey": "AIza..."
}

视频帧提取可以选装 ffmpeg 和 yt-dlp。没有这两个工具时，字幕与 Gemini 画面描述仍然可用；它们只影响逐帧图片提取。扩展要求 Pi v0.37.3 或更高版本。

快速开始

// 搜索网页
web_search({ query: "TypeScript 最佳实践" })

// 提取网页内容
fetch_content({ url: "https://docs.example.com/guide" })

// 克隆 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: "屏幕上出现了什么错误？"
})

工具

web_search

通过已配置的搜索提供商检索网页，返回带来源引用的综合答案。支持单条或批量查询、结果数量、时间范围、域名过滤、指定提供商与完整内容抓取。

web_search({ query: "Rust async programming" })
web_search({
  queries: ["query 1", "query 2"],
  numResults: 10,
  recencyFilter: "week",
  domainFilter: ["github.com"]
})

fetch_content

把一个或多个 URL 转换为易读 Markdown、原始文本响应或基于页面内容的回答。它会自动识别 GitHub 仓库、YouTube 视频、PDF、本地视频、图片和普通网页。

fetch_content({ url: "https://example.com/article" })
fetch_content({ urls: ["url1", "url2", "url3"] })
fetch_content({
  url: "https://youtube.com/watch?v=abc",
  timestamp: "23:41-25:00",
  frames: 4
})
fetch_content({
  url: "https://example.com/guide",
  mode: "answer",
  prompt: "安装步骤是什么？"
})

get_search_content

读取之前搜索或提取时保存的完整内容。缓存位于 Pi 配置目录下的私有 web-search-cache，有效期一小时；可以通过 findText 查找有限范围内的匹配段落，也可以使用 offset 与 limit 分页读取。

source_check

核查一项声明并返回机器可读的证据结果，包含精确段落引用。它会对搜索结果去重，并限制来源和内容抓取数量，适合在提交结论前验证依据。

主要能力

工作原理

• auto 模式会根据本地配置、可用认证和目标内容自动选择提供商。
• 搜索结果可进入 curator 界面进行筛选、排序和摘要审阅，再把最终内容交给智能体。
• URL 路由器先识别 GitHub、视频、PDF 与图片等特殊内容，再选择对应提取器。
• 网页内容和搜索结果保存到会话外的短期私有缓存，避免把完整页面塞入会话 JSONL。
• 出站请求包含 SSRF 防护；localhost 和字面量私有 IP 默认被阻止。

命令

配置

配置文件为 ~/.pi/web-search.json。可以选择默认搜索提供商、设置 API 密钥、调整搜索工作流、开关工具或命令，以及配置 curator 快捷键。

{
  "defaultProvider": "auto",
  "shortcuts": {
    "curate": "ctrl+shift+s",
    "activity": "ctrl+shift+w"
  },
  "autoOpenBrowser": true
}

Gemini Web 的浏览器 Cookie 访问必须通过 allowBrowserCookies: true 或 PI_ALLOW_BROWSER_COOKIES=1 明确启用。关闭时不会读取浏览器数据或密码存储。

限制

• 在 Docker、WSL、SSH 或无界面环境中，如果 curator 无法自动打开浏览器，需要手动复制它输出的 URL。
• YouTube 私密或年龄受限视频可能在所有提取路径上失败。
• Gemini 可处理的视频长度约为一小时，更长的视频可能被截断。
• PDF 目前只提取文本，不对扫描文档执行 OCR。
• 包含斜杠的 GitHub 分支名可能导致文件路径判断错误，但仓库克隆仍可使用。
• GitHub issue、PR 和 wiki 等非代码 URL 会按普通网页提取。