KimiSoul 主循环流程图

### 1. 整体流程图 ```mermaid 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() 单步执行流程 ```mermaid 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. 简化版核心循环 ```mermaid 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. 时序图 - 完整交互流程 ```mermaid 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. 状态机图 - 步骤状态转换 ```mermaid 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 --> [*] ```