pi 全景与设计哲学

1. 背景#

截至 2026-10-09，仓库约有 11.3 万个 star，许可证为 MIT。数据来自 GitHub API⁴。

2. 设计哲学：做减法#

2.1 为什么要做 pi#

Mario 的出发点³：

• 现有的 harness（比如当时的 Claude Code）功能越来越臃肿，他用不上；
• 对模型交互缺乏可观测性；
• 框架会在用户看不到的地方往上下文里塞东西，让上下文工程（context engineering）变得非常困难，甚至无法实现。

他的核心主张是：精确控制进入模型上下文的内容，才能得到更好的输出，写代码时尤其如此³。

2.2 极简的系统提示词和 4 个工具#

• 系统提示词不到 1000 token，其中已经包含 4 个核心工具（read、write、edit、bash）的定义。Mario 的理由是，前沿模型经过大量强化学习，本身就理解编码 agent 是什么，不需要冗长的提示词³。
• 源码中的默认工具常量是 DEFAULT_TOOL_NAMES = ["read", "bash", "edit", "write"]⁷。另外还有 grep、find、ls、powershell 等内置工具，可以按需开启⁸。

2.3 “不做”清单#

整张表概括自 Mario 的博文³。

3. 架构：一组可以独立使用的分层包#

图中箭头表示依赖关系，A → B 即 A 依赖 B。这些依赖是笔者从各包 package.json 中提取的¹¹。

各包说明取自 README 的 Packages 表¹，其余包的说明取自各自 package.json 的 description 字段¹¹。

3.1 “轻量”到底指什么#

笔者用 find 加 wc -l 粗略统计了各包 src/ 目录下的 TypeScript 行数，排除了测试文件和自动生成的文件：

笔者理解：

• 轻量指的是核心抽象和设计哲学，而不是整个仓库的代码量。 agent 循环本身只有 2,500 行左右，读一个下午就能读懂；外围的功能都可以按需使用。
• 这和 DSH 的“核心轻、发行版重”是同一个思路。

4. 使用方式#

以上取自官方文档¹¹²¹³。

# 安装：官方安装器会锁定依赖版本；也可以用 npm 安装
curl -fsSL https://pi.dev/install.sh | sh
# 或者：npm install -g --ignore-scripts @earendil-works/pi-coding-agent

cd /path/to/project
pi   # 进入后用 /login 连接订阅账号或 API Key，然后直接给它布置任务

运行要求：Node.js 22.19 或更高版本¹。

5. 安全模型：默认不设防，由你负责隔离#

• pi 没有内置的权限系统来限制文件系统、进程、网络或凭据的访问。默认情况下，它以启动它的用户和进程的权限运行¹。
• 扩展在 pi 进程内运行，拥有相同的权限，所以只应该加载可信来源的扩展¹⁴。
• 官方给出了三种隔离方案¹：
  • Gondolin 扩展：内置工具在本地的 Linux micro-VM 里执行；
  • 普通 Docker：把整个 pi 进程放进容器；
  • OpenShell：在一个受策略控制的沙箱里运行 pi。

5.1 供应链加固：一个值得后端借鉴的实践#

pi 把 npm 依赖的变更视同代码变更，需要经过审查¹：

• 直接依赖锁定到精确版本；
• .npmrc 设置了 min-release-age=2，不使用当天才发布的依赖；
• 安装时一律使用 --ignore-scripts；
• CI 定期运行 npm audit signatures。

6. 与 OpenClaw 的关系#

pi 的 README 把 OpenClaw 列为“真实世界的集成案例”¹。Mario 在 2026-04-08 的文章里也提到：OpenClaw 基于 pi 构建，它的走红为 pi 带来了商业关注²。

笔者理解：这正是 pi 分层设计的价值所在。上层产品可以只用 pi-ai 和 pi-agent-core 搭出完全不同的应用，不必接受 pi CLI 的交互形态。

小结#

• pi 的关键词：极简核心、完全可观测、上下文由你掌控、功能靠扩展实现、多厂商。
• 学习路线建议：
  1. 先读 pi-ai，理解统一的消息和事件模型；
  2. 再读 pi-agent-core，大约 2,500 行，是最适合学习 agent 循环工程实现的源码之一；
  3. 最后读 pi-coding-agent，看完整的 harness 和扩展系统。

相关笔记#

• 1.1 从 LLM API 到 Agent Harness 的分层
• 4.2 pi-ai 统一多模型 API · 4.3 pi-agent-core 最小 Agent 运行时 · 4.4 pi-coding-agent SDK 与扩展系统
• 对照：5.1 DeepSeek Harness 全景 · 3.3 Claude Agent SDK

参考资料#