💻 computer science

Phoenix: Safe GitHub Issue Resolution via Multi-Agent LLMs

O Phoenix é um sistema de LLM multiagente que resolve com segurança problemas do GitHub, desde a triagem até a criação de pull requests, empregando sete controles de segurança em camadas e uma estratégia de avaliação consciente da linha de base, alcançando uma taxa de resolução oracle de 75% em um recorte curado do SWE-bench Lite enquanto mantém 100% de preservação de correção em problemas do mundo real.

Autores originais: Kipngeno Koech, Muhammad Adam, Baimam Boukar Jean Jacques, Joao Barros

Publicado 2026-06-19

📖 5 min de leitura🧠 Leitura aprofundada

CC BY 4.0

Autores originais: Kipngeno Koech, Muhammad Adam, Baimam Boukar Jean Jacques, Joao Barros

Artigo original sob licença CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ Esta é uma explicação gerada por IA do artigo abaixo. Não foi escrita nem endossada pelos autores. Para precisão técnica, consulte o artigo original. Ler aviso legal completo

Imagine uma biblioteca imensa e movimentada chamada GitHub, onde milhões de pessoas deixam bilhetes adesivos nos livros pedindo correções, novos recursos ou apontando erros de digitação. Esses bilhetes são chamados de "issues" (problemas/tarefas). Normalmente, um bibliotecário humano precisa ler o bilhete, encontrar a página exata no livro, descobrir o que está errado, reescrever o texto e depois pedir a um bibliotecário sênior para verificar antes que ele volte à prateleira. Isso é lento e cansativo.

Phoenix é uma nova equipe de robôs de IA projetados para fazer este trabalho, mas com uma regra muito estrita: Não causar danos.

Veja como o Phoenix funciona, dividido em conceitos simples:

1. A Equipe de Especialistas (Os Seis Agentes)

Em vez de um único robô superinteligente tentando fazer tudo de uma vez (o que frequentemente leva a erros), o Phoenix utiliza uma equipe de seis trabalhadores especializados, como uma linha de montagem bem lubrificada:

O Planejador (The Planner): Lê o bilhete adesivo e desenha um mapa. Ele decide quais páginas precisam de mudanças e como corrigi-las.
O Reproductor (O Detetive): Antes de consertar qualquer coisa, este robô tenta recriar o problema. Ele diz: "Ok, se eu fizer X, o livro quebra?". Se ele puder provar que o livro está quebrado, ele prossegue. Se não, ele pula esta etapa para que a equipe não fique travada.
O Programador (The Coder): O escritor. Ele pega o mapa do Planejador e realmente reescreve o texto nas páginas.
O Testador (The Tester): O inspetor de qualidade. Ele passa o livro por uma máquina para ver se o novo texto causa novos erros.
O Analista de Falhas (The Failure Analyst): O médico. Se o Testador encontrar um novo erro, este robô diagnostica por que isso aconteceu e diz ao Programador como corrigir. Eles têm duas tentativas para consertar; se falharem duas vezes, param e pedem ajuda humana.
O Agente de PR (The PR Agent): O mensageiro. Assim que o conserto está pronto, ele embala tudo e entrega a um bibliotecário humano para aprovação final.

2. A "Rede de Segurança" (Sete Camadas de Proteção)

O artigo enfatiza que a IA pode ser perigosa se simplesmente começar a reescrever livros aleatoriamente. O Phoenix possui sete "guardiões de segurança" para evitar desastres:

A Cerca: Ele não permite que os robôs escrevam fora das paredes da biblioteca (evitando que deletem arquivos que não deveriam tocar).
O Crachá de Identificação: Verifica se os robôs possuem chaves (tokens) válidas para que não sejam bloqueados no meio do trabalho.
A Equipe de Limpeza: Remove partes bagunçadas e confusas dos bilhetes adesivos antes de mostrá-los aos robôs, para que eles não fiquem confusos com formatações ruins.
A Zona de "Proibido Entrar": Recusa-se a tocar nos arquivos de segurança da biblioteca (arquivos de workflow), pois mexer neles poderia trancar todos do lado de fora.
O Botão de Parada: Se os robôs ficarem presos em um loop ou continuarem cometendo o mesmo erro, o sistema puxa a tomada.
O Trabalhador Solo: Apenas um livro é trabalhado por vez para evitar que os robôs tropecem uns nos outros.
A Chave Atualizada: Atualiza automaticamente seus crachás de identificação antes que expirem, para que o trabalho nunca pare devido a um tempo limite (timeout).

3. O Teste de "Antes e Depois" (Consciência de Linha de Base)

Este é o truque mais inteligente do Phoenix. Às vezes, um livro da biblioteca já está quebrado antes de o robô tocá-lo.

Modo Antigo: Um robô corrige um erro de digitação, mas o livro ainda falha em um teste porque já estava quebrado anteriormente. O robô é culpado pela falha.
Modo Phoenix: Antes de o robô fazer qualquer alteração, ele tira uma "foto" (snapshot) do estado atual do livro. Após o robô fazer as mudanças, ele compara o novo estado com a foto original.
- Se o livro já estava quebrado e continua quebrado (mas nenhuma nova coisa quebrou), o Phoenix diz: "Sucesso! Não pioramos a situação."
- Se o livro estava funcionando e agora está quebrado, o Phoenix diz: "Pare! Introduzimos uma regressão."

4. O Que os Resultados Mostram

Os pesquisadores testaram o Phoenix de duas maneiras:

O Treino Prático (SWE-bench Lite): Deram ao Phoenix 24 problemas específicos e pré-definidos. O Phoenix resolveu 75% deles perfeitamente sem quebrar nada que já estava funcionando.
O Teste do Mundo Real (42 Problemas Reais): Deixaram o Phoenix livre em 42 problemas reais de 14 projetos diferentes.
- Segurança: O Phoenix alcançou 100% de "Preservação de Correção". Isso significa que ele nunca quebrou um teste que estava passando anteriormente. Foi incrivelmente seguro.
- Taxa de Sucesso: No entanto, apenas cerca de metade dos consertos foram de fato o conserto correto. A outra metade foram "alucinações", onde o robô escreveu código no lugar errado (como escrever um manual de reparos na seção de ficção). O robô sabia como consertar, mas às vezes não conseguia encontrar onde estava o problema.

O Ponto Principal

O Phoenix é como um aprendiz de bibliotecário muito cauteloso e altamente treinado. Ele é excelente em não tornar as coisas piores e muito bom em seguir um processo rigoroso. No entanto, às vezes tem dificuldade em encontrar a localização exata de um problema se a descrição não corresponder perfeitamente aos nomes dos arquivos.

O artigo conclui que, para a IA ser útil no mundo real, a segurança deve vir antes da velocidade. O Phoenix prova que, ao usar uma equipe de agentes especializados e guardiões de segurança rigorosos, é possível automatizar correções de software sem quebrar o software acidentalmente. O principal ponto a ser corrigido é ajudar o robô "Planejador" a encontrar a página certa no livro com mais frequência.

Resumo Técnico: Phoenix – Resolução Segura de Issues do GitHub via Multi-Agentes LLM

Declaração do Problema

Repositórios de código aberto no GitHub acumulam milhares de issues não resolvidas, criando um gargalo persistente de manutenção. Embora os Modelos de Linguagem de Grande Escala (LLMs) tenham demonstrado potencial na automação de tarefas de engenharia de software (ex: Devin, SWE-Agent, AutoCodeRover), otimizar apenas para taxas de resolução de issues pode comprometer a segurança. Sistemas que resolvem uma parte das issues, mas introduzem regressões em outras, oferecem um valor líquido incerto em ambientes de produção. Além disso, benchmarks existentes focam frequentemente no desempenho offline, negligenciando as complexidades da implantação em produção, como filtragem de gateway de API, expiração de tokens e suítes de testes pré-existentes já quebradas.

Metodologia

O Phoenix é um sistema multi-agente de LLM projetado para resolver issues do GitHub, desde o triagem até a criação de Pull Requests (PRs), priorizando a preservação da correção sobre as taxas brutas de resolução. O sistema opera através de um pipeline de malha fechada coordenado por um Orquestrador central e uma máquina de estados baseada em labels via webhook do GitHub.

Arquitetura do Sistema

O pipeline decompõe o fluxo de trabalho em seis agentes especializados, cada um correspondendo a uma etapa de um processo convencional de resolução de issues:

Agente de Planejamento (Planner Agent): Recebe o texto sanitizado da issue, árvores de arquivos do repositório e trechos relevantes. Ele gera um plano JSON estruturado detalhando a abordagem, arquivos a serem modificados, etapas de implementação e estratégia de teste. Utiliza pontuação de sobreposição de palavras-chave para determinar a relevância dos arquivos.
Agente de Reprodução (Reproducer Agent - Opcional): Tenta gerar um teste sintético que falhe na branch base para demonstrar o bug. A falha nesta etapa não é impeditiva, permitindo que o pipeline prossiga para a codificação mesmo que um harness de teste não possa ser gerado automaticamente.
Agente de Codificação (Coder Agent): Gera conteúdos completos de arquivos para os arquivos alterados com base no plano e em qualquer feedback de falha anterior. Ele impõe a autoverificação e adere aos estilos de código existentes.
Agente de Teste (Tester Agent): Executa a suíte de testes do projeto. Crucialmente, ele emprega uma estratégia de avaliação de teste ciente da linha de base (baseline-aware):
- Ele armazena temporariamente (stash) as mudanças do Phoenix e executa a suíte na branch base não modificada para coletar falhas de linha de base ( $B$ ).
- Ele restaura as mudanças e executa novamente para coletar falhas pós-mudança ( $P$ ).
- A correção é preservada se $P \setminus B = \emptyset$ (nenhum teste que passava anteriormente agora falha). Isso permite a avaliação em repositórios com pipelines de CI quebrados.
Agente de Análise de Falhas (Failure Analyst Agent): Se novas falhas forem detectadas, este agente analisa a saída e fornece feedback estruturado ao Coder por até dois ciclos de tentativa.
Agente de PR (PR Agent): Compõe e abre um pull request referenciando a issue, transicionando o estado para ai:review para inspeção humana.

Mecanismos de Segurança

Sete controles de segurança em camadas foram derivados de modos de falha empíricos observados durante o desenvolvimento e implantação:

Prevenção de travessia de diretório (path-traversal): Valida que as escritas de arquivos não escapem da raiz do repositório.
Exclusividade de estado de label: Garante transições de estado atômicas para evitar o acúmulo de labels obsoletas.
Guarda de arquivo de workflow: Descarta silenciosamente escritas em .github/workflows/ para evitar erros de permissão.
Sanitização de conteúdo: Trunca corpos de issues e remove stack traces para evitar respostas 403 de gateways de API (WAF).
Limite de ciclo de tentativa: Limita o feedback do Failure Analyst a duas rodadas; um detector de falta de progresso encerra os loops se as mudanças forem idênticas.
Serialização de concorrência: Um lock por instalação garante que uma issue seja processada por vez em clones compartilhados.
Atualização de token de instalação: Atualiza proativamente os tokens do GitHub App antes da expiração para evitar falhas de autenticação durante execuções longas.

Principais Contribuições

Arquitetura: Um pipeline de seis agentes com um Reproducer opcional, uma máquina de estados impulsionada por labels e racional de design explícito para decomposição, permitindo testes isolados e atribuição de falhas.
Avaliação Ciente da Linha de Base (Baseline-Aware): Uma estratégia de teste que distingue falhas pré-existentes de regressões introduzidas pelo Phoenix, permitindo a avaliação em repositórios com CI quebrado.
Lições de Implantação: Uma caracterização de perigos do mundo real (filtragem de WAF, expiração de token, limites de permissão) e os mecanismos específicos desenvolvidos para lidar com eles.

Resultados

O artigo apresenta resultados de dois cenários de avaliação:

1. SWE-bench Lite (24 Instâncias)

Avaliado em um recorte curado de 24 instâncias em 12 repositórios (3 instâncias cada).

Resolução Oracle: O Phoenix alcançou uma taxa de resolução oracle de 75% (18/24 instâncias).
Segurança de Regressão: Em todas as execuções que passaram no oracle, não houve regressões de "pass-to-pass".
Modos de Falha: As falhas ocorreram principalmente devido a estados terminais ai:failed ou timeouts do avaliador, não por violações de segurança.
Nota: Os autores declaram explicitamente que este recorte curado não é diretamente comparável aos resultados do leaderboard de split total devido ao uso do caminho de webhook de produção.

2. Piloto em 42 Issues Reais (14 Repositórios)

Avaliado em 14 repositórios abrangendo níveis Easy, Medium e Hard.

Preservação de Correção (CP): O Phoenix alcançou 100% de CP (42/42 issues). Nenhuma nova falha de teste foi introduzida em relação à linha de base.
Tempo de Resolução: Em repositórios de nível "Hard", o tempo médio de resolução end-to-end foi de 122 segundos.
Inspeção Qualitativa: A revisão manual revelou uma dicotomia na qualidade do output:
- ~50% dos PRs foram correções bem direcionadas, modificando módulos existentes.
- ~50% dos PRs colocaram código em caminhos incorretos e inventados (ex: src/core/config.py). Estes passaram na CP porque não introduziram regressões, mas não corrigiram o bug relatado. Esta limitação é atribuída ao ranking léxico de arquivos do Planner, e não às capacidades de síntese de código.

Significância e Alegações

O artigo posiciona o Phoenix não como um sistema que maximiza o número de issues resolvidas, mas como um sistema que prioriza a preservação da correção e a segurança em ambientes de produção.

Segurança como Requisito de Primeira Classe: Os autores argumentam que a modificação autônoma de código confiável requer tratar a segurança como um requisito de engenharia derivado de falhas empíricas, em vez de um design especulativo.
Alegações Modestas sobre Resolução: O artigo reconhece que a preservação de 100% da correção não equivale a 100% de resolução de issues. A lacuna é impulsionada por limitações de localização (a incapacidade do Planner de mapear o vocabulário da issue para caminhos de arquivos sem recuperação semântica), e não pela geração de código.
Prontidão para Produção: Diferente de trabalhos anteriores focados em benchmarks offline, o Phoenix é projetado para webhooks reais, branches reais e PRs reais, com mecanismos especificamente ajustados para lidar com a fricção da implantação em produção (ex: expiração de token, gateways de API).

Os autores concluem que, embora a recuperação semântica seja o próximo passo necessário para abordar as falhas de localização, a atual arquitetura multi-agente demonstra com sucesso que a resolução de issues de ponta a ponta e segura é alcançável com controles de segurança rigorosos e testes cientes da linha de base.