📚 dg-ai-notes

冬瓜的 AI 学习笔记 · 当前重点：Pi-Agent SDK 深度教程

🤔 Pi-Agent 是什么？为什么要学它？

Pi-Agent 是 @earendil-works 开源的 Agent SDK，定位是生产级 AI Agent 的运行时底座。

它不是玩具框架，而是一套真正能上线的 Agent 工程参考实现——同类产品（Claude Code、Cursor、Cline 等）的内部架构都能在 Pi 里找到对应。看懂 Pi，等于看懂一个完整的 Agent SDK 应该怎么设计。

核心能力：

• 🔄 Agent Loop —— 模型循环调用、停止条件、错误防线，构建可靠的 LLM 运行循环
• 🛠️ 工具系统 —— 五步管道（定义/注册/拦截/执行/回收），让 LLM 长出受控的"手脚"
• 💬 消息系统 —— 内部 7 种自由表达，对外翻译成 3 种标准 Message，兼顾灵活性与兼容性
• 📡 事件驱动 —— 同步屏障 + 发布订阅，让扩展和宿主像神经系统一样协同
• 🗂️ 会话管理 —— Session Tree 让对话可存储、可恢复、可分叉
• 🧩 扩展机制 —— 工厂函数 + throwing stubs + 事件总线，让 Pi 能被改造成任何形态

谁该学：

• 想用 pi-agent SDK 自己搭 Agent 的开发者
• 想理解生产级 Agent "内部如何运转"的工程师
• 不满足于"会用 Claude Code"，想看懂 Harness 设计的好奇心党

📖 本教程：10 章拆解一个 Agent SDK

10 章系统拆解 Pi-Agent 的源码设计与实现，每一章都回答三个层次的问题：是什么（概念）、怎么做（源码分析）、为什么这样做（设计取舍）。

ch01 开篇总览    →  ch02 三层架构   →  ch03 Agent Loop  →  ch04 模型调用  →  ch05 工具系统
                                                                       ↓
ch06 消息系统    →  ch07 事件驱动   →  ch08 上下文工程  →  ch09 上下文压缩  →  ch10 会话管理

每一章都提供 TypeScript 版（与 Pi 原作同语言）和 Python 版（方便只熟悉 Python 的读者）双版本对照。

📚 三种阅读方式

TS 版路径：pi-agent/docs/typescript/
Python 版路径：pi-agent/docs/python/

🧪 补充材料：Agent Loop Notebook

notebooks/agent-loop.ipynb 是第 3 章 Agent Loop 的可执行实验场，可以单步运行、改参数、观察 loop 状态。

⚠️ 本教程主体为"阅读型"，配套实验代码（L00-L31 课程实战）暂未公开。Notebook 仅作 Agent Loop 章节的补充实验场。

🗺️ 内容地图

详见 Pi-Agent 教程 README。

🤝 贡献

发现 typo / 内容错误？欢迎：

• 提 Issue（建议用「内容勘误」模板）
• 直接发 PR 修

详见 CONTRIBUTING.md。

📜 License

• 代码：MIT
• 文档：CC-BY-SA-4.0（要求演绎作品同样开源，保护教程不被商业站抓走洗稿）

👋 关于作者

大家好，我是冬瓜，一个热衷于拆解 AI 工程的博主

如果你觉得内容有帮助，欢迎来我的社交账号找我玩，一起交流 AI / Agent / LLM 的工程实践——

抖音 · 冬瓜 AI 技术科普 · 源码拆解

B 站 · 冬瓜 长视频教程 · 直播 coding

🙏 Acknowledgments

• Pi-Agent 官方团队 —— 没有他们的开源，就没有这本笔记
• 所有引用的开源项目作者