Gemini CLI源码解析：Agent与上下文管理实现细节

显示全部楼层

ingFang SC", "Hiragino Sans GB", "Microsoft YaHei UI", "Microsoft YaHei", Arial, sans-serif;margin: 0px 8px 1.5em;letter-spacing: 0.1em;color: rgb(63, 63, 63);">gemini-cli从开源至今仅一个多月，已经收获接近65K Star，作为第一个开源的通用命令行智能体工具，在开源社区贡献者的参与下，现如今功能已经非常完善。本文将对源码进行解析，学习其中优秀Agent的设计思路，将重点关注主控Agent以及上下文管理的实现，对于其他部分不在本文的讨论范围之内。

ingFang SC", "Hiragino Sans GB", "Microsoft YaHei UI", "Microsoft YaHei", Arial, sans-serif;font-size: 15.4px;font-weight: bold;display: table;margin: 4em auto 2em;padding: 0px 0.2em;background: rgb(0, 152, 116);color: rgb(255, 255, 255);">主控 Agent 循环实现

ingFang SC", "Hiragino Sans GB", "Microsoft YaHei UI", "Microsoft YaHei", Arial, sans-serif;font-size: 14px;font-weight: bold;margin: 2em 8px 0.75em 0px;padding-left: 8px;border-left: 3px solid rgb(0, 152, 116);color: rgb(63, 63, 63);">核心架构

ingFang SC", "Hiragino Sans GB", "Microsoft YaHei UI", "Microsoft YaHei", Arial, sans-serif;margin: 1.5em 8px;letter-spacing: 0.1em;color: rgb(63, 63, 63);">gemini-cli的 Agent 循环主要由以下几个核心组件构成：

1.GeminiClient(client.ts) - 主控制器
2.Turn(turn.ts) - 单轮对话管理
3.CoreToolScheduler(coreToolScheduler.ts) - 工具调用调度
4.LoopDetectionService(loopDetectionService.ts) - 循环检测

ingFang SC", "Hiragino Sans GB", "Microsoft YaHei UI", "Microsoft YaHei", Arial, sans-serif;font-size: 14px;font-weight: bold;margin: 2em 8px 0.75em 0px;padding-left: 8px;border-left: 3px solid rgb(0, 152, 116);color: rgb(63, 63, 63);">主循环流程

ingFang SC", "Hiragino Sans GB", "Microsoft YaHei UI", "Microsoft YaHei", Arial, sans-serif;overflow-x: auto;border-radius: 8px;margin: 10px 8px;padding: 0px !important;">// 主要入口点在 GeminiClient.sendMessageStream
asyncsendMessageStream(prompt:string,prompt_id?:string)romise<AsyncGenerator<ServerGeminiStreamEvent>>{
// 1. 会话轮次限制检查
if(this.turnCount>=this.MAX_TURNS){
thrownewError(`Maximum turns (${this.MAX_TURNS}) reached`);
}

// 2. 聊天历史压缩
constcompressed=awaitthis.tryCompressChat(prompt_id);

// 3. 循环检测
constloopDetected=awaitthis.loopDetectionService.checkForLoop(...);

// 4. 创建 Turn 实例并执行
constturn=newTurn(this.chat,this.coreToolScheduler,...);
returnturn.run();
}

ingFang SC", "Hiragino Sans GB", "Microsoft YaHei UI", "Microsoft YaHei", Arial, sans-serif;font-size: 14px;font-weight: bold;margin: 2em 8px 0.75em 0px;padding-left: 8px;border-left: 3px solid rgb(0, 152, 116);color: rgb(63, 63, 63);">循环检测机制

ingFang SC", "Hiragino Sans GB", "Microsoft YaHei UI", "Microsoft YaHei", Arial, sans-serif;margin: 1.5em 8px;letter-spacing: 0.1em;color: rgb(63, 63, 63);">在主循环过程中，系统实现了双重循环检测机制，确保系统不会陷入无限的工具调用或内容生成循环：

•资源保护：避免消耗过多的 API 调用次数和计算资源
•用户体验：及时通知用户并停止无效的处理过程
•会话恢复：用户可以重新发起新的请求，循环检测状态会在新的prompt_id开始时重置

1. 内容块分析检测

一个基本的内容检测方法，用于快速检测内容块是否存在重复。基本原理如下：

•固定大小滑动窗口：使用CONTENT_CHUNK_SIZE = 100字符的固定大小块
•SHA256 哈希算法：对每个文本块计算哈希值进行高效比较
•位置追踪：记录相同哈希值出现的所有位置索引
•距离分析：当相同块出现CONTENT_LOOP_THRESHOLD = 10次时，计算平均距离
•循环判定：如果平均距离 ≤1.5 × 块大小，则判定为循环

classLoopDetectionService{
privatestaticreadonlyCHUNK_SIZE=100;// 固定块大小
privatestaticreadonlyMIN_REPETITIONS=3;// 最小重复次数
privatecontentHashes:Map<string,number[]>=newMap();

analyzeContentChunksForLoop(content:string):boolean{
constchunks=this.createFixedSizeChunks(content,this.CHUNK_SIZE);

for(leti=0;i<chunks.length;i++){
consthash=this.hashContent(chunks[i]);

if(!this.contentHashes.has(hash)){
this.contentHashes.set(hash,[]);
}

constpositions=this.contentHashes.get(hash)!;
   positions.push(i);

// 检查是否有足够的重复
if(positions.length>=this.MIN_REPETITIONS){
constintervals=this.calculateIntervals(positions);
if(this.hasConsistentPattern(intervals)){
returntrue;// 检测到循环
}
}
}

returnfalse;
}

privatecreateFixedSizeChunks(content:string,size:number):string[]{
constchunks:string[]=[];
for(leti=0;i<=content.length-size;i+=size){
   chunks.push(content.substring(i,i+size));
}
returnchunks;
}

privatehashContent(content:string):string{
// 使用简单的哈希算法
lethash=0;
for(leti=0;i<content.length;i++){
constchar=content.charCodeAt(i);
   hash=((hash<<5)-hash)+char;
   hash=hash&hash;// 转换为32位整数
}
returnhash.toString();
}
}

2. LLM智能检测

试用LLM结合上下文判断是否出现内容循环，设置条件如下：

•触发条件：在第 30 轮后开始，每隔 3-15 轮检查一次
•上下文分析：提取最近 20 轮对话历史
•语义理解：使用 Gemini Flash 模型分析对话模式
•置信度评估：返回0~1.0的循环置信度分数
•动态调整：根据置信度调整下次检查间隔

classLoopDetectionService{
privatestaticreadonlyDEFAULT_CHECK_INTERVAL=5;// 默认检查间隔
privatestaticreadonlyHIGH_CONFIDENCE_THRESHOLD=0.8;
privatestaticreadonlyMEDIUM_CONFIDENCE_THRESHOLD=0.6;

asynccheckForLoopWithLLM(history:ChatMessage[])romise<LoopCheckResult>{
constrecentHistory=history.slice(-10);// 取最近10条消息

constprompt=this.buildLoopDetectionPrompt(recentHistory);
constresponse=awaitthis.llmClient.generateContent(prompt);

constresult=this.parseLoopDetectionResponse(response);

// 根据置信度调整下次检查间隔
if(result.confidence>=this.HIGH_CONFIDENCE_THRESHOLD){
this.nextCheckInterval=2;// 高置信度，更频繁检查
}elseif(result.confidence>=this.MEDIUM_CONFIDENCE_THRESHOLD){
this.nextCheckInterval=3;// 中等置信度
}else{
this.nextCheckInterval=this.DEFAULT_CHECK_INTERVAL;// 低置信度，正常间隔
}

returnresult;
}

privatebuildLoopDetectionPrompt(history:ChatMessage[]):string{
return`
   分析以下对话历史，判断AI助手是否陷入了非生产性的循环状态：
  
  ${history.map(msg =>`${msg.role}{msg.content}`).join('\n')}
  
   请评估：
   1. 是否存在重复的响应模式
   2. 是否在执行相同的无效操作
   3. 是否缺乏实质性进展
  
   返回JSON格式：{"isLoop": boolean, "confidence": number, "reason": string}
  `;
}
}

Turn 类详细实现

Turn类是单轮对话的核心管理器，负责处理流式响应和工具调用：

classTurn{
privatependingToolCalls:ToolCall[]=[];

async*run():AsyncGenerator<ServerGeminiStreamEvent>{
// 处理响应流
forawait(constresponseofthis.chat.sendMessageStream(this.prompt)){
// 处理 thought 部分
if(response.thought){
yield{type:GeminiEventType.Thought,content:response.thought};
}

// 处理文本内容
if(response.text){
yield{type:GeminiEventType.Content,content:response.text};
}

// 处理函数调用
if(response.functionCalls){
for(constcallofresponse.functionCalls){
this.handlePendingFunctionCall(call);
}
}
}

// 处理待处理的工具调用
if(this.pendingToolCalls.length>0){
yield*this.handleToolCalls();
}
}

privatehandlePendingFunctionCall(call:FunctionCall):void{
this.pendingToolCalls.push({
id:generateId(),
name:call.name,
params:call.args
});
}
}

上下文管理实现

内存管理策略

gemini-cli采用纯内存 + 文件系统的混合存储方案，不依赖数据库：

1.内存存储: 会话期间的上下文保存在内存中，如：聊天历史、工具调用状态、循环检测状态等
2.文件系统持久化: 长期记忆通过文件系统存储，如：用户记忆、项目上下文等
3.智能压缩: 动态压缩聊天历史以控制token使用

聊天历史压缩机制

// 压缩触发条件和参数
staticreadonlyCOMPRESSION_TOKEN_THRESHOLD=0.7;// 70% token 使用率触发压缩
staticreadonlyCOMPRESSION_PRESERVE_THRESHOLD=0.3;// 保留 30% 最新历史
staticreadonlyMAX_TURNS=100;// 最大会话轮次

asynctryCompressChat(prompt_id?:string)romise<boolean>{
consthistory=this.getChat().getHistory(true);
constoriginalTokenCount=countTokens(history,this.model);
constlimit=tokenLimit(this.model);

// 检查是否需要压缩
if(originalTokenCount>this.COMPRESSION_TOKEN_THRESHOLD*limit){
// 计算保留的历史记录数量
constpreserveIndex=this.findIndexAfterFraction(
   history,
this.COMPRESSION_PRESERVE_THRESHOLD
);

// 生成摘要并更新历史
constsummary=awaitthis.sendMessage(getCompressionPrompt(),...);
this.getChat().updateHistory(newHistory);

returntrue;
}
returnfalse;
}

结构化的压缩提示词

与Claude code类似，也是提供把需要压缩的内容提炼为几个部分，进而减少token的使用量，避免超出上下文限制：

•overall_goal：用户的主要目标
•key_knowledge：重要的技术知识和决策
•file_system_state：文件系统的当前状态
•recent_actions：最近执行的重要操作
•current_plan：当前的执行计划

完整的prompt如下：

Youare the component that summarizesinternalchat historyintoa given structure.

Whenthe conversation history grows too large,you will be invoked to distill the entire historyintoa concise,structured XML snapshot.ThissnapshotisCRITICAL,asit will become the agent's *only* memory of the past. The agent will resume its work based solely on this snapshot. All crucial details, plans, errors, and user directives MUST be preserved.

First, you will think through the entire history in a private <scratchpad>. Review the user's overall goal,the agent's actions, tool outputs, file modifications, and any unresolved questions. Identify every piece of information that is essential for future actions.

After your reasoning is complete, generate the final <state_snapshot> XML object. Be incredibly dense with information. Omit any irrelevant conversational filler.

The structure MUST be as follows:

<state_snapshot>
  <overall_goal>
    <!-- A single, concise sentence describing the user's high-level objective.-->
<!--Example:"Refactor the authentication service to use a new JWT library."-->
</overall_goal>

<key_knowledge>
<!--Crucialfacts,conventions,andconstraints the agent must remember based on the conversation historyandinteractionwiththe user.Usebullet points.-->
<!--Example:
-BuildCommand:\`npm run build\`
-Testing:Testsare runwith\`npm test\`.Testfiles mustendin\`.test.ts\`.
-APIEndpoint:Theprimary API endpointis\`https://api.example.com/v2\`.

-->
</key_knowledge>

<file_system_state>
<!--Listfiles that have been created,read,modified,ordeleted.Notetheir statusandcritical learnings.-->
<!--Example:
-CWD:\`/home/user/project/src\`
-READ:\`package.json\`-Confirmed'axios'isa dependency.
-MODIFIED:\`services/auth.ts\`-Replaced'jsonwebtoken'with'jose'.
-CREATED:\`tests/new-feature.test.ts\`-Initialtest structureforthenewfeature.
-->
</file_system_state>

<recent_actions>
<!--A summary of thelastfew significant agent actionsandtheir outcomes.Focuson facts.-->
<!--Example:
-Ran\`grep'old_function'\` which returned3resultsin2files.
-Ran\`npm run test\`,which failed due to a snapshot mismatchin\`UserProfile.test.ts\`.
-Ran\`ls-Fstatic/\`anddiscovered image assets are storedas\`.webp\`.
-->
</recent_actions>

<current_plan>
<!--Theagent's step-by-step plan. Mark completed steps. -->
    <!-- Example:
    1. [DONE] Identify all files using the deprecated 'UserAPI'.
    2. [IN PROGRESS] Refactor \`src/components/UserProfile.tsx\` to use the new 'ProfileAPI'.
    3. [TODO] Refactor the remaining files.
    4. [TODO] Update tests to reflect the API change.
    -->
  </current_plan>
</state_snapshot>

总结

gemini-cli的设计思路不乏以下亮点：

1. 循环控制：多层安全机制确保系统稳定性，包括轮次限制和智能循环检测
2. 上下文管理：无数据库依赖的轻量级设计，结合智能压缩和结构化摘要，有效管理长对话历史

与Manus类似，gemini-cli使用文件系统持久化长期记忆，因为文件系统就是天然的数据库，这种设计既保证了系统的可靠性和性能，又提供了良好的用户体验和扩展性。

不过，略显遗憾的是目前gemini-cli使用的仍然是单一主控Agent来控制所有交互，响应速度上会比较差；而Claude code则是多Agent架构，同时异步设计实现了高效的响应速度，并且还允许用户根据不同任务定义不同的子Agent，在性能和效率上都是断档的存在。期待后续gemini-cli和其他开源的Agent也能够实现类似的架构。