Skip to content

Commit 59d1dcc

Browse files
Albert-PZYclaude
Albert-PZY
and
claude
committed
docs: Pi Agent 架构教学文档与阅读页面
基于 Pi 官方源码（earendil-works/pi）整理的 11 章教学文档， 面向 AI Agent 开发初学者，逐层拆解框架架构。 文档结构： - 00-02 章：全景导读、三层架构、LLM 抽象层 - 03-06 章：Agent Loop、工具系统、消息系统、事件流 - 07-09 章：上下文工程、会话管理、扩展系统 - 10 章：术语表（60+ 条目按逻辑分组） 阅读页面（index.html）： - 单文件实现，无构建步骤 - 暗/亮色主题切换，warm tone 配色 - 代码高亮 + PlantUML 在线渲染 - 侧边栏导航、阅读进度、键盘快捷键 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
0 parents  commit 59d1dcc

17 files changed

Lines changed: 3866 additions & 0 deletions

‎.claude/launch.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"version": "0.0.1",
3+
"configurations": [
4+
{
5+
"name": "docs-server",
6+
"runtimeExecutable": "npx",
7+
"runtimeArgs": ["serve", "-l", "3456", "-C"],
8+
"port": 3456
9+
}
10+
]
11+
}

‎.github/workflows/deploy.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: Deploy to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
# 允许一次并发部署，不取消进行中的发布
14+
concurrency:
15+
group: pages
16+
cancel-in-progress: false
17+
18+
jobs:
19+
deploy:
20+
runs-on: ubuntu-latest
21+
environment:
22+
name: github-pages
23+
url: ${{ steps.deployment.outputs.page_url }}
24+
steps:
25+
- name: Checkout
26+
uses: actions/checkout@v4
27+
28+
- name: Setup Pages
29+
uses: actions/configure-pages@v5
30+
31+
- name: Upload artifact
32+
uses: actions/upload-pages-artifact@v3
33+
with:
34+
path: '.'
35+
36+
- name: Deploy to GitHub Pages
37+
id: deployment
38+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Pi 官方源码克隆（81M，自带 .git，仅作本地参考，不入库）
2+
pi-src/
3+
4+
# 工具产物
5+
.playwright-mcp/
6+
.zcode/
7+
node_modules/
8+
9+
# 本地配置
10+
.claude/settings.local.json
11+
12+
# 系统文件
13+
.DS_Store
14+
Thumbs.db

‎.nojekyll‎

Whitespace-only changes.

‎README.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Pi Agent 架构教学
2+
3+
> 一份面向 AI Agent 开发初学者的 [Pi Agent](https://github.com/earendil-works/pi) 架构学习文档，基于官方源码逐层拆解。
4+
5+
**在线阅读** → https://albert-pzy.github.io/learn-pi-agent/
6+
7+
## 这是什么
8+
9+
Pi 是 Mario Zechner（libGDX 作者）开源的 TypeScript AI Agent 框架，核心理念是 **LLM + Tools + A Loop**——用最少的代码实现最大的灵活性，`agent-core` 仅约 1500 行。
10+
11+
本文档从源码出发，用 11 个章节讲清 Pi 的完整架构，目标是**两三天内建立完整心智模型**：不只讲"怎么用"，更讲"为什么这么设计"。
12+
13+
## 章节目录
14+
15+
| 章节 | 主题 | 核心内容 |
16+
|------|------|----------|
17+
| [00](docs/00-overview.md) | 全景导读 | 设计哲学、Monorepo 结构、学习路线 |
18+
| [01](docs/01-three-layers.md) | 三层架构 | pi-ai / agent-core / coding-agent 的垂直分离 |
19+
| [02](docs/02-pi-ai.md) | LLM 抽象层 | Provider 抽象、`stream()`、懒加载、跨厂商兼容 |
20+
| [03](docs/03-agent-loop.md) | Agent Loop | 双循环引擎、Steering、工具五步生命周期 |
21+
| [04](docs/04-tool-system.md) | 工具系统 | Operations 接口、环境解耦、`Result` 类型 |
22+
| [05](docs/05-message-system.md) | 消息系统 | `AgentMessage` vs `Message`、最晚转换策略 |
23+
| [06](docs/06-event-stream.md) | 事件流 | EventStream、事件类型全表、背压处理 |
24+
| [07](docs/07-context-engineering.md) | 上下文工程 | Compaction 压缩、分支摘要、动态 System Prompt |
25+
| [08](docs/08-session-management.md) | 会话管理 | Session Tree、JSONL 存储、Fork 分叉 |
26+
| [09](docs/09-extension-system.md) | 扩展系统 | Skills / Extensions / Prompt Templates |
27+
| [10](docs/10-glossary.md) | 术语表 | 60+ 术语按逻辑分组速查 |
28+
29+
每章包含源码示例、PlantUML 架构图、检查清单，章节之间环环相扣。
30+
31+
## 本地运行
32+
33+
```bash
34+
npx serve -l 3456 -C
35+
```
36+
37+
浏览器打开 http://localhost:3456/
38+
39+
## 阅读页面特性
40+
41+
- 暗 / 亮色主题切换，warm tone 配色，适合长时间阅读
42+
- 侧边栏导航 + 底部上下章跳转 + 正文内链跳转
43+
- 代码块语法高亮、PlantUML 图在线渲染
44+
- 阅读进度指示、回到顶部
45+
- 快捷键 `Ctrl + ←/→` 切换章节
46+
47+
## 目录结构
48+
49+
```
50+
.
51+
├── index.html # 文档阅读器（单文件，无构建步骤）
52+
├── docs/ # 教学文档 Markdown 源文件
53+
│ ├── 00-overview.md
54+
│ └── ...
55+
└── .github/workflows/
56+
└── deploy.yml # 推送到 main 自动部署 Pages
57+
```
58+
59+
> `pi-src/`（Pi 官方源码克隆）不入库，需要对照源码时自行 clone：
60+
> ```bash
61+
> git clone https://github.com/earendil-works/pi.git pi-src
62+
> ```
63+
64+
## 参考资料
65+
66+
- [earendil-works/pi](https://github.com/earendil-works/pi) — Pi 官方仓库
67+
- [pi.dev](https://pi.dev) — 项目官网与文档
68+
69+
## License
70+
71+
文档内容 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)，代码 MIT。

‎docs/00-overview.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# 第零章 · Pi Agent 全景导读
2+
3+
> Pi 是一个开源的 TypeScript AI Agent 框架，由 Mario Zechner（libGDX 作者）创建。
4+
> 它的核心理念：**LLM + Tools + A Loop** —— 用最少的代码实现最大的灵活性。
5+
6+
---
7+
8+
## 0.1 Pi 是什么
9+
10+
Pi 是一个 **Agent Harness**（智能体运行框架），不是一个 AI 模型，而是让 AI 模型"动起来"的引擎。
11+
12+
把 LLM 比作大脑，Pi 就是身体——它负责：
13+
14+
- 把你的指令发给 LLM
15+
- 接收 LLM 的回复和工具调用请求
16+
- 执行工具（读文件、写代码、运行命令）
17+
- 把执行结果反馈给 LLM
18+
- 如此循环，直到任务完成
19+
20+
```
21+
你（用户）
22+
│
23+
▼
24+
┌─────────────────────────────────┐
25+
│ Pi Agent Harness │
26+
│ ┌───────┐ ┌──────┐ ┌──────┐ │
27+
│ │ pi-ai │→│ core │→│ CLI │ │
28+
│ └───────┘ └──────┘ └──────┘ │
29+
│ ↕ ↕ ↕ │
30+
│ LLM API 工具执行 终端UI │
31+
└─────────────────────────────────┘
32+
```
33+
34+
## 0.2 设计哲学
35+
36+
Pi 的设计哲学可以概括为三个词：**极简、透明、可扩展**。
37+
38+
| 维度 | Pi 的做法 | 为什么 |
39+
|------|----------|--------|
40+
| **极简** | agent-core 仅 ~1500 行代码、5 个核心文件 | 更少的代码 = 更少的 bug、更容易理解 |
41+
| **透明** | 不隐藏 LLM 交互细节，所有事件可订阅 | 开发者需要知道 Agent 在做什么 |
42+
| **可扩展** | Extension 是一等公民，不是后补丁 | 核心保持精简，功能通过扩展叠加 |
43+
44+
Pi **故意不做**的事情：
45+
46+
- 没有内置权限系统（交给容器/沙箱）
47+
- 没有 MCP 协议（工具通过 TypeScript 直接注册）
48+
- 没有 Plan Mode（不内置规划能力）
49+
- 没有子 Agent（不内置多 Agent 编排）
50+
51+
这不是功能缺失，而是刻意的取舍——**核心只做引擎，其余交给扩展**。
52+
53+
## 0.3 Monorepo 结构
54+
55+
Pi 的源码以 monorepo 组织，包含以下核心包：
56+
57+
```
58+
pi-mono/
59+
├── packages/
60+
│ ├── ai/ ← pi-ai：LLM 抽象层
61+
│ ├── agent/ ← pi-agent-core：Agent 运行时
62+
│ ├── coding-agent/ ← pi-coding-agent：编码 Agent CLI
63+
│ ├── tui/ ← pi-tui：终端 UI 库
64+
│ ├── server/ ← pi-server：HTTP 服务
65+
│ ├── storage/ ← 存储抽象
66+
│ └── evals/ ← 评估框架
67+
├── package.json
68+
└── tsconfig.json
69+
```
70+
71+
核心只有前三个包，它们构成 Pi 的**三层架构**（下一章详解）。
72+
73+
## 0.4 Pi 与同类工具的对比
74+
75+
```plantuml
76+
@startuml
77+
skinparam packageStyle rectangle
78+
skinparam backgroundColor transparent
79+
80+
package "Claude Code" {
81+
[MCP 协议] as mcp
82+
[内置权限系统] as perm
83+
[内置计划模式] as plan
84+
[Hook 扩展] as hook
85+
}
86+
87+
package "Pi Agent" {
88+
[TypeScript 扩展] as ext
89+
[Operations 接口] as ops
90+
[无内置权限] as noperm
91+
[无 MCP] as nomcp
92+
}
93+
94+
package "Cursor" {
95+
[IDE 集成] as ide
96+
[Rules 系统] as rules
97+
[专有协议] as prop
98+
}
99+
100+
note bottom of "Pi Agent"
101+
定位：平台（Platform）
102+
核心极简，一切可替换
103+
end note
104+
105+
note bottom of "Claude Code"
106+
定位：产品（Product）
107+
开箱即用，功能完整
108+
end note
109+
@enduml
110+
```
111+
112+
| 维度 | Pi | Claude Code | Cursor |
113+
|------|------|------|------|
114+
| 定位 | 平台/框架 | 产品/工具 | IDE 插件 |
115+
| 扩展方式 | TypeScript Extension | Shell Hook | Rules |
116+
| 工具协议 | 无（直接注册） | MCP | 专有 |
117+
| 工具后端 | 可插拔 Operations | 固定本地执行 | 固定 |
118+
| 权限系统 | 无（外部处理） | 内置审批 | IDE 级别 |
119+
| 模型支持 | 30+ Provider | Anthropic | 多个 |
120+
121+
## 0.5 学习路线图
122+
123+
本系列文档按照以下顺序组织，每一章都以前一章的知识为基础：
124+
125+
```plantuml
126+
@startuml
127+
skinparam backgroundColor transparent
128+
skinparam ActivityBackgroundColor #f8f9fa
129+
skinparam ActivityBorderColor #dee2e6
130+
131+
start
132+
:第0章 全景导读;
133+
note right: 你在这里
134+
135+
:第1章 三层架构;
136+
note right: 宏观理解
137+
138+
fork
139+
:第2章 pi-ai 层;
140+
note right: LLM 如何接入
141+
fork again
142+
:第3章 Agent Loop;
143+
note right: 引擎如何运转
144+
end fork
145+
146+
:第4章 工具系统;
147+
note right: Agent 的"手"
148+
149+
:第5章 消息系统;
150+
note right: Agent 的"语言"
151+
152+
:第6章 事件流;
153+
note right: Agent 的"神经"
154+
155+
:第7章 上下文工程;
156+
note right: Agent 的"记忆"
157+
158+
:第8章 会话管理;
159+
note right: Agent 的"历史"
160+
161+
:第9章 扩展系统;
162+
note right: Agent 的"成长"
163+
164+
:第10章 术语表;
165+
note right: 速查手册
166+
167+
stop
168+
@enduml
169+
```
170+
171+
**建议学习方式**：
172+
173+
1. **第一天**：读完第 0-3 章，建立全局认知
174+
2. **第二天**：读完第 4-6 章，理解核心机制
175+
3. **第三天**：读完第 7-9 章，掌握高级特性
176+
177+
每章末尾有"检查清单"，确认自己理解后再进入下一章。
178+
179+
---
180+
181+
**下一章**：[第一章 · 三层架构](01-three-layers.md) — Pi 的骨架是怎么搭的
182+

0 commit comments

Comments
 (0)