1. 整体流程图
flowchart TD
subgraph run["run() 入口"]
A1[刷新 OAuth Token] --> A2[发送 TurnBegin]
A2 --> A3{解析用户输入}
end
A3 -->|斜杠命令| B1[执行斜杠命令]
A3 -->|Ralph Loop 模式| B2[FlowRunner.ralph_loop]
A3 -->|普通对话| B3[_turn]
B1 --> EXIT[发送 TurnEnd]
subgraph ralph["Ralph Loop (任务级循环)"]
B2 --> R1[FlowRunner.run]
R1 --> R2{node.kind?}
R2 -->|begin| R3[跳到下一个节点]
R2 -->|task| R4[_flow_turn]
R2 -->|decision| R4
R2 -->|end| R5[结束 Flow]
R3 --> R2
R4 --> R6{choice?}
R6 -->|CONTINUE| R2
R6 -->|STOP| R5
R5 --> EXIT
end
subgraph turn["_turn()"]
B3 --> C1[检查 LLM/能力]
C1 --> C2[checkpoint + append_message]
C2 --> C3[_agent_loop]
end
subgraph agent_loop["_agent_loop() (步骤级循环)"]
C3 --> D1[step_no++]
D1 --> D2{超限?}
D2 -->|YES| D3[MaxStepsReached]
D2 -->|NO| D4[_step]
D4 --> D5{有工具?}
D5 -->|YES| D1
D5 -->|NO| D6[返回 TurnOutcome]
end
D6 --> EXIT
2. _step() 单步执行流程
flowchart TD
subgraph step["_step() 单步执行"]
START[开始] --> S1[kosong.step 调用 LLM]
subgraph retry["带重试机制"]
S1 --> S1a[输入: chat_provider, system_prompt, toolset, history]
S1a --> S1b[回调: on_message_part, on_tool_result]
S1b --> S1c[返回: StepResult]
end
S1c --> S2[发送 StatusUpdate 事件]
S2 --> S3[await result.tool_results]
S3 --> S4[asyncio.shield _grow_context]
S4 --> S5{检查结果}
S5 -->|工具被拒绝| S6["return 'tool_rejected'"]
S5 -->|有 D-Mail| S7[raise BackToTheFuture]
S5 -->|有工具调用| S8["return None (继续)"]
S5 -->|无工具调用| S9["return 'no_tool_calls' (结束)"]
end
3. 简化版核心循环
flowchart LR
subgraph 入口
RUN[run] --> TURN[_turn]
end
subgraph 主循环
TURN --> LOOP[_agent_loop]
LOOP --> STEP[_step]
STEP --> CHECK{有工具?}
CHECK -->|YES| LOOP
CHECK -->|NO| END[结束]
end
subgraph 事件
LOOP -->|发送| E1[StepBegin]
STEP -->|发送| E2[StatusUpdate]
STEP -->|发送| E3[ContentPart/ToolResult]
END -->|发送| E4[TurnEnd]
end
4. 时序图 - 完整交互流程
sequenceDiagram
participant U as User/Client
participant R as run()
participant T as _turn()
participant L as _agent_loop()
participant S as _step()
participant W as Wire
participant C as Context
participant LLM as kosong/LLM
U->>R: user_input
R->>W: TurnBegin
R->>T: 调用
T->>T: 检查 LLM 配置
T->>C: checkpoint()
T->>C: append_message(user)
T->>L: 调用
loop 步骤循环
L->>W: StepBegin(n)
L->>C: checkpoint()
L->>S: 调用
S->>LLM: kosong.step()
LLM-->>S: StepResult (流式)
S->>W: ContentPart (流式)
S->>W: StatusUpdate
S->>S: await tool_results()
S->>C: _grow_context()
S->>W: ToolResult
alt 有工具调用
S-->>L: None (继续)
else 无工具调用
S-->>L: StepOutcome(no_tool_calls)
else 工具被拒绝
S-->>L: StepOutcome(tool_rejected)
else D-Mail
S-->>L: raise BackToTheFuture
L->>C: revert_to(checkpoint)
end
end
L-->>T: TurnOutcome
T-->>R: 返回
R->>W: TurnEnd
R-->>U: 完成
5. 状态机图 - 步骤状态转换
stateDiagram-v2
[*] --> TurnBegin: run()
TurnBegin --> TurnInit: 解析输入
state TurnInit {
[*] --> CheckLLM
CheckLLM --> CheckCaps: LLM OK
CheckLLM --> [*]: LLM未配置
CheckCaps --> CreateCheckpoint: 能力支持
CheckCaps --> [*]: 能力不支持
CreateCheckpoint --> [*: 进入主循环]
}
TurnInit --> AgentLoop: _agent_loop()
state AgentLoop {
[*] --> StepCounter
StepCounter --> CheckMaxSteps: step_no++
CheckMaxSteps --> [*]: 超过最大步数
CheckMaxSteps --> CheckContext: 未超限
CheckContext --> Compact: 上下文超限
CheckContext --> ExecuteStep: 上下文正常
Compact --> ExecuteStep
ExecuteStep --> EvalOutcome
EvalOutcome --> [*: 无工具/拒绝]
EvalOutcome --> StepCounter: 有工具调用
EvalOutcome --> TimeTravel: BackToTheFuture
TimeTravel --> CheckContext: 恢复检查点
}
AgentLoop --> TurnEnd: 轮次结束
TurnEnd --> [*]