深入理解 Pi Agent
面向 Java 开发者的 AI Agent 二次开发指南
"任何足够先进的技术，都与魔法无异。" —— 亚瑟·C·克拉克
但在源码面前，没有魔法。这本书就是你的魔法书。
这是什么
一本开源的中文技术书籍，逐行解析 Pi 的源码。
2025 年，AI Coding Agent 遍地开花。这些终端里的工具帮你写代码、修 bug、跑测试，像魔法一样。但当你试图理解它们如何工作时——所有教程都在讲"怎么用"，几乎没人讲"怎么造"。
这本书填补了这个空白。从 LLM 调用到工具执行，从会话管理到上下文压缩，把 AI Agent 的每一层机制拆开给你看。
不需要 TypeScript 背景。只需要你会 Java。
适合谁读
| 你是 | 你会得到 |
|---|---|
| Java 开发者，没用过 TypeScript | 用 Java 概念系统映射 TS，消除语言恐惧 |
| 用 AI 工具写代码，想知道原理 | 从 LLM 调用到工具执行的完整数据流 |
| 想基于 Pi 做二次开发 | Extension、Tool、Provider 的实战开发方法 |
| 想从零构建自己的 Agent | 基于 Agent Core 构建 300 行独立 Agent |
目录
| 章节 | 主题 |
|---|---|
| 第一章 | TypeScript for Java Developers —— 结构化类型、联合类型、async/await |
| 第二章 | Monorepo 结构与构建系统 —— Bun、Workspace、发布流程 |
| 第三章 | 统一的 LLM 调用抽象 —— 25+ Provider、streamSimple()、Registry 模式 |
| 第四章 | 消息体系 —— UserMessage → ToolResult 的完整流转 |
| 第五章 | TypeBox 与 Schema 驱动开发 —— 泛型、类型推导、运行时校验 |
| 第六章 | Agent Core —— 双层循环、事件驱动、Steering/FollowUp 队列 ★ 核心 |
| 第七章 | 工具系统 —— 7 大内置工具的完整实现 |
| 第八章 | 会话管理 —— JSONL 持久化、树形分支、fork/reset |
| 第九章 | 上下文压缩 —— Compaction 算法与触发策略 |
| 第十章 | 扩展系统 —— Extension API 的 24 种事件钩子 |
| 第十一章 | 从零构建你的 Agent —— 300 行代码理解最小核心 |
| 附录 | 术语表 · 设计模式索引 · FAQ |
全书约 4000 行，覆盖 Pi 全部核心架构。
Pi 架构全景
┌──────────────────────────────────────────────────────────┐
│ Layer 4: Run Modes │
│ interactive (TUI) │ print │ RPC │ SDK │
├──────────────────────────────────────────────────────────┤
│ Layer 3: Coding Agent Session │
│ 7 Tools │ Extensions │ Compaction │ Skills │ Sessions │
├──────────────────────────────────────────────────────────┤
│ Layer 2: Agent Core（5 文件, ~1600 行） │
│ Agent Loop │ State Machine │ Events │ Message Queue │
├──────────────────────────────────────────────────────────┤
│ Layer 1: AI（统一 LLM API） │
│ 25+ Providers │ streamSimple() │ TypeBox Schemas │
└──────────────────────────────────────────────────────────┘快速开始
在线阅读
👉 thinkpeace.github.io/pi-agent-for-java-devs
下载 PDF
本地阅读
bash
git clone https://github.com/ThinkPeace/pi-agent-for-java-devs.git配合源码食用更佳
bash
git clone https://github.com/badlogic/pi-mono.git
cd pi-mono && git checkout v0.70.6贡献
发现笔误、逻辑错误或有更好的解释方式？欢迎提 Issue 或 PR。
致谢
- Mario Zechner 创造了 Pi
- Pi 社区的每一位贡献者