Questa pagina è tradotta dalla documentazione inglese. Comandi, identificatori ed esempi restano invariati. Runtime 7.24.4 · SDK 2.6.7. Testo inglese

AX Wiki del repository

Stato: attivo Ambito: stato attuale Ultima revisione: 2026-10-03 Responsabile: runtime di AX Code

AX Wiki è il compilatore nativo di wiki del repository di AX Code. Trasforma sorgente tracciato, configurazione, test, flussi di lavoro e documentazione esistente in una piccola base di conoscenza Markdown appoggiata al sorgente sotto .ax-wiki/. Usa la stessa configurazione dei provider e lo stesso instradamento dei modelli di AX Code; non esiste un eseguibile separato né un archivio di credenziali.

ax-code wiki viz disegna le pagine compilate e i file che citano. Gli screenshot di quella mappa sono in Visualizzazione delle prove Wiki.

Dove si colloca

La prosa della Wiki è uno strato di navigazione compilato, non una prova strutturale. Se la wiki è in disaccordo con il codice, fidati del codice ed esegui ax-code wiki update.

Avvio rapido

Connetti un provider di AX Code, poi esegui:

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

ax-code init --wiki genera AGENTS.md, inserisce il blocco puntatore di AX Wiki e compila la wiki in un solo flusso di lavoro. Usa --wiki-only-agents per aggiungere puntatori senza chiamate al modello.

Comandi

Le opzioni di generazione includono --model provider/model, --dir <relative>, --quiet, --skip-agents e --force. --force è richiesto di proposito per sostituire contenuto generato modificato manualmente fuori dalle sezioni protette.

Directory del repository

Dalla v7.22.2, la directory di output predefinita è .ax-wiki/. Il prefisso nascosto identifica la conoscenza del repository mantenuta da AX Code. Non rende i file ignorati da Git: scegli se committare questa conoscenza oppure aggiungere /.ax-wiki/ al .gitignore del repository.

Usa wiki.dir in ax-code.json o --dir docs/knowledge per scegliere un’altra directory relativa; il flag della CLI ha la precedenza. Generazione, stato, puntatori dell’agente, manutenzione in background e visualizzazione usano quella selezione. Il compilatore non rileva, sposta o unisce automaticamente una directory ax-wiki/ più vecchia. I nomi di pacchetto e generatore, ax-wiki.config.json e ax-wiki.instructions.md restano invariati.

Contratto generato

AX Wiki scrive pagine Markdown e .ax-wiki/.manifest.json. Ogni pagina ha un frontmatter che contiene:

• generated_by: ax-wiki
• un summary conciso
• symbols esatti restituiti dalla generazione appoggiata alle prove
• il sources relativo al repository usato per compilare la pagina

Il manifesto memorizza l’hash del piano deterministico, gli hash del sorgente del repository, gli hash delle pagine, il modello di generazione, la revisione git e l’ora di generazione. Le pagine vengono scritte in modo atomico; il manifesto viene scritto per ultimo e solo dopo che il candidato completo in memoria supera la validazione.

La scoperta del sorgente preferisce l’elenco dei file tracciati e non ignorati di Git, esclude directory generate, di build e di vendor e la wiki stessa, salta i file binari o troppo grandi e rifiuta percorsi o symlink fuori dal repository.

Navigazione dei sottosistemi

Il piano predefinito mantiene le pagine di avvio rapido, architettura e sviluppo. Un modulo che supera il budget di conteggio sorgenti o di byte di prove di una pagina può ricevere anche pagine mirate come modules/core/src/session.md. Queste pagine coprono le sottodirectory dirette sotto la directory src, lib o app del modulo, con almeno tre file di codice per sottosistema e due sottosistemi idonei nel modulo.

Le pagine di sottosistema includono il loro sottoalbero di implementazione e i file corrispondenti sotto la directory test o tests del modulo. Le loro istruzioni di generazione chiedono punti di ingresso, flusso di runtime, confini, posizioni concrete di modifica e test rilevanti. Le pagine di modulo collocano fino a due file di test subito dopo il sorgente di rango più alto, così i test possono partecipare alla selezione limitata delle prove.

Il budget predefinito totale resta di 12 pagine, incluse le tre pagine di panoramica. Le panoramiche dei moduli e le pagine di sottosistema competono per gli slot rimanenti in base al conteggio dei sorgenti; un sottosistema è incluso solo dopo la panoramica del genitore. I sottosistemi più grandi possono quindi spostare pagine di pacchetto più piccole. Anteprima il risultato con ax-code wiki plan. Aumenta maxPages (fino a 40 per i piani automatici), oppure configura pages espliciti quando un sottosistema particolare ha bisogno di copertura garantita. I piani espliciti restano autorevoli e non ricevono pagine di sottosistema automatiche.

Questo migliora la navigazione e il fuoco delle prove; non verifica la prosa generata né garantisce che un agente legga la wiki. Segui le citazioni fino al sorgente corrente prima di affidarti ai dettagli di implementazione.

Come gli agenti usano la wiki

Gli agenti raggiungono la wiki in tre modi, dal più economico al più specifico:

1. Indice nel prompt. Quando esiste una wiki sana, il prompt di sessione porta un blocco breve <repo_wiki>: la posizione della wiki, un’etichetta di freschezza e una riga per pagina (percorso e un riepilogo ritagliato, circa 750 token per le 12 pagine predefinite). I riepiloghi localizzano solo dove leggere; non sono una prova.
2. Strumento repo_wiki. Uno strumento di sola lettura con tre operazioni: index (schede di pagina con freschezza per pagina), read (una pagina più i sorgenti citati, quali sorgenti citati sono cambiati e gli eventuali simboli del frontmatter non trovati in quei sorgenti) e related (pagine per un simbolo, una menzione nel corpo o un percorso sorgente). È disponibile nei profili di strumenti completo e di programmazione e usa il permesso read.
3. Strumenti di file generici. read, glob e grep su .ax-wiki/ funzionano ancora.

La freschezza del prompt è giudicata per pagina: una pagina è fresca finché ogni sorgente che cita corrisponde ancora all’hash del manifesto. Un file aggiunto o modificato che nessuna pagina cita lascia l’etichetta del prompt fresh e aggiunge una nota che la wiki non lo copre ancora. Un sorgente citato cambiato marca l’etichetta stale e il prompt chiede all’agente di trattare la wiki solo come navigazione. ax-code wiki status e wiki lint mantengono il verdetto più stretto sull’intero repository, dove qualsiasi file idoneo aggiunto, rimosso o modificato è non aggiornato.

La wiki non sostituisce mai il sorgente: ogni risultato read elenca i file da verificare, e se una pagina e il codice sono in disaccordo vince il codice.

Aggiornamenti incrementali e contenuto manuale

wiki update confronta gli hash del sorgente corrente con il manifesto e mappa i cambiamenti attraverso i selettori di ogni pagina. Un cambiamento di piano rigenera tutte le pagine pianificate; altrimenti le pagine non correlate restano intatte.

La prosa generata è di proprietà del compilatore. Metti il testo durevole del manutentore dentro un blocco protetto:

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

Production migrations require an operator-approved maintenance window.

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

I corpi protetti sopravvivono alla rigenerazione. AX Wiki rifiuta di sovrascrivere altre modifiche manuali salvo che sia fornito --force. Le pagine generate obsolete vengono rimosse solo quando il loro contenuto gestito è invariato e non contengono una sezione protetta.

Configurazione

Configura l’integrazione nel ax-code.json di progetto:

{
  "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 e maxPageSourceBytes controllano la scoperta delle prove e i budget. instructions aggiunge una guida del compilatore specifica del progetto. Per un piano interamente curato, configura voci pages con path, title, purpose e selectors; un piano esplicito deve includere quickstart.md.

generationConcurrency accetta 1 o 2. La generazione cloud nativa usa per impostazione predefinita due chiamate di pagina simultanee; i motori locali e i provider CLI usano per impostazione predefinita una. Impostalo su 1 quando un provider mette in coda o limita le richieste sovrapposte. La pianificazione non invalida il contenuto esistente delle pagine. Il pacchetto riutilizzabile resta seriale salvo che questa impostazione sia fornita.

Ogni pagina del modello ottiene al massimo due tentativi classificati che condividono una scadenza di 180 secondi. I collegamenti Wiki relativi vengono controllati rispetto al piano delle pagine prima che la pagina sia accettata; una risposta con collegamento rotto può usare il tentativo rimanente per riparare quella pagina. La validazione finale e le protezioni del contenuto manuale girano ancora prima della pubblicazione.

Le build interrotte conservano i risultati validati in .ax-wiki/.page-cache/ (o nella directory Wiki configurata). Una build successiva riusa i risultati corrispondenti solo dopo aver controllato le prove del sorgente corrente, il piano, il generatore, il modello e il contenuto precedente. La generazione iniziale resta non pubblicata finché il candidato completo non supera la validazione. La pubblicazione riuscita rimuove le voci di staging consumate; un successivo wiki generate esplicito rigenera comunque tutte le pagine. Le voci di cache sono limitate e vincolate dai permessi; le voci corrotte o inaccessibili vengono ignorate.

.build-report.json distingue le pagine generate dal modello e quelle in cache dalle pagine written, che sono state davvero pubblicate. Il suo array facoltativo pages registra tentativi, durata, dimensioni in byte di prompt e sorgente e l’uso esatto dei token di ogni pagina, quando il provider li fornisce. Le build fallite o annullate non riportano pagine pubblicate.

Puoi anche mettere la guida del compilatore in ax-wiki.instructions.md e la configurazione del motore centrale in ax-wiki.config.json. Le impostazioni esplicite del runtime di AX Code scavalcano la configurazione centrale dove entrambe sono fornite.

Manutenzione interattiva predefinita

Aprire un progetto nella TUI di AX Code abilita per impostazione predefinita la manutenzione Wiki in background. Dopo 30 secondi di inattività del progetto, gli artefatti mancanti vengono generati e gli artefatti non aggiornati vengono aggiornati in modo incrementale. Le sessioni occupate o in nuovo tentativo, il lavoro in coda e una bozza non vuota hanno la priorità e annullano la generazione in background. Si applicano i permessi di lettura e scrittura dell’agente corrente; gli agenti di sola lettura non generano. Questo flusso di lavoro in background non riscrive alcun file di istruzioni dell’agente.

Usa "wiki": { "auto": false } per disabilitare la manutenzione in background, oppure enabled: false per disabilitare compilazione e iniezione del prompt. auto è true per impostazione predefinita e non scrive configurazione. Usa il modello Wiki configurato o il modello predefinito di AX Code, con una scadenza del job di 10 minuti e fino a tre tentativi automatici con backoff. Una richiesta esplicita di grafo o un cambiamento di sorgente o configurazione consente un altro tentativo. Le esecuzioni headless e CI non abilitano il pianificatore interattivo. Le directory non Git richiedono una richiesta esplicita. Nei progetti Git, generazione e consumo della Wiki usano la radice del worktree più vicina, quindi aprire AX Code in un pacchetto non crea una Wiki di pacchetto separata.

La barra laterale della sessione e /wiki-viz aprono subito una pagina di progresso locale e richiedono la manutenzione. Quando un’istantanea è pronta, quella pagina mostra le relazioni registrate tra pagine Wiki e sorgenti. Vedi Visualizzazione Wiki.

Instradamento degli agenti

Quando esiste una wiki sana e wiki.enabled non è false, i prompt di sessione ricevono un protocollo compatto <repo_wiki>. Dice agli agenti di partire dall’avvio rapido, caricare solo le pagine rilevanti, verificare le affermazioni importanti tramite i file citati e usare gli strumenti di grafo e LSP per le domande strutturali.

healthy descrive la presenza della directory della wiki, dell’indice e del manifesto. Il campo separato freshness è fresh, stale o unknown. Stato e instradamento di sessione confrontano gli hash del sorgente corrente usando le impostazioni effettive di inclusione, esclusione e dimensione, così vengono rilevate modifiche non committate, aggiunte e cancellazioni. I controlli non riusano un verdetto fresco in cache; esaminano i sorgenti idonei con concorrenza di lettura limitata. Le wiki mancanti o disabilitate evitano la scansione del sorgente. La freschezza è un controllo del sorgente in un istante, non la validazione di ogni affermazione o pagina generata; usa lint per la validazione degli artefatti.

Le wiki non aggiornate o non verificate restano disponibili per la navigazione, con un’istruzione esplicita di verificare il sorgente originale corrente prima di affidarsi alle affermazioni di implementazione. Gli errori di verifica producono unknown. wiki status esce con 0 quando non esiste una directory wiki (la wiki mancante è il rapporto). Quando una wiki è presente, esce senza successo se la wiki non è sana o la freschezza non è fresh.

Le prove della wiki sono limitate: ogni sorgente selezionato contribuisce al massimo i suoi primi 32,000 byte dentro il budget della pagina, con il troncamento marcato per il generatore. GraphContext può aggiungere frammenti selezionati, ma ogni frammento è limitato a 80 righe. Questi aiuti di navigazione non garantiscono la conservazione di ogni funzione modificata o di ogni protezione richiesta; fornisci separatamente il codice originale necessario per una revisione circoscritta.

Il blocco gestito <!-- AX-WIKI:START --> in AGENTS.md porta la stessa policy di instradamento senza copiare il contenuto della wiki nelle istruzioni del repository.

CI

Esegui ax-code wiki update seguito da ax-code wiki lint in un job autenticato presso il provider, poi apri una PR di documentazione. Vedi examples/ax-wiki-update.yml. Tratta le modifiche generate della wiki come altra documentazione: rivedi le citazioni del sorgente ed evita l’unione automatica dell’output del modello.

Risoluzione dei problemi