Desconstrução profunda do código Claude Código-fonte: a filosofia da arquitetura de agentes por trás de 510.000 linhas de código

Recentemente, a Anthropic lançou seu assistente de codificação de IA nativo Claude Código. com base em uma revisão do @anthropic-ai/claude-code Código-fonte da v2.1.88Esse sistema de engenharia de 510.000 linhas de código TypeScript espalhadas por 1.902 arquivos não apenas mostra como criar uma ferramenta CLI de endpoint com recursos completos, mas também é uma análise de nível de engenharia que revela como o Head AI Lab lida com a interação de modelos grandes com sistemas físicos reais, controle de privilégios e gerenciamento de contexto.

(Observação: a análise de 500.000 linhas de código levou mais de uma hora para ser executada).

II. panorama do projeto e filosofia de design

2.1 Tamanho do código e principais responsabilidades

A distribuição do volume do diretório de código fornece uma visão clara da direção da inclinação dos recursos do projeto. A camada de infraestrutura e a camada de renderização da interface do usuário ocupam a maior parte:

módulo (em software)	fila	porcentagem	Principais responsabilidades
utils	180,472	35.2%	Controle de permissões, interceptações de segurança do Bash, pipelines de processamento de mensagens, interações do Git, clientes MCP e outras infraestruturas subjacentes
components	81,546	15.9%	React Componentes da interface do usuário do endpoint (diálogos de confirmação de permissão, exibição da diferença de código Diff, mecanismo de renderização de mensagens)
services	53,680	10.5%	Encapsulamento de chamadas de API, algoritmos de compactação de contexto em várias camadas, serviços de back-end de MCP, análise de dados e autenticação OAuth
tools	50,828	9.9%	Implementações específicas de mais de 40 ferramentas principais (execução do Bash, edição do FileEdit, envio de agentes, ferramentas MCP, etc.)
commands	26,428	5.2%	Entrada de terminal para mais de 90 comandos de barra (por exemplo, /compact, /model, /mcp)
ink	19,842	3.9%	Versão Fork de nossa própria estrutura Ink, um mecanismo de renderização de alto desempenho para ambientes de endpoint.
hooks	19,204	3.7%	Fornecer ganchos React para desacoplar o tratamento de permissões, a integração do estado do IDE e a lógica de interação por voz
bridge	12,613	2.5%	Protocolos de controle remoto que permitem que máquinas locais executem tarefas como ambientes com ponte
cli	12,353	2.4%	Análise de parâmetros de linha de comando da CLI e gerenciamento de ciclo de vida para sessões em segundo plano

2.2 Vista aérea da arquitetura

A camada inferior do sistema depende de vários serviços básicos, enquanto a camada superior conduz a tomada de decisões e a operação do agente por meio de máquinas de estado e mecanismos de eventos sofisticados, apresentando um caráter altamente modular.

2.3 Cinco princípios de design transversais

Depois de desmontar essas 510.000 linhas de código, é possível destilar cinco diretrizes de design principais que dominam a direção da arquitetura:

1. Ferramentas como limites de competênciaO Agent não possui backdoors para contornar o conjunto de ferramentas e manipular o ambiente diretamente. A leitura de um arquivo requer uma chamada para o FileReadTool, a modificação de um arquivo depende do FileEditTool e a execução de comandos do sistema só é possível com o BashTool. A expansão dos recursos do sistema é totalmente equivalente à adição de novas ferramentas.
2. Padrão de segurança fechado por falhaTodas as configurações padrão que envolvem propriedades de segurança são extremamente conservadoras. As ferramentas não permitem a execução paralela por padrão (isConcurrencySafe: false), a suposição padrão de destrutividade de gravação (isReadOnly: false), e todas as permissões de operação são bloqueadas por padrão, forçando o usuário a autorizar.
3. Engenharia de contexto em vez de engenharia imediataO foco da engenharia não está em dizer ao modelo “quem você é” com uma longa dica, mas em montar dinamicamente o ambiente contextual completo em cada rodada de diálogo, por meio de cache segmentado, injeção de estado dinâmico e compactação de contexto multinível.
4. Altamente combinávelReutilização perfeita entre diferentes módulos. Os subagentes reutilizam diretamente o query() a ferramenta externa MCP reutiliza o pipeline interno de verificação de permissões do sistema, e o modelo de colaboração da equipe reutiliza o mecanismo de execução subjacente do Subagent.
5. A eliminação em tempo de compilação é melhor do que a avaliação em tempo de execuçãoUso do tempo de execução do Bun feature() A macro [7] ativa a eliminação de código morto (DCE) no momento da compilação. Além de os recursos não habilitados não serem executados em tempo de execução, o código físico está completamente ausente do pacote Bundle final gerado.

III Loop do agente: o coração executivo do sistema

estar situado em src/QueryEngine.ts(Linha 1295) vs. src/query.ts(linha 1729), além da camada de implementação da ferramenta StreamingToolExecutor.ts(530 linhas) e toolExecution.ts(1.745 linhas), que juntos formam o núcleo do que move o Agent.

3.1 Modelo cíclico de duas camadas

Em vez do tradicional loop while, o Agent Loop constrói uma máquina de estado implícita com 7 caminhos de recuperação e 10 condições de encerramento, e é estruturado em duas camadas:

QueryEngine (gerenciamento de sessão da camada externa)Manutenção do estado de várias rodadas, persistência do disco do Transcript, adaptação do protocolo SDK e APIs: lida com a manutenção do estado de várias rodadas, persistência do disco do Transcript, adaptação do protocolo SDK e APIs. Token Consumo acumulado.
queryLoop (rodada interna única de execução)Foco no início de chamadas de API, análise e execução de ferramentas e mecanismos locais de recuperação de erros.

A conexão entre as duas camadas é estabelecida por meio do AsyncGenerator: o queryLoop interno é responsável pelo yield produz o objeto de mensagem, que o QueryEngine externo é responsável por consumir. Esse projeto resolve três problemas de engenharia:

1. Controle de contrapressãoO chamador extrai os dados sob demanda para evitar inundar a memória com a saída de streaming maciço do modelo.
2. interromper a transmissão semânticaChamada do gerador .return() A capacidade de fechar em cascata todas as instâncias do Generator aninhadas permite que os cancelamentos do usuário se propaguem instantaneamente para todas as tarefas subjacentes.
3. combinação de fluxo (por exemplo, fornecimento de gás e eletricidade): Subagente runAgent() O retorno também é um AsyncGenerator, o que permite que ele seja aninhado diretamente no fluxo de dados do Agent principal.

3.2 Projeto de máquina de estado para queryLoop

O queryLoop é essencialmente um while(true) Um loop em que cada iteração representa um ciclo de “chamada de API + execução de ferramenta”. A saída do loop é determinada por dois tipos:

• TerminalA condição de término é atingida, encerrando o loop e retornando a causa específica.
• ContinueAcione o caminho de recuperação state = next; continue Transportar o novo estado para a próxima iteração.

Para evitar omissões de estado, o sistema não usa atribuições de variáveis fragmentadas, mas mantém centralmente um State Estruturas:

type State = {
messages: Message[]
toolUseContext: ToolUseContext
autoCompactTracking: AutoCompactTrackingState | undefined
maxOutputTokensRecoveryCount: number
hasAttemptedReactiveCompact: boolean
pendingToolUseSummary: Promise<ToolUseSummaryMessage | null> | undefined
turnCount: number
transition: Continue | undefined
}

código-fonte query.ts:266-268 Os comentários na seção anterior afirmam especificamente essa motivação: a substituição de várias alterações de variáveis independentes por uma atribuição completa de estado força o desenvolvedor a declarar explicitamente todo o estado em cada local de continuação, evitando assim inconsistências contextuais.

3.3 Pipeline de pré-processamento de mensagens: gerenciamento de contexto leve a pesado

Antes de uma solicitação de API ser iniciada, a lista de mensagens passa por um pipeline de pré-processamento que segue rigorosamente o princípio do “mais leve para o mais pesado”. O sistema prioriza operações locais de baixo custo antes de operações pesadas que consomem a cota da API.

O Context Collapse é executado antes que o AutoCompact seja chamado, porque o AutoCompact é caro e destrói o contexto refinado, enquanto o Context Collapse preserva o máximo possível da solicitação original, recolhendo as mensagens secundárias.

Existe um modelo matemático preciso para o acionamento do AutoCompact, com a seguinte fórmula:

Janela de contexto efetiva = Janela de contexto do modelo - max(max_output_tokens, 20000)

Limite de acionamento = Janela de contexto efetiva - 13000

Para um modelo com um limite de janela de 200k, a ação de compressão é de cerca de 167k. tokens Início próximo. Notavelmente, o mecanismo do disjuntor foi projetado para parar de tentar novamente após três falhas consecutivas. Os comentários do código-fonte citam dados reais de telemetria: “1.279 sessões em todo o mundo tiveram mais de 50 falhas de compactação consecutivas (até 3.272), desperdiçando cerca de 250 mil chamadas de API por dia”. Esse pequeno mecanismo bloqueia buracos negros de recursos em implantações de grande escala.

3.4 A essência do controle de simultaneidade para atuadores de ferramentas de fluxo contínuo

Quando o modelo gera vários blocos de chamada de ferramenta em paralelo em uma única solicitação, o sistema usa o padrão StreamingToolExecutor(execução de streaming). Durante a fase de recepção de streaming da API, assim que um bloco tool_use completo é recebido, a execução é iniciada.

O modelo de controle simultâneo para atuadores de fluxo contínuo é baseado na ideia de particionamento de ferramentas:

O atuador faz isso lendo o isConcurrencySafe(input) agrupa ferramentas de segurança consecutivas em uma “partição paralela”. Sempre que uma ferramenta não segura é encontrada (por exemplo, FileEdit, em que dois FileEdits paralelos que modificam o mesmo arquivo inevitavelmente resultam em deslocamentos e substituições de números de linha), uma nova partição é aberta. A execução serial é imposta entre as partições, enquanto o paralelismo total é permitido dentro das partições.
Um dos projetos defensivos é que, se a própria função de verificação de segurança lançar uma exceção de análise, o sistema seguirá o princípio de falha fechada e a tratará como uma execução de ferramenta não segura por padrão, em vez de sacrificar o desempenho e arriscar conflitos de simultaneidade.

3.5 Retenção de mensagens e gerenciamento de orçamento de token

Nem todas as informações retornadas pela API são vazadas diretamente para o front-end. O sistema retém três tipos de mensagens:

1. erro de prompt muito longoCompressão: retida pelo reactiveCompact, tentada novamente internamente após a tentativa de compressão.
2. erro de tamanho de mídiaRepetição interna após a tentativa de remover anexos de imagem de tamanho grande.
3. erro max_output_tokensComando sucessor: fica suspenso aguardando que o sistema decida se deve injetar um comando sucessor.
   O núcleo desse mecanismo de retenção é proteger os consumidores do SDK (por exemplo, clientes de desktop) - os consumidores tendem a encerrar suas sessões quando recebem um campo de erro, e ocultar erros de estado intermediário garante que o loop de recuperação interno não seja interrompido prematuramente pelo mundo externo.

Quando o modelo para de produzir normalmente, mas não consegue concluir a tarefa porque o texto é muito longo, o sistema injeta uma mensagem de incentivo para que o modelo continue, desde que o orçamento de tokens seja suficiente. Os subagentes são proibidos de usar esse orçamento para evitar interrupções infinitas. A detecção de retornos decrescentes também entra em vigor: se o incremento for inferior a 500 tokens em três detecções consecutivas, o modelo estará ocioso e o sistema o forçará a encerrar.

IV. o sistema de ferramentas: restrições e capacidades

O sistema de ferramentas abrange mais de 40 diretórios e quase 50.000 linhas de código, e tudo o que o Agent pode fazer é completamente limitado pela biblioteca de ferramentas fornecida pelo sistema.

4.1 Seis grupos funcionais da interface da ferramenta

A ferramenta de interface genérica especifica cerca de 30 métodos, que são funcionalmente divididos em seis módulos. O módulo buildTool As funções de fábrica injetam padrões de segurança severos:

causalidade	valor padrão	Motivação para o design
isConcurrencySafe	false	Forçar o enfileiramento em série, presumindo que conflitos simultâneos serão acionados
isReadOnly	false	Assumindo um recurso de operação de gravação, acionando a auditoria estrita de permissão de gravação
isDestructive	false	Não predefinido como uma ação destrutiva para evitar que a fadiga da interface do usuário envie avisos de spam
checkPermissions	allow	Versão padrão interna, a interceptação real é tratada pelo sistema de permissões globais externas sob o capô

4.2 Mais de 40 estados do ToolUseContext

instrumental call() precisa receber um valor extremamente grande de ToolUseContext o que mostra que a ferramenta subjacente não é de forma alguma uma função pura:

parágrafos de texto superior e inferior	uso	Por que não pode ser omitido
readFileState	Cache de registro de leitura de arquivo	O FileEditTool deve verificar esse campo para negar a edição de arquivos que não tenham sido revisados pelo modelo.
abortController	Cancelamento da alça de sinal	Permite que o usuário interrompa comandos de compilação demorados executados pelo BashTool a qualquer momento.
setToolJSX	Injeção de retorno de chamada de renderização da interface do usuário	Permite que ferramentas como o BashTool desenhem componentes da barra de progresso diretamente no terminal
agentId	identificação da instância	Distinguir entre o processo mestre e os subagentes para vincular diretórios CWD separados
contentReplacementState	Controle orçamentário	Interceptação de saída de ferramenta descontrolada para evitar que ela estoure instantaneamente o contexto do sistema
updateFileHistoryState	Indicador de estado histórico	Fornece rastreamento de alterações de documentos e é /rewind Desfazer as dependências subjacentes do comando

Se o estado global precisar ser modificado depois que a ferramenta for executada (por exemplo cd (troca de diretórios), o que só pode ser feito retornando contextModifier Os campos estão sujeitos a modificações controladas. E essa permissão está aberta apenas para ferramentas seriais; ferramentas executadas simultaneamente são estritamente proibidas de interferir no ambiente global.

4.3 Eliminação em tempo de compilação e registro de partição

src/tools.ts Três estratégias são usadas para registro e carregamento de ferramentas:

Bun's feature() As macros desempenham um papel fundamental aqui. As macros sob o controle da porta de recursos require() Se for determinado que uma ramificação é falsa, o construtor não só não executa a lógica, como também usa o DCE (Dead Code Elimination) para apagá-la completamente do produto. Devido à dinâmica require() Suporte ao agrupamento de instruções condicionais enquanto estático import Não, então o require()。
Fase de montagem da ferramenta assembleToolPool Uma estratégia rigorosa de classificação de partições foi implementada: as ferramentas integradas vêm em primeiro lugar e são classificadas em ordem alfabética, introduzidas externamente MCP no final da lista. Esse layout não híbrido garante que os pontos de interrupção do cache do Prompt Cache no lado do servidor caiam consistentemente após a última ferramenta integrada, evitando que MCPs carregados dinamicamente invalidem caches de longa duração.

4.4 BashTool: uma fortaleza de segurança para 18 arquivos

Devido ao poder destrutivo quase ilimitado do comando Shell, o BashTool ocupa 18 arquivos apenas, criando um sistema de defesa de 8 camadas.

Vários projetos de segurança altamente informativos:
Isolamento físico do Composite CommandO sistema usa o tree-sitter para analisar o Shell AST, que irá cd /path && python3 evil.py Dividido com precisão em SimpleCommands separados, o comando composto inteiro será rejeitado se algum dos subcomandos falhar na auditoria. Para evitar ataques de ReDoS e inanição de loop de eventos, um único comando é obrigatoriamente dividido em um máximo de 50 subcomandos.
Validação de lista branca no nível do sinalizadorComando: Não apenas o nome do comando é bloqueado, mas também o valor do parâmetro (sinalizador) é examinado em profundidade. Por exemplo, limitar xargs -I formato de entrada para proteger contra a exploração maliciosa do modelo -i Semântica da variante GNU para execução de injeção de processos.
25 Detecção de injeção de sintaxe：bashSecurity.ts Mais de 25 lógicas de detecção específicas de sintaxe estão incluídas, abrangendo a substituição de comandos (aspas invertidas ou $()), substituição de processos (<()), métodos incorporados de alto risco específicos do Zsh (por exemplo zmodload、syswrite), caracteres de controle e vários tipos de espaços em branco de camuflagem Unicode.
Bolsas ambientais Sandbox：SandboxManager Uma camada final da rede de segurança é construída restringindo os caminhos de leitura e gravação no sistema de arquivos, limitando os endereços de acesso à rede e os soquetes Unix.

4.5 Invariantes de busca e substituição do FileEditTool

Em vez de usar a lógica de adição/exclusão baseada no número da linha, o FileEditTool impõe a “busca e substituição”. Isso pressupõe que o modelo fornece old_string O bloco de código deve ter uma correspondência exclusiva no arquivo de origem de destino. Se houver mais de uma correspondência, o sistema interromperá a modificação e solicitará que o modelo continue fornecendo mais código de contexto até que ele seja exclusivo. Essa restrição rígida, porém confiável, elimina completamente os acidentes catastróficos em que o modelo altera o local errado.
Enquanto isso, o já mencionado readFileState Uma segunda linha de defesa invariante é construída: a proibição de editar arquivos não lidos. O modelo não pode editar cegamente um arquivo de sua própria “memória alucinatória”; ele deve primeiro usar o FileRead para confirmar o estado atual do arquivo.

V. Sistema de competência: uma barreira imunológica para o sistema

Esse sistema de mais de 70 documentos define delicadamente a escala de confiança entre “permitir que a IA opere de forma autônoma” e “evitar uma catástrofe sistêmica”.

5.1 Espectro contínuo de gradientes de confiança

O sistema de permissão define seis gradientes, desde o bloqueio até a delegação total:

paradigma	Características comportamentais essenciais	Fluxos de trabalho aplicáveis
plan	Privar tudo do acesso de gravação, os modelos só podem ser usados para planejamento arquitetônico e revisão de código	Análises e auditorias exploratórias
default	Modo de inicialização padrão, cada chamada de ferramenta exibe uma interface do usuário solicitando confirmação manual	Colaboração diária e rotineira no desenvolvimento
acceptEdits	Os arquivos de leitura e gravação no espaço de trabalho são liberados silenciosamente; o restante do ambiente ainda precisa ser bloqueado para confirmar a modificação.	Refatoração de código com um nível muito alto de confiança
auto	Introdução de classificadores inteligentes no lado do modelo para avaliar a segurança em tempo real (ambiente interno)	Automação de alta frequência
bypassPermissions	Ignora completamente o processo de verificação manual regular, mantendo apenas o bloqueio subjacente do kernel	Ambiente de CI ou contêiner de isolamento controlado
dontAsk	Quando você encontrar um prompt de interceptação, converta-o diretamente em Deny para ignorar a tarefa sem uma janela pop-up	Scripts autônomos puramente automatizados

Em conjunto com esse modelo, o sistema é incorporado a um mecanismo de controle baseado em Statsig. bypassPermissionsKillswitch.ts Fusível remoto. Quando o Anthropic Faça o downgrade instantâneo e remoto de clientes globais no modo bypass quando uma violação de segurança em larga escala for capturada.auto O modo tem um efeito semelhante autoModeCircuitBroken O mecanismo de corte.

5.2 Avaliação multicamada da tubulação e mascaramento regular

ser direcionado contra rm -rf / Esse tipo de instrução sensível é avaliado com um mecanismo de pipeline de várias camadas desenvolvido pelo sistema:

As regras explícitas do Ask têm precedência absolutaMesmo que você esteja atualmente no bypassPermissionsSe o usuário configurar manualmente o ask: ["Bash(npm publish:*)"]O sistema também aborta a execução automática e abre uma janela. Isso implementa a filosofia de design de que “os comandos explícitos do usuário sempre substituem o modo global”.
Imunidade de caminho codificada:: Para o .git/、.claude/、.vscode/ e arquivos de configuração de terminal (por exemplo .bashrc、.zshrcAs modificações no modo de desvio são codificadas para serem imunes ao modo de desvio e devem ser verificadas manualmente em todos os casos.
Proteção do fusível classificadorNo modo automático, se o classificador de IA rejeitar o comando três vezes seguidas, ou um total de 20 rejeições em uma única sessão, o sistema fará o downgrade de uma rejeição inteligente para um pop-up forçado solicitando a intervenção do usuário. Se o sistema estiver no momento no modo Headless, ele lançará diretamente o comando AbortError Destruir todo o processo do agente.

5.3 Detecção de fontes de regras, sintaxe e mascaramento

Cada regra de permissão é controlada em 8 níveis de origem diferentes. Os administradores corporativos usam policySettings Com domínio absoluto, ao abrir o allowManagedPermissionRulesOnly: true Depois disso, o sistema só reconhece o livro de regras emitido pela empresa.

A sintaxe de correspondência do Shell suporta correspondência exata, correspondência de prefixo antigo (npm:*) e curingas regulares. O sistema acrescenta um toque elegante aqui: quando o padrão termina com um espaço mais um curinga (como em git *), o sistema compila a cauda como uma correspondência opcional, de modo que a regra corresponda a ambos os git add Também compatível com comandos simples git。
Para abordar os pontos problemáticos da experiência do usuário, ashadowedRuleDetection.ts A detecção de mascaramento de regras será realizada no arquivo de configuração. Quando um usuário define incorretamente o deny: ["Bash"] colocar em allow:["Bash(ls:*)"] Anteriormente, esse último nunca poderia ser alcançado devido à ordem do pipeline de avaliação, e o nível da interface do usuário exibia imediatamente um aviso vermelho instruindo o usuário a ajustar a ordem.

5.4 Três manipuladores para a transmissão de privilégios em vários agentes

O processador de permissões divide três caminhos para diferentes tipos de agentes subordinados:

• interactiveHandlerModelo de interação orientado por padrões, solicitado por meio de um pop-up de interface.
• coordinatorHandlerTrabalhar com Classificadores e Ganchos para priorizar aprovações silenciosas e intervir manualmente quando elas falharem.
• swarmWorkerHandler: Cooperação bubble Um mecanismo de bubbling que envia solicitações entre processos para o Leader Permission Bridge do ponto de extremidade da linha principal.
  Se o agente for um arquivo com a extensão shouldAvoidPermissionPrompts: true Como a tarefa assíncrona é marcada, ela não tem interface para aparecer quando encontra uma solicitação de corroboração e simplesmente executa um veto silencioso (rejeição automática) na tarefa.

Colaboração multiagente: criando inteligência de enxame

Diante de tarefas de desenvolvimento complexas e de longo prazo, o sistema deriva uma arquitetura multiagente robusta por meio da divisão de tarefas e do isolamento do espaço de trabalho.

6.1 Limite de abstração de três camadas

• SubagentNó filho: nós filhos extremamente leves, geralmente puxados de forma síncrona ou assíncrona pelo nó pai, usados para executar tarefas atômicas semelhantes às definidas pela função de recuperação.
• Team/SwarmTopologia de equipe com um ciclo de vida completo. Os membros são divididos em líder e colega de equipe, com recursos de comunicação ponto a ponto, o que os torna ideais para refatoração paralela em front-end e back-end.
• CoordinatorModo de orquestração: Um orquestrador de tarefas puro. Os nós nesse modo não podem invocar as ferramentas de leitura/gravação subjacentes e se concentram inteiramente na análise de relatórios de nós filhos e na emissão de comandos.

6.2 Roteamento unificado com o AgentTool

Todas as ações acionadas contra subprocessos no sistema convergem para o único AgentTool. Essa iniciativa reduz significativamente a sobrecarga cognitiva das ferramentas de chamada de modelo.

O agente é abstraído como uma grande definição de tipo federado de três níveis contendo: nós internos (BuiltIn), substituição do usuário (Custom), bem como plug-ins externos (Plugin). Os conflitos ocorrem built-in < plugin < userSettings < projectSettings < flagSettings < policySettings o princípio da substituição hierárquica.

6.3 Agente incorporado extremamente personalizável

Vários agentes com funções especializadas são codificados no sistema:
Explorar (específico para pesquisa)O modelo Haiku é forçado a bloquear o modelo Haiku (o mais barato e mais rápido), desativando completamente as permissões de edição/gravação. De forma ainda mais extrema, os comentários do código-fonte mostram que ele ativamente abandona as permissões CLAUDE.md(configuração da especificação do projeto) e o status do Git são dois grandes dados somente de leitura. Em uma implantação em grande escala, com 34 milhões de chamadas derivadas por semana, omitir apenas essas duas informações economiza 5-15 Gtok/week A dosagem horrível.
VerificaçãoO Prompt é o Prompt mais longo: com quase 120 linhas, ele foi projetado para combater a ilusão autodestrutiva a que o LLM está propenso de que “o código parece bom e o teste deve passar”, exigindo a saída de instruções específicas de execução de teste, bem como um registro de saída padrão antes de chegar a uma conclusão. Além disso, ele vem com background: true sempre computados de forma assíncrona em segundo plano.

6.4 Controle refinado dos mecanismos de execução de subnós

runAgent() assume o ônus da execução do nó filho. Sua lógica central é reutilizar completamente o query() Estrutura cíclica.
Para substituições de permissão, o sistema introduz uma lógica de restrição de segurança obrigatória: os nós filhos podem se declarar permissionModemas nunca é permitido executar o comando bypassPermissions、acceptEdits 和 auto O nó pai do padrão é puxado para o default Modo. Em resumo, os subsistemas não podem quebrar o mecanismo de fluxo de confiança global mascarando-se como um nível de segurança mais alto.

A filtragem de ferramentas foi submetida a três níveis de triagem rigorosa:

1. A tabela de desativação global (ALL_AGENT_DISALLOWED_TOOLS) está bloqueada em todo o quadro.
2. A tabela de desativação de agente não incorporada (CUSTOM_AGENT_DISALLOWED_TOOLS) bloqueia ferramentas ilegais.
3. Controle de lista branca específico do agente assíncrono (ASYNC_AGENT_ALLOWED_TOOLS).
   Vale a pena observar que todos os produtos que começam com mcp__ As ferramentas MCP externas com nome de prefixo são liberadas na íntegra, ignorando todas as regras acima, garantindo que as extensões externas não sejam restritas pelo tipo de topologia interna.

No final do ciclo de vida, a fase de limpeza deve executar exatamente oito tarefas de limpeza: quebrar links MCP proprietários, limpar o ouvinte de ganchos de sessão, forçar a limpeza do Prompt Cache alocado, liberar o dicionário do cache de estado do arquivo, cancelar o registro dos identificadores de rastreamento de desempenho do Perfetto, esvaziar a tabela de mapeamento de transcrição, varrer tarefas órfãs, eliminar os processos residentes do processos residentes do bash em segundo plano que não foram encerrados.

6.5 Subagente de bifurcação: redução extrema das taxas de acerto do cache

Como um modelo experimental, o Fork tem como objetivo herdar totalmente o contexto da memória e os registros de diálogo do nó mestre.
Sua principal tarefa é maximizar a taxa de acerto do Prompt Cache. Todas as estruturas de mensagens de histórico de entrada e tool_use Os espaços reservados devem ser mantidos consistentes em nível de bit, anexando apenas uma instrução específica ao nó filho atual no final do fluxo de dados. Quando vários garfos são iniciados simultaneamente, eles atingem diretamente a extremidade mais distante do cache de prefixo de alta velocidade porque as sequências de dados do primeiro 99% se sobrepõem completamente.
O projeto contra explosões induzidas por recursão é igualmente exigente: o sistema implementa um mecanismo de verificação dupla. Ele se baseia no querySource (verificador anticompressão) e na varredura do fluxo de mensagens para o <fork-boilerplate> Os rótulos funcionam como uma apólice de seguro dupla que bloqueia a derivação infinita.
No comando de injeção final, o comando “STOP. READ THIS FIRST.” (PARE. LEIA ISSO PRIMEIRO), em inglês, é usado para forçar o desvio da atenção do LLM, exigindo que ele ignore a antiga identidade herdada e assuma as tarefas recém-designadas.

6.6 Mecanismo de back-end de trilha dupla do Team/Swarm

Para dar suporte ao trabalho em equipe, o sistema é construído com duas arquiteturas subjacentes completamente diferentes:

O sistema executa a detecção e a degradação com base no estado do ambiente: se estiver no tmux, habilite o TmuxBackend; se estiver no iTerm2, habilite o ITermBackend; se não estiver em nenhum dos dois, mas o sistema for detectado como detentor do tmux, chame uma sessão externa do Tmux; se não estiver em nada, force um aborto com lançamento de erro e peça ao usuário para configurar o ambiente. No modo puramente orientado pelo SDK, o sistema é bloqueado usando In-process.
Esses dois back-ends estão sendo consistentemente TeammateExecutor A especificação da interface protege as diferenças, e as APIs expostas ao nível superior são todas simples spawn()、sendMessage() 和 terminate()。

6.7 Motores em processo extremamente complexos

Com quase 1.400 linhas de código, o src/utils/swarm/inProcessRunner.ts É o hub mais complexo da rede colaborativa.

Proteção contra evasão de privilégios para memória compartilhada.createInProcessCanUseTool() Foi construído um fluxo de aprovação refinado de três níveis:

1. Realize as verificações usuais de permissão/negação.
2. Em caso de pergunta, ela será tentada primeiro pelo classificador de back-end.
3. Habilite os componentes principais se for necessária uma intervenção manual Leader Permission Bridge(ponte de privilégio do nó mestre).
   A tarefa em segundo plano usa a ponte para fazer a chamada reversa do processo REPL em primeiro plano exposto setToolUseConfirmQueueOs resultados da aprovação são enviados de volta para o colega de equipe com o crachá do colega de equipe, que desenha uma caixa de confirmação de substituição com o crachá específico do colega de equipe na tela inicial. Os resultados da aprovação são retornados com preserveMode: true isolando completamente os subsistemas de sondar os padrões de privilégios globais do sistema mestre por meio desse caminho.

O estado de espera ocioso é introduzido no controle do ciclo de vida. Em vez de destruir fisicamente o processo quando o colega de equipe conclui sua tarefa, ele fica suspenso e envia uma mensagem de ociosidade ao nó mestre contendo um resumo de comunicação ponto a ponto (resumo DM ponto a ponto).
Para a inflação descontrolada da memória, o componente incorporou o TEAMMATE_MESSAGES_UI_CAP = 50 As notas do código-fonte revelam que, durante um desastroso teste de estresse de “sessão de baleia”, o sistema gerou 292 Linked Agents em 2 minutos. Esse limite físico é uma lição aprendida em um teste de estresse desastroso de "sessão de baleia", no qual o sistema gerou 292 Linked Agents em 2 minutos e o consumo de memória excedeu instantaneamente 36,8 GB.

6.8 Caixas postais inter-redes e conceitos de design do coordenador

A comunicação colaborativa entre processos físicos independentes é incorporada ao sistema de arquivos local ~/.claude/teams/<teamName>/mailbox/<agentName>/ Acima do caminho. Utilização unificada SendMessageTool Montar a rota.

O protocolo de comunicação contém quadros de controle estruturados (por exemplo shutdown_request、shutdown_response 及 plan_approval_request), permitindo que a rede tenha recursos de auto-recuperação e processamento de fluxo de resposta.

Mais acima na camada.coordinatorMode.ts Revela as diretrizes de design do Supreme Commander. Ele contém apenas seis ferramentas de comando, como TeamCreate, TaskStop, SendMessage e assim por diante. Seu Prompt proprietário de 260 linhas define uma lógica de quatro fases que inclui síntese e análise, emissão de comandos e assim por diante.
Há um tabu central do antipadrão oculto aqui:“Nunca delegue o processo de compreensão.”O coordenador é proibido de enviar instruções vagas como “conserte o bug com base em sua análise” para os nós filhos e precisa analisar todo o contexto por conta própria, traduzindo-o em instruções de execução com ponteiros claros para o número do arquivo e da linha.
Para compensar a incapacidade do Coordenador de editar arquivos, ele tem um diretório Scratchpad especial. Todos os funcionários podem colocar artefatos de análise intermediários nesse diretório, independentemente das aprovações regulares de leitura/gravação. Além disso, esse modelo é totalmente mutuamente exclusivo do Fork - um Commander que não tem nenhum poder real sobre o estado de um arquivo e não pode gerar nenhuma herança válida.

6.9 Infraestrutura para trabalho assíncrono: o sistema de tarefas

Qualquer lógica que bloqueie a interface principal por muito tempo é colocada no AppState.tasks A custódia centralizada é realizada.

LocalAgentTask Fornece dimensionamento extremamente preciso: relatório em tempo real do número total de ferramentas invocadas, um registro global de sobrecarga de token com entradas e saídas e uma descrição em texto das últimas 5 invocações.
InProcessTeammateTask A arquitetura de controle do AbortController duplo é mantida: o controlador principal abortController responsável pela extração física de toda a máquina, e o currentWorkAbortController Simplesmente retire o polling da ferramenta que está aguardando no momento.
DreamTask （O mais específico desses conceitos é a Tarefa do Organizador de Sonhos. Durante a inatividade do terminal, essa tarefa é iniciada automaticamente como um daemon, regurgitando dados de conversas recentes e condensando-os em um arquivo de memória. No caso de uma interrupção não planejada, ela kill() A rotina executa automaticamente a técnica de reversão do registro de data e hora do arquivo de bloqueio para garantir uma retransmissão contínua na próxima reinicialização.

6.10 Transmissão do conjunto completo de permissões entre vários nós

Essas seis cadeias de transmissão aderem estritamente à “exposição mínima + prevenção da proliferação além dos limites da autoridade”.

VII. Projeto System Prompt: reformulando o contexto

entrar em src/constants/prompts.ts 与 src/context.tsA lógica aqui é uma rejeição completa dos Prompts mecânicos. O sistema realiza uma engenharia de contexto extremamente sofisticada.

7.1 Sistema de cache segmentado por memorização

Em vez de ser montado em uma única sequência gigante de caracteres, o enorme banco de palavras-chave é dividido em string[] Contêineres segmentados. O driver principal vai direto para a camada de API do contêiner Prompt Cache Otimização.

SYSTEM_PROMPT_DYNAMIC_BOUNDARY como uma bacia hidrográfica. Acima disso estão as constantes estáticas que carregam scope: 'global' Os identificadores de cache são compartilhados entre usuários globais. Quando um grande número de solicitações atinge a mesma constante de prefixo, não apenas o custo da API cai vertiginosamente, mas o tempo de resposta também é extremamente reduzido.
A passagem abaixo do limite é exclusiva do usuário. O código-fonte permite que as funções que pretendem romper esse limite com o DANGEROUS_uncachedSystemPromptSection Prefixo de aviso para forçar os desenvolvedores a fornecer o _reason Parâmetros de quantidade literal para revisão de código.

7.2 Constituição estática e estratégias de especialização

O princípio da “simplicidade do código” é enfatizado para o modelo várias vezes no parágrafo da especificação Doing Tasks: “Três linhas de código semelhantes são melhores do que uma abstração prematura. uma abstração prematura”. Essa é essencialmente uma diretriz defensiva para suprimir a tendência inerente do LLM de “fazer engenharia excessiva e se exibir”.
O parágrafo de controle de ações declara explicitamente o princípio do isolamento da autorização: “A permissão de um usuário uma vez não significa que ela seja liberada em todos os contextos”.
Para a versão interna da configuração privilegiada, há até mesmo a restrição peculiar de “não escrever nenhum comentário de código por padrão”. As anotações confirmaram que, nas primeiras avaliações do modelo Capybara v8, em que a lógica hipotética gerada pelo modelo resultou em uma taxa de declarações falsas de 29-30%, a proibição total das anotações tornou-se o compromisso provisório mais rápido.
Para a seção de ferramentas, o modelo é rigorosamente especificado para usar ferramentas especializadas em vez da cadeia de comando Bash (por exemplo, FileRead em vez de cat), e a saída estruturada e o ambiente controlado fornecidos por ferramentas especializadas podem reduzir significativamente as surpresas.

7.3 Detecção ambiental e injeção incremental dinâmica

Durante a fase de inicialização da sessão, osrc/context.ts detectará e mesclará as camadas para cima retrospectivamente. CLAUDE.md O arquivo é injetado no userContext em. Isso é adotado aqui --bare O Pure Start, embora interrompa a exploração automática, ainda segue um caminho rigoroso através do --add-dir A regra para montagens manuais, ou seja, “bare significa não adicionar ativamente, não aceitar entrada”.
Isso também quebra o loop interno sem saída do classificador:yoloClassifier → claudemd → filesystem → permissions → yoloClassifier。CLAUDE.md Codificado para a primeira vez após o carregamento bootstrap/state.ts Fornece bloqueio de cache.
A injeção de estado do Git extrai cinco fluxos de informações simultaneamente (ramo atual, ramo mestre, estado do espaço de trabalho, últimos cinco commits e operador). Para evitar a sobrecarga de informações, o status do espaço de trabalho é limitado a 2.000 caracteres, e o modelo de prompt obtém o registro completo do BashTool quando necessário.
Ao se comunicar com um servidor MCP externo.isMcpInstructionsDeltaEnabled Os switches controlam os comandos para fazer o downstream incremental somente quando a topologia muda, bloqueando a transmissão desnecessária de bytes duplicados.

7.4 Compressão e reconstrução das quatro linhas de defesa

Quando os contextos limitados de token estão à beira da exaustão, o sistema permite quatro níveis diferentes de defesa de compactação:

Estratégia AutoCompactO prompt de inicialização usado é extremamente refinado, forçando a retenção de nove categorias de informações, incluindo o roteamento de erros. O foco principal é “todas as mensagens originais de comando do usuário que não são convertidas em saída de ferramenta devem ser mantidas”. O LLM é propenso a perder solicitações adicionais do usuário, como “Acabei de dizer não Redux” no estágio de resumo, que é essencialmente uma tecnologia anti-esquecimento. A engenharia é essencialmente uma técnica contra o esquecimento.
Depois que a compactação for concluída e a fase de reconstrução estiver em andamento, o sistema extrairá novamente até 5 arquivos principais (com um limite de 5.000 tokens cada) e 25.000 fragmentos de tokens de comandos de habilidade para reinjeção reversa, a fim de garantir que não tenha perdido completamente a visão dos detalhes dos arquivos.
Além disso, como o AutoCompact é tão destrutivo, ele é naturalmente exclusivo do Context Collapse, um esquema de dobramento progressivo leve - o AutoCompact é suprimido à força quando o modo de dobramento é ativado.

Terminal UI: Refatorando o mecanismo de renderização avançado do React

Toda a interface CLI consiste nos dados armazenados no src/ink/ 90 arquivos no diretório, quase 20.000 linhas de código React assumiram o controle. Isso muda completamente a imagem da CLI como uma saída grosseira.

8.1 Pipeline de renderização de nível 5 com TS Yoga

1. React Reconciler: Chamada react-reconciler Colocando o React <Box> Analisa o DOM do ponto de extremidade com o mecanismo de Yoga montado na parte inferior. ink-box. ConcurrentRoot com suporte para os recursos de simultaneidade do React 19.
2. Yoga Pure TS Refactoredelimina a lógica de cálculo do arquivo WASM referenciada pelo Ink original para evitar await loadYoga() atraso na primeira tela e inchaço linear da memória após uma longa execução, movendo todas as interfaces de renderização para a camada de isolamento LayoutNode Alinhamento.
3. pool de objetos residentesOs caracteres ASCII são obtidos em um Int32Array. CharPool O índice O(1) atingido noStylePool As sequências diferenciais antes e depois da conversão são armazenadas diretamente em cache; contém gravações de link para protocolos OSC 8 especiais HyperlinkPool. Os removedores cronometrados executados a cada cinco minutos contarão com o migrateScreenPools método para recuperar e migrar unidades celulares (células) ainda ativas.

8.2 Otimização máxima em nível de hardware contra a cintilação

O sistema percorre apenas a ocorrência de dirty Marca a área de visualização gerada pelo movimento ou deslocamento. Isso faz com que a sobrecarga da CPU de uma animação de relógio ou de um componente de rotação da barra de progresso dependa apenas de sua área.
Em vez de executar o redesenho por força bruta diante de uma grande saída de rolagem de texto, o mecanismo de rolagem DECSTBM em nível de driver de hardware do terminal subjacente é simulado (veja abaixo). CSI top;bot r 及 CSI n S instrução) e, ao mesmo tempo, o prev.screen O mapeamento de deslocamento é realizado para que o algoritmo Diff tenha que lidar apenas com a única linha nova que aparece na tela.
O mecanismo Double Buffering é usado para manter os dois quadros dos canais frontal e traseiro, complementado pela aceleração de alta frequência do Lodash (16 ms a 60 fps). leading + trailing (modo DEC 2026) e, por meio do protocolo DEC 2026, a BSU (Begin Synchronised Update) e a ESU são encapsuladas antes e depois dos dados de atualização completos, realizando completamente a atualização atômica sincronizada com quadros da tela do terminal e eliminando a cintilação estroboscópica. A análise em linha também introduz charCache Força um acerto no resultado ANSI computado para pular a operação demorada.

8.3 Capturando o mecanismo de borbulhamento sem estado do Redux

Um sofisticado interceptador de eventos em nível de DOM (Dispatcher) está incorporado. A entrada do teclado recebe o DiscreteEventPriority(direitos de processamento imediato do plug-in), enquanto a transformação da janela (Resize) etc. é planejada no ContinuousEventPriority Execute o processo de pontilhamento e mesclagem.
Abandonando o Redux pesado e redundante, o DeepImmutable-based AppState Mantém cerca de 50 dicionários de estado central para acompanhar a injeção nativa do React Context. Globalmente, ele se baseia apenas no onChangeAppState Os ganchos capturam efeitos colaterais de alta prioridade, como a troca de modo de permissão, e os enviam para os componentes relevantes em tempo real.

IX Integração de MCP: módulos plug-in de capacidade padronizada

enfrentado Model Context Protocol (MCP), um protocolo que está se tornando um padrão do setor, os módulos são colocados no src/services/mcp/ Médio.

fundo (de uma pilha) config.ts Extraia configurações de rede de seis fontes diferentes, como política empresarial, especificações de projetos locais etc. Ao encontrar a lista de sincronização do ambiente de nuvem do Claude.ai, odedupClaudeAiMcpServers Assumirá a desduplicação e cederá o controle de alta prioridade para a configuração local.
Novas ferramentas externas descobertas são recapituladas no momento do acesso, com uma conversão obrigatória de nome para mcp__<serverName>__<toolName> Esse formato específico evita conflitos de substituição, e sua definição de esquema JSON é remapeada na rede de validação de proteção Zod do próprio sistema. refreshTools() para capturar as alterações funcionais mais recentes em nós externos.
embutido McpAuthTool São fornecidas interfaces especiais para servidores que exigem autenticação secundária. Quando uma operação de modelo é bloqueada, o processo pode ser interrompido, orientando o usuário a passar pelo handshake do OAuth no lado do navegador e retornar com as credenciais para reinstruir o usuário.

X. Inspiração da arquitetura e profundidade de reflexão da engenharia

A dissecação dessa enorme quantidade de código de engenharia resultou nos seguintes padrões de projeto valiosos para qualquer desenvolvedor que esteja tentando criar um sistema do tipo Agentic:

AsyncGenerator como uma pedra fundamental absolutaO gerador assíncrono lida com toda a cadeia de execução, demonstrando o domínio incomparável do sistema das cadeias Promise na solução de simultaneidade de streaming de modelos, supressão de contrapressão reversa, redução em cascata de sinais de revogação segura e invocações combinatórias.

Capô de segurança com fechamento por falha extremaO fato de não registrar um atributo de simultaneidade significa que a simultaneidade é proibida, e o fato de não especificar um atributo de leitura/gravação significa que ele é tratado como uma gravação maliciosa. Esse tipo de projeto, em que as vulnerabilidades são pré-programadas como negações por meio da camada de estrutura, merece ser emulado nas camadas subjacentes de todos os sistemas.

Abandone definitivamente o isolamento de construção if-else：feature() As macros [7] no nível físico eliminam qualquer chance de a funcionalidade não pronta entrar no ambiente de produção, evitando possíveis anomalias no tempo de execução ou vazamentos de descompilação.

Tudo para o projeto de refatoração do serviço de cache do PromptDesde a cuidadosa ordenação para trás e para frente das listas de ferramentas, passando pelo fatiamento constitucional dos limites do sistema, até a estranha reposição de sufixos das operações Fork. As arquiteturas de sistemas grandes devem considerar as taxas de acerto do cache como um “cidadão de primeira classe” em vez de uma reflexão tardia.

Contramedidas de engenharia para lidar com as deficiências do LLMPor exemplo, o histórico de pré-compressão determina que “nenhum valor de retorno não instrumentado da instrução original pode ser descartado”, usando a engenharia para compensar a dureza generalizada do modelo de linguagem grande que tende a descartar pequenos requisitos do usuário e levar à amnésia.

Perigos da arquitetura legada: mesmo que rigoroso como é, em bootstrap/state.ts O aviso “NÃO ADICIONE MAIS ESTADO AQUI” permanece em um objeto global com mais de 200 campos de dicionário mantidos no sistema. Para um sistema complexo de 500.000 linhas, a falta de gerenciamento de estado granular baseado em injeção de dependência é um sinal de alerta.
Também.BashTool Embora bem projetado, o código é muito grande e complexo devido ao mecanismo de validação de isolamento de 8 camadas, e a capacidade de expansão da estrutura seria bastante aprimorada se a lógica de validação pudesse ser retirada e substituída por uma configuração de mecanismo declarativo no estilo OPA (Open Policy Agent) ou Rego.
No nível de persistência de dados, o feedback do fluxo de ferramentas ainda está na forma de strings planas. Se puder ser reconfigurado em um armazenamento de camada de dados com capacidade de recuperação estruturada, isso ajudará o sistema de memória de longa duração e o Context Collapse a obter pontos de entrada de dobra mais precisos.
Com o Anthropic extraindo os módulos principais em uma distribuição de SDK de código aberto, a evolução futura será desacoplada e com plug-ins.

Apêndice: Índice do motor principal e da superfície de controle

módulo do sistema	Documentação subjacente de programação e implementação	Avaliação do volume do código
Núcleo do mecanismo de Loop do agente	src/QueryEngine.ts, src/query.ts	3.024 linhas
Triagem de ferramentas e agendador de simultaneidade	src/services/tools/StreamingToolExecutor.ts, toolExecution.ts	2.275 linhas
Métodos abstratos e montagem de ferramentas	src/Tool.ts, src/tools.ts	1.181 linhas
Superfície de controle da caixa de areia física do Bash	src/tools/BashTool/ Catálogo (18 arquivos)	Aprox. 5.000 linhas
Centro de Auditoria de Autorização de Segurança Global	src/utils/permissions/permissions.ts	Aprox. 1.400 linhas
Mascaramento de regras e avaliação de redes de interceptação	src/utils/permissions/ Catálogo (24 arquivos)	Aprox. 5.000 linhas
Rede de topologia de tarefas de subagentes	src/tools/AgentTool/ Catálogo (20 arquivos)	Aprox. 6.000 linhas
Swarm Conectividade entre equipes e caixas de correio	src/utils/swarm/ Catálogo (22 arquivos)	Aprox. 5.000 linhas
Constantes incorporadas do prompt do sistema	src/constants/prompts.ts	914 Fila
Módulo dobrável de compressão de informações globais	src/services/compact/ Catálogo (11 arquivos)	3.960 linhas
Componente de renderização de hardware React-Ink	src/ink/ Catálogo (90 arquivos)	19.842 linhas
Camada de conectividade e conversão do protocolo MCP	src/services/mcp/client.ts	3.348 linhas
Consolidação e eliminação de camadas de múltiplas fontes MCP	src/services/mcp/config.ts	1.578 linhas
Inicializar o buffer do sistema de inicialização	src/bootstrap/state.ts	Aprox. 800 linhas
Árvore de estado imutável do aplicativo React	src/state/AppStateStore.ts	Aprox. 400 linhas