No MCP
不做协议适配层。替代方案:把 CLI 工具写成带 README 的技能,或者自己写扩展。源码里对应的是 skills.ts 与 registerTool()。
→ skills.ts 509 行 · registerTool 动态工具加载
pi coding agent · v0.85.1 · source reading · 2025.08 — 2026.09
pi 源码里被反复打磨的从来不是功能,而是让功能可以后装进来的那层接口。 60,334 行 TypeScript 里只有 8 个内置工具、4 条运行模式;其余绝大部分是资源发现、 事件分发、状态持久化与终端渲染——也就是「让插件彼此不自相矛盾」的那部分。
01 命题
README 的 Philosophy 一节是整份源码的钥匙。六条「No」不是营销话术,而是架构决策的清单: 每一条被砍掉的功能,都对应源码里一处留给外部的接口。读 pi 的源码,实际是在看 「一个功能如果不由核心提供,它需要哪些机制才能被安全地补上」。
不做协议适配层。替代方案:把 CLI 工具写成带 README 的技能,或者自己写扩展。源码里对应的是 skills.ts 与 registerTool()。
→ skills.ts 509 行 · registerTool 动态工具加载
不做子智能体。替代方案:用 tmux 开第二个 pi 实例,或者用扩展自己写一个。
→ examples/extensions/subagent/ · pi.exec()
不做权限弹窗。替代方案:跑在容器里,或者用扩展按你自己的环境写确认流程。
→ on("tool_call") 可拦截 · trust-manager.ts 245 行
不做计划模式、不做内置待办、不做后台 bash。三条都由扩展或外部工具(TODO.md、tmux)补位——官方示例里就带了完整的 plan mode 实现。
→ examples/extensions/plan-mode/ · todo.ts
02 四条支线
这个工程真正需要理解的主干只有四条。它们彼此解耦:把交互层整个删掉, 会话层仍然能被 RPC 与 SDK 完整驱动。
一个 AgentSession 类承载会话生命周期、模型与思考级别、压缩、分支、bash 执行,被三种外壳共用。它是唯一的真相源,其余都是 I/O。
agent-session 3,524 → session-manager 1,746 → settings-manager 1,371 → compaction 1,559
扩展、技能、提示模板、主题四类资源,从全局目录、项目目录、npm、git、本地路径五个入口汇入同一条发现管线,并统一做去重与作用域裁决。
package-manager 2,699 → resource-loader 1,097 → package-manager-cli 1,102
自研 TUI:差分渲染、43 个组件、三套内置主题。这里花了全仓最多的行数——因为终端 UI 没有现成的抽象可借。
interactive-mode 6,592 → components 10,010(43 文件) → theme 1,552
四种接入面:交互 TUI、print/JSON 事件流、stdio RPC(JSONL)、以及作为库被 import 的 SDK。会话层不知道自己在跟谁说话。
rpc-mode 821 → rpc-client 609 → print/json 230 → export-html 746
| 运行模式 | 触发条件 | I/O 面 | 主要消费方 |
|---|---|---|---|
| interactive | stdin 是 TTY | 全屏 TUI | 人类用户 |
| print / json | -p / --mode json / 非 TTY | stdout 文本或结构化事件 | 脚本、CI |
| rpc | --mode rpc | stdin/stdout JSONL | 编辑器插件、宿主程序 |
| sdk | import "@earendil-works/pi-coding-agent" | 进程内 API | 自己的应用 |
03 源码地图 · 八层
下面每一层都只依赖它上面的层。行数来自对 v0.85.1 发布包 sourcemap 的还原 (sourcesContent 保留了原始 TypeScript),因此这是真实源码而不是编译产物。
入口层 · 1,416 + 981 + 579 行
入口只做三件事:解析 argv、判定运行模式、把模式翻译成会话选项。真正的业务逻辑一行都不在这里—— 这是全仓最克制的一层。
src/cli/12 文件 · 1,416 行
解析参数、选择会话、处理凭证、信任门预检、启动横幅。会话文件的定位逻辑(绝对路径 / 相对路径 / 会话 ID)都在这里。
src/main.ts981 行
isTTY 判定 → interactive;否则 print;显式 --mode 覆盖。首次运行向导、主题初始化、信任提示都在这条路径上完成。
会话层 · 8,200 行
AgentSession 把「会话是什么」定义完整:消息、模型、思考级别、压缩、分支、bash 执行、扩展钩子。 三种运行模式都只是它的外壳。换掉界面不会动到状态,换掉状态必须重写界面。
core/agent-session.ts3,524 行
全部模式共用。事件订阅、状态访问、自动持久化、压缩触发、会话切换与分支都在这里收口。
core/session-manager.ts1,746 行
JSONL。每一行一个对象,靠 id/parentId 组成树,所以分支不需要复制文件,只需新增一条边。加载时自动把 v1 线性格式迁移到 v3。
core/settings-manager.ts1,371 行
全局与项目设置合并、资源的启用禁用、包的去重与覆盖规则,全在一个 1,371 行的合并器里。
扩展层 · 4,125 行 · 36 个事件
扩展系统只有五个文件,其中 1,797 行是类型定义。这不是过度设计:接口的精度就是生态的边界—— 每个事件的入参与返回值都被写死,扩展才知道自己能改什么、不能改什么。
core/extensions/types.ts1,797 行
36 个事件、9 类注册点、ExtensionContext 的全部能力。可拦截事件都带明确的返回值类型(如 tool_call 可返回 {block: true})。
core/extensions/loader.ts804 行
扩展不需要编译。加载器同时负责发现顺序、作用域、以及信任门之后的重新加载。
core/extensions/runner.ts1,286 行
谁先拿到事件、谁能阻止后续、扩展抛错时怎么隔离、工具调用如何被包装回传——分发语义都在这里定义。
呈现层 · 17,051 行 · 全仓最重
interactive-mode 一个文件 6,592 行,components 目录 43 个文件 10,010 行。终端没有 DOM, 没有布局引擎,没有现成组件库——于是这层成了整个工程里最大的一块手写代码。
modes/interactive/components/43 文件 · 10,010 行
树选择器 1,427 行、会话选择器 1,031、设置选择器 945、配置选择器 942——四个最大的组件全部是「让用户在终端里挑东西」。
modes/interactive/theme/3 文件 · 1,552 行
主题是可以热加载的 JSON,并且带校验器;扩展也能改主题、替换页脚、替换编辑器组件。
生态层 · 5,407 行
package-manager 2,699 行——比绝大多数 agent 的全部源码还长。它要处理三种来源(npm / git / 本地路径)、 两个作用域(全局 / 项目)、版本锁定、以及「同一个包在两个作用域出现时谁赢」。 生态的复杂度最终都压在安装器上。
core/package-manager.ts2,699 行
npm 走 ~/.pi/agent/npm/,git 克隆到 ~/.pi/agent/git/<host>/<path>,本地路径只登记不复制。身份判定分别用包名、去 ref 的仓库地址、解析后的绝对路径。
core/resource-loader.ts1,097 行
扩展、技能、提示模板、主题。约定目录优先,package.json 的 pi 字段其次,设置里的过滤器最后叠加。
package-manager-cli.ts1,102 行
把安装器的能力暴露成 4 组子命令,并负责把结果写回设置文件。
工具层 · 3,390 + 1,049 + 3,636 行
内置工具只有八个:read bash powershell edit write grep find ls; 默认只开前四个。其余四个是只读模式用的。工具集小到可以逐个读完——这正是扩展能被信任接管工具的前提(同名注册即覆盖内置)。
core/tools/ + utils/16 + 8 + 33 文件
每个工具都拆成「定义」与「本地实现」两半,并导出 *Operations 类型——把执行端做成可替换的接口,所以才有后面的「把内置工具路由进微虚拟机」这种扩展写法。 工具库 33 个文件 3,636 行,处理图片缩放、剪贴板、MIME、shell 转义、前端 matter 解析、syntax highlight 等。
04 机制深读
把源码读薄之后,真正有辨识度的机制只剩这些。它们共同构成了「核心不肯做的事,外部能安全接住」的条件。
AgentSession被interactive/print/json/rpc/sdk共同复用|换界面不动状态
事件面(36 个钩子,可拦截)+资源面(extensions / skills / prompts / themes)|动态行为 + 静态知识
loader(发现与信任)→runner(分发与生命周期)→wrapper(把扩展工具包成内置工具的样子)
trust.json按目录记忆→未信任时只加载全局与 CLI 扩展→项目资源全部搁置|245 行换来 1 个安全前提
Key mechanisms · 2026
docs/security.md 把话说得很直:pi 不带沙箱,扩展与工具都以当前用户权限运行, 项目信任(project trust)只是输入加载的守卫,不是隔离边界。理由也写在文档里—— 进程内的半吊子沙箱会被人误当成安全边界,而真正的隔离必须来自操作系统或虚拟机。 于是容器化、微虚拟机(Gondolin)这些方案被推到官方文档里,作为「怎么跑不可信代码」的答案。
这套设计的代价是可预测的:安装任何 pi 包等于给一段陌生代码 root 级信任。 官方文档的措辞是「Only install from sources you trust」,而不是「我们做了隔离」。
/tree 与 /fork 都是就地操作。core/compaction/ 1,559 行负责逻辑,会话管理器只管 I/O,压缩后重新加载会话。tool_call / tool_result / input / context / message_end / 六种 session_before_*。pi update --models),本地 models-store.json 只是缓存。provider-composer.ts 581 行做 provider 组合,model-resolver 782 行做解析与降级。models.json,或写一个 registerProvider 扩展。powershell 工具与 windows-self-update,这在同类工具里很少见。05 数字判读
60,334 行按目录切开,重心立刻显形:交互层与状态层吃掉一半以上, 真正「和模型对话」的部分反而很薄——因为它被外包给了同仓的 pi-ai 包。
单个文件更能说明问题:最大的 12 个文件合计 24,906 行,占全仓 41%。
| 文件 | 行数 | 它在解决什么 |
|---|---|---|
| modes/interactive/interactive-mode.ts | 6,592 | 整个终端交互循环 |
| core/agent-session.ts | 3,524 | 会话状态与生命周期 |
| core/package-manager.ts | 2,699 | 包的安装、更新、作用域裁决 |
| core/extensions/types.ts | 1,797 | 扩展接口的全部类型 |
| core/session-manager.ts | 1,746 | JSONL 会话树与迁移 |
| modes/interactive/components/tree-selector.ts | 1,427 | 会话树导航 UI |
| core/settings-manager.ts | 1,371 | 全局/项目设置合并 |
| core/extensions/runner.ts | 1,286 | 事件分发与生命周期 |
| modes/interactive/theme/theme.ts | 1,234 | 主题加载与热更新 |
| package-manager-cli.ts | 1,102 | install / remove / update / config |
| core/resource-loader.ts | 1,097 | 四类资源的发现管线 |
| modes/interactive/components/session-selector.ts | 1,031 | 历史会话浏览 |
发行包的构成则是另一套账:代码 19 MB,依赖 416 MB。bundle 被切成 48 个 chunk, 最大一个 3.9 MB;光是 Amazon Bedrock 的 Converse 流式实现就占 892 KB,比整个交互层还大。
把它放回时间轴:从 0.10.0 到 0.85.1 共 274 个版本,跨 284 天——平均每天发版一次。 同仓还有 259 个 GitHub release、315 个 tag、3,196 个 PR、6,199 个 issue。 这不是一个「稳定后冻结」的核心,而是一个被高频迭代仍保持分层不变的骨架。
06 判读
按「删掉它,架构是否还成立」来分级。
read。client 与 experimental/plugin 只在源码检出下可见,发布包里没有。docs/extensions.md(3,023 行)为准,比源码更权威。尾 结论
这 60,334 行真正在做的,是把「核心」与「生态」的边界写成可执行的类型。
8 个工具、36 个事件、4 类资源、3 种包来源——这些数字小得可以逐条读完。 但正是它们的精度,让一个不愿意内置功能的核心,仍然能被 10,000 多个社区包伸展开。 读这份源码的价值不在于学到某个技巧,而在于看到一个判断被坚持到底的样子: 功能会过时,接口的形状不会。