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

Controles do harness e avaliação verificada

Status: Ativo

Escopo: estado atual

Última revisão: 2026-09-14

Responsável: runtime do ax-code

Para o esforço específico de cada modelo, os interruptores de thinking e a reprodução do raciocínio, veja controles atuais de raciocínio do modelo.

Controles opcionais de contexto e de ferramentas

Ative cada experimento de forma independente na configuração do AX Code:

{
  "experimental": {
    "context_recovery": true,
    "mcp_tool_discovery": true,
    "tail_reminders": true,
    "read_only_recipes": true
  }
}

As quatro opções vêm desativadas por padrão. Meça o sucesso da tarefa e o tempo decorrido com o seu modelo antes de adotá-las em conjunto. Elas preservam as permissões de ferramenta e as configurações de isolamento já existentes. Veja diagnósticos de desempenho.

context_recovery expõe context_recover e acrescenta ponteiros de código-fonte aos resumos de compactação bem-sucedidos. A ferramenta aceita uma palavra-chave, um ID de mensagem, um ID de parte opcional e um limite de resultados. Ela só lê a sessão atual, inclusive o histórico anterior à compactação, e exclui material revertido, raciocínio oculto e texto ignorado ou sintético. Devolve os IDs originais de mensagem e de parte, além de trechos limitados. A busca examina no máximo 100 partes por página e os primeiros 16.000 caracteres de cada parte; before continua nas partes mais antigas. A falta de uma correspondência não prova que o histórico inteiro não contenha esse texto. Os forks usam o histórico copiado e IDs novos. Atribuições de credenciais são redigidas nos trechos.

mcp_tool_discovery mantém as ferramentas integradas disponíveis e introduz tool_search para as ferramentas MCP conectadas. Uma busca devolve até cinco esquemas correspondentes e torna essas ferramentas disponíveis na próxima requisição ao modelo. Ela não as executa. As seleções ficam restritas à sessão, limitadas a 32 ferramentas, e são cruzadas com a admissão vigente em cada requisição. Esquemas grandes podem ser omitidos do resultado da busca e carregados na requisição seguinte. Se tool_search for negado, o catálogo MCP admitido da forma habitual permanece disponível. Uma ferramenta já existente, com o nome conflitante tool_search, produz um erro.

tail_reminders move apenas os lembretes dinâmicos de turno gerados pelo AX Code para o fim da requisição ao provedor. Mensagens armazenadas do usuário, raciocínio do assistente, histórico de ferramentas e instruções estáticas permanecem inalterados. Isso pode mudar o comportamento do modelo e o uso de cache; por si só, não comprova um ganho de velocidade.

read_only_recipes expõe read_recipe. Ele executa até oito chamadas dependentes de read, glob ou grep pelo despachante normal de ferramentas. Cada chamada filha tem as próprias verificações de permissão, os próprios hooks, o próprio cancelamento e a própria evidência de sessão. Uma receita não pode avaliar código, executar comandos de shell, gravar arquivos, chamar ferramentas MCP nem aninhar outra receita.

{
  "steps": [
    { "id": "files", "tool": "glob", "parameters": { "pattern": "src/**/*.ts" } },
    {
      "id": "source",
      "tool": "read",
      "parameters": { "filePath": { "$ref": { "step": "files", "path": ["paths", 0] } } }
    }
  ],
  "select": [{ "step": "source", "path": ["text"] }]
}

Os resultados canônicos de glob contêm paths e truncated; os resultados de grep contêm matches com path, line e text; os resultados de read contêm kind, text renderizado e truncated. Selecione um resultado anterior pelo passo e pelo caminho de propriedade própria. Seleções de array aceitam um filtro literal contains e limit. Confira o status devolvido e o truncamento. A receita tem prazo de cancelamento de 60 segundos, orçamento de argumentos de 32 KB, orçamento intermediário de 192 KB e saída final limitada. O cancelamento espera a ferramenta sob controle se estabilizar. Instruções novas do repositório, ou mídia, pausam a execução e preservam a saída normal da chamada filha, para que o modelo as veja antes de continuar. Seleções bem-sucedidas substituem as saídas intermediárias apenas na requisição ao modelo; os registros originais das chamadas filhas permanecem no histórico. Pais interrompidos conservam a saída das filhas.

Corrigir uma geração em andamento

GET /session/{sessionID}/steering devolve o UUID da geração ativa e os recibos recentes. Inclua o parâmetro de consulta directory já existente ao selecionar um projeto pelo servidor HTTP.

Envie POST /session/{sessionID}/steering com:

{
  "expectedGeneration": "00000000-0000-4000-8000-000000000001",
  "clientID": "correction_1",
  "text": "Preserve the existing public function signature."
}

Use o UUID obtido no GET, não o UUID de exemplo. accepted significa que a correção está pendente. applied significa que ela foi gravada como mensagem do usuário em um limite de loop e inclui o ID dessa mensagem; isso não garante a conclusão no provedor. rejected significa que ela não foi aplicada. Hooks de ciclo de vida podem vetar a admissão. Uma correção aceita prolonga em mais uma iteração uma geração que estava prestes a terminar, de modo que uma correção enviada no instante da conclusão é aplicada, em vez de rejeitada. Cancelamento e erros ainda rejeitam correções pendentes, e uma geração antiga não pode admitir texto na geração seguinte. Repetições idênticas devolvem o mesmo recibo retido; conteúdo diferente sob um ID de cliente já existente devolve HTTP 409. O gesto de envio imediato da TUI, ctrl+s, usa este endpoint.

Chamadas paralelas de ferramenta em um passo

Quando o modelo emite várias chamadas de ferramenta na mesma mensagem do assistente, o runtime as executa em paralelo por um gate de leitor/escritor no escopo da sessão. Ferramentas somente leitura compartilham a faixa e se sobrepõem; edições de arquivo, bash, bash_input, edições de notebook, ops_apply, ferramentas MCP e qualquer batch que contenha uma chamada filha sem segurança para concorrência ocupam a faixa exclusiva e rodam sozinhas, na ordem de chegada. Uma chamada abortada enquanto espera nunca chega a rodar. O lote mantém a própria barreira de ordenação para as chamadas que despacha, e as sessões filhas têm o próprio gate.

Os recibos são locais ao processo, com no máximo 256 por sessão e 32 requisições pendentes. Recibos em estado terminal e entradas de sessão inativa podem ser descartados. Depois de um reinício, obtenha a geração nova e reconcilie as mensagens salvas; esta API não promete consulta durável de recibos entre reinícios. O SDK gerado expõe session.steering e session.steer.

Levar um acompanhamento salvo para o turno em execução

POST /task-queue/{taskID}/steer admite o texto de um acompanhamento enfileirado na geração em execução da sessão, no próximo limite de passo — o mesmo ponto de entrega de POST /session/{sessionID}/steering — e cancela a linha da fila na mesma requisição, registrando steeredInto (o UUID da geração) e steeredAt no payload da linha, para auditoria. Acompanhamentos só de texto, com até 16.000 caracteres, podem ser direcionados; o texto direcionado usa o agente, o modelo e as ferramentas do turno em execução. Anexos, tipos que não são acompanhamento, linhas já resolvidas e texto grande demais são rejeitados com HTTP 400. Uma linha que passa a outro status no meio da requisição devolve HTTP 409.

A resposta traz o item mais recente da fila e um recibo que pode ser nulo. Quando não há geração ativa, a linha permanece intacta e a resposta informa generation_not_active com recibo nulo; quem chama pode então recorrer a POST /task-queue/{taskID}/send-now, que apenas move a linha para a frente da fila e ainda espera o turno terminar. Uma linha direcionada não pode ser desfeita, mas continua visível como cancelled no histórico de /queue, com os campos de auditoria.

Na TUI, o atalho input_submit_steer (padrão ctrl+s) direciona o rascunho digitado quando ele existe; com o compositor vazio diante de uma sessão ocupada, promove, em ordem FIFO, o prefixo direcionável da fila salva e para na primeira linha que não pode ser direcionada, para que acompanhamentos posteriores nunca passem à frente dela. A seção Acompanhamentos da barra lateral e o diálogo /queue oferecem a mesma ação de direcionar agora, por linha, e uma dica junto aos acompanhamentos enfileirados mostra a tecla associada. O SDK gerado expõe taskQueue.steer.

Propor uma habilidade a partir de trabalho verificado

Os candidatos a habilidade são registros explícitos no armazenamento local já existente do AX Code. Eles não entram na descoberta de habilidades até que você os promova, e nunca disparam uma chamada automática de modelo nem uma reescrita de instruções.

Crie um arquivo JSON de proposta com name, description, applicability, procedure e evidence, contendo sessionID, messageID e partID. A evidência precisa identificar um resultado original e bem-sucedido de verify_project, com envelopes de teste ou de verificação de tipos executados contra a revisão Git limpa atual. Uma frase de sucesso, ou uma saída arbitrária de shell, não basta. A validação precisa citar a verificação bem-sucedida de outra sessão na mesma revisão.

ax-code skill candidate propose --proposal proposal.json
ax-code skill candidate show verified-procedure
ax-code skill candidate validate verified-procedure --proposal independent-evidence.json
ax-code skill candidate promote verified-procedure
ax-code skill candidate retire verified-procedure

Mantenha o JSON de entrada fora da worktree, ou em um diretório local ignorado, para que a verificação da revisão limpa continue significativa. A promoção cria .ax-code/skill/{name}/SKILL.md sem sobrescrever uma habilidade existente. A evidência de origem é conferida de novo antes da promoção. Diretórios acessados por link simbólico são rejeitados. A aposentadoria remove apenas o arquivo próprio do candidato que não foi alterado; edições manuais provocam um conflito. Reinicie uma instância de runtime já em execução para atualizar a descoberta de habilidades em cache. Verificações aprovadas estabelecem evidência dessas verificações; revise se o procedimento se aplica antes de promover.

Capturar um experimento pareado

A partir de um checkout do código-fonte, use:

pnpm --dir packages/ax-code exec tsx script/harness-eval.ts run /path/to/manifest.json > /path/to/runs.ndjson
pnpm --dir packages/ax-code exec tsx script/harness-eval.ts compare /path/to/runs.ndjson baseline candidate

O manifesto confiável do operador contém um provider/model explícito, runtimeRevision, um argv opcional de CLI command, repetitions, timeoutMs, exatamente dois arms nomeados e tasks. Cada braço tem features opcional (as flags experimentais acima) e toolProfile. Cada tarefa fornece id, prompt, files embutido (path/content) e um oracle. O oráculo é JavaScript confiável, executado pelo Node.js depois que o processo de programação termina; process.argv[1] identifica o fixture temporário. O código do oráculo permanece fora do espaço de trabalho do agente e nunca vem da resposta do modelo.

Cada tentativa recebe um fixture Git novo. O oráculo precisa falhar com saída 1 no fixture inicial. O executor usa uma invocação fixa da CLI sem interface, alterna a ordem dos braços entre as repetições, aplica um tempo limite e executa o oráculo outra vez depois de uma tentativa concluída. elapsedMs inclui o processo de programação e a verificação posterior à execução; verificationMs identifica essa verificação em separado. A preparação do fixture e a verificação inicial que falha ficam de fora. O fluxo registra cada tentativa concluída, com falha, com tempo esgotado ou cancelada no momento em que ela termina. Prompts brutos, saída de subprocesso e credenciais não aparecem nos registros de avaliação. Uma coorte interrompida permanece incompleta e não pode produzir uma comparação pareada.

A comparação rejeita duplicatas e pares ausentes ou divergentes de tarefa, modelo, coorte e repetição. Tentativas com falha e tentativas não verificadas permanecem nos denominadores da taxa de sucesso. Medianas de latência e razões pareadas ficam explicitamente condicionadas ao sucesso verificado. O P95 exige 20 observações bem-sucedidas dentro de uma célula de tarefa, modelo, coorte e braço; agregados de células misturadas o omitem. A coorte calcula o hash do manifesto, mas a revisão do runtime e as condições externas de provedor, configuração e cache ainda exigem controle do operador. Uma passagem curta de teste de fumaça não estabelece superioridade geral de velocidade nem justifica alterar os padrões.

Seleção de capacidade e diagnósticos de recuperação

Requisições autônomas podem incluir um pacote de contexto para agente longo quando o modelo tem pelo menos 64.000 tokens de contexto, suporte a raciocínio e suporte a ferramentas. Para modelos sem entrada no registro, os três itens precisam estar declarados nos metadados resolvidos do modelo. O pacote suplementar tem um teto de 2.048 tokens, estimado por caracteres; ele não é a janela da conversa. Declarações negativas explícitas e restrições registradas impedem a admissão. Esta otimização do texto do prompt não estabelece compatibilidade de cache nem de thinking preservado, e não altera os prazos automáticos nem o ritmo do Super-Long. Esses comportamentos conservam as regras existentes de qualificação e de substituição.

Duas falhas estruturadas e consecutivas de ferramenta, depois da mensagem mais recente do usuário (contadas antes dos lembretes sintéticos de cauda), pedem raciocínio mais profundo na chamada seguinte ao modelo, quando existe uma variante de esforço utilizável. Um resultado bem-sucedido de ferramenta zera a contagem. O esforço explícito do usuário e as opções de raciocínio configuradas têm precedência. Isso altera a seleção de esforço, não os limites de nova tentativa nem as permissões de ferramenta.

Os eventos locais de reprodução de llm.request incluem capabilityResolution: protocolo, janela de contexto, se um pacote de contexto ou o modo Super-Long foi selecionado, falhas consecutivas de ferramenta e a seleção de raciocínio ou um motivo de não aplicação. boundary: "policy-selection" descreve a decisão do AX Code; plugins e SDKs de provedor ainda podem alterar a requisição final. Valores explícitos de esforço do GPT-6 são preservados; a API exige low ou um nível superior, e não none nem minimal. O evento guarda hashes da requisição, não corpos de prompt nem de credencial. A ausência de uma variante de esforço não significa que o thinking padrão do provedor esteja desativado.

A captura pareada do harness lê os eventos JSON step_finish e tool_use da CLI para tokens de entrada, de saída, de raciocínio e de leitura de cache, chamadas de ferramenta concluídas e erros de ferramenta. IDs de parte duplicados contam uma só vez. metricsStatus é observed, partial ou unavailable; fluxos truncados ou malformados e tentativas interrompidas não informam os totais. As comparações apresentam, para cada métrica, a mediana e as contagens de execuções observadas e ausentes, inclusive tentativas com falha quando existem observações. Valores ausentes continuam ausentes. Esses contadores descrevem eventos emitidos pelo runtime, não a cobrança do provedor, o uso de sessões filhas nem ferramentas internas nativas da CLI. Um fluxo observado por completo, sem eventos de ferramenta em estado terminal, informa zero chamadas de ferramenta. A verificação do oráculo continua sendo a fonte do sucesso da tarefa; o uso, isoladamente, não comprova recuperação bem-sucedida nem qualidade melhor.