slug: pi-research
tags: [AI, Coding Agent, 开源, 调研, Mario Zechner, earendil-works, pi-mono]
date: 2026-06-17
Pi 调研：极简 4 工具 + 自我扩展 + Tree 会话，开源 Coding Agent 反向定义 Claude Code
极简不是简陋。Mario Zechner（libGDX 作者）做了一款不靠堆功能取胜的 Coding Agent，让 ” 工具不够用 ” 成为用户自己写扩展的理由。
写在前面
Claude Code、Cursor、Codex、Windsurf 这类 AI 编程工具越来越像 ” 全功能 IDE”：内置子智能体、Plan Mode、权限管理、LSP 集成、调试器……功能越多，工具层越臃肿，模型经常被格式、字符串匹配、上下文浪费等 ” 小问题 ” 拖垮。
Pi (pi-mono) 走了一条反方向的路：只给 4 个核心工具 + 一个干净的 Agent Harness，剩下的让用户和 Agent 自己扩展。这篇文章拆解它凭什么能用 1k tokens 的 system prompt 撑起一整套生产级 Coding Agent 体系。
特别值得一提的是，OpenClaw 的底层就基于 Pi 构建——这是 ”Pi 是底座、OpenClaw 是体验 ” 的双层结构。
一、它解决什么问题
| 维度 | 值 |
|---|---|
| 项目名 | Pi (pi-mono) |
| 维护方 | Mario Zechner（@badlogic）/ Earendil Works |
| 主仓库 | https://github.com/earendil-works/pi（原 badlogic/pi-mono 已迁移） |
| 官网 | https://pi.dev |
| 协议 | MIT |
| Stars | 11.1k+（截止 2026-06） |
| 最近 commit | 持续高活跃，2026-06 多 commit |
| 系统 prompt | <1000 tokens |
| 核心工具数 | 4（Read / Write / Edit / Bash） |
| 模型支持 | 15+ 提供商，数百个模型 |
| 主语言 | TypeScript |
一句话定位 ：极简、克制、自我扩展的开源 Coding Agent 框架。系统 prompt 极小，工具集极简， 功能靠用户和 Agent 自己构建。
二、核心维度 1：极简哲学 + 4 工具设计
Pi 的设计原则可以浓缩成一句话：“Primitives, not features”（给原语，不给功能）。
1. 只给 4 个核心工具
- Read — 读文件
- Write — 写文件
- Edit — 精确编辑
- Bash — 执行命令
不内置 ” 搜索整个仓库 ”” 调用 LSP”” 运行测试 ”——这些都通过 Bash 调用外部命令，或通过 Extension 注入。
2. 系统 prompt 不到 1k tokens
对比 Claude Code / Cursor 的 5k+ tokens system prompt，Pi 走的是 精瘦路线。小 prompt 的好处是：
- 便宜：每次 LLM 调用塞更少 context
- 快：命中缓存概率高
- 可控：用户能完整阅读、自己改
3. 用户能改的地方
| 配置文件 | 作用 |
|---|---|
AGENTS.md |
项目指令（启动时从 ~/.pi/agent/、父目录、当前目录加载） |
SYSTEM.md |
替换或追加默认 system prompt（per-project） |
models.json |
自定义 provider 和模型 |
| Extensions | TypeScript 模块，可访问工具、命令、快捷键、事件、TUI |
| Skills | 按需加载的能力包（带 prompt caching 友好） |
| Prompt Templates | Markdown 模板，/name 调用 |
4. 把所有 ” 功能 ” 做成可拼装
Pi 的官网原话：
Features that other agents bake in, you can build yourself. Extensions are TypeScript modules with access to tools, commands, keyboard shortcuts, events, and the full TUI.
官方仓库自带的 50+ 扩展示例（很多就是用户后续可以照抄的脚手架）：
subagent— 子智能体plan-mode— 计划模式permission-gate.ts— 权限网关protected-paths.ts— 路径保护ssh.ts— SSH 执行sandbox/— 沙箱custom-compaction.ts— 自定义上下文压缩- MCP 集成、自定义编辑器、status bar、overlay
这就是它的反向操作 ：Cursor 加功能靠团队写代码，Pi 加功能靠用户 写 Extension 或让 Agent 自己改自己。
三、核心维度 2：差异化能力（自我扩展 / Tree Session / 上下文工程）
1. 自我扩展：让 Agent 改自己
Pi 支持 ” 让 Pi 在运行中修改自己，加载后 /reload 立刻生效 ”。
# 让 Pi 加一个新工具
> Add a new tool that runs sqlx migrate and shows the result
# Pi 改自己的源码 → /reload → 继续干活官网原话：
Pi isn’t a sealed product. If you need a command, tool, provider, workflow, or UI tweak, just ask Pi to build it.
这种 ”让 AI 编辑自己的运行环境“ 的设计哲学，在 Claude Code / Cursor 是没有的——它们都把 Agent 当作 ” 产品 ” 封装起来，用户只能配置不能改。
2. Tree-structured, shareable history
会话以 树形结构 存储，不是线性列表：
/tree跳到任意历史点继续对话- 所有分支存 单文件
- 按消息类型过滤
- 条目可加书签
导出 / 分享：
/export # 导出 HTML
/share # 上传到 GitHub gist，生成可分享 URL示例会话：https://pi.dev/session/#0ea51497613daf7e1de28ee99950b074
3. 上下文工程（Context Engineering）
| 能力 | 描述 |
|---|---|
| AGENTS.md | 项目级指令，自动加载 |
| SYSTEM.md | 替换 / 追加 system prompt |
| Compaction | 接近 context 上限时自动摘要，完全可定制（按主题摘要 / 代码感知摘要 / 用不同模型） |
| Skills | 按需加载的 ” 能力包 ”，progressive disclosure 不爆 prompt cache |
| Prompt Templates | Markdown 模板，/name 展开 |
| Dynamic Context | Extension 注入：每轮前插消息、过滤历史、做 RAG、长期记忆 |
4. Steer / Follow-up
在 Agent 工作中可发消息：
- Enter = 发送 steering（打断当前工具队列）
- Alt+Enter = 发送 follow-up（等当前轮结束）
这种 ” 工作流不被打断 ” 的体验，是 Claude Code 早期版本没有的（后来加上了，但 Pi 是 native 支持）。
5. 15+ 提供商
Anthropic, OpenAI, Google, Azure, Bedrock, Mistral, Groq, Cerebras, xAI, Hugging Face, Kimi For Coding, MiniMax, OpenRouter, Ollama…
会话中 /model 或 Ctrl+L 切模型，Ctrl+P 翻收藏夹。
OAuth 和 API Key 两种认证。
四、四种运行模式
| 模式 | 用途 | 示例 |
|---|---|---|
| Interactive | 完整 TUI 体验 | pi |
| Print/JSON | 脚本调用 | pi -p "query" / --mode json 流式事件 |
| RPC | JSON over stdin/stdout，非 Node 集成 | 见 docs/rpc.md |
| SDK | 嵌入到自己的应用 | OpenClaw 就是真实例子 |
特别值得展开的是 RPC 模式 ——它让任何能发 stdin/stdout 的语言（Python/Go/Rust/Shell）都能把 Pi 当作 子进程嵌入。这是 OpenClaw 能 ” 换 UI 不换 Agent” 的关键。
五、对比 Claude Code / Cursor / OpenCode / Aider
| 维度 | Pi | Claude Code | Cursor | OpenCode | Aider |
|---|---|---|---|---|---|
| 协议 | MIT | 闭源 | 闭源 | MIT | Apache 2.0 |
| 形态 | CLI / SDK | CLI | GUI 编辑器 | CLI / Desktop | CLI |
| 内置工具数 | 4 | 10+ | 20+ | 30+ | 15+ |
| System Prompt | <1k tokens | ~5k+ | ~5k+ | 5k+ | 4k+ |
| 模型支持 | 15+ providers | Anthropic only | OpenAI + Anthropic | 75+ providers | OpenAI + Anthropic + 其它 |
| 子智能体 | Extension 提供 | 内置 | 内置 | 内置 | 无 |
| Plan Mode | Extension 提供 | 内置 | 内置 | 内置 | 无 |
| Tree Session | ✅ 原生 | ❌ | ❌ | ❌ | ❌ |
| 自我扩展 | ✅ 改自己 | ❌ | ❌ | ❌ | ❌ |
| LSP 集成 | Extension | 部分 | ✅ 内置 | ✅ 内置 | 部分 |
| DAP 调试器 | Extension | ❌ | 部分 | 部分 | ❌ |
| MCP 集成 | Extension | ✅ | ✅ | ✅ | 部分 |
| Token 优化 | 极简 prompt | 一般 | 一般 | 一般 | 较好 |
| 学习曲线 | 陡（要会写 Extension） | 缓 | 缓 | 中 | 中 |
结论：
- 选 Pi —— 你想 ” 自己掌控 Agent 的每一寸 ”、愿意写 TypeScript 扩展、追求最小 token 成本
- 选 Claude Code / Cursor —— 你想 ” 开箱即用 ”、不在乎体积、买的是体验
- 选 OpenCode —— 你想 ” 开源 + 完整功能 ” 两全
- 选 Aider —— 你想 ”Git 提交信息 + diff 风格 ” 工作流
Pi 真正的护城河不是功能，是 ” 极简哲学 + 自我扩展 ” 的设计取舍。Claude Code / Cursor 短期不会跟进这个方向，因为它们的商业模型依赖 ” 封装好的体验 ”。
六、实战：3 步跑通
1. 安装
# macOS / Linux
curl -fsSL https://pi.dev/install | sh
# 或 Bun 全局
bun install -g @earendil-works/pi-coding-agent
# Windows (PowerShell)
irm https://pi.dev/install.ps1 | iex2. 配置 API Key
export ANTHROPIC_API_KEY="sk-..."
# 或
export OPENAI_API_KEY="sk-..."
# 多 provider 见 models.json3. 启动 + 第一个任务
pi
# 进入 TUI 后
> 看一下当前目录的 package.json
> 加一个 zod 依赖
> 跑一下测试脚本调用模式：
pi -p " 找出所有 TODO 注释并按文件分组 "
pi --mode json -p " 重构 src/auth.ts 里的 try-catch" | jq .七、决策表（按场景推荐）
| 场景 | 推荐 | 理由 |
|---|---|---|
| 终端重度用户、写 TypeScript / Node 项目 | Pi | TUI 流畅，自我扩展 |
| 想要 IDE + AI 体验融合 | Cursor / OpenCode Desktop | GUI 是刚需 |
| Anthropic 死忠、不在乎体积 | Claude Code | 官方亲儿子 |
| 开源 + 完整功能、企业部署 | OpenCode | 75+ provider、Desktop/IDE/Terminal 三形态 |
| 老派 diff 风格 + Python / Shell | Aider | Git-first 工作流 |
| 想 ” 自己造 Agent” 研究学习 | Pi | 1k tokens prompt、SDK、RPC，入手最快 |
| 做 ”AI 编程工具 ” 二次开发 | Pi + OpenClaw 模式 | 上面跑 UI，下面接 Pi |
八、风险与坑
- 学习曲线陡 —— 想用好 Pi 必须会写 TypeScript Extension。普通用户上手成本比 Claude Code 高。
- 没有内置权限系统 —— Pi 跑起来就是用户进程的权限。 生产环境必须 用 Gondolin Extension / Docker / OpenShell 做沙箱（官方有 3 种模式文档）。
- 依赖治理严格 ——
.npmrc设了save-exact=true和min-release-age=2，新依赖要等 2 天。这是为了 供应链安全（防止 npm 同日 release 投毒），但牺牲了一点点灵活性。 - 新项目、自动关闭 issue —— “New issues and PRs from new contributors are auto-closed by default”（维护者每天 review）。社区贡献门槛略高。
- 极简 ≠ 简单 —— 4 个工具是哲学选择，不是简化。你需要花时间设计自己的 Extension / Skills，否则会感觉 ” 啥都没有 ”。
九、总结
最值得装的 3 个理由：
- 极简哲学 = 真省钱 —— 1k tokens 的 system prompt + 4 工具，每次 LLM 调用成本压到最低
- 自我扩展 = 真自由 —— 想要什么让 Pi 自己改自己，不被产品团队牵着走
- OpenClaw 实战验证 = 真能用 —— 不是 demo，https://github.com/OpenClaw/OpenClaw 整个产品都跑在 Pi 上
先试一周：
拿你最熟悉的 TypeScript / Node 项目跑起来，先用默认 4 工具干一周活，遇到 ” 想要 X 功能 ” 的瞬间，记下来——这就是你的第一个 Extension。
如果一周后你觉得 ” 我还是想要现成的 ”，Cursor / Claude Code 还在等你。
但如果你发现 ” 自己改 Agent 比改 IDE 爽 ”——恭喜，你已经上了 Pi 的船。
参考
- 官方仓库：https://github.com/earendil-works/pi（原 badlogic/pi-mono）
- 官网 / 文档：https://pi.dev / https://pi.dev/docs/latest
- Mario Zechner 解读 Pi 哲学：https://lucumr.pocoo.org/2026/1/31/pi/
- Harness Problem 深度文：https://blog.can.ac/2026/02/12/the-harness-problem/
- oh-my-pi 副线（11.1k stars）：https://github.com/can1357/oh-my-pi
- OpenClaw 集成示例：https://github.com/OpenClaw/OpenClaw
- Pi RFC 长期规划：https://rfc.earendil.com/keyword/pi/
- Pi 公开会话数据集：https://huggingface.co/datasets/badlogicgames/pi-mono