Mergulhando no núcleo do gemini-cli: descobrindo o projeto Prompt e a implementação do agente

gemini-cli Como uma inteligência de linha de comando de código aberto, por trás de sua rápida popularidade está uma série de pensamentos sutis no design do agente. Para entender realmente como ele funciona, não podemos ficar apenas no nível funcional, precisamos nos aprofundar em seus dois pilares: o primeiro é a "engenharia de palavras-chave estruturadas" projetada para obter memória de longo prazo e o segundo é o "princípio de implementação de agente único" construído para garantir a operação estável do sistema. O primeiro é o "projeto de palavra-chave estruturada" projetado para obter memória de longo prazo, e o segundo é o "princípio de implementação de agente único" construído para a operação estável do sistema.

Este documento desconstrói esses dois núcleos e analisa suas filosofias de projeto e compensações técnicas.

Engenharia de palavras-chave: criação de memória de longo prazo controlada para agentes

Todos os grandes modelos de linguagem enfrentam um desafio comum: uma janela de contexto limitada. Quando um diálogo é muito longo, as informações iniciais são esquecidas, levando à "amnésia" do agente.gemini-cli A resposta não é um simples resumo histórico, mas um elaborado mecanismo de compressão estruturado. A alma desse mecanismo é a seguinte dica completa e detalhada de "modelo de memória". Ela orienta o modelo a destilar o longo histórico de conversas em um instantâneo XML altamente condensado que é essencial para tarefas futuras.

You are the component that summarizes internal chat history into a given structure.
When the conversation history grows too large, you will be invoked to distill the entire history into a concise, structured XML snapshot.This snapshot is CRITICAL, as it 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>
<!--Crucial facts, conventions, and constraints the agent must remember based on the conversation history and interaction with the user.Use bullet points.-->
<!--Example:
-Build Command: `npm run build`
-Testing:Tests are run with `npm test`.Test files must end in `.test.ts`.
- API Endpoint:The primary API endpoint is `https://api.example.com/v2`.
-->
</key_knowledge>
<file_system_state>
<!--List files that have been created, read, modified, or deleted.Note their status and critical learnings.-->
<!--Example:
- CWD: `/home/user/project/src`
- READ: `package.json` -Confirmed'axios'is a dependency.
- MODIFIED: `services/auth.ts` -Replaced'jsonwebtoken'with'jose'.
- CREATED: `tests/new-feature.test.ts` -Initial test structure for the new feature.
-->
</file_system_state>
<recent_actions>
<!-- A summary of the last few significant agent actions and their outcomes.Focus on facts.-->
<!--Example:
-Ran `grep 'old_function'` which returned 3 results in 2 files.
-Ran `npm run test`, which failed due to a snapshot mismatch in `UserProfile.test.ts`.
-Ran `ls -F static/` and discovered image assets are stored as `.webp`.
-->
</recent_actions>
<current_plan>
<!--The agent'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>

O modelo de dica é muito mais do que uma restrição de formatação; ele atua como uma "estrutura cognitiva", forçando o modelo a pensar e lembrar de uma forma estruturada. Vamos detalhar a função mais profunda de cada rótulo, um por um:

• <overall_goal>: A Estrela do Norte da missão. Em tarefas longas e complexas, é fácil para um agente ficar atolado em subtarefas triviais e se afastar da meta original. Essa rotulagem exige que o modelo tenha em mente o resultado final e garanta que todas as ações atendam a esse objetivo principal, evitando efetivamente o "desvio de objetivo".
• <key_knowledge>: "Post-it notes" de informações importantes. O diálogo conterá um grande número de regras que precisam ser respeitadas ao longo do tempo, preferências específicas do usuário ou restrições técnicas importantes (por exemplo, os comandos de teste são npm testO endereço da API é https://api.example.com/v2). A solidificação dessas informações evita que o agente repita perguntas ou cometa erros em operações subsequentes.
• <file_system_state>: Instantâneos do ambiente. Para uma ferramenta de linha de comando que interage frequentemente com o sistema de arquivos, é fundamental estar ciente do estado do ambiente. Essa tag registra as adições, exclusões e exclusões de arquivos, fornecendo ao agente uma "percepção de cena" precisa de onde ele está e quais recursos possui.
• <recent_actions>: Memória de trabalho de curto prazo. O registro das últimas operações críticas e de seus resultados (sucessos, falhas, saídas) fornece o contexto mais direto para a próxima decisão do agente, além de pistas valiosas para a solução de problemas.
• <current_plan>: Roteiro de implementação dinâmicoEsse é o núcleo do autogerenciamento do Agente. Esse é o núcleo do autogerenciamento do agente. Ao dividir grandes tarefas em tarefas com [DONE], [IN PROGRESS], [TODO] No caso de etapas estaduais, o Agente não só avança seu trabalho de forma ordenada, mas também continua exatamente de onde parou após uma interrupção, permitindo a persistência e a continuidade da tarefa.

Essa abordagem estruturada, que é essencialmente umaMudança de carga cognitivaEle transforma o problema aberto de "como memorizar de forma eficaz" em um problema de "preencher a lacuna". Ele transforma o problema aberto de "como memorizar de forma eficaz" em uma pergunta "preencha a lacuna", o que reduz muito a probabilidade de erro do modelo e torna a memória e o estado do agente controláveis, previsíveis e fáceis de depurar.

Implementação de agentes: um conjunto rigoroso de ciclos de monômeros e mecanismos de autorreparação

Se a engenharia de dicas é o cérebro de um agente, então seu loop de tempo de execução é o coração do agente.gemini-cli É usado um projeto clássico de agente monolítico, cuja operação estável depende de um conjunto de loops de controle com recursos de autocorreção.

Ciclo básico:Turn do ciclo "pensar-agir

Todo o comportamento do agente gira em torno do Turn A aula se desenvolve. Cada Turn representa um ciclo completo de pensamento-ação. Quando o usuário insere um comando, oGeminiClient Em seguida, o controlador principal cria um Turn instância. Essa instância é responsável por chamar o Gemini transmitindo o modelo thought(processo de pensamento) e text(conteúdo de texto) e coletar todos os functionCalls(chamadas de ferramenta). Quando todo o raciocínio e a saída de texto estiverem concluídos, ele executa todas as chamadas de ferramenta coletadas de uma só vez e alimenta os resultados de volta ao modelo para iniciar a próxima rodada de Turn. Esse design garante que as ações sejam ordenadas e atômicas.

Autorreparo: o "sistema imunológico" na detecção de loop de duas camadas

Um dos maiores riscos dos agentes autônomos é ficar preso em um loop infinito, executando as mesmas ações repetidamente sem chegar a lugar algum, o que não apenas desperdiça recursos, mas também prejudica a experiência do usuário.gemini-cli Um "sistema imunológico" de duas camadas é construído para combater o problema.

1. Detecção rápida e de baixo custo (baseada em hash)Mecanismo de resposta rápida: Esse é um mecanismo de resposta rápida. Ele divide o conteúdo gerado em pequenos pedaços e calcula o valor de hash. Se determinados trechos de conteúdo forem repetidos em uma alta frequência em uma distância curta, como no caso da detecção de gagueira, o sistema decide imediatamente que se trata de um loop. Esse método tem um custo computacional muito baixo e é eficaz para interceptar essas duplicatas literais padronizadas.
2. Detecção semântica de ordem superior (baseada em LLM)Padrão de looping: À medida que o número de rodadas de diálogo aumenta, o padrão de looping pode se tornar mais insidioso (por exemplo, tentar repetidamente maneiras diferentes de resolver um problema que não existe). Nesse ponto, o sistema iniciará a detecção de ordem superior. Ele extrairá o histórico de diálogo mais recente e chamará um modelo leve (como o Gemini FlashEsse pequeno modelo é usado para determinar se o agente principal está "semanticamente" andando em círculos. Isso é equivalente a um espectador, que examina se o comportamento do agente principal é razoável em uma dimensão superior. Com base no nível de confiança retornado, o sistema também pode ajustar dinamicamente a frequência da próxima verificação, alcançando um equilíbrio entre custo e efeito.

Esse mecanismo de dois níveis reflete o pensamento maduro da engenharia: resolver os problemas mais comuns com o menor custo e usar recursos mais caros somente quando necessário.

Perspectivas e compensações de arquitetura

gemini-cli A arquitetura monolítica do Agent, aliada a uma estratégia de persistência leve de "sistema de arquivos como banco de dados", torna-o simples, confiável e fácil de implantar. Essa é uma opção pragmática para desenvolvedores individuais e projetos de pequeno e médio porte.

No entanto, o gargalo desse projeto também é óbvio. O mecanismo de processamento em série limita sua eficiência de execução. Diante de tarefas complexas que exigem muitas operações paralelas (por exemplo, analisar e modificar vários arquivos ao mesmo tempo), um único agente pode ficar sobrecarregado.

É mais provável que as futuras arquiteturas avançadas de agentes avancem para um modelo colaborativo de vários agentes. Imagine um agente "mestre" que divide as tarefas e as distribui para vários subagentes dedicados - "leitores de código", "geradores de código", "engenheiros de teste" etc. Eles trabalham em paralelo e reportam uns aos outros de forma assíncrona, "Gerador de código", "Engenheiro de teste", etc., que trabalham em paralelo e reportam de forma assíncrona. Essa arquitetura, embora mais complexa em termos de design, certamente está à frente em termos de eficiência e limite de recursos.gemini-cli Ele nos mostra até onde um único agente sólido e confiável pode ir e nos deixa com uma referência valiosa para pensar sobre a evolução da arquitetura de agentes da próxima geração.