Pi 是一个开源的 TypeScript AI Agent 框架，由 Mario Zechner（libGDX 作者）创建。
它的核心理念：LLM + Tools + A Loop —— 用最少的代码实现最大的灵活性。
Pi 是一个 Agent Harness（智能体运行框架），不是一个 AI 模型，而是让 AI 模型"动起来"的引擎。
把 LLM 比作大脑，Pi 就是身体——它负责：
- 把你的指令发给 LLM
- 接收 LLM 的回复和工具调用请求
- 执行工具（读文件、写代码、运行命令）
- 把执行结果反馈给 LLM
- 如此循环，直到任务完成
你（用户）
│
▼
┌─────────────────────────────────┐
│ Pi Agent Harness │
│ ┌───────┐ ┌──────┐ ┌──────┐ │
│ │ pi-ai │→│ core │→│ CLI │ │
│ └───────┘ └──────┘ └──────┘ │
│ ↕ ↕ ↕ │
│ LLM API 工具执行 终端UI │
└─────────────────────────────────┘
Pi 的设计哲学可以概括为三个词：极简、透明、可扩展。
| 维度 | Pi 的做法 | 为什么 |
|---|---|---|
| 极简 | agent-core 仅 ~1500 行代码、5 个核心文件 | 更少的代码 = 更少的 bug、更容易理解 |
| 透明 | 不隐藏 LLM 交互细节，所有事件可订阅 | 开发者需要知道 Agent 在做什么 |
| 可扩展 | Extension 是一等公民，不是后补丁 | 核心保持精简，功能通过扩展叠加 |
Pi 故意不做的事情：
- 没有内置权限系统（交给容器/沙箱）
- 没有 MCP 协议（工具通过 TypeScript 直接注册）
- 没有 Plan Mode（不内置规划能力）
- 没有子 Agent（不内置多 Agent 编排）
这不是功能缺失，而是刻意的取舍——核心只做引擎，其余交给扩展。
Pi 的源码以 monorepo 组织，包含以下核心包：
pi-mono/
├── packages/
│ ├── ai/ ← pi-ai：LLM 抽象层
│ ├── agent/ ← pi-agent-core：Agent 运行时
│ ├── coding-agent/ ← pi-coding-agent：编码 Agent CLI
│ ├── tui/ ← pi-tui：终端 UI 库
│ ├── server/ ← pi-server：HTTP 服务
│ ├── storage/ ← 存储抽象
│ └── evals/ ← 评估框架
├── package.json
└── tsconfig.json
核心只有前三个包，它们构成 Pi 的三层架构（下一章详解）。
@startuml
skinparam packageStyle rectangle
skinparam backgroundColor transparent
package "Claude Code" {
[MCP 协议] as mcp
[内置权限系统] as perm
[内置计划模式] as plan
[Hook 扩展] as hook
}
package "Pi Agent" {
[TypeScript 扩展] as ext
[Operations 接口] as ops
[无内置权限] as noperm
[无 MCP] as nomcp
}
package "Cursor" {
[IDE 集成] as ide
[Rules 系统] as rules
[专有协议] as prop
}
note bottom of "Pi Agent"
定位：平台（Platform）
核心极简，一切可替换
end note
note bottom of "Claude Code"
定位：产品（Product）
开箱即用，功能完整
end note
@enduml| 维度 | Pi | Claude Code | Cursor |
|---|---|---|---|
| 定位 | 平台/框架 | 产品/工具 | IDE 插件 |
| 扩展方式 | TypeScript Extension | Shell Hook | Rules |
| 工具协议 | 无（直接注册） | MCP | 专有 |
| 工具后端 | 可插拔 Operations | 固定本地执行 | 固定 |
| 权限系统 | 无（外部处理） | 内置审批 | IDE 级别 |
| 模型支持 | 30+ Provider | Anthropic | 多个 |
本系列文档按照以下顺序组织，每一章都以前一章的知识为基础：
@startuml
skinparam backgroundColor transparent
skinparam ActivityBackgroundColor #f8f9fa
skinparam ActivityBorderColor #dee2e6
start
:第0章 全景导读;
note right: 你在这里
:第1章 三层架构;
note right: 宏观理解
fork
:第2章 pi-ai 层;
note right: LLM 如何接入
fork again
:第3章 Agent Loop;
note right: 引擎如何运转
end fork
:第4章 工具系统;
note right: Agent 的"手"
:第5章 消息系统;
note right: Agent 的"语言"
:第6章 事件流;
note right: Agent 的"神经"
:第7章 上下文工程;
note right: Agent 的"记忆"
:第8章 会话管理;
note right: Agent 的"历史"
:第9章 扩展系统;
note right: Agent 的"成长"
:第10章 Provider 与认证;
note right: 深入：认证怎么解析
fork
:第11章 Session 树与上下文构建;
note right: 深入第8章
fork again
:第12章 Compaction 内部机制;
note right: 深入第7章
end fork
:第13章 SDK 与嵌入集成;
note right: 把 Pi 当库用
:第14章 术语表;
note right: 速查手册
stop
@enduml前 9 章是主干，建立从抽象层到扩展系统的完整认知；第 10–13 章是深入篇，往主干的关键节点再钻一层（认证、会话树、压缩、嵌入集成），可按需选读。
建议学习方式：
- 第一天：读完第 0-3 章，建立全局认知
- 第二天：读完第 4-6 章，理解核心机制
- 第三天：读完第 7-9 章，掌握高级特性
- 进阶：按兴趣挑第 10-13 章深入；第 14 章术语表随时速查
每章末尾有"检查清单"，确认自己理解后再进入下一章。
下一章：第一章 · 三层架构 — Pi 的骨架是怎么搭的