Cette page est traduite de la documentation anglaise. Les commandes, identifiants et exemples sont inchangés. Runtime 7.24.4 · SDK 2.6.7. Source anglaise

AX Wiki compilé

Statut : Actif
Portée : état actuel
Dernière revue : 2026-10-03 Responsable : runtime AX Code

AX Wiki est le compilateur natif de wiki de dépôt d’AX Code. Il transforme les sources suivies, la configuration, les tests, les flux de travail et la documentation existante en une petite base de connaissances Markdown appuyée sur les sources, sous .ax-wiki/. Il utilise la même configuration de fournisseur et le même routage de modèles qu’AX Code ; il n’existe ni exécutable distinct ni magasin d’identifiants séparé.

ax-code wiki viz dessine les pages compilées et les fichiers qu’elles citent. Les captures de cette carte se trouvent dans Visualisation des preuves du wiki.

Où il s'insère

La prose du wiki est une couche de navigation compilée, pas une preuve structurelle. Si le wiki contredit le code, faites confiance au code et exécutez ax-code wiki update.

Démarrage rapide

Connectez un fournisseur AX Code, puis exécutez :

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

ax-code init --wiki génère AGENTS.md, insère le bloc de pointeur AX Wiki et compile le wiki en un seul flux de travail. Utilisez --wiki-only-agents pour ajouter des pointeurs sans appel de modèle.

Commandes

Les options de génération comprennent --model provider/model, --dir <relative>, --quiet, --skip-agents et --force. --force est exigé à dessein pour remplacer un contenu généré modifié manuellement hors des sections protégées.

Répertoire du dépôt

Depuis la v7.22.2, le répertoire de sortie par défaut est .ax-wiki/. Le préfixe masqué identifie les connaissances du dépôt maintenues par AX Code. Il ne rend pas les fichiers ignorés par Git : choisissez de valider ces connaissances ou d’ajouter /.ax-wiki/ au .gitignore de votre dépôt.

Utilisez wiki.dir dans ax-code.json ou --dir docs/knowledge pour choisir un autre répertoire relatif ; l’option CLI a la préséance. Toute la génération, l’état, les pointeurs d’agents, la maintenance en arrière-plan et la visualisation utilisent cette sélection. Le compilateur ne détecte, ne déplace ni ne fusionne pas automatiquement un ancien répertoire ax-wiki/. Les noms de paquet et de générateur, ax-wiki.config.json et ax-wiki.instructions.md restent inchangés.

Contrat généré

AX Wiki écrit des pages Markdown et .ax-wiki/.manifest.json. Chaque page possède un frontmatter contenant :

• generated_by: ax-wiki
• un summary concis
• les symbols exacts renvoyés par une génération appuyée sur des preuves
• le sources relatif au dépôt utilisé pour compiler la page

Le manifeste conserve le hachage déterministe du plan, les hachages des sources du dépôt, les hachages des pages, le modèle de génération, la révision Git et l’heure de génération. Les pages sont écrites de façon atomique ; le manifeste est écrit en dernier, et seulement après que le candidat complet en mémoire a passé la validation.

La découverte des sources préfère la liste des fichiers suivis et non ignorés de Git, exclut les répertoires générés, de construction ou de fournisseurs ainsi que le wiki lui-même, ignore les fichiers binaires ou trop volumineux, et refuse les chemins ou liens symboliques hors du dépôt.

Navigation par sous-système

Le plan par défaut conserve les pages de démarrage rapide, d’architecture et de développement. Un module qui dépasse le budget de nombre de sources ou d’octets de preuves d’une page peut aussi recevoir des pages ciblées telles que modules/core/src/session.md. Ces pages couvrent les sous-répertoires directs sous le répertoire src, lib ou app du module, avec au moins trois fichiers de code par sous-système et deux sous-systèmes éligibles dans le module.

Les pages de sous-système incluent leur sous-arbre d’implémentation et les fichiers correspondants sous le répertoire test ou tests du module. Leurs instructions de génération demandent les points d’entrée, le flux d’exécution, les frontières, les emplacements concrets de changement et les tests pertinents. Les pages de module placent jusqu’à deux fichiers de test immédiatement après la source la mieux classée, afin que les tests puissent participer à la sélection bornée des preuves.

Le budget total par défaut reste de 12 pages, y compris les trois pages de vue d’ensemble. Les vues d’ensemble de modules et les pages de sous-système se disputent les emplacements restants selon le nombre de sources ; un sous-système n’est inclus qu’après la vue d’ensemble de son parent. Des sous-systèmes plus grands peuvent donc déplacer des pages de paquets plus petites. Prévisualisez le résultat avec ax-code wiki plan. Augmentez maxPages (jusqu’à 40 pour les plans automatiques), ou configurez des pages explicites lorsqu’un sous-système particulier a besoin d’une couverture garantie. Les plans explicites restent souverains et ne reçoivent pas de pages de sous-système automatiques.

Cela améliore la navigation et la concentration des preuves ; cela ne vérifie pas la prose générée et ne garantit pas qu’un agent lise le wiki. Suivez les citations jusqu’à la source actuelle avant de vous fier aux détails d’implémentation.

Comment les agents utilisent le wiki

Les agents atteignent le wiki de trois façons, de la moins coûteuse à la plus spécifique :

1. Index d’invite. Lorsqu’un wiki sain existe, l’invite de session porte un court bloc <repo_wiki> : l’emplacement du wiki, une étiquette de fraîcheur et une ligne par page (chemin et résumé tronqué, environ 750 jetons pour les 12 pages par défaut). Les résumés indiquent seulement où lire ; ils ne sont pas une preuve.
2. Outil repo_wiki. Un outil en lecture seule avec trois opérations : index (cartes de pages avec la fraîcheur par page), read (une page plus ses sources citées, les sources citées qui ont changé, et tout symbole de frontmatter absent de ces sources), et related (pages pour un symbole, une mention dans le corps ou un chemin de source). Il est disponible dans les profils d’outils complets et de codage, et utilise la permission read.
3. Outils de fichiers génériques. read, glob et grep sur .ax-wiki/ fonctionnent encore.

La fraîcheur de l’invite est jugée par page : une page est fraîche tant que chaque source qu’elle cite correspond encore au hachage du manifeste. Un fichier ajouté ou modifié qu’aucune page ne cite laisse l’étiquette d’invite fresh et ajoute une note indiquant que le wiki ne le couvre pas encore. Une source citée qui a changé marque l’étiquette stale et l’invite demande à l’agent de traiter le wiki comme une navigation seulement. ax-code wiki status et wiki lint conservent le verdict plus strict à l’échelle du dépôt, où tout fichier éligible ajouté, retiré ou modifié est périmé.

Le wiki ne remplace jamais la source : chaque résultat read liste les fichiers à vérifier, et si une page et le code divergent, le code l’emporte.

Mises à jour incrémentales et contenu manuel

wiki update compare les hachages de source actuels au manifeste et projette les changements à travers les sélecteurs de chaque page. Un changement de plan régénère toutes les pages planifiées ; sinon, les pages sans lien restent intactes.

La prose générée appartient au compilateur. Placez le texte durable du mainteneur dans un bloc protégé :

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

Production migrations require an operator-approved maintenance window.

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

Les corps protégés survivent à la régénération. AX Wiki refuse d’écraser les autres modifications manuelles, sauf si --force est fourni. Les pages générées obsolètes ne sont retirées que lorsque leur contenu géré est inchangé et qu’elles ne contiennent aucune section protégée.

Configuration

Configurez l’intégration dans le ax-code.json du projet :

{
  "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 et maxPageSourceBytes contrôlent la découverte des preuves et les budgets. instructions ajoute des consignes de compilateur propres au projet. Pour un plan entièrement choisi, configurez des entrées pages avec path, title, purpose et selectors ; un plan explicite doit inclure quickstart.md.

generationConcurrency accepte 1 ou 2. La génération cloud native utilise par défaut deux appels de pages simultanés ; les moteurs locaux et les fournisseurs CLI en utilisent un. Réglez-le sur 1 lorsqu’un fournisseur met en file ou limite les requêtes qui se chevauchent. L’ordonnancement n’invalide pas le contenu de page existant. Le paquet réutilisable reste sériel tant que ce réglage n’est pas fourni.

Chaque page de modèle dispose d’au plus deux tentatives classées qui partagent une échéance de 180 secondes. Les liens Wiki relatifs sont vérifiés par rapport au plan de pages avant l’acceptation de la page ; une réponse avec lien cassé peut utiliser la tentative restante pour réparer cette page. La validation finale et les gardes de contenu manuel s’exécutent encore avant la publication.

Les constructions interrompues conservent les résultats validés dans .ax-wiki/.page-cache/ (ou le répertoire Wiki configuré). Une construction ultérieure réutilise les résultats correspondants seulement après avoir vérifié les preuves de source actuelles, le plan, le générateur, le modèle et le contenu précédent. La génération initiale reste non publiée tant que le candidat complet n’a pas passé la validation. Une publication réussie retire les entrées de préparation consommées ; un wiki generate explicite ultérieur régénère encore toutes les pages. Les entrées de cache sont bornées et soumises aux permissions ; les entrées corrompues ou inaccessibles sont ignorées.

.build-report.json distingue les pages générées par modèle et mises en cache des pages written, qui ont réellement été publiées. Son tableau facultatif pages enregistre, pour chaque page, les tentatives, la durée, les tailles en octets de l’invite et des sources, ainsi que l’usage exact de jetons lorsque le fournisseur le fournit. Les constructions échouées ou annulées ne signalent aucune page publiée.

Vous pouvez aussi placer les consignes du compilateur dans ax-wiki.instructions.md et la configuration du moteur principal dans ax-wiki.config.json. Les réglages explicites du runtime AX Code remplacent la configuration principale lorsque les deux sont fournis.

Maintenance interactive par défaut

Ouvrir un projet dans le TUI d’AX Code active par défaut la maintenance Wiki en arrière-plan. Après 30 secondes d’inactivité du projet, les artefacts manquants sont générés et les artefacts périmés sont mis à jour de façon incrémentale. Les sessions occupées ou en nouvel essai, le travail en file et un brouillon non vide ont la priorité et annulent la génération en arrière-plan. Les permissions de lecture et d’écriture de l’agent courant s’appliquent ; les agents en lecture seule ne génèrent pas. Ce flux de travail en arrière-plan ne réécrit aucun fichier d’instructions d’agent.

Utilisez "wiki": { "auto": false } pour désactiver la maintenance en arrière-plan, ou enabled: false pour désactiver la compilation et l’injection dans l’invite. auto vaut vrai par défaut et n’écrit pas de configuration. Il utilise le modèle Wiki configuré ou le modèle par défaut d’AX Code, avec une échéance de tâche de 10 minutes et jusqu’à trois tentatives automatiques avec temporisation croissante. Une demande de graphe explicite ou un changement de source ou de configuration autorise une autre tentative. Les exécutions sans interface et CI n’activent pas l’ordonnanceur interactif. Les répertoires hors Git exigent une demande explicite. Dans les projets Git, la génération et la consommation du Wiki utilisent la racine du worktree le plus proche, de sorte qu’ouvrir AX Code dans un paquet ne crée pas un Wiki de paquet distinct.

La barre latérale de session et /wiki-viz ouvrent immédiatement une page de progression locale et demandent la maintenance. Dès qu’un instantané est prêt, cette page montre les relations enregistrées entre pages Wiki et sources. Voir Visualisation du wiki.

Routage des agents

Lorsqu’un wiki sain existe et que wiki.enabled n’est pas false, les invites de session reçoivent un protocole compact <repo_wiki>. Il demande aux agents de commencer par le démarrage rapide, de charger seulement les pages pertinentes, de vérifier les affirmations importantes à travers les fichiers cités, et d’utiliser les outils de graphe et LSP pour les questions structurelles.

healthy décrit la présence du répertoire du wiki, de l’index et du manifeste. Le champ distinct freshness vaut fresh, stale ou unknown. L’état et le routage de session comparent les hachages de source actuels avec les réglages effectifs d’inclusion, d’exclusion et de taille, de sorte que les modifications, ajouts et suppressions non validés sont détectés. Les contrôles ne réutilisent pas un verdict de fraîcheur mis en cache ; ils parcourent les sources éligibles avec une concurrence de lecture bornée. Les wikis manquants ou désactivés évitent le parcours des sources. La fraîcheur est un contrôle de source à un instant donné, pas la validation de chaque affirmation ou page générée ; utilisez lint pour la validation des artefacts.

Les wikis périmés ou non vérifiés restent disponibles pour la navigation, avec une instruction explicite de vérifier la source originale actuelle avant de se fier aux affirmations d’implémentation. Les erreurs de vérification produisent unknown. wiki status se termine avec le code 0 lorsqu’aucun répertoire de wiki n’existe (le wiki manquant constitue le rapport). Lorsqu’un wiki est présent, il se termine en échec si le wiki est en mauvaise santé ou si la fraîcheur n’est pas fresh.

Les preuves du wiki sont bornées : chaque source sélectionnée contribue au plus ses 32 000 premiers octets dans le budget de la page, la troncature étant marquée pour le générateur. GraphContext peut ajouter des extraits sélectionnés, mais chaque extrait est limité à 80 lignes. Ces aides à la navigation ne garantissent pas la conservation de chaque fonction modifiée ou de chaque garde exigée ; fournissez séparément le code original nécessaire pour une revue bornée.

Le bloc géré <!-- AX-WIKI:START --> dans AGENTS.md porte la même politique de routage sans copier le contenu du wiki dans les instructions du dépôt.

CI

Exécutez ax-code wiki update puis ax-code wiki lint dans une tâche authentifiée auprès d’un fournisseur, puis ouvrez une demande d’intégration documentaire. Voir examples/ax-wiki-update.yml. Traitez les changements de wiki générés comme le reste de la documentation : revoyez les citations de source et évitez la fusion automatique de la sortie du modèle.

Dépannage