01 接外部世界

Agent 从对话走向行动:MCP 协议化与浏览器/网络接入

1. 这个方向的插件试图解决什么问题

Pi 默认只带 read、bash、edit、write 四个本地工具。要查实时网页、读取 PDF 或视频、连接外部 SaaS 与本地 MCP 服务,同时不让几十个工具定义把上下文窗口撑爆,就需要这一层接入扩展。

早期给终端 Agent 接外部能力,常见做法是把所有 MCP Server 的工具 schema 全量塞进系统提示词。只要接入三四个服务,工具定义本身就可能消耗上万 token,模型还没开始干活,上下文已经被占满。

另一类问题是网络读取的可用性。网页反爬、多搜索引擎回退、YouTube 与本地视频理解、云端浏览器自动化操作,都不适合靠手写 curl 脚本临时拼接。

2. 在 Pi 里怎么体现

Pi 的扩展机制允许在运行时通过 pi.registerTool() 动态注册工具,并配合 context、before_agent_start、tool_call、mcp_servers_change 等生命周期事件,按需向模型暴露工具集。

以 pi-mcp-adapter 为代表,扩展把多台 MCP Server 折叠成少量代理工具或按语义检索后再动态激活,避免首轮全量注入 schema;pi-web-access 与 pi-web-search 负责多引擎搜索回退与页面抽取;@onkernel/browser-loop 则把云端浏览器动作封装为可跨模型编译的 Pi 工具扩展。

延伸实测阅读

如果希望先了解 Pi 核心 1.0 起内置的 QuickJS Codemode 沙箱如何从内核层减少 MCP 工具的上下文消耗,可对照阅读已发布解析:Pi Agent 1.0 与 1.1 深度解析:MCP 接入、Codemode 沙箱与选型指南。

涉及的 Pi 事件钩子与注册接口

pi.registerTool()pi.setActiveTools()before_agent_starttool_calltool_resultmcp_servers_change

3. 代表包与生态实例

下表包名均核实自 npm、GitHub 与 pi.dev/packages(核对日期 2026-11-22)。前 3 项已上线独立机制详评页,正文不展示容易过期的静态下载量快照。

包名 分发形态 主要作用 详情 / 源码
pi-mcp-adapter npm 按需检索与激活 MCP 工具,支持 MCP Tasks 后台执行与结果字段抽取,减少工具定义对上下文的占用。
pi-web-access npm 集成多引擎联网搜索、网页内容与字段抽取、GitHub 克隆、PDF 提取及 YouTube/本地视频理解。
@onkernel/browser-loop npm 由 Kernel 提供的浏览器工具框架与 Pi 扩展,将点击、输入、滚动等动作编译适配不同模型并接入 Kernel 浏览器执行。
pi-mcp-extension npm 支持 stdio、SSE、Streamable HTTP 传输与 OAuth 2.1(PKCE + DCR)的轻量 MCP 扩展,支持懒加载和急加载生命周期。
pi-web-search npm 面向模型原生联网能力的 Pi 搜索扩展,支持 Gemini URL Context、xAI Grok、OpenAI Responses、Anthropic 等原生搜索接口。
webfox npm 同时提供命令行工具、TypeScript 库和 Pi 扩展的网页搜索与深度研究路由层,支持自带多家 API Key。

4. 怎么装

代表包安装命令示例
pi install npm:pi-mcp-adapter
  • 常规安装使用 pi install npm:<包名>,Pi 会将依赖写入 ~/.pi/agent/settings.json 并自动发现 package.json 中 pi.extensions 声明的入口。
  • 如果只想单次试用而不写入全局配置,可使用 pi -e npm:<包名>。
  • 部分网络或浏览器扩展需要环境变量或登录授权,例如 @onkernel/browser-loop 需要 KERNEL_API_KEY,pi-mcp-adapter 提供 /mcp-auth 斜杠命令完成 OAuth 认证。

5. 和同类怎么选

包名解决的接入面核心机制特点适用场景
pi-mcp-adapter 外部 MCP 服务桥接 按需搜索工具、支持 MCP Tasks 后台执行与 extract 结果裁剪 已有一批 MCP Server,但不想把 schema 全量灌入上下文
pi-mcp-extension 轻量标准 MCP 客户端 支持 stdio / SSE / Streamable HTTP 与 OAuth 2.1,支持懒加载/急加载 需要轻量、直接按标准协议挂载少量 MCP 服务
pi-web-access 联网搜索、抓页、视频与仓库读取 多搜索源回退、页面字段抽取、PDF 与视频理解 需要一套包覆盖搜索、抓页和多媒体读取
pi-web-search 模型原生搜索调用 调用 Gemini / xAI / OpenAI / Anthropic 原生联网能力 直接复用当前模型厂商自带的搜索与 URL Context 能力
webfox CLI + TS 库 + Pi 扩展三合一联网 统一路由多家搜索/抽取 API,自带 CLI 与扩展入口 希望同一套配置同时给终端脚本和 Pi 使用
@onkernel/browser-loop 云端浏览器操作 框架无关浏览器工具目录 + 按模型编译 + Kernel 执行 需要完整浏览器点击、表单、滚动等 GUI 自动化动作

看完「01 接外部世界」后的下一步

可先读已公开的入门实操文章,或点击下方制作中项目表达关注度(不收集邮箱或隐私)

从 Claude Code / Codex 切到 Pi:最小可用配置单与实机演示视频

已上线入门参考: 《Pi 入门笔记》 (比 Codex 更自由,但也更折腾)

出口 1(配置单与实机演示制作中)

Coding Agent 实战交付课:如何可控地把想法做成线上产品

由 kuhung 策划主讲。面向希望把 Coding Agent 用到真实工程与产品交付的开发者,讲清需求拆解、上下文控制、安全边界与上线验证。

出口 2(实战交付课筹备中)