文档中心
最后更新：2026-10-10
从架构到落地，按主题浏览 Pi 的设计与用法。建议先读总体架构，再按需深入。Pi 是一套「可自我扩展」的 AI 编码代理：它的工具、扩展与资源可以在运行时按需加载，而不必重启内核，这让代理能像人一样边做边学、边扩展能力。
Pi 是什么
Pi Agent 由 earendil-works 开源，采用 MIT 协议。它不是又一个把提示词写死的编码脚本，而是一个有清晰分层、可长期演进的编码代理运行时。它的核心循环稳定而简单：准备上下文、请求模型、处理模型返回的工具调用、把结果写回会话、继续或为最终答案收尾。围绕这个内核，Pi 通过四个 npm 包（核心包详解）向外生长出模型接入、工具执行、终端界面与扩展能力。
理解 Pi 的关键是抓住核心概念：消息与流式事件如何沿核心循环向上回传、工具如何注册与回写、会话如何以 JSONL 树持久化并支持分支与断点续跑、上下文如何在接近窗口上限时自动压缩。把这些串起来，你就能读懂任意一层的代码。
在日常使用里，你会在仓库中启动编码代理，它读取代码、修改文件、执行命令并自我纠错，像一个常驻的结对程序员。由于模型与工具都在运行时被解耦，你可以随时切换到更强的模型或加装新工具，而无需改动 Pi 本身——这正是「可自我扩展」落到体验上的样子。
文档地图
总体架构
三层分工：交互层、运行层、核心循环。理解 Pi 如何把稳定内核与可变外设分离。
核心包
pi-ai、pi-agent-core、pi-coding-agent、pi-tui 各自的职责与边界。
核心概念
消息与流式事件、工具调用机制、会话/树/分支、上下文与压缩。
运行与调试
本地运行、测试、权限模型（Gondolin / Docker / OpenShell）与供应链加固。
模型供应商
OpenAI、Anthropic、Google、Bedrock、Vertex、Copilot 等接入方式。
官方仓库
源码、Issue、更新日志与上游文档，一切以仓库为准。
阅读建议
常见问题（FAQ）
Pi Agent 是什么？它和普通编码助手有什么不同？
Pi Agent 是 earendil-works 开源的、可自我扩展的 AI 编码代理，采用 MIT 协议。可自我扩展指工具、扩展与资源能在运行时按需加载，无需重启内核。它把稳定的核心循环与易变的外部世界（模型、UI、扩展）分离，因此换模型、换界面都不会动到运行时内核。
这套中文文档与官方 GitHub 仓库是什么关系？
文档由中文文档站基于上游 earendil-works/pi 仓库整理，用中文重新组织；权威更新、Issue 与源码仍以 GitHub 仓库为准。文档侧更侧重概念讲解与本地实践，适合中文读者系统学习。
我应该先读哪一篇文档？
建议先读本页的文档地图，再进入总体架构建立三层心智模型，之后按需深入核心包、核心概念、运行与调试、模型供应商。想快速跑通可先看快速上手。
文档里提到的教学版是做什么的？
教学版（how-pi-agent-works）用最小依赖还原 Pi 的三层结构：Express 后端、JSONL 会话存储、MockModel 与工具注册表。它帮助读者从零理解 Pi 的运行时，真实仓库在此基础上增加了流式、扩展加载与多供应商适配。
没有 API key 也能体验 Pi 的核心循环吗？
可以。pi-ai 提供 MockModel，在完全离线、无密钥的情况下也能跑通从请求模型到工具调用再到回写结果的完整循环，非常适合学习、演示与 CI。真实模型接入见模型供应商与运行调试两篇文档。
