源码篇第1章 地图的比例尺——pi-mono ​

小A读完概念篇,信心满满地打开了 pi-mono。三分钟后,他盯着屏幕发呆:packages/ 下面躺着十几个目录,ai、agent、tui、coding-agent、protocol……他随手点开一个,又是几百个文件。
“老Z,”他喊道,“这地图也太大了。我该从哪个目录开始?”
老Z走过来,看了一眼屏幕,反问:“概念篇留下的问题是什么?”
“模型、循环、会话和终端各自的边界,在一套真实工程里究竟落在哪里。”小A背得很熟。
“对。你不是来‘读完 Pi’的,是来验证这几个边界的。”老Z说,“所以先别按目录猜,先固定地图的比例尺,再画主路径。”
本篇的已确认事实全部以上游 pi 仓库(github.com/earendil-works/pi,2026-09 由 badlogic/pi-mono 迁移而来)的标签 v1.0.0 为准,提交 a13d35a742c6ef8462812a28fbe1d8c8b7431c32,提交日期 2026-10-01。本书沿用 pi-mono 这个名字指这个 monorepo。下列八个包的 package.json 版本均为 1.0.0,而根 package.json 的 monorepo 版本是 0.0.3,不能混用。本书仓库的 pi/ 目录是这个标签的快照,另加了中文注释,路径和符号与上游一致,行号会因注释而偏移。
这个“八个”是本书的阅读范围,不是根 workspace 的总数:packages/ 下共有 13 个包,另外五个是 chord、codemode、durable、mcp、telemetry。chord 与 telemetry 只在用到时点名;codemode 与 mcp 在附录10、附录11 细读;durable 是源码篇第13章的专章对象。根 workspace 还包含扩展示例;packages/evals 是私有工作区包,不是发布包。
Pi 1.0 带来的七项产品变化 ​
小A问:“既然源码基线是 v1.0.0,这一版给使用者增加了什么?”
老Z说:“先看 pi-coding-agent 的 1.0.0 发布说明。它把七项产品变化列在 New Features 下。这里总结的是 1.0 发布时公布的亮点,不表示每项底层能力都在 1.0 才首次出现;例如 Codemode 和 MCP 在更早的版本里已经出现,1.0 继续改进了它们。”
| 1.0 发布亮点 | 具体变化 | 继续阅读 |
|---|---|---|
| 全屏终端界面 | 交互界面默认使用全屏模式;设 tuiMode: "regular" 可恢复普通终端滚屏。 |
源码篇第6章 终端;终端设置 |
| 更精简的 Codemode | 发布说明称默认工具配置下提示词约减少 40%,并改进错误信息,让模型能看到缺失名称的近似项和修复方向。这个比例是发布说明给出的概述,不是所有模型、工具组合都保证的固定值。 | Codemode 文档 |
| 在 Codemode 中生成图像 | 脚本可通过 models.generateImages() 调用图像模型,使用当前会话凭据;生成结果可由 image() 交回模型。 |
Codemode 图像生成 |
| Radius 登录 | /login 可登录 Radius,并接着配置它提供的 MCP server。 |
Provider 文档 |
| Anthropic 复制授权码登录 | 浏览器在另一台机器上时,可从授权页面复制代码并粘贴回 Pi,适用于远程或无头环境。 | 交互式认证 |
| 加固 MCP OAuth | 可指定授权服务器元数据地址;按 RFC 9207 校验授权响应中的 iss;凭据按 server 名称和 URL 区分;追加权限时保留已授予的 scope。 |
MCP OAuth 文档 |
| 只显示启动标题 | quietStartup: "header" 保留版本号和快捷键提示,同时隐藏模型范围与已加载资源列表。 |
终端设置 |
“这七项主要改变交互、模型能力接入和认证体验。”老Z说,“架构层还有一项需要单独记:@earendil-works/pi-durable 在 1.0 首次发布;同一版把实验性 harness 从 pi-agent-core 移除,作为破坏性 API 变更,将耐久会话能力交给 pi-durable。这是包边界调整,不是上面七项 CLI 功能之一,也不表示 Pi 不再支持耐久会话。”(durable 发布记录;agent-core 变更记录)
源码篇后续会在源码篇第5章、源码篇第6章和源码篇第8章解释会话、终端与扩展边界。本节先给出版本地图;要核对完整范围和每条说明,应回到固定标签 v1.0.0 的各包 changelog 与文档。
先固定地图的比例尺 ​
小A:“八个包……是不是八个独立程序?”
“不是。”老Z说,“工作区名和发布包边界能证明可独立导入的单元,不能证明运行时一定独立进程。先读包元数据和导出,再顺着一次输入的控制流找证据。”
比喻:地图的比例尺
先定“一厘米代表多少公里”,地图才不误导。八个包是本书的阅读比例尺,不是仓库的全貌,更不是八个独立进程。
本书所说“八个包”是下表选取的八个产品/基础范围包。包的职责来自其 package.json 的名称、描述、依赖和导出;描述是维护者声明,不是对全部代码行为的证明。
| 包 | npm 包名 | 可确认的边界证据 | 本书沿它追什么 | 暂不在本章断言 |
|---|---|---|---|---|
packages/ai |
@earendil-works/pi-ai |
有根、api/*、providers/* 等导出 |
模型、认证、流适配 | 各厂商服务质量 |
packages/agent |
@earendil-works/pi-agent-core |
只依赖 pi-ai,只有根导出 |
Agent 与循环 |
会话存储(已不在本包) |
packages/tui |
@earendil-works/pi-tui |
零内部依赖的终端 UI 包 | 组件与渲染 | Agent 决策 |
packages/coding-agent |
@earendil-works/pi-coding-agent |
pi 二进制入口,依赖 9 个内部包 |
命令行装配、会话、压缩、工具与扩展 | 所有扩展行为 |
packages/protocol |
@earendil-works/pi-protocol |
传输中立的 CBOR 协议包,依赖 chord |
帧、信封 schema、版本 | 网络可靠性 |
packages/client |
@earendil-works/pi-client |
依赖 chord、pi-protocol |
远程客户端连接与请求 | 服务端策略 |
packages/server |
@earendil-works/pi-server |
描述为 experimental,依赖 chord、pi-protocol |
握手、请求路由、会话附着 | 生产部署保证 |
packages/evals |
@earendil-works/pi-evals |
私有评测工作区包 | harness、对照实验与 judge | 产品质量结论 |
小A的目光停在 coding-agent 那行:“它依赖九个内部包?那 agent 呢?”
“agent 只直接依赖 AI。”老Z说,“这也是这张表里最容易跳过的一点:通用循环被设计成不必直接知道终端、远程协议或会话文件。v1.0.0 还把原来放在 agent 包里的实验性 harness 整个移走了,会话和压缩落到了 coding-agent。由此可以推断,通用循环是独立于产品外壳的;但不能由依赖图推出任何一个产品都必须以同一种方式持久化会话。”
本章其余小节为付费内容
登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。