Pi Deep Dive
THE SOURCE-GUIDED EDITIONv0.82.1

Understand Pi.
From agent loop
to source code.

一份不是从 README 改写而来的技术教材。沿着真实源码，理解 Pi 如何把模型、工具、状态与人类控制装配成一个可扩展的 Agent Harness。

开始学习 查看源码地图
pi — runtime traceLIVE MODEL

00:00.000agent_startsession 019f…

00:00.004turn_startcontext 18.2k

00:01.218message_updatethinking_delta

00:02.046tool_execution_startread

00:02.063tool_execution_end12.4ms

00:02.069turn_endtoolUse

LOOP
model → tool → context
01固定源码版本5bc1c2c0
02逐层解释直觉 / 工程 / 源码
03真实调用链paths + symbols
04可运行教程tool + extension
THE IDEA

Pi 的价值，不在于
替你隐藏复杂度。

它把复杂度放在你可以看见、插入和改变的位置。

模型调用在 pi-ai，循环与状态在 pi-agent-core，会话、CLI 和扩展在 pi-coding-agent。这不是“万能大脑”，而是一组克制的工程边界。

理解 Pi 的核心抽象
ARCHITECTURE AT A GLANCE

先看边界，再进文件。每一层只承担足够少的职责。

SYSTEM MAPPi 的四层边界
调用由上向下；事件、增量与结果由下向上返回。Extension 横切 coding-agent 层，不是独立沙箱。
ONE DAY PATH

从使用者
走到贡献者。

顺序设计为 6–8 小时的系统阅读。你可以跳读，但不需要预先理解 Agent。

01
Beginner

建立 Agent 心智模型

从一次回答，走向持续的感知—行动循环。

02
Developer

拆解 Pi Runtime

跟进消息、工具、事件与流式响应的真实调用链。

03
Architect

理解系统取舍

看懂 Session、Context、Extension 的边界为何这样划分。

04
Contributor

从源码开始构建

写一个 Tool，再写一个可以改变行为的 Extension。

TRUST THE SOURCE

每个结论，都有版本边界。

本教材分析的是 2026-07-26 的 Pi v0.82.1，固定在 commit 5bc1c2c0a6f0。旧的 @mariozechner/* 名称只作为历史说明；当前示例使用 @earendil-works/*。

阅读研究方法