Esta página é uma tradução da documentação em inglês. Comandos, identificadores e exemplos permanecem iguais. Runtime 7.24.4 · SDK 2.6.7. Original em inglês

Compilador AX Wiki

Status: Ativo
Escopo: estado atual
Última revisão: 2026-10-03 Responsável: runtime do AX Code

A AX Wiki é o compilador nativo de wiki de repositório do AX Code. Ela transforma código-fonte rastreado, configuração, testes, fluxos de trabalho e a documentação existente em uma base de conhecimento Markdown pequena e apoiada no código, em .ax-wiki/. Usa a mesma configuração de provedor e o mesmo roteamento de modelo do AX Code; não há executável separado nem armazenamento próprio de credenciais.

ax-code wiki viz desenha as páginas compiladas e os arquivos que elas citam. Capturas desse mapa estão em Visualização de evidência da Wiki.

Onde ela se encaixa

A prosa da wiki é uma camada compilada de navegação, não uma prova estrutural. Se a wiki discordar do código, confie no código e execute ax-code wiki update.

Início rápido

Conecte um provedor do AX Code e depois execute:

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

ax-code init --wiki gera AGENTS.md, insere o bloco de ponteiro da AX Wiki e compila a wiki em um único fluxo. Use --wiki-only-agents para acrescentar ponteiros sem chamadas de modelo.

Comandos

As opções de geração incluem --model provider/model, --dir <relative>, --quiet, --skip-agents e --force. --force é exigido de propósito para substituir conteúdo gerado que foi editado manualmente fora das seções protegidas.

Diretório do repositório

A partir da v7.22.2, o diretório padrão de saída é .ax-wiki/. O prefixo oculto identifica conhecimento do repositório mantido pelo AX Code. Ele não torna os arquivos ignorados pelo Git: escolha se vai enviar esse conhecimento ao repositório ou acrescente /.ax-wiki/ ao .gitignore do repositório.

Use wiki.dir em ax-code.json ou --dir docs/knowledge para escolher outro diretório relativo; a flag da CLI tem precedência. Toda geração, status, ponteiros de agente, manutenção em segundo plano e visualização usam essa seleção. O compilador não detecta, move nem mescla automaticamente um diretório antigo ax-wiki/. Os nomes de pacote e de gerador, ax-wiki.config.json e ax-wiki.instructions.md, permanecem iguais.

Contrato gerado

A AX Wiki grava páginas Markdown e .ax-wiki/.manifest.json. Cada página tem frontmatter contendo:

• generated_by: ax-wiki
• um summary conciso
• symbols exatos, devolvidos pela geração apoiada em evidência
• o sources relativo ao repositório, usado para compilar a página

O manifesto guarda o hash determinístico do plano, os hashes de fonte do repositório, os hashes das páginas, o modelo de geração, a revisão git e o horário da geração. As páginas são gravadas de forma atômica; o manifesto é gravado por último, e somente depois que o candidato completo em memória passa na validação.

A descoberta de fonte prefere a lista de arquivos rastreados e não ignorados do Git, exclui diretórios gerados, de build e de vendor e a própria wiki, pula arquivos binários ou grandes demais e recusa caminhos ou links simbólicos fora do repositório.

Navegação por subsistema

O plano padrão mantém páginas de início rápido, de arquitetura e de desenvolvimento. Um módulo que ultrapassa o orçamento de contagem de fontes ou de bytes de evidência de uma página também pode receber páginas focadas, como modules/core/src/session.md. Essas páginas cobrem subdiretórios diretos sob o diretório src, lib ou app do módulo, com pelo menos três arquivos de código por subsistema e dois subsistemas elegíveis no módulo.

As páginas de subsistema incluem a subárvore de implementação e os arquivos correspondentes sob o diretório test ou tests do módulo. As instruções de geração pedem pontos de entrada, fluxo do runtime, fronteiras, locais concretos de mudança e testes relevantes. As páginas de módulo colocam até dois arquivos de teste logo depois da fonte de maior classificação, para que os testes participem da seleção limitada de evidência.

O orçamento padrão total continua em 12 páginas, inclusive as três páginas de visão geral. Visões gerais de módulo e páginas de subsistema disputam as vagas restantes pela contagem de fontes; um subsistema só entra depois da visão geral pai. Subsistemas maiores podem, portanto, deslocar páginas menores de pacote. Veja o resultado com ax-code wiki plan. Aumente maxPages (até 40 para planos automáticos) ou configure pages explícito quando um subsistema específico precisar de cobertura garantida. Planos explícitos continuam autoritativos e não recebem páginas automáticas de subsistema.

Isso melhora a navegação e o foco da evidência; não verifica a prosa gerada nem garante que um agente leia a wiki. Siga as citações de volta ao código-fonte atual antes de confiar em detalhes de implementação.

Como os agentes usam a wiki

Os agentes chegam à wiki de três maneiras, da mais barata à mais específica:

1. Índice no prompt. Quando existe uma wiki saudável, o prompt da sessão traz um bloco curto <repo_wiki>: o local da wiki, um rótulo de atualidade e uma linha por página (caminho e um resumo aparado, cerca de 750 tokens para as 12 páginas padrão). Os resumos apenas indicam onde ler; não são prova.
2. Ferramenta repo_wiki. Uma ferramenta somente leitura com três operações: index (cartões de página com atualidade por página), read (uma página mais as fontes citadas, quais fontes citadas mudaram e quaisquer símbolos de frontmatter não encontrados nessas fontes) e related (páginas para um símbolo, uma menção no corpo ou um caminho de fonte). Ela está disponível nos perfis completo e de programação e usa a permissão read.
3. Ferramentas genéricas de arquivo. read, glob e grep em .ax-wiki/ continuam funcionando.

A atualidade no prompt é julgada por página: uma página está atual enquanto cada fonte que ela cita ainda coincide com o hash do manifesto. Um arquivo acrescentado ou editado que nenhuma página cita deixa o rótulo do prompt em fresh e acrescenta uma nota de que a wiki ainda não o cobre. Uma fonte citada que mudou marca o rótulo como stale, e o prompt pede ao agente que trate a wiki apenas como navegação. ax-code wiki status e wiki lint conservam o veredito mais estrito de todo o repositório, em que qualquer arquivo elegível acrescentado, removido ou editado está desatualizado.

A wiki nunca substitui a fonte: cada resultado de read lista os arquivos a conferir, e, se uma página e o código discordarem, o código prevalece.

Atualizações incrementais e conteúdo manual

wiki update compara os hashes atuais da fonte com o manifesto e mapeia as mudanças pelos seletores de cada página. Uma mudança de plano regenera todas as páginas planejadas; caso contrário, páginas não relacionadas permanecem intactas.

A prosa gerada pertence ao compilador. Coloque texto durável de quem mantém dentro de um bloco protegido:

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

Production migrations require an operator-approved maintenance window.

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

Os corpos protegidos sobrevivem à regeneração. A AX Wiki recusa sobrescrever outras edições manuais, a menos que --force seja informado. Páginas geradas obsoletas são removidas somente quando o conteúdo administrado não mudou e elas não contêm seção protegida.

Configuração

Configure a integração no ax-code.json do projeto:

{
  "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 controlam a descoberta de evidência e os orçamentos. instructions acrescenta orientação de compilador específica do projeto. Para um plano totalmente curado, configure entradas pages com path, title, purpose e selectors; um plano explícito precisa incluir quickstart.md.

generationConcurrency aceita 1 ou 2. A geração nativa na nuvem usa, por padrão, duas chamadas simultâneas de página; engines locais e provedores de CLI usam uma. Defina como 1 quando um provedor enfileira ou limita requisições sobrepostas. O agendamento não invalida o conteúdo existente das páginas. O pacote reutilizável permanece serial, a menos que esta configuração seja informada.

Cada página de modelo recebe no máximo duas tentativas classificadas, que compartilham um prazo de 180 segundos. Links relativos da Wiki são conferidos contra o plano de páginas antes de a página ser aceita; uma resposta com link quebrado pode usar a tentativa restante para reparar essa página. A validação final e as proteções de conteúdo manual ainda rodam antes da publicação.

Compilações interrompidas conservam resultados validados em .ax-wiki/.page-cache/ (ou no diretório configurado da Wiki). Uma compilação posterior reutiliza resultados correspondentes somente depois de conferir a evidência atual da fonte, o plano, o gerador, o modelo e o conteúdo anterior. A geração inicial permanece não publicada até o candidato completo passar na validação. Uma publicação bem-sucedida remove as entradas de preparação já consumidas; um wiki generate explícito posterior ainda regenera todas as páginas. As entradas de cache são limitadas e protegidas por permissão; entradas corrompidas ou inacessíveis são ignoradas.

.build-report.json distingue páginas geradas pelo modelo e páginas em cache das páginas written, que foram de fato publicadas. A matriz opcional pages registra, para cada página, as tentativas, a duração, os tamanhos em bytes do prompt e da fonte e o uso exato de tokens, quando o provedor os informa. Compilações com falha ou canceladas não informam páginas publicadas.

Você também pode colocar orientação do compilador em ax-wiki.instructions.md e a configuração central do engine em ax-wiki.config.json. Configurações explícitas do runtime do AX Code substituem a configuração central quando as duas são informadas.

Manutenção interativa padrão

Abrir um projeto na TUI do AX Code ativa, por padrão, a manutenção da Wiki em segundo plano. Depois de 30 segundos de ociosidade do projeto, artefatos ausentes são gerados e artefatos desatualizados são atualizados de forma incremental. Sessões ocupadas ou em nova tentativa, trabalho enfileirado e um rascunho não vazio têm prioridade e cancelam a geração em segundo plano. Valem as permissões de leitura e de escrita do agente atual; agentes somente leitura não geram. Este fluxo em segundo plano não reescreve arquivos de instrução de agente.

Use "wiki": { "auto": false } para desativar a manutenção em segundo plano, ou enabled: false para desativar a compilação e a injeção no prompt. auto vem como verdadeiro por padrão e não grava configuração. Usa o modelo configurado da Wiki ou o modelo padrão do AX Code, com prazo de 10 minutos por trabalho e até três tentativas automáticas com espera crescente. Um pedido explícito de grafo, ou uma mudança de fonte ou de configuração, permite outra tentativa. Execuções sem interface e a CI não ativam o agendador interativo. Diretórios que não são Git exigem um pedido explícito. Em projetos Git, a geração e o consumo da Wiki usam a raiz da worktree mais próxima, então abrir o AX Code em um pacote não cria uma Wiki separada desse pacote.

A barra lateral da sessão e /wiki-viz abrem na hora uma página local de progresso e pedem a manutenção. Quando um instantâneo está pronto, essa página mostra as relações registradas de página e de fonte da Wiki. Veja Visualização da Wiki.

Roteamento do agente

Quando existe uma wiki saudável e wiki.enabled não é false, os prompts da sessão recebem um protocolo compacto <repo_wiki>. Ele pede aos agentes que comecem pelo início rápido, carreguem apenas as páginas relevantes, verifiquem afirmações importantes pelos arquivos citados e usem ferramentas de grafo e de LSP para perguntas estruturais.

healthy descreve a presença do diretório da wiki, do índice e do manifesto. O campo separado freshness é fresh, stale ou unknown. O status e o roteamento da sessão comparam os hashes atuais da fonte usando as configurações efetivas de inclusão, exclusão e tamanho, então edições não confirmadas, acréscimos e exclusões são detectados. As verificações não reutilizam um veredito de atualidade em cache; examinam as fontes elegíveis com concorrência limitada de leitura. Wikis ausentes ou desativadas evitam a varredura da fonte. A atualidade é uma conferência da fonte em um instante, não a validação de cada afirmação ou página gerada; use o lint para validar os artefatos.

Wikis desatualizadas ou não verificadas continuam disponíveis para navegação, com uma instrução explícita de conferir a fonte original atual antes de confiar em afirmações de implementação. Erros de verificação produzem unknown. wiki status termina com 0 quando não existe diretório de wiki (a wiki ausente é o relatório). Quando uma wiki está presente, termina sem sucesso se a wiki não estiver saudável ou se a atualidade não for fresh.

A evidência da wiki é limitada: cada fonte selecionada contribui com no máximo os primeiros 32.000 bytes dentro do orçamento da página, com o truncamento marcado para o gerador. O GraphContext pode acrescentar trechos selecionados, mas cada trecho se limita a 80 linhas. Esses auxílios de navegação não garantem a preservação de cada função alterada nem de cada proteção exigida; forneça à parte o código original necessário para uma revisão com escopo definido.

O bloco administrado <!-- AX-WIKI:START --> em AGENTS.md carrega a mesma política de roteamento, sem copiar o conteúdo da wiki para as instruções do repositório.

CI

Execute ax-code wiki update e depois ax-code wiki lint em um job autenticado no provedor e, em seguida, abra um PR de documentação. Veja examples/ax-wiki-update.yml. Trate as mudanças geradas da wiki como outra documentação: revise as citações de fonte e evite mesclar automaticamente a saída do modelo.

Solução de problemas