Agent Loop 拆解：从 OpenClaw 到 nanobot 再到 PicoClaw

@startuml
!theme plain
skinparam backgroundColor #FEFEFE
skinparam componentStyle rectangle
skinparam defaultFontSize 13

package "Agent Loop 通用架构" {

  [MessageBus] as MB #LightBlue
  note right of MB
    异步消息队列
    InboundMessage / OutboundMessage
  end note

  [AgentLoop] as AL #LightGreen
  note bottom of AL
    核心编排器
    Run() → processMessage()
    → runAgentLoop() → runLLMIteration()
  end note

  [ContextBuilder] as CB #LightYellow
  note right of CB
    上下文组装
    SystemPrompt + History
    + Skills + Memory
  end note

  [LLM Provider] as LLM #Orange
  note right of LLM
    模型调用
    支持 Fallback Chain
    多 Provider 路由
  end note

  [ToolRegistry] as TR #LightCoral
  note right of TR
    工具注册与执行
    内置 + MCP 扩展
    安全沙箱策略
  end note

  [SessionManager] as SM #Plum
  note right of SM
    会话持久化
    JSONL 格式
    Summary/Compaction
  end note

  [ChannelManager] as CM #LightSkyBlue
  note left of CM
    多通道管理
    Telegram/Discord
    Slack/CLI/...
  end note

  [AgentRegistry] as AR #Wheat
  note left of AR
    多 Agent 路由
    隔离 Workspace
    独立 Session
  end note
}

CM --> MB : 发布入站消息
MB --> AL : 消费消息
AL --> AR : 路由到 Agent
AL --> CB : 组装上下文
AL --> LLM : 调用模型
LLM --> AL : 返回响应/ToolCalls
AL --> TR : 执行工具
TR --> AL : 返回工具结果
AL --> SM : 持久化会话
AL --> MB : 发布出站消息
MB --> CM : 路由到通道

@enduml

@startuml
!theme plain
skinparam backgroundColor #FEFEFE
skinparam sequenceMessageAlign center
skinparam defaultFontSize 12

actor User as U
participant "Channel\n(Telegram)" as CH
participant "MessageBus" as MB
participant "AgentLoop\nRun()" as AL
participant "processMessage()" as PM
participant "runAgentLoop()" as RAL
participant "ContextBuilder" as CB
participant "runLLMIteration()" as RLI
participant "LLM Provider" as LLM
participant "ToolRegistry" as TR
participant "SessionManager" as SM

== 1. 消息接入 ==
U -> CH : 发送消息
CH -> MB : PublishInbound(\nInboundMessage)
MB -> AL : ConsumeInbound()

== 2. 路由与预处理 ==
AL -> PM : processMessage(ctx, msg)
PM -> PM : 语音转写 (如有)
PM -> PM : 检查是否命令 (/new, /help...)
PM -> PM : resolveMessageRoute()\n选择 Agent + SessionKey

== 3. 上下文组装 ==
PM -> RAL : runAgentLoop(agent, msg, opts)
RAL -> SM : 加载 session 历史
RAL -> CB : BuildMessages()\n组装 System Prompt\n+ History + Skills + Memory
RAL -> SM : 保存 user 消息

== 4. LLM 推理循环 (iteration 1) ==
RAL -> RLI : runLLMIteration(messages)
RLI -> LLM : Chat(messages, tools)
LLM --> RLI : Response(tool_calls:\n[web_search("今天天气")])

== 5. 工具执行 ==
RLI -> RLI : 追加 assistant 消息到 history
RLI -> TR : Execute("web_search",\n{"query": "今天天气"})
TR --> RLI : ToolResult{ForLLM: "...",\nForUser: "正在搜索..."}
RLI -> MB : PublishOutbound(ForUser)\n即时反馈
RLI -> RLI : 追加 tool result 到 history

== 6. LLM 推理循环 (iteration 2) ==
RLI -> LLM : Chat(messages + tool_result)
LLM --> RLI : Response(content:\n"今天天气晴, 25°C...")
RLI --> RAL : 返回 finalContent

== 7. 保存与响应 ==
RAL -> SM : 保存 assistant 消息
RAL -> SM : 检查是否需要 summarization
RAL --> PM : 返回响应文本
PM --> AL : 返回响应
AL -> MB : PublishOutbound(response)
MB -> CH : 路由到 Telegram
CH -> U : 显示回复

@enduml

@startuml
!theme plain
skinparam backgroundColor #FEFEFE
skinparam activityFontSize 13
skinparam defaultFontSize 12

title Agent Loop - runLLMIteration 活动图

start

:初始化 iteration = 0;
:选择模型候选 (主模型/轻量模型);
:固定本轮 tier (防止中途换模型);

repeat

  :iteration++;

  if (iteration > MaxIterations?) then (yes)
    :返回 "达到最大迭代次数";
    stop
  endif

  :调用 LLM Provider.Chat(messages, tools);

  if (调用出错?) then (yes)
    if (是 Context Window 溢出?) then (yes)
      :forceCompression()\n丢弃最旧一半历史\n插入压缩说明;
      if (重试次数 < maxRetries?) then (yes)
        :重试 LLM 调用;
      else (no)
        :返回错误;
        stop
      endif
    else (no)
      if (有 Fallback 模型?) then (yes)
        :切换到下一个 Fallback 模型;
      else (no)
        :返回错误;
        stop
      endif
    endif
  endif

  :解析 LLM 响应;

  if (response 包含 tool_calls?) then (no)
    :finalContent = response.content;
    :跳出循环;
  else (yes)
    :将 assistant + tool_calls\n追加到消息历史;

    partition "工具执行 (可并行)" {
      :遍历每个 tool_call;
      :调用 ToolRegistry.Execute(name, args);

      if (工具返回 ForUser?) then (yes)
        :即时发送给用户\n(中间反馈);
      endif

      :将 ForLLM 结果\n作为 tool message 追加;
    }
  endif

repeat while (还有 tool_calls 且未超过 MaxIterations)

:保存 assistant 最终回复到 session;

if (session 消息数 > 阈值?) then (yes)
  :异步触发 summarization\n(不阻塞响应);
endif

:返回 finalContent;

stop

@enduml

while (running) {
    msg = bus.consume()                    // 1. 接入
    agent, session = route(msg)            // 2. 路由
    context = build(history + prompt + skills) // 3. 上下文

    while (iteration < max) {              // 4. 推理循环
        response = llm.chat(context, tools)
        if (no tool_calls) break

        for (tc in tool_calls) {           // 5. 工具执行
            result = tools.execute(tc)
            if (result.forUser) send(result)
            context.append(result.forLLM)
        }
    }

    session.save(context)                  // 6. 持久化
    if (shouldSummarize) async { summarize() }  // 7. 记忆压缩
    bus.publish(response)                  // 8. 响应
}

@startmindmap
!theme plain
skinparam backgroundColor #FEFEFE

* Agent Loop 拆解
** 是什么
*** 对话操作系统内核
*** 六层架构: 接入/路由/推理/工具/记忆/运维
*** "想 → 做 → 看 → 再想" 循环
** 三个框架
*** OpenClaw (TS)
**** 企业级，6 层工具策略
**** Block Reply Chunking
**** Compaction + Memory Flush
*** nanobot (Python)
**** 极简 <500 行核心
**** asyncio.Lock 串行化
**** memory_window 阈值归档
*** PicoClaw (Go)
**** <10MB 嵌入式目标
**** goroutine 异步
**** 硬件工具 I2C/SPI
** 核心流程
*** Run() 主循环
*** processMessage() 路由
*** runAgentLoop() 上下文
*** runLLMIteration() 推理+工具
** 关键设计
*** 有界迭代 (MaxIterations)
*** ForUser vs ForLLM 分离
*** Context 溢出紧急压缩
*** 模型 tier 固定不漂移
*** 异步 Summarization
** 通用公式
*** 消息驱动 + 有界循环
*** 先写后读 + 异步压缩
*** 优雅降级链

@endmindmap