读懂 Pi：
一个可扩展的
编码智能体内核Inside Pi:
an extensible coding-agent core

要点Key points

• pi-coding-agent 直接依赖 pi-agent-core、pi-ai、pi-tui、pi-mcp、pi-codemode 和 chord。pi-coding-agent depends on pi-agent-core, pi-ai, pi-tui, pi-mcp, pi-codemode and chord.
• pi-ai 唯一的内部依赖是 pi-telemetry；pi-tui、pi-mcp、pi-codemode、chord 没有任何内部依赖，可以独立使用。pi-ai's only internal dependency is pi-telemetry; pi-tui, pi-mcp, pi-codemode and chord have none and can be used standalone.
• Durable 与远程会话是一组独立的包：pi-durable、pi-env、pi-protocol、pi-client、pi-server，都构建在 chord 之上。Durable and remote sessions form a separate cluster — pi-durable, pi-env, pi-protocol, pi-client, pi-server — all built on chord.
• 虚线是 devDependencies：pi-coding-agent 只在测试中使用 client / protocol / server；pi-evals 依赖 coding-agent 与 ai。Dashed edges are devDependencies: pi-coding-agent only uses client / protocol / server in tests; pi-evals depends on coding-agent and ai.

工作原理How it works

1. 根 package.json 用 npm workspaces 管理 packages/*。The root package.json manages packages/* with npm workspaces.
2. npm run build 按拓扑顺序依次构建：chord → tui → telemetry → codemode → mcp → ai → durable → env → agent → protocol → client → server → coding-agent。npm run build builds in topological order: chord → tui → telemetry → codemode → mcp → ai → durable → env → agent → protocol → client → server → coding-agent.
3. 图中的边直接取自每个包 package.json 里的 @earendil-works/* 依赖。Edges are read from each package's @earendil-works/* entries in package.json.

要点Key points

• pi-ai：把 42 个内置 provider 归一为一套流式事件协议 AssistantMessageEventStream。pi-ai normalizes 42 built-in providers into one streaming protocol, AssistantMessageEventStream.
• pi-agent-core：与具体产品无关的工具调用循环，所有策略通过 AgentLoopConfig 钩子注入。pi-agent-core is a product-agnostic tool-calling loop; all policy is injected through AgentLoopConfig hooks.
• pi-coding-agent：AgentSession 组装会话、8 个内置工具、扩展、压缩、设置与模型解析。pi-coding-agent: AgentSession wires in sessions, 8 built-in tools, extensions, compaction, settings and model resolution.
• 运行模式：interactive、print（text / json）和 rpc 共享同一个 AgentSessionRuntime；只有 interactive 使用 pi-tui。Run modes: interactive, print (text / json) and rpc share one AgentSessionRuntime; only interactive uses pi-tui.

工作原理How it works

1. 模式层调用 AgentSessionRuntime，它持有当前 AgentSession，并在 new / switch / fork 时整体替换会话。Modes call AgentSessionRuntime, which owns the current AgentSession and replaces it wholesale on new / switch / fork.
2. AgentSession 把自己的逻辑挂到 Agent 的钩子上：prepareNextTurn、prepareRequest、finishTurn、beforeToolCall 等。AgentSession attaches its logic to the Agent hooks: prepareNextTurn, prepareRequest, finishTurn, beforeToolCall and more.
3. sdk.ts 把 streamFn 设为 modelRuntime.streamSimple()，由 Models 注册表找到 provider 和对应的 API 实现。sdk.ts sets streamFn to modelRuntime.streamSimple(); the Models registry resolves the provider and its API implementation.

要点Key points

• AgentSession.prompt() 的顺序：扩展命令 → input 事件 → 展开 skill 与 prompt template → 若正在流式输出则排队为 steer / follow-up → 预检压缩 → before_agent_start → agent.prompt()。AgentSession.prompt() order: extension commands → input event → expand skills and prompt templates → queue as steer / follow-up if streaming → pre-prompt compaction check → before_agent_start → agent.prompt().
• pi-ai 的流事件（text_delta、toolcall_delta 等）在 agent 层变成 message_update。pi-ai stream events (text_delta, toolcall_delta, …) become message_update agent events.
• transformContext 在 coding agent 中调用 emitContext()，扩展可以在每次请求前改写消息。In the coding agent transformContext calls emitContext(), so extensions can rewrite messages before every request.

工作原理How it works

1. Interactive 模式订阅会话事件，每个 delta 都触发一次（批处理后的）重绘。Interactive mode subscribes to session events; each delta triggers a (batched) re-render.
2. AgentSession 在每个 message_end 时调用 sessionManager.appendMessage()，会话文件随每条完成的消息增量写入。AgentSession calls sessionManager.appendMessage() on every message_end, so the session file grows with each completed message.
3. 工具结果追加到上下文后，循环自动发起下一次请求，直到模型以 stop 结束。After tool results join the context the loop issues the next request automatically, until the model ends with stop.

要点Key points

• Agent 的钩子都是公开字段（beforeToolCall、prepareRequest、finishTurn …），由上层直接赋值或包装。Agent hooks are public fields (beforeToolCall, prepareRequest, finishTurn, …) that the layer above assigns or wraps.
• ModelRuntime 实现 pi-ai 的 Models 接口，并允许扩展通过 registerProvider 注册 provider。ModelRuntime implements pi-ai's Models interface and lets extensions register providers via registerProvider.
• ExtensionRunner 在 AgentSession 内部创建，bindCore() 把会话动作暴露给扩展。ExtensionRunner is created inside AgentSession; bindCore() exposes session actions to extensions.

工作原理How it works

1. Agent 维护 steering 与 follow-up 两个队列（PendingMessageQueue），转化为循环的 getSteeringMessages / getFollowUpMessages。Agent keeps two queues (PendingMessageQueue) for steering and follow-up and exposes them to the loop as getSteeringMessages / getFollowUpMessages.
2. AgentSessionRuntime.fork() / switchSession() 先发出 session_before_* 扩展事件，再拆除当前会话并创建新会话。AgentSessionRuntime.fork() / switchSession() emit session_before_* extension events, then tear down the current session and create a new one.

要点Key points

• 第 1 行是 session 头（version 3、id、cwd、可选 parentSession）。Line 1 is the session header (version 3, id, cwd, optional parentSession).
• 11 种条目：message、thinking_level_change、model_change、usage、compaction、branch_summary、custom、custom_message、label、session_info、context_edit。11 entry types: message, thinking_level_change, model_change, usage, compaction, branch_summary, custom, custom_message, label, session_info, context_edit.
• 分支不会改写历史：把 leaf 移回旧条目，下一次追加自然形成兄弟分支。Branching never rewrites history: move the leaf to an older entry and the next append becomes a sibling branch.
• context_edit 只追加，能把某个旧条目从模型上下文中删除（replacement: null）或替换其内容。context_edit is append-only and can drop an earlier entry from model context (replacement: null) or replace its content.

工作原理How it works

1. branchWithSummary() 把 leaf 移到分支点，并追加一个 branch_summary（fromId 指向被放弃的 leaf），记录那条路径做过什么。branchWithSummary() moves the leaf to the branch point and appends a branch_summary (with fromId pointing at the abandoned leaf) describing that path.
2. buildSessionContext() 从 leaf 走到根，应用最新的 compaction 与 context_edit，再转换为 LLM 消息。buildSessionContext() walks from leaf to root, applies the latest compaction and context edits, and converts entries to LLM messages.
3. 文件位于 ~/.pi/agent/sessions/<cwd>/，custom 条目供扩展保存状态但不进入上下文，custom_message 则会进入。Files live under ~/.pi/agent/sessions/<cwd>/; custom entries store extension state outside the context, custom_message entries enter it.

要点Key points

• threshold：contextTokens > contextWindow − reserveTokens（默认 reserveTokens = 16384）。threshold: contextTokens > contextWindow − reserveTokens (default reserveTokens = 16384).
• overflow：provider 返回上下文溢出错误或可恢复的 length 截断；删除失败消息、压缩，并只重试一次。overflow: a context-overflow error or a recoverable length stop; drop the failed message, compact, and retry exactly once.
• findCutPoint() 保留约 keepRecentTokens（默认 20000）的最近内容，并让切点落在轮次边界上。findCutPoint() keeps about keepRecentTokens (default 20000) of recent content and puts the cut on a turn boundary.
• 扩展可在 session_before_compact 中取消压缩，或直接提供自己的压缩结果。Extensions can cancel compaction in session_before_compact or supply their own result.

工作原理How it works

1. 自动检查发生在三处：agent_end 之后、提交新提示之前，以及 prepareNextTurn 中（同一次运行的轮次之间）。Automatic checks run in three places: after agent_end, before a new prompt, and inside prepareNextTurn (between turns of one run).
2. token 数优先取最后一条 assistant 的 usage；出错或 usage 为 0 时按 chars/4 估算。Token counts come from the last assistant usage; on errors or zero usage they are estimated at chars/4.
3. appendCompaction(summary, firstKeptEntryId, tokensBefore, …) 之后，上下文重建为“摘要 + 保留的消息”。After appendCompaction(summary, firstKeptEntryId, tokensBefore, …) the context is rebuilt as summary + kept messages.