Esta página es una traducción de la documentación en inglés. Los comandos, identificadores y ejemplos no cambian. Runtime 7.24.4 · SDK 2.6.7. Original en inglés

Guía de AX Wiki

Estado: Activo Alcance: estado actual Última revisión: 2026-10-03 Responsable: entorno de ejecución de AX Code

AX Wiki es el compilador nativo de wiki del repositorio de AX Code. Convierte el código fuente rastreado, la configuración, las pruebas, los flujos y la documentación existente en una base de conocimiento Markdown pequeña y respaldada por el código fuente, bajo .ax-wiki/. Usa la misma configuración de proveedor y el mismo enrutado de modelo que AX Code; no hay un ejecutable ni un almacén de credenciales aparte.

ax-code wiki viz dibuja las páginas compiladas y los archivos que citan. Las capturas de ese mapa están en visualización de la evidencia de la wiki.

Dónde encaja

La prosa de la wiki es una capa de navegación compilada, no una prueba estructural. Si la wiki discrepa del código, confía en el código y ejecuta ax-code wiki update.

Inicio rápido

Conecta un proveedor de AX Code y luego ejecuta:

ax-code wiki plan
ax-code wiki generate
ax-code wiki doctor

ax-code init --wiki genera AGENTS.md, inserta el bloque de puntero de AX Wiki y compila la wiki en un solo flujo. Usa --wiki-only-agents para añadir punteros sin llamadas al modelo.

Comandos

Las opciones de generación incluyen --model provider/model, --dir <relative>, --quiet, --skip-agents y --force. --force se exige de forma intencionada para sustituir contenido generado editado a mano fuera de las secciones protegidas.

Directorio del repositorio

Desde v7.22.2, el directorio de salida predeterminado es .ax-wiki/. El prefijo oculto identifica el conocimiento del repositorio que mantiene AX Code. No hace que los archivos se ignoren en Git: elige si confirmas este conocimiento o añades /.ax-wiki/ al .gitignore de tu repositorio.

Usa wiki.dir en ax-code.json o --dir docs/knowledge para elegir otro directorio relativo; la marca de la CLI tiene precedencia. Toda la generación, el estado, los punteros del agente, el mantenimiento en segundo plano y la visualización usan esa selección. El compilador no detecta, mueve ni fusiona de forma automática un directorio antiguo ax-wiki/. Los nombres de paquete y de generador, ax-wiki.config.json y ax-wiki.instructions.md no cambian.

Contrato generado

AX Wiki escribe páginas Markdown y .ax-wiki/.manifest.json. Cada página tiene frontmatter que contiene:

• generated_by: ax-wiki
• un summary conciso
• los symbols exactos devueltos por la generación respaldada por evidencia
• el sources relativo al repositorio usado para compilar la página

El manifiesto almacena el hash determinista del plan, los hashes del código fuente del repositorio, los hashes de las páginas, el modelo de generación, la revisión de git y la hora de generación. Las páginas se escriben de forma atómica; el manifiesto se escribe al final y solo después de que la candidata completa en memoria apruebe la validación.

El descubrimiento de código fuente prefiere la lista de archivos rastreados y no ignorados de Git, excluye directorios generados, de compilación y de terceros y la propia wiki, omite archivos binarios o sobredimensionados, y rechaza rutas o enlaces simbólicos fuera del repositorio.

Navegación por subsistemas

El plan predeterminado conserva las páginas de inicio rápido, arquitectura y desarrollo. Un módulo que supera el presupuesto de recuento de fuentes o de bytes de evidencia de una página también puede recibir páginas enfocadas como modules/core/src/session.md. Estas páginas cubren subdirectorios directos bajo el directorio src, lib o app del módulo, con al menos tres archivos de código por subsistema y dos subsistemas aptos en el módulo.

Las páginas de subsistema incluyen su subárbol de implementación y los archivos coincidentes bajo el directorio test o tests del módulo. Sus instrucciones de generación piden puntos de entrada, flujo del entorno de ejecución, límites, ubicaciones concretas de cambio y pruebas pertinentes. Las páginas de módulo colocan hasta dos archivos de prueba justo después de la fuente de mayor rango, para que las pruebas puedan participar en la selección acotada de evidencia.

El presupuesto predeterminado total sigue en 12 páginas, incluidas las tres páginas de visión general. Las visiones de módulo y las páginas de subsistema compiten por los huecos restantes según el recuento de fuentes; un subsistema se incluye solo después de la visión general de su padre. Los subsistemas más grandes pueden por tanto desplazar páginas de paquete más pequeñas. Previsualiza el resultado con ax-code wiki plan. Aumenta maxPages (hasta 40 para planes automáticos), o configura pages explícitos cuando un subsistema concreto necesite cobertura garantizada. Los planes explícitos siguen siendo autoritativos y no reciben páginas automáticas de subsistema.

Esto mejora la navegación y el foco de la evidencia; no verifica la prosa generada ni garantiza que un agente lea la wiki. Sigue las citas hasta el código fuente actual antes de confiar en detalles de implementación.

Cómo usan la wiki los agentes

Los agentes llegan a la wiki de tres maneras, de la más barata a la más específica:

1. Índice del prompt. Cuando existe una wiki sana, el prompt de la sesión lleva un bloque corto <repo_wiki>: la ubicación de la wiki, una etiqueta de frescura y una línea por página (ruta y un resumen recortado, unos 750 tokens para las 12 páginas predeterminadas). Los resúmenes solo localizan dónde leer; no son prueba.
2. Herramienta repo_wiki. Una herramienta de solo lectura con tres operaciones: index (tarjetas de página con frescura por página), read (una página más sus fuentes citadas, qué fuentes citadas cambiaron y cualquier símbolo del frontmatter no encontrado en esas fuentes) y related (páginas para un símbolo, una mención del cuerpo o una ruta de origen). Está disponible en los perfiles de herramientas completo y de programación, y usa el permiso read.
3. Herramientas genéricas de archivo. read, glob y grep sobre .ax-wiki/ siguen funcionando.

La frescura del prompt se juzga por página: una página está fresca mientras cada fuente que cita sigue coincidiendo con el hash del manifiesto. Un archivo añadido o editado que ninguna página cita deja la etiqueta del prompt en fresh y añade una nota de que la wiki aún no lo cubre. Una fuente citada cambiada marca la etiqueta stale y el prompt pide al agente que trate la wiki solo como navegación. ax-code wiki status y wiki lint conservan el veredicto más estricto de todo el repositorio, donde cualquier archivo apto añadido, eliminado o editado está obsoleto.

La wiki nunca sustituye al código fuente: cada resultado read lista los archivos contra los que verificar, y si una página y el código discrepan gana el código.

Actualizaciones incrementales y contenido manual

wiki update compara los hashes actuales del código fuente con el manifiesto y mapea los cambios a través de los selectores de cada página. Un cambio de plan regenera todas las páginas planificadas; si no, las páginas no relacionadas permanecen intactas.

La prosa generada es propiedad del compilador. Pon el texto durable de quien mantiene el proyecto dentro de un bloque protegido:

<!-- AX-WIKI:PROTECTED:START deployment-warning -->

Production migrations require an operator-approved maintenance window.

<!-- AX-WIKI:PROTECTED:END -->

Los cuerpos protegidos sobreviven a la regeneración. AX Wiki se niega a sobrescribir otras ediciones manuales salvo que se aporte --force. Las páginas generadas obsoletas se eliminan solo cuando su contenido gestionado no ha cambiado y no contienen una sección protegida.

Configuración

Configura la integración en el ax-code.json del proyecto:

{
  "wiki": {
    "enabled": true,
    "auto": true,
    "dir": ".ax-wiki",
    "model": "openai/gpt-5-mini",
    "autoInjectAgents": true,
    "touchClaudeMd": true,
    "maxPages": 12,
    "generationConcurrency": 2,
    "maxSourcesPerPage": 80,
    "exclude": ["fixtures/**"]
  }
}

include, exclude, maxSourceBytes y maxPageSourceBytes controlan el descubrimiento de evidencia y los presupuestos. instructions añade orientación del compilador específica del proyecto. Para un plan plenamente curado, configura entradas pages con path, title, purpose y selectors; un plan explícito debe incluir quickstart.md.

generationConcurrency acepta 1 o 2. La generación nativa en la nube usa de forma predeterminada dos llamadas de página simultáneas; los motores locales y los proveedores de CLI usan uno. Establécelo en 1 cuando un proveedor encola o limita las solicitudes solapadas. La planificación no invalida el contenido existente de las páginas. El paquete reutilizable sigue en serie salvo que se aporte este ajuste.

Cada página de modelo obtiene como máximo dos intentos clasificados que comparten un plazo de 180 segundos. Los enlaces relativos de la wiki se comprueban contra el plan de páginas antes de aceptar la página; una respuesta con un enlace roto puede usar el intento restante para reparar esa página. La validación final y las protecciones de contenido manual siguen ejecutándose antes de la publicación.

Las compilaciones interrumpidas conservan los resultados validados en .ax-wiki/.page-cache/ (o en el directorio de wiki configurado). Una compilación posterior reutiliza los resultados coincidentes solo después de comprobar la evidencia actual del código fuente, el plan, el generador, el modelo y el contenido anterior. La generación inicial permanece sin publicar hasta que la candidata completa apruebe la validación. La publicación exitosa elimina las entradas de preparación consumidas; un wiki generate explícito posterior sigue regenerando todas las páginas. Las entradas de caché están acotadas y condicionadas por permisos; las entradas corruptas o inaccesibles se ignoran.

.build-report.json distingue las páginas generadas por el modelo y las de caché de las páginas written, que se publicaron de verdad. Su array opcional pages registra los intentos de cada página, la duración, los tamaños en bytes del prompt y del código fuente, y el uso exacto de tokens cuando el proveedor lo aporta. Las compilaciones fallidas o canceladas no informan páginas publicadas.

También puedes colocar la orientación del compilador en ax-wiki.instructions.md y la configuración del motor central en ax-wiki.config.json. Los ajustes explícitos del entorno de ejecución de AX Code anulan la configuración central donde se aportan ambos.

Mantenimiento interactivo predeterminado

Abrir un proyecto en la TUI de AX Code activa de forma predeterminada el mantenimiento de la wiki en segundo plano. Tras 30 segundos de inactividad del proyecto, se generan los artefactos ausentes y los artefactos obsoletos se actualizan de forma incremental. Las sesiones ocupadas o en reintento, el trabajo en cola y un borrador no vacío tienen prioridad y cancelan la generación en segundo plano. Se aplican los permisos de lectura y escritura del agente actual; los agentes de solo lectura no generan. Este flujo de segundo plano no reescribe ningún archivo de instrucciones del agente.

Usa "wiki": { "auto": false } para desactivar el mantenimiento en segundo plano, o enabled: false para desactivar la compilación y la inyección en el prompt. auto es true de forma predeterminada y no escribe configuración. Usa el modelo de wiki configurado o el modelo predeterminado de AX Code, con un plazo de trabajo de 10 minutos y hasta tres intentos automáticos con espera creciente. Una solicitud explícita de grafo o un cambio de código fuente o de configuración permite otro intento. Las ejecuciones headless y CI no activan el planificador interactivo. Los directorios que no son Git exigen una solicitud explícita. En los proyectos Git, la generación y el consumo de la wiki usan la raíz del worktree más cercano, así que abrir AX Code en un paquete no crea una wiki de paquete aparte.

La barra lateral de la sesión y /wiki-viz abren de inmediato una página local de progreso y solicitan mantenimiento. Cuando hay una instantánea lista, esa página muestra las relaciones registradas de página y fuente de la wiki. Consulta visualización de la wiki.

Enrutado del agente

Cuando existe una wiki sana y wiki.enabled no es false, los prompts de sesión reciben un protocolo compacto <repo_wiki>. Indica a los agentes que empiecen por el inicio rápido, carguen solo las páginas pertinentes, verifiquen las afirmaciones importantes mediante los archivos citados y usen herramientas de grafo y LSP para las preguntas estructurales.

healthy describe la presencia del directorio de la wiki, el índice y el manifiesto. El campo aparte freshness es fresh, stale o unknown. El estado y el enrutado de sesión comparan los hashes actuales del código fuente usando los ajustes efectivos de inclusión, exclusión y tamaño, así que se detectan las ediciones, adiciones y eliminaciones sin confirmar. Las comprobaciones no reutilizan un veredicto fresco en caché; examinan las fuentes aptas con una concurrencia de lectura acotada. Las wikis ausentes o desactivadas evitan el examen del código fuente. La frescura es una comprobación del código fuente en un instante, no la validación de cada afirmación o página generada; usa lint para la validación de artefactos.

Las wikis obsoletas o no verificadas siguen disponibles para navegar, con una instrucción explícita de verificar el código fuente original actual antes de confiar en afirmaciones de implementación. Los errores de verificación producen unknown. wiki status sale con 0 cuando no existe un directorio de wiki (la wiki ausente es el informe). Cuando hay una wiki, sale sin éxito si la wiki está enferma o la frescura no es fresh.

La evidencia de la wiki está acotada: cada fuente seleccionada aporta como máximo sus primeros 32,000 bytes dentro del presupuesto de la página, con el truncamiento marcado para el generador. GraphContext puede añadir fragmentos seleccionados, pero cada fragmento se limita a 80 líneas. Estas ayudas de navegación no garantizan la conservación de cada función cambiada o de cada guarda exigida; aporta aparte el código original necesario para una revisión acotada.

El bloque gestionado <!-- AX-WIKI:START --> en AGENTS.md lleva la misma política de enrutado sin copiar el contenido de la wiki en las instrucciones del repositorio.

CI

Ejecuta ax-code wiki update seguido de ax-code wiki lint en un trabajo autenticado con el proveedor y luego abre una PR de documentación. Consulta examples/ax-wiki-update.yml. Trata los cambios generados de la wiki como el resto de la documentación: revisa las citas del código fuente y evita fusionar de forma automática la salida del modelo.

Resolución de problemas