Dando um Veredito sobre a Saúde de Repositórios com Agentes de IA

Seu agente de IA recomendará uma biblioteca que não enviou um commit em mais de um ano—e não hesitará. Ele não consegue distinguir um projeto próspero de um moribundo, então trata um repositório vibrante e um abandonado como igualmente seguros para construir. É assim que dependências obsoletas entram em produção: não por descuido, mas porque nada no ciclo nunca perguntou isso ainda está sendo mantido?

Os desenvolvedores perguntam isso constantemente—eles apenas fazem isso manualmente, de forma inadequada. Um padrão que continuei vendo enquanto pesquisava isso: as pessoas se apoiam em um único sinal e sabem que é um mau sinal. Como um desenvolvedor colocou no r/selfhosted: "se um repositório do github não foi atualizado nos últimos 2 anos, eu costumo considerá-lo abandonado… mas há alguns projetos mais antigos que eu ainda usaria felizmente." A data do último commit é uma ferramenta grosseira. Assim como as estrelas. Assim como a contagem de problemas abertos—"talvez os mantenedores não pensem que são tão importantes; o rastreador de problemas muitas vezes estará sobrecarregado." Todos têm uma heurística; ninguém tem um veredicto.

Então eu construí GitHub Repo Intelligence MCP—o quarto ator no meu portfólio Apify. Aponte para qualquer owner/name ou URL do GitHub e ele retorna um de quatro veredictos — Ativamente mantido, Desacelerando, Em risco, ou Provavelmente abandonado—apoiado pelas métricas e os limites fixos que o produziram. Ele funciona como um servidor MCP, então um agente de IA pode chamá-lo durante a tarefa em vez de adivinhar.

Aqui está como ele é construído—e a decisão de design na qual tudo isso se baseia.

A Decisão de Design Central: O Veredicto É o Produto

A maioria das ferramentas do GitHub para agentes entrega ao modelo um monte de dados da API e deixa a conclusão para adivinhação. O servidor oficial do GitHub MCP ficará feliz em buscar commits, problemas e PRs—mas "aqui estão 300 problemas" não é uma resposta para "devo depender disso?" O modelo ainda precisa inventar um julgamento, sem um critério consistente, toda vez.

Eu invertei isso. O trabalho inteiro do ator é fazer a síntese e retornar a conclusão, com as evidências anexadas:

get_repo_health          — veredicto principal + detalhamento por dimensão + justificativa
get_activity_metrics     — cadência de commits, lançamentos, tendência de momentum
get_issue_health         — tempo de resposta do mantenedor + razão de backlog obsoleto
get_pr_health            — taxa de mesclagem + PR mais antigo aberto
get_contributor_insights — contagem de contribuidores + sinal de fator de ônibus

Quatro dimensões—atividade, problemas, PRs, contribuidores — colapsam em um único veredicto. Crucialmente, o veredicto não é uma pontuação de caixa-preta. Cada resposta envia as métricas e os limites fixos por trás dela, para que um humano (ou um agente) possa auditar por que, não apenas ler um número. Julgamento, não acesso bruto.

E é determinístico: o mesmo estado do repositório e a mesma configuração sempre produzem o mesmo veredicto. Sem deriva heurística por chamada, sem "o modelo se sentiu diferente desta vez." Essa propriedade é mais importante para uma ferramenta de agente do que parece—significa que o veredicto é reproduzível, testável e seguro para construir um fluxo de trabalho.

A Arquitetura: Uma Busca, Cinco Ferramentas

A maneira ingênua de construir cinco ferramentas é cinco conjuntos de chamadas de API. Isso é lento, e contra os limites de taxa do GitHub é ativamente hostil.

Em vez disso, uma única consulta GraphQL do GitHub puxa tudo o que as cinco ferramentas precisam em uma única viagem. O resultado é armazenado em cache e compartilhado, então descer do veredicto principal (get_repo_health) para uma dimensão (get_issue_health) custa zero chamadas adicionais para cima—está lendo do mesmo fetch em cache. O GraphQL é o que torna isso possível: um pedido precisamente moldado em vez de uma dúzia de viagens REST para commits, problemas, PRs, lançamentos e contribuidores.

A lógica do veredicto em si é pura: métricas entram, limites aplicados, veredicto sai. Isso torna trivialmente testável sem tocar na rede—o mesmo rigor que eu mantive em cada ator neste portfólio.

O Problema: Traga um Token do GitHub (Aqui Está o Porquê)

A falha que a maioria das pessoas enfrentará primeiro não está no meu código—é a coisa que faz toda a ferramenta cair se você pular: GraphQL rejeita solicitações não autenticadas de forma categórica. A API REST do GitHub dá a chamadores anônimos uma pequena cota; a API GraphQL não dá nada. Sem token, sem dados.

Fica pior no Apify especificamente. Os atores são executados a partir de uma saída em nuvem compartilhada, então se solicitações anônimas fossem permitidas, cada usuário do Apify estaria extraindo da mesma cota de IP anônima compartilhada—o que se esgota quase instantaneamente. O sintoma que um usuário despreparado enfrenta é uma onda de erros de limite de taxa que parecem surgir do nada e não têm nada a ver com seu próprio uso.

Então o esquema de entrada torna um token do GitHub um passo de primeira classe, guiado, em vez de um pensamento posterior enterrado em um README. Um token de acesso fino com permissão de leitura de repositórios públicos é suficiente—sessenta segundos nas configurações do GitHub—e ele te eleva a 5.000 solicitações/hora que são suas, não compartilhadas. A lição que continuo reaprendendo em todo este portfólio: as falhas de configuração mais assustadoras são aquelas que parecem que a ferramenta está quebrada quando na verdade é o ambiente que você não preparou.

Uma Execução Real

Eu apontei para dois repositórios que tornam o contraste óbvio—um próspero, um congelado famosamente—contra o endpoint ao vivo.

vercel/next.js:

{
  "repo": "vercel/next.js",
  "verdict": "Ativamente mantido",
  "activity": "Saudável",
  "issues": "Saudável",
  "pullRequests": "Moderado",
  "contributors": "Saudável",
  "rationale": "No geral: a atividade é Saudável; a dimensão mais fraca é pull requests (Moderado)."
}

moment/moment:

{
  "repo": "moment/moment",
  "verdict": "Provavelmente abandonado",
  "activity": "Provavelmente abandonado",
  "issues": "Em Risco",
  "pullRequests":