3 分钟看懂 Pi:和 Claude Code / Codex 有什么不同

理解 Pi 为什么把内置内核压缩到只剩 4 个基础工具,以及社区扩展如何通过事件钩子与工具注册拼出完整的 Agent 工程系统。

1. 一句话定位差异

Claude Code 与 Codex 倾向交付一套官方打包好、开箱即用的一体化终端产品;Pi(主包 @earendil-works/pi-coding-agent,早期包名 @mariozechner/pi-coding-agent)遵循 MIT 开源协议,定位为可由用户自由组装的极简编码代理底座(Minimal Agent Harness)。

对照维度 Pi Coding Agent Claude Code / Codex
内置工具数 默认只带 read、write、edit、bash 四个工具 官方预置子代理、计划模式、搜索与权限框架
模型绑定 支持 15 家以上模型供应商与本地模型(BYOK 或代理网关) 分别围绕 Anthropic Claude 或 OpenAI 体系深度优化
MCP 接入策略 内置 QuickJS Codemode 沙箱按需发现并编排,避免全量 schema 撑爆上下文 原生接入 MCP 生态,配置体验开箱即用
扩展机制 TypeScript 扩展热加载(/reload),可拦截任意工具与消息生命周期 依赖官方提供的 Hooks、Skills 与插件约定

2. 扩展怎么插进 Pi 的主循环

Pi 通过 jiti 直接加载 TypeScript 扩展,不需要单独编译步骤。每一个扩展导出默认工厂函数并接收 ExtensionAPI(通常记作 pi),通过三类能力改造 Agent 行为:

  • 注册新入口:用 pi.registerTool() 给模型增加可调用工具(如浏览器点击、结构化问卷、语义记忆查询),用 pi.registerCommand() 增加斜杠命令,用 pi.registerProvider() 接入新模型。
  • 拦截与改写生命周期:通过 pi.on(...) 订阅关键节点。例如在 tool_call 放行或返回 block: true 拦截高危命令;在 tool_result 附加 LSP 类型报错;在 context 与 session_before_compact 裁剪上下文或接管压缩;在 turn_end / agent_end 采集追踪链路或提取记忆。
  • 接管交互界面与持久化:通过 ctx.ui 在终端渲染自定义确认弹窗、状态栏与浮层组件,并用 pi.appendEntry() 把扩展状态持久化进会话文件。

3. 快速安装与试用方式

全局安装 Pi(要求 Node.js 22.19 及以上)
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
安装社区扩展包(写入 ~/.pi/agent/settings.json)
pi install npm:pi-mcp-adapter
仅本次会话临时挂载一个扩展而不改全局配置
pi -e npm:cc-safety-net
  • 安装项目级扩展可加 -l 参数写入 .pi/settings.json,Pi 会在首次进入目录时触发 project_trust 信任确认,未经授权不会自动执行仓库自带代码。
  • 本地调试自己写的扩展时,直接把文件放到 ~/.pi/agent/extensions/ 或 .pi/extensions/,改完在会话内敲 /reload 即可热重载。

4. 按当前工程痛点选第一站

装好极简内核后,不必一次性堆满插件。直接从日常编码中最常卡住的环节切入,先装 1 到 2 个关键扩展试用。

当前遇到的问题 优先查看方向 首个参考包
MCP 服务过多导致上下文膨胀、Token 消耗失控 01 接外部世界 pi-mcp-adapter
担心 AI 在本地终端执行高危破坏性命令或越权读写 03 安全与权限 cc-safety-net
长对话后记忆丢失、反复重复上下文 04 记忆与上下文经济 context-mode
改动前缺乏结构化计划审阅与确认流程 05 计划、评审与人机交互 @narumitw/pi-plan-mode
重构多文件时缺乏 LSP 类型校验与快速索引反馈 06 代码智能 pi-lens
希望跑持续迭代任务或基于 Pi 二次封装桌面与多端应用 10 二开形态与底座 oh-my-pi

5. 延伸实测与版本脉络

如果准备深入上手体验或了解 Pi 1.0 以来对 MCP Codemode 与 Pi Durable 长任务底座的架构演进,可直接阅读已发布的 3 篇实操与版本解析。

  • kuhung 博客实操

    Pi 入门笔记:比 Codex 更自由,但也更折腾

    从日常编码体验切入,记录 Pi 的命令行习惯、常用指令、多模型切换与本地项目配置细节。

    阅读《Pi 入门笔记》全文

    适合从 Claude Code / Codex 刚切过来准备上手试跑的读者
  • Vibe Coding 入门专题

    Pi Agent 1.0 与 1.1 深度解析:MCP 接入、Codemode 沙箱与选型指南

    解析 Pi 1.0 对 MCP 的立场演进、QuickJS Codemode 沙箱省 Token 原理、Pi Durable 与横向选型。

    阅读《MCP 与 Codemode 解析》

    适合对照官方 Codemode 机制与扩展生态分工的读者
  • kuhung 博客演进观察

    Pi 1.0 与 1.1:一个靠说「不」出名的工具,开始说「是」了

    梳理 Pi 从极简 4 工具内核走向正式接纳 MCP、推出 Pi Durable 及引发精简分支讨论的完整时间线。

    阅读《Pi 1.0 与 1.1 演进观察》

    适合关注 Pi 设计哲学与社区分支争论脉络的读者

看完「Pi 扩展底座速览」后的下一步

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

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

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

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

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

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

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