Readme i18n

dingyufei615/ai-code-review-helper

Share
OriginalDeutschEnglishEspañolfrançais日本語한국어PortuguêsРусский中文
Last translated: 26 Jun 2025

Translation Not Available Yet

This repository's README hasn't been translated yet. Once translated, it will be easier to read and understand in your native language (中文).

After translating, add the links to README so others can view it directly.

Deutsch | English | Español | français | 日本語 | 한국어 | Português | Русский | 中文

Assistente de Revisão de Código com IA

Um assistente automatizado de revisão de código baseado em LLM. Monitora alterações em PR/MR através de Webhooks do GitHub/GitLab, utiliza IA para analisar o código e posta comentários automáticos no PR/MR, com suporte a múltiplos canais de notificação.

Assista ao vídeo de demonstração no Bilibili

Devido a limitações do GitHub, não é possível incorporar diretamente um player de vídeo.

Principais Funcionalidades

  • Suporte a múltiplas plataformas: Integração com Webhooks do GitHub e GitLab para monitorar eventos de Pull Request / Merge Request.
  • Modos de revisão inteligente:
    • Revisão detalhada (/github_webhook, /gitlab_webhook): A IA analisa cada arquivo modificado para identificar problemas específicos. Os comentários são estruturados (ex: localização da linha, classificação do problema, gravidade, análise e sugestão) e postados individualmente no PR/MR. O modelo de IA gera saída em formato JSON, que é convertido em múltiplos comentários.
    • Revisão geral (/github_webhook_general, /gitlab_webhook_general): A IA faz uma análise holística de cada arquivo modificado e gera um comentário resumido em Markdown por arquivo.
  • Fluxo automatizado:
    • Posta automaticamente os comentários da revisão (múltiplos no modo detalhado, um por arquivo no modo geral).
    • Após revisar todos os arquivos, posta um comentário resumido no PR/MR.
    • Mesmo quando não encontra problemas, posta uma mensagem amigável de confirmação.
    • Processamento assíncrono das tarefas de revisão para resposta rápida ao Webhook.
    • Utiliza Redis para evitar revisões duplicadas do mesmo Commit.
  • Configuração flexível:
    • Configuração básica via variáveis de ambiente.
    • Painel de administração web (/admin) e API (/config/*) para gerenciar:
      • Webhook Secrets e Access Tokens de repositórios/projetos no GitHub/GitLab.
      • Parâmetros do LLM (API Key, Base URL, Model).
      • URLs de Webhook para notificações (WeCom, Webhook customizado).
      • Histórico de revisões pela IA.
    • Armazenamento persistente das configurações e resultados no Redis.
  • Notificações e registro:
    • Envia resumos das revisões (com links do PR/MR, informações de branch e resultados) para WeCom e Webhooks customizados.
    • Armazena resultados no Redis (expiração padrão de 7 dias), com visualização pelo painel e limpeza automática após fechamento/merge do PR/MR.
  • Deploy: Suporte a Docker ou execução direta da aplicação Python.

🚀 Começo Rápido

🐳 Implantação Rápida

# 使用官方镜像
docker run -d -p 8088:8088 \
  -e ADMIN_API_KEY="your-key" \
  -e OPENAI_API_BASE_URL="https://api.openai.com/v1" \
  -e OPENAI_API_KEY="your-key" \
  -e OPENAI_MODEL="gpt-4o" \
  -e REDIS_HOST="your-redis-host" \
  -e REDIS_PASSWORD="your-redis-pwd"
  --name ai-code-review-helper \
  dingyufei/ai-code-review-helper:latest

📌 Variáveis de ambiente obrigatórias:

  • ADMIN_API_KEY - Senha do painel administrativo (padrão: change_this_unified_secret_key)
  • OPENAI_API_KEY - Chave da API da IA
  • REDIS_HOST - Endereço do Redis

Configuração

1. Variáveis de Ambiente (principais)

  • ADMIN_API_KEY: Obrigatório. Chave para proteger as interfaces administrativas (padrão: change_this_unified_secret_key - altere obrigatoriamente).
  • OPENAI_API_KEY: Obrigatório. Chave da API da OpenAI.
  • OPENAI_MODEL: (padrão: gpt-4o) Modelo da OpenAI a ser utilizado.
  • OPENAI_API_BASE_URL: (opcional) URL base da API da OpenAI (formato: http(s)://xxxx/v1) (padrão: https://api.openai.com/v1)
  • WECOM_BOT_WEBHOOK_URL: (opcional) URL do Webhook do bot WeCom.
  • REDIS_HOST: Obrigatório. Endereço do servidor Redis. Sem isso, o serviço não inicia.
  • REDIS_PORT: (padrão: 6379) Porta do Redis.
  • REDIS_PASSWORD: (opcional) Senha do Redis.
  • REDIS_DB: (padrão: 0) Número do banco de dados Redis.
  • REDIS_SSL_ENABLED: (padrão: true) Habilita SSL para conexão Redis. Defina false para desativar.
  • (Outras variáveis como SERVER_HOST, SERVER_PORT, GITHUB_API_URL, GITLAB_INSTANCE_URL etc. - consulte logs ou código-fonte.)

2. Painel Administrativo e API

  • Painel Administrativo (/admin): Interface web para:
    • Configurar Webhook Secrets e Access Tokens de repositórios/projetos.
    • Gerenciar parâmetros globais do LLM (API Key, Base URL, Model).
    • Definir URLs de Webhook para notificações (WeCom, Webhook customizado).
    • Visualizar histórico de revisões pela IA.
    • Todas as ações requerem autenticação via ADMIN_API_KEY.
  • API de Configuração: API RESTful (/config/*) para gerenciamento programático das configurações, também requer cabeçalho X-Admin-API-Key.

Persistência de Configurações:

  • Redis (obrigatório): Armazena configurações de repositórios/projetos, SHAs de commits processados e resultados das revisões (expiração em 7 dias, limpeza após fechamento/merge). Serviço depende totalmente do Redis.
  • Variáveis de Ambiente: Carregam configurações globais (LLM Key/URL, conexão Redis, Admin API Key). Alterações via painel têm efeito imediato, mas reinicializações recarregam das variáveis. Recomenda-se usar variáveis para configurações globais persistentes.

Como Usar

  1. Inicie o serviço: Via Docker ou Python, com variáveis obrigatórias configuradas (ADMIN_API_KEY, OPENAI_API_KEY, REDIS_HOST etc.).
  2. Configure repositórios/projetos: No painel (/admin) ou via API, adicione configurações para os repositórios/projetos alvo (Webhook Secret e Access Token com permissão para comentar em PR/MR).
  3. Configure Webhooks: Nas configurações do repositório/projeto no GitHub/GitLab:
    • Payload URL: Endereço do seu serviço com o endpoint apropriado (ver abaixo).
    • Content type: application/json.
    • Secret: O Webhook Secret configurado no painel.
    • Events: GitHub selecione "Pull requests", GitLab marque "Merge request events".
  4. Disparar revisão: Crie ou atualize um PR/MR para iniciar a revisão automática.

Escolha do Modo de Revisão

  • Revisão detalhada (endpoints: /github_webhook, /gitlab_webhook):
    • A IA tenta analisar minuciosamente cada alteração, gerando comentários estruturados sobre problemas específicos (se possível por linha).
    • Cada problema vira um comentário independente no PR/MR.
    • Neste modo, a IA gera saída em JSON, que é convertida em comentários.
    • Ideal para modelos com boa capacidade de seguir instruções e gerar JSON estável (ex: GPT-4). Verifique logs se houver problemas no formato.
  • Revisão geral (endpoints: /github_webhook_general, /gitlab_webhook_general):
    • Análise macro de cada arquivo modificado, com um comentário resumido em Markdown por arquivo.
    • Alternativa quando o modo detalhado tem saída instável.

Modo de Desenvolvimento

# 1. 克隆仓库
git clone https://github.com/dingyufei615/ai-code-review-helper.git
cd ai-code-review-helper

# 2. 创建并激活虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 3. 安装依赖
pip install -r requirements.txt

# 4. 配置环境变量 (参考 .env.example 或 配置 部分)

# 5. 启动服务
python -m api.ai_code_review_helper

# 6. 运行测试 (可选)
python -m unittest discover tests

Observações Importantes

  • Segurança: Use um ADMIN_API_KEY forte e proteja todos os Tokens e Secrets.
  • Custos: Atenção aos custos da API do serviço de LLM utilizado.
  • Logs: O serviço gera logs detalhados no console para troubleshooting.
  • Dependência do Redis: Serviço requer Redis para funcionar corretamente.

Contribuição

90% deste código foi desenvolvido com Aider + Gemini. Contribuições via Pull Requests ou Issues são bem-vindas.