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 | Русский | 中文

Asistente de Revisión de Código con IA

Un asistente automatizado de revisión de código basado en LLM. Monitorea cambios en PR/MR a través de Webhooks de GitHub/GitLab, utiliza IA para analizar el código y publica comentarios de revisión automáticamente en PR/MR, con soporte para múltiples canales de notificación.

Ver video demostrativo en Bilibili

Debido a limitaciones de GitHub, no es posible incrustar reproductores de video directamente.

Funcionalidades principales

  • Soporte multiplataforma: Integración con Webhooks de GitHub y GitLab para monitorear eventos de Pull Request / Merge Request.
  • Modos de revisión inteligente:
    • Revisión detallada (/github_webhook, /gitlab_webhook): La IA analiza cada archivo modificado para identificar problemas específicos. Los comentarios se publican en PR/MR de manera estructurada (ej: ubicación de líneas, clasificación de problemas, gravedad, análisis y recomendaciones). El modelo de IA genera resultados en formato JSON que se convierten en comentarios independientes.
    • Revisión general (/github_webhook_general, /gitlab_webhook_general): La IA realiza un análisis global de cada archivo modificado y genera un comentario resumen en Markdown por archivo.
  • Flujo automatizado:
    • Publicación automática de comentarios de revisión (múltiples en modo detallado, uno por archivo en modo general).
    • Comentario resumen final al completar la revisión de todos los archivos.
    • Notificación amigable cuando no se detectan problemas.
    • Procesamiento asíncrono de tareas para respuesta rápida a Webhooks.
    • Uso de Redis para evitar revisiones duplicadas del mismo Commit.
  • Configuración flexible:
    • Configuración base mediante variables de entorno.
    • Panel de administración web (/admin) y API (/config/*) para gestionar:
      • Webhook Secrets y Access Tokens para repositorios/proyectos.
      • Parámetros de LLM (API Key, Base URL, Modelo).
      • URLs de Webhook para notificaciones (WeCom, Webhooks personalizados).
      • Historial de revisiones de IA.
    • Almacenamiento persistente de configuraciones y resultados en Redis.
  • Notificaciones y registro:
    • Envío de resúmenes de revisión (con enlaces a PR/MR, información de ramas y resultados) a WeCom y Webhooks personalizados.
    • Almacenamiento de resultados en Redis (expiración predeterminada: 7 días) con limpieza automática para PR/MR cerrados/fusionados.
  • Despliegue: Soporte para Docker o ejecución directa de la aplicación Python.

🚀 Inicio rápido

🐳 Despliegue rápido

# 使用官方镜像
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

📌 Variables de entorno requeridas:

  • ADMIN_API_KEY - Contraseña del panel de administración (valor predeterminado: change_this_unified_secret_key)
  • OPENAI_API_KEY - Clave API del servicio de IA
  • REDIS_HOST - Dirección de Redis

Configuración

1. Variables de entorno (clave)

  • ADMIN_API_KEY: Requerido. Clave secreta para proteger las interfaces de administración. Valor predeterminado: change_this_unified_secret_key (debe modificarse).
  • OPENAI_API_KEY: Requerido. Clave API de OpenAI.
  • OPENAI_MODEL: (Predeterminado: gpt-4o) Modelo de OpenAI a utilizar.
  • OPENAI_API_BASE_URL: (Opcional) URL base de la API de OpenAI (formato: http(s)://xxxx/v1). Valor predeterminado: https://api.openai.com/v1
  • WECOM_BOT_WEBHOOK_URL: (Opcional) URL de Webhook para bots de WeCom.
  • REDIS_HOST: Requerido. Dirección del servidor Redis. Sin configuración o conexión fallida, el servicio no iniciará.
  • REDIS_PORT: (Predeterminado: 6379) Puerto del servidor Redis.
  • REDIS_PASSWORD: (Opcional) Contraseña de Redis.
  • REDIS_DB: (Predeterminado: 0) Número de base de datos Redis.
  • REDIS_SSL_ENABLED: (Predeterminado: true) Habilita SSL para conexiones Redis. Establecer false para desactivar.
  • (Más variables como SERVER_HOST, SERVER_PORT, GITHUB_API_URL, GITLAB_INSTANCE_URL disponibles en registros o código fuente.)

2. Panel de administración y API

  • Panel de administración (/admin):
    • Configura Webhook Secrets y Access Tokens para repositorios/proyectos.
    • Gestiona parámetros globales de LLM (API Key, URL base, Modelo).
    • Configura URLs de Webhook para notificaciones (WeCom, Webhooks personalizados).
    • Visualiza y gestiona historial de revisiones de IA.
    • Todas las operaciones requieren autenticación con ADMIN_API_KEY.
  • API de configuración: API RESTful (/config/*) para gestión programática de configuraciones, con autenticación mediante cabecera X-Admin-API-Key.

Persistencia de configuración:

  • Redis (requerido): Almacena configuraciones, SHAs de commits procesados y resultados de revisiones (expiración: 7 días). Servicio depende críticamente de Redis.
  • Variables de entorno: Carga configuraciones globales. Los cambios en el panel tienen efecto inmediato pero se recargan desde variables al reiniciar. Se recomienda usar variables para configuraciones globales persistentes.

Modo de uso

  1. Iniciar servicio: Usar Docker o ejecutar directamente la aplicación Python, asegurando variables necesarias (ADMIN_API_KEY, OPENAI_API_KEY, REDIS_HOST).
  2. Configurar repositorios/proyectos: Añadir configuraciones mediante panel (/admin) o API, incluyendo Webhook Secret y Access Token con permisos para comentar en PR/MR.
  3. Configurar Webhook: En ajustes de repositorio/proyecto de GitHub/GitLab:
    • URL de payload: Dirección del servicio con endpoint correspondiente (ver abajo).
    • Tipo de contenido: application/json.
    • Secret: Webhook Secret configurado previamente.
    • Eventos: "Pull requests" en GitHub, "Merge request events" en GitLab.
  4. Disparar revisión: Crear o actualizar PR/MR para iniciar revisión automática.

Selección de modo de revisión

  • Revisión detallada (endpoints: /github_webhook, /gitlab_webhook):
    • Análisis pormenorizado por archivo, generando comentarios estructurados por línea de código (si es posible).
    • Cada problema se publica como comentario independiente.
    • Requiere modelos con buena capacidad de seguir instrucciones y generar JSON estable (ej: serie GPT-4).
  • Revisión general (endpoints: /github_webhook_general, /gitlab_webhook_general):
    • Análisis global por archivo, con comentario resumen en Markdown por archivo.
    • Alternativa cuando el modo detallado produce resultados inconsistentes.

Modo desarrollo

# 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

Consideraciones

  • Seguridad: Usar ADMIN_API_KEY fuerte y proteger Tokens/Secrets.
  • Costos: Monitorear costos de llamadas API al servicio LLM.
  • Registros: El servicio genera registros detallados en consola para diagnóstico.
  • Dependencia de Redis: Servicio requiere Redis para funcionamiento correcto.

Contribuciones

El 90% de este código fue desarrollado con Aider + Gemini. Se aceptan Pull Requests e Issues.