源码版本 v0.83.0

深入浅出 Pi

从 Agent Loop 到完整运行时

沿 earendil-works/pi 的固定源码版本，追踪模型适配、Agent Loop、工具执行、会话树、扩展系统与终端界面怎样组成一套可嵌入的 Agent 运行时，并明确已实现行为与 Harness v2 设计之间的边界。

开始阅读查看源码

查阅索引

abandoned branch summary: 压缩与回到旧分支怎样改变上下文
abort propagation: 重试、溢出与中止在哪一层收口
acceptance versus completion: RPC 模式如何把会话变成可控制进程
accepted mutation: 运行中改配置，什么时候才真正生效
active context usage: 自动压缩、重试与用量统计怎样协作
active leaf: JSONL 会话文件怎样记录一棵树
active leaf pointer: Session 保存的是树，不是一串消息
active run ownership: `Agent` 怎样把事件还原成状态
active tool set: 七个内置工具为什么默认只开四个
agent run: 两层循环为什么缺一不可
agent turn: 两层循环为什么缺一不可
AgentMessage: AgentMessage 为什么不能直接发给模型
allowlist and denylist: 七个内置工具为什么默认只开四个
API dispatch: 不同模型 API 怎样被压到同一接口
append log versus tree topology: Session 保存的是树，不是一串消息
append-only JSONL: JSONL 会话文件怎样记录一棵树
AppMode: 一个 pi 命令，四种运行方式
argument coercion: 工具执行前先经过哪些检查
assistant retry: 重试、溢出与中止在哪一层收口
auth resolution: 密钥与 OAuth 怎样落到一次请求
auto compaction: 自动压缩、重试与用量统计怎样协作
behavioral evaluation: Evals 怎样把 Agent 行为变成可检查结果
bind-mount write-through: Pi 没有内置沙箱，这意味着什么
bootstrap extension set: 扩展代码从哪里加载，信任边界在哪里
bounded streaming output: Bash 输出太长时，完整结果去了哪里
bracketed paste: 键盘输入怎样穿过终端协议到达编辑器
branch navigation: 压缩与回到旧分支怎样改变上下文
branch-scoped context: Session 保存的是树，不是一串消息
canonical path key: 读写文件时，Pi 怎样避免相互踩踏
capability clamping: 模型切换与设置热更新怎样保持一致
chained transform: Extension Runner 怎样串起事件与变换
command short circuit: 一条 Prompt 在调用模型前还要过多少关
compaction barrier: 压缩与回到旧分支怎样改变上下文
completion order: 并行工具为什么仍要保留原始顺序
context overflow recovery: 重试、溢出与中止在哪一层收口
context projection: JSONL 会话文件怎样记录一棵树
Context projection: 请求发出前，Context 还会经历什么
context token clamp: 请求发出前，Context 还会经历什么
continuation: 一次 Run 怎样停止、失败与继续
control plane: `AgentSession` 如何成为 Coding Agent 的控制面
cooperative abort: 一次 Run 怎样停止、失败与继续读写文件时，Pi 怎样避免相互踩踏
crash recovery boundary: 持久会话为什么还不等于持久运行
credential storage: 密钥与 OAuth 怎样落到一次请求
cross-model replay: 不同模型 API 怎样被压到同一接口
cumulative usage: 自动压缩、重试与用量统计怎样协作
current runtime state: 模型切换与设置热更新怎样保持一致
cwd-bound services: 启动阶段到底组装了什么不启动 TUI，怎样把 Pi 嵌进自己的程序
declaration merging: AgentMessage 为什么不能直接发给模型
default discovery: 不启动 TUI，怎样把 Pi 嵌进自己的程序
delayed persistence: JSONL 会话文件怎样记录一棵树
dependency defaults: `createAgentSession()` 怎样交出一个可运行会话
design versus shipped behavior: 怎样验证本册结论，并看清 Harness v2 的边界
drain point: Steering 与 Follow-up 不是同一种排队
durable conversation state: 持久会话为什么还不等于持久运行
dynamic models: 模型目录与 Provider Registry 各管什么
effective session cwd: 启动阶段到底组装了什么
entry projection: Session 保存的是树，不是一串消息
escape-sequence framing: 键盘输入怎样穿过终端协议到达编辑器
event projection: `AgentSession` 如何成为 Coding Agent 的控制面
event-reduced state: `Agent` 怎样把事件还原成状态
event-to-view projection: 流式消息与工具结果怎样出现在屏幕上
evidence hierarchy: 怎样验证本册结论，并看清 Harness v2 的边界
executable extension: 扩展代码从哪里加载，信任边界在哪里
extension event projection: Extension Runner 怎样串起事件与变换
external isolation boundary: Pi 没有内置沙箱，这意味着什么
final-line diff: Pi 为什么不用每次重画整个终端
fixed source version: 先固定版本，再谈 Pi 的架构
focused input routing: 键盘输入怎样穿过终端协议到达编辑器
follow-up queue: Steering 与 Follow-up 不是同一种排队
full redraw fallback: Pi 为什么不用每次重画整个终端
global defaults: 模型切换与设置热更新怎样保持一致
global settings: 配置、信任与资源从哪里进入
graceful stop: 一次 Run 怎样停止、失败与继续
grapheme-aware editing: 键盘输入怎样穿过终端协议到达编辑器
hardware cursor marker: TUI 组件、焦点与覆盖层怎样配合
hardware cursor projection: Pi 为什么不用每次重画整个终端
hook settlement: 运行中改配置，什么时候才真正生效
host ownership: 不启动 TUI，怎样把 Pi 嵌进自己的程序
I/O adapter: 启动阶段到底组装了什么
immediate tool outcome: 工具执行前先经过哪些检查
in-flight immutability: 一轮请求为什么需要快照与保存点
inner tool loop: 两层循环为什么缺一不可
input loading trust: Pi 没有内置沙箱，这意味着什么
input transformation: 一条 Prompt 在调用模型前还要过多少关
instance metadata: `pi-server` 管的是进程，还是 Agent
isolated AgentSession: Evals 怎样把 Agent 行为变成可检查结果
JSON event stream: 一个 pi 命令，四种运行方式
JSONL event stream: 同一场运行怎样投影成文本与 JSON
JSONL RPC protocol: 一个 pi 命令，四种运行方式
keyboard protocol negotiation: 键盘输入怎样穿过终端协议到达编辑器
lazy spill file: Bash 输出太长时，完整结果去了哪里
lazy stream setup: 流式响应怎样变成可消费事件
line-oriented component tree: TUI 组件、焦点与覆盖层怎样配合
listener settlement: `Agent` 怎样把事件还原成状态
live config versus request config: 一轮请求为什么需要快照与保存点
load-order precedence: 扩展代码从哪里加载，信任边界在哪里
logical branch: 恢复、分叉与切换会话不是同一个动作
Message: AgentMessage 为什么不能直接发给模型
migration boundary: `AgentHarness` 为什么没有包住 `Agent`
model boundary: AgentMessage 为什么不能直接发给模型
model catalog: 模型目录与 Provider Registry 各管什么
model variability: Evals 怎样把 Agent 行为变成可检查结果
model-visible repair: 工具执行前先经过哪些检查
monorepo workspace: 先固定版本，再谈 Pi 的架构
mutation ownership: 读写文件时，Pi 怎样避免相互踩踏
name collision precedence: 自定义工具、Provider 与渲染器谁覆盖谁
non-capturing overlay: TUI 组件、焦点与覆盖层怎样配合
OAuth refresh locking: 密钥与 OAuth 怎样落到一次请求
observable proof: Evals 怎样把 Agent 行为变成可检查结果
offline build verification: 怎样验证本册结论，并看清 Harness v2 的边界
ordered settlement: 并行工具为什么仍要保留原始顺序
outer follow-up loop: 两层循环为什么缺一不可
output projection: 同一场运行怎样投影成文本与 JSON
overlay composition: TUI 组件、焦点与覆盖层怎样配合
package boundary: 先固定版本，再谈 Pi 的架构
parallel orchestration surfaces: `AgentHarness` 为什么没有包住 `Agent`
parallel tool batch: 并行工具为什么仍要保留原始顺序
parent-linked tree: JSONL 会话文件怎样记录一棵树
partial message: 流式响应怎样变成可消费事件
per-entry atomicity: 持久会话为什么还不等于持久运行
per-file serialization: 读写文件时，Pi 怎样避免相互踩踏
persisted branch state: 运行中改配置，什么时候才真正生效
physical fork: 恢复、分叉与切换会话不是同一个动作
pinned source identity: 怎样验证本册结论，并看清 Harness v2 的边界
post-run recovery: 自动压缩、重试与用量统计怎样协作
preflight: 一条 Prompt 在调用模型前还要过多少关
process control plane: RPC 模式如何把会话变成可控制进程
process permission inheritance: Pi 没有内置沙箱，这意味着什么
process supervisor: `pi-server` 管的是进程，还是 Agent
project context: AGENTS.md、Skills 与 Prompt 模板怎样被发现
project settings: 配置、信任与资源从哪里进入
project trust: 配置、信任与资源从哪里进入扩展代码从哪里加载，信任边界在哪里
prompt pipeline: 一条 Prompt 在调用模型前还要过多少关
prompt template: AGENTS.md、Skills 与 Prompt 模板怎样被发现
provider composition: 自定义工具、Provider 与渲染器谁覆盖谁
provider normalization: 不同模型 API 怎样被压到同一接口
provider payload: 请求发出前，Context 还会经历什么
provider registry: 模型目录与 Provider Registry 各管什么
queue mode: Steering 与 Follow-up 不是同一种排队
raw terminal input: 键盘输入怎样穿过终端协议到达编辑器
release archive completeness: 怎样验证本册结论，并看清 Harness v2 的边界
render request coalescing: Pi 为什么不用每次重画整个终端
renderer lookup: 自定义工具、Provider 与渲染器谁覆盖谁
request auth: 密钥与 OAuth 怎样落到一次请求
request correlation: RPC 模式如何把会话变成可控制进程
request option normalization: 请求发出前，Context 还会经历什么
resource discovery: 配置、信任与资源从哪里进入
restart recovery: `pi-server` 管的是进程，还是 Agent
retained recent context: 压缩与回到旧分支怎样改变上下文
retry budget: 自动压缩、重试与用量统计怎样协作
RPC child process: `pi-server` 管的是进程，还是 Agent
run settlement: 一次 Run 怎样停止、失败与继续 `AgentSession` 如何成为 Coding Agent 的控制面
run snapshot: `Agent` 怎样把事件还原成状态
runnable session: `createAgentSession()` 怎样交出一个可运行会话
runtime call chain: 先固定版本，再谈 Pi 的架构
runtime composition: 模型目录与 Provider Registry 各管什么
runtime factory: 启动阶段到底组装了什么
runtime ownership: `AgentHarness` 为什么没有包住 `Agent``pi-server` 管的是进程，还是 Agent
runtime replacement: 恢复、分叉与切换会话不是同一个动作不启动 TUI，怎样把 Pi 嵌进自己的程序
runtime visibility: 运行中改配置，什么时候才真正生效
save-point ordering: 一轮请求为什么需要快照与保存点
SDK embedding: 不启动 TUI，怎样把 Pi 嵌进自己的程序
session persistence: `AgentSession` 如何成为 Coding Agent 的控制面
session rebinding: RPC 模式如何把会话变成可控制进程
session restoration: `createAgentSession()` 怎样交出一个可运行会话
session resume: 恢复、分叉与切换会话不是同一个动作
session-backed reconstruction: 流式消息与工具结果怎样出现在屏幕上
session-local history: 模型切换与设置热更新怎样保持一致
settings reload: 模型切换与设置热更新怎样保持一致
short-circuit hook: Extension Runner 怎样串起事件与变换
single input focus: TUI 组件、焦点与覆盖层怎样配合
single-shot execution: 同一场运行怎样投影成文本与 JSON
skill metadata: AGENTS.md、Skills 与 Prompt 模板怎样被发现
source order: 并行工具为什么仍要保留原始顺序
source precedence: AGENTS.md、Skills 与 Prompt 模板怎样被发现
stale context: Extension Runner 怎样串起事件与变换
stale extension context: 恢复、分叉与切换会话不是同一个动作
state wrapper versus session harness: `AgentHarness` 为什么没有包住 `Agent`
status event projection: 流式消息与工具结果怎样出现在屏幕上
stdout isolation: 同一场运行怎样投影成文本与 JSON
steering queue: Steering 与 Follow-up 不是同一种排队
streaming protocol: 流式响应怎样变成可消费事件
strict JSONL framing: RPC 模式如何把会话变成可控制进程
synchronized terminal output: Pi 为什么不用每次重画整个终端
synthetic failure message: 一次 Run 怎样停止、失败与继续
tail truncation: Bash 输出太长时，完整结果去了哪里
terminal event: 流式响应怎样变成可消费事件
tool allowlist: `createAgentSession()` 怎样交出一个可运行会话
tool call repair: 不同模型 API 怎样被压到同一接口
tool definition: 七个内置工具为什么默认只开四个
tool override: 自定义工具、Provider 与渲染器谁覆盖谁
tool preflight: 工具执行前先经过哪些检查
tool registry: 七个内置工具为什么默认只开四个
tool-call correlation: 流式消息与工具结果怎样出现在屏幕上
tool-routing isolation: Pi 没有内置沙箱，这意味着什么
transcript normalization: Evals 怎样把 Agent 行为变成可检查结果
transient streaming state: 流式消息与工具结果怎样出现在屏幕上
transport retry: 重试、溢出与中止在哪一层收口
TTY detection: 一个 pi 命令，四种运行方式
turn snapshot: 一轮请求为什么需要快照与保存点
turn-local system prompt: 一条 Prompt 在调用模型前还要过多少关
UTF-8 stream decoding: Bash 输出太长时，完整结果去了哪里
viewport-aware cursor movement: Pi 为什么不用每次重画整个终端
volatile orchestration state: 持久会话为什么还不等于持久运行