pi coding agent · v0.85.1 · source reading · 2025.08 — 2026.09

核心很小,
接口很大
the shape of the interface

pi 源码里被反复打磨的从来不是功能,而是让功能可以后装进来的那层接口。 60,334 行 TypeScript 里只有 8 个内置工具、4 条运行模式;其余绝大部分是资源发现、 事件分发、状态持久化与终端渲染——也就是「让插件彼此不自相矛盾」的那部分。
60,334行coding-agent 源码 · 206 文件
36扩展事件 · 9 类注册点
8/4内置工具 / 默认启用
274版本 · 0.10.0 → 0.85.1

01 命题

它先把功能否认了一遍

README 的 Philosophy 一节是整份源码的钥匙。六条「No」不是营销话术,而是架构决策的清单: 每一条被砍掉的功能,都对应源码里一处留给外部的接口。读 pi 的源码,实际是在看 「一个功能如果不由核心提供,它需要哪些机制才能被安全地补上」。

No MCP

不做协议适配层。替代方案:把 CLI 工具写成带 README 的技能,或者自己写扩展。源码里对应的是 skills.ts 与 registerTool()。

→ skills.ts 509 行 · registerTool 动态工具加载

No sub-agents

不做子智能体。替代方案:用 tmux 开第二个 pi 实例,或者用扩展自己写一个。

→ examples/extensions/subagent/ · pi.exec()

No permission popups

不做权限弹窗。替代方案:跑在容器里,或者用扩展按你自己的环境写确认流程。

→ on("tool_call") 可拦截 · trust-manager.ts 245 行

No plan mode / todos / bg bash

不做计划模式、不做内置待办、不做后台 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 面主要消费方
interactivestdin 是 TTY全屏 TUI人类用户
print / json-p / --mode json / 非 TTYstdout 文本或结构化事件脚本、CI
rpc--mode rpcstdin/stdout JSONL编辑器插件、宿主程序
sdkimport "@earendil-works/pi-coding-agent"进程内 API自己的应用

03 源码地图 · 八层

从入口到生态,一层压一层

下面每一层都只依赖它上面的层。行数来自对 v0.85.1 发布包 sourcemap 的还原 (sourcesContent 保留了原始 TypeScript),因此这是真实源码而不是编译产物。

  1. 入口层 · 1,416 + 981 + 579 行

    先决定「我在跟谁说话」

    入口只做三件事:解析 argv、判定运行模式、把模式翻译成会话选项。真正的业务逻辑一行都不在这里—— 这是全仓最克制的一层。

    src/cli/12 文件 · 1,416 行

    参数与会话选择

    解析参数、选择会话、处理凭证、信任门预检、启动横幅。会话文件的定位逻辑(绝对路径 / 相对路径 / 会话 ID)都在这里。

    接入

    src/main.ts981 行

    模式分派中枢

    isTTY 判定 → interactive;否则 print;显式 --mode 覆盖。首次运行向导、主题初始化、信任提示都在这条路径上完成。

    接入编排
  2. 会话层 · 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 行的合并器里。

    状态
  3. 扩展层 · 4,125 行 · 36 个事件

    把「可扩展」写成类型

    扩展系统只有五个文件,其中 1,797 行是类型定义。这不是过度设计:接口的精度就是生态的边界—— 每个事件的入参与返回值都被写死,扩展才知道自己能改什么、不能改什么。

    core/extensions/types.ts1,797 行

    接口本体

    36 个事件、9 类注册点、ExtensionContext 的全部能力。可拦截事件都带明确的返回值类型(如 tool_call 可返回 {block: true})。

    装载接口

    core/extensions/loader.ts804 行

    用 jiti 直接读 TypeScript

    扩展不需要编译。加载器同时负责发现顺序、作用域、以及信任门之后的重新加载。

    装载

    core/extensions/runner.ts1,286 行

    事件分发与生命周期

    谁先拿到事件、谁能阻止后续、扩展抛错时怎么隔离、工具调用如何被包装回传——分发语义都在这里定义。

    装载
  4. 呈现层 · 17,051 行 · 全仓最重

    终端 UI 没有捷径

    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. 生态层 · 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 行

    install / remove / update / config

    把安装器的能力暴露成 4 组子命令,并负责把结果写回设置文件。

    生态
  6. 工具层 · 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/settings.json · .pi/extensions · .pi/skills · .pi/prompts · .pi/themes · SYSTEM.md / APPEND_SYSTEM.md
始终加载AGENTS.md / CLAUDE.md 等上下文文件 · 全局扩展 · CLI 传入的 -e 扩展
非交互模式-p / --mode json / --mode rpc 不弹信任提示,由 defaultProjectTrust 与 --approve 决定
逃生口project_trust 事件:第一个返回明确 yes/no 的扩展拥有决定权

这套设计的代价是可预测的:安装任何 pi 包等于给一段陌生代码 root 级信任。 官方文档的措辞是「Only install from sources you trust」,而不是「我们做了隔离」。

会话与压缩

  • JSONL + id/parentId — 会话是树,不是列表;/tree 与 /fork 都是就地操作。
  • v1 → v3 自动迁移 — 历史会话加载时升级,旧格式无需人工处理。
  • 压缩是纯函数 — core/compaction/ 1,559 行负责逻辑,会话管理器只管 I/O,压缩后重新加载会话。

扩展的边界

  • 可拦截:tool_call / tool_result / input / context / message_end / 六种 session_before_*。
  • 可替换:编辑器组件、页脚、启动头、主题、自动补全、消息渲染器、工具本身。
  • 可注册:工具、命令、快捷键、旗标、provider、markdown 变换器。

多模型抽象

  • 模型目录是可刷新的远程数据(pi update --models),本地 models-store.json 只是缓存。
  • provider-composer.ts 581 行做 provider 组合,model-resolver 782 行做解析与降级。
  • 想接自定义 API 有两条路:写 models.json,或写一个 registerProvider 扩展。

刻意留下的粗糙面

  • 依赖体积不管:安装后 node_modules 416 MB,dist 19 MB。
  • 单文件巨型化:interactive-mode 6,592 行、agent-session 3,524 行,都没有继续拆。
  • Windows 是一等公民:内置 powershell 工具与 windows-self-update,这在同类工具里很少见。

05 数字判读

行数分布说明了优先级

60,334 行按目录切开,重心立刻显形:交互层与状态层吃掉一半以上, 真正「和模型对话」的部分反而很薄——因为它被外包给了同仓的 pi-ai 包。

core(会话·模型·资源·扩展)18,848 · 31.2%
interactive/components10,010 · 16.6%
interactive(除 components)7,041 · 11.7%
core/extensions4,125 · 6.8%
utils(33 个工具库)3,636 · 6.0%
src 根(入口与编排)3,421 · 5.7%
core/tools + renderers4,439 · 7.4%
modes/rpc + 主题 + export-html4,083 · 6.8%
cli + compaction + llama 扩展4,428 · 7.3%

单个文件更能说明问题:最大的 12 个文件合计 24,906 行,占全仓 41%。

文件行数它在解决什么
modes/interactive/interactive-mode.ts6,592整个终端交互循环
core/agent-session.ts3,524会话状态与生命周期
core/package-manager.ts2,699包的安装、更新、作用域裁决
core/extensions/types.ts1,797扩展接口的全部类型
core/session-manager.ts1,746JSONL 会话树与迁移
modes/interactive/components/tree-selector.ts1,427会话树导航 UI
core/settings-manager.ts1,371全局/项目设置合并
core/extensions/runner.ts1,286事件分发与生命周期
modes/interactive/theme/theme.ts1,234主题加载与热更新
package-manager-cli.ts1,102install / remove / update / config
core/resource-loader.ts1,097四类资源的发现管线
modes/interactive/components/session-selector.ts1,031历史会话浏览

发行包的构成则是另一套账:代码 19 MB,依赖 416 MB。bundle 被切成 48 个 chunk, 最大一个 3.9 MB;光是 Amazon Bedrock 的 Converse 流式实现就占 892 KB,比整个交互层还大。

node_modules(依赖)416 MB
dist(编译产物)19 MB
bundle/chunks(48 个)7.7 MB
└ 最大单 chunk3.9 MB
└ Bedrock 流式实现892 KB

把它放回时间轴:从 0.10.0 到 0.85.1 共 274 个版本,跨 284 天——平均每天发版一次。 同仓还有 259 个 GitHub release、315 个 tag、3,196 个 PR、6,199 个 issue。 这不是一个「稳定后冻结」的核心,而是一个被高频迭代仍保持分层不变的骨架。

06 判读

哪些是骨架,哪些是皮肉

按「删掉它,架构是否还成立」来分级。

五根骨架

  • agent-session.ts — 删掉它,三种模式各自要重写状态机。
  • extensions/{types,loader,runner} — 删掉它,pi 退化成又一个固定功能表。
  • session-manager.ts — 删掉它,就没有「会话是树」这件事。
  • resource-loader + package-manager — 删掉它,生态只能手工拷文件。
  • trust-manager.ts — 只有 245 行,却是前四者能被信任安装的前提。

可替换的皮肉

  • 整个 interactive 层 — 用 RPC 或 SDK 驱动时完全不需要它,却占全仓近三成。
  • 主题与渲染器 — 扩展可以整套换掉。
  • 内置工具 — 同名注册即覆盖,官方示例里就直接替换了 read。

看得见的取舍

  • 宁可让行数难看,也不做深层抽象 — 大文件、显式分支、很少的间接层。
  • 宁可不做功能,也不做半安全的安全 — 沙箱、权限弹窗、MCP 都属于这一类。
  • 把复杂度推到安装器 — 2,699 行的 package-manager 换来外部世界的整洁。

读源码时该警惕的

  • 版本演进快 — 每天一版意味着这里的行号与结构几周就可能失效,结论要带版本号读。
  • 实验面向源码开放 — client 与 experimental/plugin 只在源码检出下可见,发布包里没有。
  • 文档即接口 — 扩展能做什么,以 docs/extensions.md(3,023 行)为准,比源码更权威。

尾 结论

这 60,334 行真正在做的,是把「核心」与「生态」的边界写成可执行的类型。

8 个工具、36 个事件、4 类资源、3 种包来源——这些数字小得可以逐条读完。 但正是它们的精度,让一个不愿意内置功能的核心,仍然能被 10,000 多个社区包伸展开。 读这份源码的价值不在于学到某个技巧,而在于看到一个判断被坚持到底的样子: 功能会过时,接口的形状不会。