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

小A和老Z俯看分层地图,用放大镜和空白尺聚焦一条橙色主路径,穿过溪流、环形小路与小屋。

小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?登录即解锁完整章节。