Pi 到底是什么
把 Pi 放回它真实的 monorepo：不是单一 CLI，而是模型层、runtime 与 coding harness 的组合。
5bc1c2c0一句话定义
Pi 是一个 self-extensible agent harness：它提供跨模型 API、通用 agent loop、会话与终端交互，再允许扩展在这些边界上注册工具、命令、事件与 UI。
如果模型是发动机，Pi 不是一辆焊死的车，而是一套裸露接口的底盘：你能换发动机、加仪表、改控制方式。
Pi monorepo 的主链是 pi-coding-agent → pi-agent-core → pi-ai，TUI 是交互适配层。CLI、SDK、JSON 与 RPC 是不同入口，共享会话能力。
根 README 将 coding-agent、agent-core、ai 列为三个核心包；coding-agent/package.json 也把 agent-core、ai、tui 声明为直接依赖。
README.md:13-35Pi Agent Harness packages
三个核心包
| 包 | 责任 | 不负责 |
|---|---|---|
pi-ai |
统一 provider/model/stream 消息语义 | 会话树、CLI 工作流 |
pi-agent-core |
loop、state、tool dispatch、runtime events | 持久会话文件、终端 UI |
pi-coding-agent |
CLI、Session、Context、Extension、内建工具 | 自己实现每个模型协议 |
pi-tui 提供差分渲染的终端组件；它重要，但不是 Agent 决策核心。
当前版本边界
本教材固定在 Pi v0.82.1 / commit 5bc1c2c0…。旧文章和旧 npm 页面可能使用 @mariozechner/pi-*；当前源码使用 @earendil-works/pi-*。这不是无关紧要的文字差异：复制旧示例会直接得到无法解析的 import。
packages/coding-agent/docs/security.md:1-53trust boundary
Pi 解决的不是“模型不够聪明”
它主要解决四类装配问题：
- 同一套上层逻辑如何面对不同模型 provider。
- 模型流式输出和工具调用如何组成稳定事件序列。
- 长对话如何保存、分支、压缩和恢复。
- 开发者如何在不膨胀核心的情况下改变系统行为。
Why / What / How / Trade-off
Why
Agent 产品常把 provider、loop、UI、权限和业务规则揉成一个难以替换的框架。Pi 把它们拆成窄层。
What
它提供一个可嵌入、可观察、可扩展的 coding-agent 基座，而不是一个固定工作流编排器。
How
低层统一消息与 streaming；中层持有 agent state 并执行 loop；高层投影 session、加载 resources 并适配 CLI/SDK/RPC。
Trade-off
“最小核心”意味着许多能力由扩展或宿主承担。初学者得到的默认政策更少，开发者得到的控制更多。
CONTRIBUTING.md:5-17minimal core