图解 Pi AgentPi Agent,
Illustrated

要点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.