Pi Agent · 核心运行链路

聚焦 AgentLoop 的一次 ReAct 迭代，以及工具调用如何从「决策 → 执行 → 结果回灌」一步步流转。基于 ARCHITECTURE.md 真实模块绘制。

① 核心 AgentLoop：一次 ReAct 迭代 编排

每一轮都走完 6 个阶段并回到起点，直到模型不再产出工具调用。中心是 AgentLoop，它贯穿持有状态的 RuntimeContext。点击任意阶段看职责与代码位置；「播放」会按真实顺序走一遍。

点「播放一次完整流转」，或悬停 / 点击左侧任意阶段。
循环不变量：所有事件都包在 EventEnvelope（eventId / timestamp / runId）里，供 SSE 去重、回放与 Trace 对齐。

② 工具怎么流转：决策后的 4 条路径 tools / 协调器

模型返回含 tool_call 时进入工具路径。按风险与意图分流：普通工具直接执行、高风险命令走审批、需要信息时走追问，都不含工具调用时收束为终答。点击任一张卡看触发条件、涉及协调器、SSE 事件与回灌语义。

🔀 模型返回 tool_call？（否则 → 终答）

③ 横切关注点 契约

暂停 / 取消与事件信封贯穿整个 Loop，不绑定某一步。

⏸ 协作式暂停（POST /api/chat/pause）

任一处命中取消信号 → 追加 ABORTED 消息 → agent_end(status=cancelled) 收束。不强行杀正在执行的模型请求或子进程。

✉️ 事件信封 EventEnvelope

eventId : 事件唯一 ID（SSE 去重）
timestamp : 产生时间
runId : 关联 RuntimeContext（Trace 对齐）
事件类型：turn_start / model_retry / tool_call_start / tool_execution_end / tool_result / user_input_required / tool_permission / agent_end …