Pi Agent SDK 高级课程

课程目标

这组文章面向高级工程师，目标是从 Pi Agent SDK 的实际使用进入源码阅读，再进一步理解如何基于 Pi 构建接近 Codex / Claude Code 工作流能力的 coding agent harness。

文档不会把每节课写成 API 列表，而是按“结论、入口问题、心智模型、源码推演、课堂练习、掌握标准、课后习题”的结构组织。第 1 到第 18 课已经把原来的位置索引改成文内可读的省略版源码，读者可以先理解机制，再到配套材料中精读。

配套材料

• 课程配套有一个本地 lab，用来承载每节课的 starter、练习和阶段项目。
• 课程配套有一份 Pi 源码快照，用来保证源码阅读时版本稳定。
• 文章正文以机制和省略版源码为主；需要动手时，先根据课程标题进入对应 starter，再对照文中的代码形状理解主线。
• 第 1 到第 18 课已经改为“省略版源码推演”写法：读者不打开本地源码，也能看到主要代码形状和职责边界。

阶段一：对标与体系认知

• 第 1 课：Coding Agent 产品解剖
• 第 2 课：Pi 项目结构总览

阶段二：从 SDK 使用到 Agent Harness 心智

• 第 3 课：SDK 心智模型
• 第 4 课：第一个 SDK 程序
• 第 5 课：流式事件与可观测性
• 第 6 课：模型与认证配置
• 第 7 课：内置工具与安全边界
• 第 8 课：自定义工具开发
• 第 9 课：上下文与行为控制
• 第 10 课：会话管理与任务连续性
• 第 11 课：SDK 小项目整合
• 第 12 课：从 SDK 过渡到源码

阶段三：源码阅读与核心 Runtime

• 第 13 课：LLM Provider 层
• 第 14 课：Agent Loop
• 第 15 课：Tool System 源码
• 第 16 课：Session 持久化源码
• 第 17 课：ResourceLoader 源码
• 第 18 课：Runtime Services

阶段四：魔改成高级 Coding Agent

• 第 19 课：权限与安全模型
• 第 20 课：沙箱与 Worktree
• 第 21 课：Subagent 架构
• 第 22 课：Planner 与任务分解
• 第 23 课：PR 工作流
• 第 24 课：Code Review Agent
• 第 25 课：Long-running Task Engine
• 第 26 课：MCP 与外部工具集成

阶段五：产品化、评测与可靠性

• 第 27 课：Agent 评测体系
• 第 28 课：可观测性与 Trace Replay
• 第 29 课：Prompt 与系统指令工程
• 第 30 课：可靠性工程
• 第 31 课：发布与插件生态
• 第 32 课：毕业项目评审

学习方式

建议每节课按以下顺序学习：

1. 先读“入口问题”和“心智模型”，建立本节课要解决的问题。
2. 按源码推演和课堂练习从浅到深推进，不急着读完整源码。
3. 在本地 lab 中运行或阅读对应示例。
4. 再回到 Pi 源码快照中精读文中提到的机制。
5. 完成一题实践题和一题思考题。