zjp1997720/codex-doctor

Codex Doctor

Ejecuta un chequeo de salud en dos niveles:

1. Reutiliza el comando integrado estable de Codex codex doctor --json para comprobaciones de instalación, configuración, autenticación, entorno de ejecución, Git, terminal, servidor de aplicaciones, actualizaciones e inventario de hilos.
2. Ejecuta el escáner de solo lectura incluido para la gobernanza del contexto del workspace que el comando integrado no cubre.

El escáner recopila evidencia determinista. Tú realizas el juicio semántico. Esta separación es importante porque un script puede probar que el texto se repite, pero no puede decidir de manera segura si un hecho de negocio, un límite de seguridad, la voz de una marca o una regla de directorio es desechable.

Ejecutar el chequeo

Resuelve el directorio de la Skill desde la ruta de Skill cargada y luego ejecuta:

python3 <skill-dir>/scripts/scan_workspace.py --cwd "$PWD" --compact-json

Para una pasada más rápida solo del workspace cuando el informe integrado ya se ejecutó en la misma tarea:

python3 <skill-dir>/scripts/scan_workspace.py --cwd "$PWD" --compact-json --skip-built-in

--compact-json conserva todos los hallazgos y cada fila de verificación integrada, omitiendo grandes inventarios de Skills y detalles detallados de verificaciones aprobadas. Usa --json solo cuando se requiera evidencia completa de inventario determinista.

No guardes el informe integrado sin procesar dentro del repositorio. Si se necesita almacenamiento temporal, usa /tmp y elimínalo antes de finalizar.

Interpretar hallazgos

Lee checks-and-repair-policy.md antes de proponer cualquier limpieza o reparación. Mantén separados la gravedad y la confianza:

• S0: exposición de secreto comprobada o riesgo destructivo comprobado
• S1: configuración efectiva rota, reglas estrictas truncadas, ejecutables habilitados faltantes o desajuste de instalación/actualización
• S2: redundancia exacta, nombres/fuentes activos duplicados o una violación clara de higiene del proyecto
• S3: presión de mantenimiento, entradas deshabilitadas obsoletas, aviso de nueva versión o descripciones sobredimensionadas
• S4: informativo, candidato semántico o brecha de evidencia

Trata los semantic_candidates como indicaciones para inspección, no como hallazgos. Lee la sección de origen relevante y clasifícala como una de:

• regla de comportamiento o límite de seguridad: conservar
• preferencia del usuario, voz de marca, hecho de negocio o contrato de directorio: conservar
• hecho del repositorio que requiere síntesis de múltiples archivos: generalmente conservar
• inventario directamente descubrible, versión del framework, lista de dependencias o listado de directorios: candidato a recortar
• declaración obsoleta o contradictoria: verificar contra el repositorio antes de proponer un cambio

Evidencia de Skills no utilizadas

El descubrimiento estático no puede probar que una Skill no se usa. Si el usuario solicita explícitamente Skills no utilizadas o de baja frecuencia, usa la Skill instalada codex-skill-admin en modo de auditoría de solo lectura:

python3 <codex-skill-admin-dir>/scripts/codex_skill_admin.py audit-unused --cwd "$PWD" --days 30

Informa la ventana de evidencia y el recuento distinto de sesiones/fuentes. No deshabilites nada a menos que el usuario lo solicite por separado y apruebe la lista de destino.

Estructura del informe

Comienza con el resultado general y luego muestra solo los elementos procesables o relevantes para la decisión:

# Codex 健康检查

Estado: PASS / WARN / FAIL

## Necesita tratamiento
- [id del hallazgo] gravedad / confianza — conclusión
  Evidencia: origen y estado observado
  Impacto: fallo concreto o costo de contexto
  Recomendación: siguiente acción exacta

## Sugerir revisión manual
- candidatos semánticos con por qué pueden ser inferibles u obsoletos

## Aprobado
- dominios agrupados, no cada fila de bajo nivel

## Brechas de evidencia
- verificaciones que no pueden probarse a partir de datos públicos/locales

Conserva las sub-verificaciones del doctor integrado como hechos separados. Por ejemplo, un fallo de accesibilidad HTTP y un éxito de WebSocket deben permanecer como dos filas; no los colapses en "la red está rota".

Protocolo de reparación

El diagnóstico no autoriza la reparación. Cuando el usuario solicite corregir hallazgos:

1. Muestra un ID de hallazgo, el origen exacto, por qué está mal y un diff unificado de un solo archivo.
2. Solicita aprobación explícita de ese ID de hallazgo cuando el cambio elimine o reescriba semánticamente instrucciones, cambie la configuración, habilite/deshabilite un componente o mueva archivos.
3. Recalcula el SHA-256 del archivo fuente inmediatamente antes de aplicar el parche. Detente si difiere de la evidencia del escaneo.
4. Aplica solo el diff aprobado con apply_patch.
5. Vuelve a ejecutar la verificación relevante e informa el resultado antes/después.

Nunca automáticamente:

• eliminar o debilitar reglas de seguridad, reglas de marca/persona, hechos de negocio, hechos del proyecto, puertas de Git o límites de directorio
• eliminar texto simplemente porque está duplicado en AGENTS.md y CLAUDE.md; la paridad entre hosts puede ser intencional
• ejecutar hooks para medir rendimiento
• confiar en hooks, iniciar sesión en MCP, exponer credenciales, instalar dependencias, actualizar Codex o cambiar proveedores
• modificar configuraciones de sandbox, aprobación, modelo, red o autenticación
• ejecutar comandos destructivos de Git, limpiar archivos no rastreados o mover directorios protegidos del proyecto

Verificaciones de finalización

Antes de informar finalización:

• confirma que el escáner no realizó cambios en el repositorio
• distingue los diagnósticos integrados de Codex de los hallazgos de gobernanza del workspace
• etiqueta la inferencia como inferencia
• informa las verificaciones omitidas y las brechas de evidencia
• si se aprobaron reparaciones, verifica cada archivo cambiado y vuelve a ejecutar su verificación de dominio