注意: 本文档将始终以中文更新和维护
本文档分析 Gemini CLI 代码库中的主要 AI 任务执行循环（"游戏循环"）- 即 AI 审查、规划和执行用户任务的迭代循环。
按照"名词-动词-引擎-点火钥匙"的架构逻辑来理解 Gemini CLI 的核心执行框架：
GeminiClient: 主控制引擎
┌─────────────────────────────────────────────────────────────┐
│ GeminiClient 主控制引擎 │
├─────────────────────────────────────────────────────────────┤
│ 用户输入 │
│ ↓ │
│ sendMessageStream() ──→ 检查循环 ──→ 压缩历史 │
│ ↓ ↓ ↓ │
│ 创建 Turn ──→ 执行 API 调用 ──→ 处理响应 │
│ ↓ ↓ │
│ 工具调用? ──Yes──→ 调度工具 ──→ 等待完成 │
│ ↓No ↓ │
│ checkNextSpeaker() ──→ 继续? ──Yes──→ 递归调用 │
│ ↓No │
│ 返回给用户 │
└─────────────────────────────────────────────────────────────┘CoreToolScheduler: 工具执行引擎
┌─────────────────────────────────────────────────────────────┐
│ CoreToolScheduler 工具执行引擎 │
├─────────────────────────────────────────────────────────────┤
│ ToolCallRequest │
│ ↓ │
│ Validating ──→ 验证参数 ──→ shouldConfirmExecute() │
│ ↓ ↓ │
│ 需要确认? ──Yes──→ WaitingApproval ──→ 用户批准? │
│ ↓No ↓Yes ↓No │
│ Scheduled ──→ 加入执行队列 ──────────┘ Cancel │
│ ↓ ↓ │
│ Executing ──→ 异步执行工具 ──→ 收集结果 │
│ ↓ ↓ │
│ Success/Error ──→ 格式化响应 ──→ 返回结果 │
└─────────────────────────────────────────────────────────────┘LoopDetectionService: 安全防护引擎
┌─────────────────────────────────────────────────────────────┐
│ LoopDetectionService 安全防护引擎 │
├─────────────────────────────────────────────────────────────┤
│ 每个事件输入 │
│ ↓ │
│ 简单重复检测 ──→ 哈希对比 ──→ 超阈值? ──Yes──→ 触发循环警告 │
│ ↓ ↓No │
│ 轮次计数 > 30? ──No──→ 继续监控 │
│ ↓Yes │
│ LLM 智能检测 ──→ 分析历史 ──→ 计算置信度 │
│ ↓ ↓ │
│ 调整检测间隔 ──→ 高置信度? ──Yes──→ 频繁检测 │
│ ↓ ↓No │
│ 继续监控 ←────── 降低频率 │
└─────────────────────────────────────────────────────────────┘NextSpeakerChecker: 决策引擎
┌─────────────────────────────────────────────────────────────┐
│ NextSpeakerChecker 决策引擎 │
├─────────────────────────────────────────────────────────────┤
│ 轮次结束触发 │
│ ↓ │
│ 提取对话历史 ──→ 格式化上下文 ──→ 构建分析提示 │
│ ↓ ↓ │
│ 调用 LLM 分析 ──→ 生成结构化输出 │
│ ↓ │
│ 解析决策结果: │
│ - next_speaker: 'model'/'user' │
│ - reasoning: 决策理由 │
│ ↓ │
│ 返回决策 ──→ 'model'? ──Yes──→ 继续执行 │
│ ↓No │
│ 等待用户输入 │
└─────────────────────────────────────────────────────────────┘submitQuery() - 用户交互启动整个循环next_speaker === 'model' - 自动继续的判断逻辑handleCompletedTools() - 工具执行完成后的循环重启AbortSignal - 用户随时可以终止执行的控制机制用户输入(点火钥匙) → GeminiClient(主引擎) → Turn(名词) → sendMessageStream(动词)
↓
API响应 → CoreToolScheduler(工具引擎) → ToolCall(名词) → schedule(动词)
↓
工具执行完成 → NextSpeakerChecker(决策引擎) → checkNextSpeaker(动词)
↓
判断继续 → 递归调用sendMessageStream(重新点火) 或 等待用户输入这种架构设计实现了一个自驱动的、可控的、安全的 AI 任务执行循环，每个组件职责明确，通过标准化的数据结构和操作接口实现松耦合协作。
sendMessageStream() (第 274-370 行)// 带边界检查的主递归循环
const boundedTurns = Math.min(turns, this.MAX_TURNS); // MAX_TURNS = 100
// 处理当前轮次
const turn = new Turn(this.getChat(), prompt_id);
const resultStream = turn.run(request, signal);
// 如果模型应该继续发言则继续
if (nextSpeakerCheck?.next_speaker === 'model') {
yield* this.sendMessageStream(
nextRequest,
signal,
prompt_id,
boundedTurns - 1, // 递减轮次
initialModel,
);
}主控制器
sendMessageStream() (第 274-370 行)主要功能: GeminiClient 是整个 AI 任务执行循环的核心控制器，负责管理与 Gemini API 的交互、聊天会话状态、循环检测和内容生成。
关键特性:
sendMessageStream() 方法实现主循环，通过递归调用处理连续的 AI 响应LoopDetectionService，防止无限循环，设置最大轮次限制（100轮）checkNextSpeaker 决定是否需要继续执行核心流程:
sendMessageStream 中开始消息循环重要机制:
这个文件是整个 AI 执行循环的"大脑"，协调所有其他组件的工作。
轮次处理器
run() (第 167-258 行)主要功能: Turn 类代表单个对话轮次，是主循环中的基本执行单元，负责处理与 Gemini API 的单次交互，包括内容生成、工具调用请求的处理。
关键特性:
run() 方法作为异步生成器，实时处理 API 的流式响应事件流处理:
核心数据结构:
与主循环的关系: Turn 是 Client.sendMessageStream() 创建的执行单元，每次 AI 响应都通过 Turn 实例处理，其 pendingToolCalls 属性会被工具调度器进一步处理。
这个文件是主循环中的"执行器"，将抽象的 AI 交互转换为具体的事件流。
工具执行调度器
schedule() 和 attemptExecutionOfScheduledCalls() (第 403-687 行)主要功能: CoreToolScheduler 是工具执行的核心调度器，管理从工具调用请求到执行完成的整个生命周期，包括验证、确认、执行和结果处理。
关键特性:
核心工作流程:
状态类型系统:
与主循环的关系: 接收来自 Turn 的 ToolCallRequestInfo，通过状态机管理工具执行，最终返回结果给 UI 层继续主循环。
这个文件是主循环中的"执行引擎"，将工具调用从请求转换为实际的系统操作。
UI 集成循环
submitQuery() 和 handleCompletedTools() (第 531-774 行)主要功能: useGeminiStream 是 React Hook，作为前端 UI 与后端核心执行循环之间的桥梁，管理用户交互、流状态和工具执行的 UI 表现。
关键特性:
核心循环实现:
UI 状态管理:
与主循环的关系: 这是主循环在 UI 层的体现，通过 submitQuery 触发后端的 sendMessageStream，通过 handleCompletedTools 实现循环的继续。
这个文件是主循环的"用户界面"，将后端的抽象执行转换为用户可见的交互体验。
循环检测服务
主要功能: LoopDetectionService 负责检测和防止 AI 执行过程中的无限循环，使用多种策略包括简单重复检测和基于 LLM 的智能分析。
关键特性:
检测策略:
防护机制:
与主循环的关系: 在每个轮次开始时和事件处理时进行检测，一旦发现循环立即终止主循环执行。
这个文件是主循环的"安全卫士"，防止执行陷入无限循环。
下一发言者逻辑
主要功能: nextSpeakerChecker 通过分析对话上下文来智能决定下一个发言者应该是 AI 模型还是用户，是主循环继续执行的关键判断逻辑。
关键特性:
决策逻辑:
返回格式:
{
next_speaker: 'model' | 'user',
reasoning: string // 决策理由
}与主循环的关系: 在每个轮次结束后被调用，其返回值决定是否继续递归调用 sendMessageStream，是主循环自动继续的核心判断机制。
这个文件是主循环的"决策大脑"，智能判断何时继续执行，何时等待用户输入。
submitQuery() 触发下一次迭代MAX_TURNS)AbortController 信号| 组件 | 文件 | 行号 |
|---|---|---|
| 主循环入口 | packages/core/src/core/client.ts | 274 |
| 递归继续 | packages/core/src/core/client.ts | 360-367 |
| 工具执行循环 | packages/core/src/core/coreToolScheduler.ts | 625-686 |
| 轮次处理 | packages/core/src/core/turn.ts | 167 |
| UI 继续 | packages/cli/src/ui/hooks/useGeminiStream.ts | 758-764 |
Gemini CLI 实现了一个健壮的、有界的执行循环，能够处理复杂的多轮 AI 工作流。该架构提供：
这种设计使 AI 能够迭代地处理复杂任务，使用工具并在多个轮次中进行推理，直到任务完成或用户干预。