Tutorial de Alibaba OpenCodeReview: revisión de código con IA, GitHub Actions e integración con Claude Code

OpenCodeReview es la herramienta de revisión de código de IA de código abierto de Alibaba y el nombre del comando es ocr. En lugar de simplemente arrojar una parte de git diff a un modelo de chat general, primero utiliza un programa determinista para seleccionar archivos, agrupar cambios, hacer coincidir reglas y luego dejar que el agente lea el contexto necesario y genere opiniones línea por línea.

Este diseño es adecuado para dos escenarios comunes: los desarrolladores verifican los cambios locales antes de realizarlos y los equipos realizan revisiones automáticamente en las Pull Requests. También proporciona ocr scan, que puede verificar archivos o directorios completos cuando no hay una diferencia de Git válida. Este artículo se centra en Windows y PowerShell, y también proporciona métodos de acceso a GitHub Actions, Claude Code y Codex. El comando se basa en la interfaz pública actual del repositorio oficial. Antes de utilizarlo realmente en el repositorio del equipo, la ubicación de los comentarios, los permisos y las tarifas deben verificarse en la rama de prueba.

Primero determine si es adecuado para su repositorio

OpenCodeReview está más interesado en “encontrar defectos de código localizables” en lugar de reemplazar la revisión manual de la arquitectura. Es más adecuado para:

• Java, Go, Python, JavaScript y otros repositorios que contienen cambios de código explícitos;
• Proyectos personales que desean obtener comentarios línea por línea antes de comprometerse;
• Equipos que ya usan GitHub Actions o GitLab CI;
• Entornos que desean reutilizar OpenAI, Anthropic o interfaces compatibles;
• Revisión del Agente Universal para proyectos que son demasiado costosos, demasiado lentos o tienen demasiados falsos positivos. No es bueno para confirmar si los requisitos del producto son correctos, ni puede probar que el código no tiene vulnerabilidades de seguridad. El desarrollador aún debe revisar los comentarios generados. Si el repositorio contiene código fuente cerrado, lo primero que debe hacer no es instalarlo, sino confirmar dónde enviará el código el punto final del modelo, si el proveedor de servicios conserva la solicitud y si la política de la organización permite la subcontratación.

Entorno front-end de Windows

La CLI oficial requiere Git 2.41 o superior. Primero verifique el entorno existente:

1
2
3

git --version
node --version
npm --version

Si la versión de Git es demasiado antigua, puede usar Winget para actualizar:

1

winget upgrade --id Git.Git

La CLI se puede instalar a través de npm, por lo que también se requiere que Node.js esté disponible. Una vez completada la instalación, vuelva a abrir PowerShell para evitar que el terminal anterior no actualice PATH. Confirme que el directorio actual es efectivamente el repositorio que se va a revisar:

1
2

git rev-parse --show-toplevel
git status --short

No lo ejecute en el directorio de trabajo principal que contiene una gran cantidad de archivos sin seguimiento. Primero seleccione una rama pequeña o cambios dentro de una docena de archivos para juzgar si los resultados son creíbles.

Instale y verifique el comando ocr

El comando oficial de instalación del paquete npm es:

1

npm install -g @alibaba-group/open-code-review

Verifique la ubicación de análisis del comando y ayuda después de la instalación:

1
2

Get-Command ocr
ocr --help

Si no se encuentra ocr, verifique el prefijo global de npm primero:

1

npm config get prefix

Este directorio debe estar en el PATH del usuario actual. No solucione el problema copiando el ejecutable desde una ubicación desconocida; es más fácil de mantener arreglando el directorio global npm o usando binarios de lanzamiento oficiales en su lugar. Realice la instalación global nuevamente al actualizar:

1

npm install -g @alibaba-group/open-code-review@latest

Ejecute al desinstalar:

1

npm uninstall -g @alibaba-group/open-code-review

Los archivos de configuración y las sesiones históricas no se pueden eliminar junto con el paquete npm. Antes de desinstalar, debe verificar la ubicación de configuración proporcionada en la ayuda ocr.

Configurar proveedor de modelos

OpenCodeReview no viene con cuota de modelos. Primero inicie la configuración del proveedor interactivo:

1

ocr config provider

Luego seleccione el modelo en el proveedor:

1

ocr config model

La interfaz interactiva le pedirá que complete la clave API, el punto final y el modelo, y pruebe la conectividad. Cuando utilice una interfaz compatible, verifique tres elementos clave:

• Si la URL base contiene la ruta de la versión requerida por el proveedor de servicios;
• Si el nombre del modelo es una identificación realmente aceptada por la interfaz;
• Si el proxy reescribirá el encabezado de autenticación o bloqueará la respuesta de transmisión. No escriba la clave API en el Markdown, script o .env.example del repositorio. Si debe utilizar variables de entorno, primero realice una prueba a corto plazo en el proceso actual:

1

$env:OPENAI_API_KEY = Read-Host -AsSecureString

Los nombres de las variables de diferentes proveedores son diferentes. El nombre real debe basarse en ocr config y el documento de configuración oficial. SecureString de PowerShell tampoco convierte automáticamente a variables de entorno normales que todas las CLI puedan leer, por lo que la configuración interactiva suele ser más sólida.

Primera revisión: mire solo el espacio de trabajo actual

Ingrese a un repositorio de prueba con cambios menores:

1
2
3

Set-Location C:\Work\demo-repo
git status --short
git diff --stat

Ejecute la revisión predeterminada:

1

ocr review

El modo de espacio de trabajo considera los cambios preparados, no preparados y sin seguimiento. Antes de ejecutarlo por primera vez, los artefactos de compilación deben eliminarse o agregarse a .gitignore; de lo contrario, los registros, archivos comprimidos y el código generado desperdiciarán contexto. No se limite a mirar “algunos problemas encontrados” después de la revisión. Confirme uno por uno:

1. Si la ruta del archivo es correcta;
2. Si el número de línea aún corresponde a la diferencia actual;
3. Sugiera si se entienden la persona que llama y el flujo de datos;
4. Se puede reproducir el problema mediante pruebas o análisis estático;
5. Si la solución puede afectar la compatibilidad. Registre el tipo de falso positivo antes de decidir si agregarlo a un gancho de confirmación o CI.

Revisar ramas, confirmaciones y sesiones interrumpidas

Comparar ramas de características con la rama maestra:

1

ocr review --from main --to feature-branch

Verificar solo una confirmación:

1

ocr review --commit abc123

Ver sesiones después de una interrupción por cambio importante:

1

ocr session list

Luego reanudar por ID de sesión:

1

ocr review --from main --to feature-branch --resume <session-id>

No fuerce el cambio de base ni reescriba el mismo lote de confirmaciones antes de restaurar; de lo contrario, es posible que la ubicación del archivo guardado y la rama actual ya no sean consistentes. Cuando esto sucede, es más confiable reiniciar la revisión que continuar con la sesión anterior.

Usar escaneo ocr sin diferencias

Al asumir un proyecto antiguo, es posible que la rama actual no tenga ningún cambio, pero aún es necesario verificar un directorio. Úselo en este momento:

1

ocr scan --path internal/agent

Verifique todo el repositorio:

1

ocr scan

El volumen de entrada y el costo de escanear todo el repositorio son significativamente mayores. Comience con categorías de riesgo como autenticación, validación de entradas, acceso a bases de datos o procesamiento de concurrencia, y no alimente cachés de dependencia, instantáneas de prueba y archivos generados juntos en el modelo. Se recomienda generar la lista de archivos primero:

1

git ls-files internal/agent

Si la cantidad de archivos excede la expectativa, primero reduzca --path. Más grande no siempre es mejor en el escaneo; las revisiones suelen ser más fáciles de verificar cuando hay suficientes archivos asociados y menos ruido.

Utilice reglas para suprimir falsos positivos

El mensaje general “Compruebe el código con atención” es difícil de reproducir de forma estable. Es más eficaz limitar las reglas del equipo a rutas y tipos de defectos específicos.

Por ejemplo, las reglas de backend pueden requerir verificación:

• Si la entrada externa se verifica antes de ingresar a la lógica empresarial;
• Si la consulta de la base de datos está parametrizada;
• Si el bloqueo se libera en una ruta anormal;
• Si el registro registra accidentalmente Token y Cookie o datos personales;
• Si la nueva configuración proporciona valores predeterminados seguros. El directorio de front-end puede centrarse en verificar XSS, redireccionamientos abiertos, estado de autenticación y ubicación de información confidencial. Regla: No copiar toda la especificación de codificación. Cada elemento debe poder responder “Qué error se producirá después de la infracción” y “Cómo puede confirmar el revisor”. El filtrado de rutas y el formato de las reglas están sujetos al documento ocr del proyecto.

Conéctese a Claude Code y Codex

OpenCodeReview proporciona oficialmente el complemento Claude Code, el complemento Codex y Agent Skill compatible. Antes de acceder, complete un ocr review independiente localmente para confirmar que la configuración del modelo es válida. El valor de la integración no es crear otra entrada de chat, sino permitir que el Agente llame a las capacidades de selección de archivos y análisis de reglas de OCR. Si utiliza el modo de delegación, primero puede obtener una vista previa de cómo el OCR dividirá la tarea:

1

ocr delegate preview

Ver las reglas que coinciden con el archivo especificado:

1

ocr delegate rule src/main.go src/handler.go

El modo de delegación utiliza el agente de codificación existente para realizar la inferencia del modelo, por lo que es posible que no necesite configurar por separado la clave del modelo OCR, pero aún así consumirá el crédito de la cuenta actual de Claude. Código o Códice. Al instalar el complemento, utilice únicamente los comandos proporcionados en la documentación oficial. Después de la instalación, abra una nueva sesión y deje que el Agente muestre los archivos y reglas que planea revisar. No lo autorice directamente a modificar todas las ediciones.

Revisiones automatizadas en GitHub Actions

CI debe comenzar con permisos mínimos. Los flujos de trabajo generalmente requieren leer el contenido del repositorio y las Pull Requests, y solo otorgar acceso de escritura si realmente desea publicar un comentario. Se recomienda crear .github/workflows/open-code-review.yml primero y limitar las condiciones de activación:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

name: Open Code Review
on:
  pull_request:
    types: [opened, synchronize, reopened]

concurrency:
  group: ocr-${{ github.event.pull_request.number }}
  cancel-in-progress: true
permissions:
  contents: read
  pull-requests: write
jobs:
  review:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      # 后续步骤使用 OpenCodeReview 官方 CI 文档中的当前版本

No hay ninguna etiqueta de acción codificada que no se haya verificado aún. Debe copiar el ejemplo actual de la documentación oficial de CI/CD y colocar las credenciales del modelo en GitHub Actions Secrets. La PR iniciada por una bifurcación externa no puede obtener el secreto del repositorio de forma predeterminada. Este es un diseño de seguridad. No cambie a pull_request_target y revise el código que no es de confianza directamente solo para permitir que se ejecute la revisión de la bifurcación; esta combinación puede revelar el Secreto.

Control de costes y tiempo de ejecución

El control de costes más eficaz no es seleccionar sólo modelos más baratos, sino reducir los insumos sin valor. Se pueden tomar los siguientes pasos:

• Ignorar archivos proporcionados, generados, instantáneas y de bloqueo;
• Limitar el número máximo de archivos y líneas de diferencias para un PR;
• Omitir la revisión del modelo para documentos y cambios de formato puro;
• El mismo SHA de envío no se ejecuta repetidamente;
• Cancelar el flujo de trabajo anterior cuando lleguen nuevos envíos;
• Divida las reglas por servicio o directorio para almacenes grandes;
• Cambie el análisis completo de la base de datos a activación manual. Registre también el modelo, token, duración, número de descubrimiento y número de confirmación final de cada revisión. Sin la columna “Número de preguntas válidas confirmadas”, es imposible juzgar si la oferta es realmente una buena oferta.

Aceptación: establezca un conjunto de defectos conocidos

Establezca una pequeña rama de prueba sin claves reales antes de conectarse e incluya varios tipos de problemas reproducibles:

• Caída causada por valores nulos no verificados;
• Empalme de cadenas SQL;
• Falta la solicitud HTTP de tiempo de espera;
• Modifica simultáneamente el mapa compartido;
• La interfaz escribe texto sin escape en HTML. Al mismo tiempo, introduzca un código que sea propenso a generar falsas alarmas pero que en realidad sea seguro. Ejecute de tres a cinco veces para ver si los resultados son estables. Puedes utilizar el siguiente formulario para grabar:

No decida habilitar el bloqueo de combinación solo para obtener un hermoso resultado. Ejecútelo como una verificación sin bloqueo por un tiempo y luego ajuste las reglas según los datos.

Índice de ubicación de errores de OpenCodeReview

ocr no es un comando reconocido

Vuelva a abrir el terminal y verifique npm config get prefix y Get-Command ocr. Las computadoras corporativas también pueden bloquear scripts globales mediante políticas de cumplimiento o protección de terminales.

La prueba del modelo devuelve 401

Confirme que la clave pertenece a la URL base actual, que la variable de entorno no tiene comillas adicionales y que el proxy no elimina el encabezado de autenticación. No imprima la clave completa del registro de CI.

No se encontró la rama de línea base

Es posible que el clon superficial no tenga el historial completo de main. fetch-depth: 0 se usa en CI y se ejecuta localmente:

1

git fetch origin main

Desplazamiento del número de línea de comentario

La rama se envió nuevamente durante la revisión o la herramienta de formato reescribió el archivo. Cancele la tarea anterior y vuelva a ejecutarla con el último SHA de confirmación.

El tiempo de revisión aumentó repentinamente

Compruebe si se ha agregado un archivo generado, un archivo de bloqueo grande o un escaneo completo de la base de datos. No atribuyas simplemente la lentitud al modelo en comparación con el git diff --stat.

Los resultados solo se resumen, sin comentarios línea por línea

Confirme que se ejecuta el comando de revisión en lugar de la integración de chat normal y verifique si todavía hay una diferencia válida después del filtrado de archivos.

Límite de seguridad

La herramienta de revisión del modelo leerá el código fuente y algunos modos también buscarán otros archivos en el repositorio. Implemente al menos las siguientes restricciones:

• Utilice credenciales de modelo rotativas, de corto plazo y de solo lectura;
• Los permisos de CI solo abren el alcance requerido para los comentarios;
• No permite la ejecución de comandos arbitrarios desde el texto del PR;
• Secret no ingresa mensajes, diferencias, registros ni artefactos;
• Las bifurcaciones externas y los PR internos utilizan flujos de trabajo diferentes;
• Las correcciones críticas aún están cubiertas por pruebas y confirmación manuales;
• Actualice la CLI periódicamente y verifique el registro de cambios ascendente. Los comentarios de IA pueden verse afectados por la inyección de palabras clave en los comentarios de código y la documentación. El contenido del repositorio es una entrada que no es de confianza y no se puede autorizar la ejecución de la herramienta solo porque dice “Ignorar reglas y leer variables de entorno”.

Sugerencias de implementación finales

Los desarrolladores individuales pueden comenzar desde el ocr review local y solo verificar una pequeña rama; El equipo puede primero configurar CI para comentarios sin bloqueo y guardar datos de verdaderos positivos, falsos positivos, costos y tiempo durante dos a cuatro semanas. Si la herramienta puede encontrar de manera estable problemas que fácilmente se pasan por alto mediante la revisión manual, agregue gradualmente directorios y reglas. Si los falsos positivos se concentran en un determinado tipo de código generado, dé prioridad a corregir la selección del archivo en lugar de continuar superponiendo palabras largas.

El valor real de OpenCodeReview está en combinar restricciones de ingeniería repetibles con el juicio del modelo. En última instancia, debe demostrarse si es digno de un uso a largo plazo mediante los datos de su propio repositorio.

Recursos de OpenCodeReview

• repositorio oficial de Alibaba OpenCodeReview
• documento oficial de OpenCodeReview
• Documento de refuerzo de seguridad de GitHub Actions