代理循环（Moltbot）

代理循环是代理的一次完整「真实」运行：接收 → 上下文组装 → 模型推理 → 工具执行 → 流式回复 → 持久化。它是将消息变为动作与最终回复、并保持会话状态一致的主路径。

在 Moltbot 中，一次循环是每会话的单一、串行运行，在模型思考、调用工具和流式输出时发出生命周期与流式事件。

入口

• 网关 RPC：agent 与 agent.wait。
• CLI：agent 命令。

工作流程（高层）

1. agent RPC 校验参数、解析会话（sessionKey/sessionId）、持久化会话元数据，立即返回 { runId, acceptedAt }。
2. agentCommand 运行代理：解析模型与 thinking/verbose 默认、加载技能快照、调用 runEmbeddedPiAgent；若嵌入式循环未发出则发出 lifecycle end/error。
3. runEmbeddedPiAgent：通过每会话与全局队列串行化运行；解析模型与认证配置并构建 pi 会话；订阅 pi 事件并流式输出 assistant/tool 增量；执行超时并在超时时中止运行；返回负载与用量元数据。
4. subscribeEmbeddedPiSession 将 pi-agent-core 事件桥接到 Moltbot agent 流：tool 事件 => stream: "tool"；assistant 增量 => stream: "assistant"；生命周期事件 => stream: "lifecycle"（phase: "start" | "end" | "error"）。
5. agent.wait 使用 waitForAgentJob：等待 runId 的 lifecycle end/error；返回 { status: ok|error|timeout, startedAt, endedAt, error? }。

排队与并发

• 运行按会话键（会话车道）串行，并可经全局车道串行。
• 消息频道可选择队列模式（collect/steer/followup）向该车道系统投递。参见 命令队列。

会话与工作区准备

• 工作区被解析并创建；沙箱运行可能重定向到沙箱工作区根。
• 技能被加载（或从快照复用）并注入环境与提示。
• 引导/上下文文件被解析并注入系统提示报告。
• 获取会话写锁；在流式前打开并准备 SessionManager。

提示组装与系统提示

• 系统提示由 Moltbot 基础提示、技能提示、引导上下文与每轮覆盖构建。
• 执行模型特定限制与压缩保留 token。参见 系统提示。

钩子点（可拦截处）

Moltbot 有两套钩子：内部钩子（网关钩子）：针对命令与生命周期事件的事件驱动脚本。插件钩子：代理/工具生命周期与网关管道内的扩展点。内部钩子包括 agent:bootstrap、命令钩子（/new、/reset、/stop 等）。插件钩子包括 before_agent_start、agent_end、before_compaction/after_compaction、before_tool_call/after_tool_call、tool_result_persist、message_received/message_sending/message_sent、session_start/session_end、gateway_start/gateway_stop。详见 流式、压缩。

超时与提前结束

• 代理超时（中止）、AbortSignal（取消）、网关断开或 RPC 超时、agent.wait 超时（仅等待，不停止代理）。