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

Operar o AX Code para trabalho de longa duração

Status: Ativo Escopo: estado atual Última revisão: 2026-09-13 Responsável: mantenedores do AX Code

O AX Code limita uma execução interativa Super-Long a 72 horas. Para operar por dias ou semanas, execute um processo supervisionado ax-code serve e divida o trabalho em ocorrências agendadas e duráveis. O supervisor reinicia o servidor; o banco do projeto preserva agendas e o estado da fila.

Espaço de trabalho interativo persistente

Para trabalho local que deve continuar depois de fechar o terminal, opte por um runtime de projeto:

ax-code runtime start --dir /absolute/path/project
ax-code runtime attach --dir /absolute/path/project --continue
ax-code runtime status --dir /absolute/path/project
ax-code runtime list                  # every managed runtime on this machine
ax-code runtime stop --dir /absolute/path/project

runtime attach também inicia o runtime quando nenhum existe. O runtime é identificado pelo diretório canônico do projeto; inícios concorrentes reutilizam um processo. A TUI mostra o host de execução e uma ação Desconectar. Desconectar fecha o cliente e mantém em execução o trabalho aceito. runtime stop desliga o runtime desse projeto e interrompe o trabalho ativo dele. Um ax-code comum conserva o ciclo de vida já existente em primeiro plano.

Acompanhamentos aceitos, enviados enquanto uma sessão está ocupada, são salvos no servidor. Por padrão eles começam depois que o turno em execução termina, então um pedido sem relação nunca desvia o trabalho em curso. Para corrigir o turno em execução, em vez disso, pressione ctrl+s (input_submit_steer em keybinds) com um rascunho só de texto: o texto é admitido na geração ativa e gravado como mensagem do usuário na próxima fronteira de passo do laço, depois que as chamadas de ferramenta em curso assentam e antes da próxima solicitação de modelo. Uma correção admitida enquanto o turno está terminando estende a execução em uma iteração, em vez de ser descartada. O direcionamento é por melhor esforço: se não houver mais geração ativa, o rascunho segue o caminho comum; se um hook o vetar, o rascunho fica no compositor, com o motivo. Rascunhos com anexos e comandos de barra sempre usam a fila de acompanhamento. A mesma entrega está disponível para outros clientes pela API de direcionamento descrita em controles do harness. Acompanhamentos salvos também podem ser direcionados depois: pressionar ctrl+s com o compositor vazio promove, em ordem, o prefixo direcionável da fila e para na primeira linha não direcionável, e a seção Acompanhamentos da barra lateral e o diálogo /queue oferecem a mesma ação de direcionar agora, por linha. Linhas pausadas são direcionáveis no lugar — interromper um turno pausa os acompanhamentos em espera, e direcionar um entrega o texto dele sem retomar o resto da fila. Só linhas que não são acompanhamento (comandos de barra enfileirados, comandos de shell), linhas com anexos, texto vazio ou grande demais, e linhas já em execução ou concluídas são barreiras. Linhas direcionadas são canceladas com uma trilha de auditoria steeredInto e permanecem visíveis no histórico /queue. Quando não há geração ativa, direcionar agora recua para priorizar a linha na frente da fila — ela ainda só começa depois que o turno termina. O compositor só limpa depois da confirmação. Reanexe à mesma sessão e use /queue para inspecionar, pausar, editar, retomar ou cancelar. Editar primeiro pausa o item e preserva anexos e a seleção de modelo; salvar não retoma. Edições concorrentes e obsoletas são rejeitadas. Em /queue, Ctrl+R inclui o histórico concluído e cancelado. Terminais estreitos também mostram um título clicável Follow-ups. Uma vista desconectada fica em cache e não pode alterar itens. Interromper o turno ativo pausa acompanhamentos pendentes, para que eles não iniciem na hora outro turno. Retome-os de forma explícita quando estiver pronto.

Depois de um reinício do backend, acompanhamentos aceitos e em espera podem retomar. Um prompt comum em curso, interrompido por esse reinício, é marcado como falha e exige inspeção antes de nova tentativa; restaurar registros da fila não restaura um processo de shell em execução. Uma confirmação perdida pode ser tentada de novo a partir do compositor inalterado, com a mesma identidade de solicitação, durante essa sessão do cliente. Rascunhos não salvos não são trabalhos aceitos, e isto não garante efeitos externos exatamente uma vez.

Este modo não instala um serviço de login, não reinicia sozinho um servidor que falhou e não executa enquanto o host está adormecido ou desligado. Inicie ou anexe de novo depois de uma falha; use os exemplos de serviço supervisionado abaixo para reinícios sem supervisão do servidor. Usuários de SSH devem executar o runtime num host remoto acordado e anexar lá. Não exponha a porta HTTP publicamente.

A descoberta de runtime guarda uma capacidade privada e um log na pasta runtime/ do diretório de estado do AX Code. A saída de status omite a capacidade. O desligamento exige uma identidade autenticada e correspondente do runtime, não só um PID salvo. Um processo ao vivo indisponível, um registro corrompido ou uma incompatibilidade de versão exige inspeção; a CLI recusa matar um processo não verificado. Pare um runtime saudável antes de atualizar e reinicie-o com o executável novo.

Modelo de confiabilidade

Isto é recuperação segura contra duplicata, não entrega exatamente uma vez para efeitos externos arbitrários. Integrações que gravam em sistemas externos ainda devem usar as próprias chaves de idempotência.

Antes de instalar um serviço

1. Instale e teste o executável ax-code como o mesmo usuário que vai executar o serviço.
2. Escolha um caminho absoluto de projeto. Defina-o como AX_CODE_PROJECT para que a inicialização do servidor pré-aqueça esse projeto e inicie o agendador dele.
3. Mantenha o servidor em 127.0.0.1; o servidor do AX Code é só local.
4. Coloque as credenciais do provedor no ambiente protegido do supervisor, em vez de num arquivo de serviço enviado ao repositório.
5. Substitua cada espaço reservado /absolute/path/... no exemplo escolhido.

Os exemplos usam uma porta fixa, para que clientes Desktop ou SDK possam reconectar:

ax-code serve --hostname=127.0.0.1 --port=4096

Serviço de usuário systemd

Copie o exemplo systemd para ~/.config/systemd/user/ax-code.service, substitua os caminhos absolutos e, se quiser, coloque credenciais em ~/.config/ax-code/server.env.

chmod 600 ~/.config/ax-code/server.env
systemctl --user daemon-reload
systemctl --user enable --now ax-code.service
systemctl --user status ax-code.service
journalctl --user -u ax-code.service -f

Use loginctl enable-linger "$USER" somente se a política do sistema permitir que o serviço do usuário execute enquanto o usuário está desconectado.

Agente launchd

Copie o exemplo launchd para ~/Library/LaunchAgents/com.axcode.server.plist, substitua os caminhos absolutos e depois valide e carregue:

plutil -lint ~/Library/LaunchAgents/com.axcode.server.plist
launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/com.axcode.server.plist
launchctl kickstart -k "gui/$(id -u)/com.axcode.server"

launchd não expande variáveis de shell em ProgramArguments. Use caminhos absolutos e forneça as credenciais necessárias por um mecanismo administrado pelo operador.

PM2

Copie o exemplo PM2, substitua os caminhos e inicie:

pm2 start docs/examples/ax-code-ecosystem.config.cjs
pm2 save
pm2 logs ax-code-server

Siga as instruções de partida específicas da plataforma do PM2 se o processo precisar voltar depois de uma reinicialização do host.

Prazos, atraso e recuperação

As tarefas agendadas usam catchUpPolicy: "run_once" por padrão. Depois de uma parada, o AX Code executa uma ocorrência juntada, em vez de criar um acúmulo sem limite. Escolha "skip" quando trabalho atrasado seria enganoso ou inseguro.

Cada tarefa agendada pode definir maxRunDurationMs de 1 segundo até 72 horas. Fora isso, a execução da fila de tarefas usa o teto de 72 horas. Itens ativos atualizam uma marca de batimento a cada 30 segundos, e o status terminal e os detalhes de erro permanecem no banco do projeto.

Os endpoints assíncronos de prompt, de comando e de shell devolvem o item durável da fila na resposta HTTP 202. Os clientes devem conservar o id dele e consultar GET /task-queue/:id até completed, failed ou cancelled; a aceitação, sozinha, não é conclusão.

Na inicialização, um backend persistente do AX Code retoma itens da fila agendada e itens assíncronos marcados de forma explícita que foram confirmados, mas não tinham começado. Comandos de CLI de uma vez não tomam posse desses itens. Trabalho de prompt já iniciado é marcado como falha, com uma explicação de reinício, para que um operador possa inspecionar efeitos colaterais antes de tentar de novo.

Ver o que as tarefas agendadas estão fazendo

Cada ocorrência de tarefa agendada fica visível enquanto acontece e pode ser auditada depois:

• Começar, concluir, falhar, pular e pausas automáticas por falha persistente cada um levanta uma notificação no aplicativo nomeando a tarefa.
• O comando de TUI /schedule lista cada tarefa com o status, a agenda, a próxima hora de execução e o último erro, e abre o histórico recente de execução. Dali você pode pausar, retomar, executar agora, apagar (pressione ctrl+d duas vezes para confirmar) e saltar para a sessão que uma execução produziu. As ferramentas list_scheduled_tasks e list_scheduled_task_runs do agente respondem às mesmas perguntas em conversa.
• Cada execução acontece numa sessão nova, titulada com o título da tarefa, então os resultados ficam a uma entrada da lista de sessões, mesmo se uma notificação foi perdida.
• Se uma execução pedir uma permissão ou uma resposta de pergunta enquanto você vê uma conversa diferente, um aviso nomeia a sessão que precisa de você; /attention lista os pedidos pendentes conhecidos e abre a sessão que pediu. Os pedidos podem ser respondidos nessa sessão ou na vista de um ancestral carregado, inclusive sessões filhas e netas. Abrir um pedido nunca o aprova sozinho.
• Uma tarefa única só é desativada depois de uma execução bem-sucedida. Uma ocorrência que falhou tenta de novo com uma espera delimitada, e falhas repetidas pausam a tarefa com uma notificação — um lembrete não pode mais sumir em silêncio.

Checagens operacionais

• Observe a contagem de reinícios do supervisor e os logs do servidor.
• Inspecione itens da fila de tarefas que falharam e erros de tarefa agendada antes de tentar de novo.
• Confirme espaço em disco suficiente para o banco SQLite do projeto e os logs.
• Exercite um executar agora manual depois de mudar credenciais, modelos ou caminhos de serviço.
• Pare pelo supervisor, para que o AX Code receba SIGTERM; os exemplos permitem até 90 segundos para um desligamento gracioso.

/loop é, de propósito, local do processo e não sobrevive a um reinício. Use tarefas agendadas para trabalho durável sem supervisão.

Navegar sessões paralelas

Com 146 colunas de terminal ou mais, uma barra lateral de navegação à esquerda mostra as sessões do workspace atual e os agentes filhos carregados. Expanda uma linha com o controle + e clique num título para abri-la. Sessões fixadas conservam a ordem e os números de atalho. Rótulos completos de atividade distinguem trabalhando, tentando de novo, aprovações e perguntas; os pais também refletem pedidos dos descendentes. Esses rótulos não significam que uma tarefa passou na verificação. A barra lateral direita já existente conserva o contexto e os controles da sessão atual.

O título Projeto identifica o diretório atual. Clique nele ou use /navigation-info para ver o caminho completo do projeto e o título da sessão atual. Recentes mostra sessões carregadas; Ativas conserva árvores de sessão trabalhando ou em espera e a árvore da sessão atual. O filtro é compartilhado com o seletor de navegação e lembrado. Use /navigation-filter para alterná-lo pelo teclado. Durante a desconexão, ele mostra sessões em cache, em vez de inferir quais sessões estão ativas. Limpar (ou /navigation-clear) pede confirmação e depois oculta linhas históricas só do trilho esquerdo e do seletor de navegação. Não apaga sessões; /sessions ainda as lista. A árvore da sessão atual, as sessões fixadas e as árvores observadas trabalhando ou em espera permanecem no trilho. Abrir uma sessão a partir de /sessions a devolve à lista.

Use /navigation-width ou a ação Largura da navegação para escolher 20, 24, 28, 30, 32, 36 ou 40 colunas (padrão 28). A barra lateral direita da sessão tem a mesma ação Largura e /sidebar-width (padrão 32). As duas preferências são lembradas e encolhem sozinhas quando preciso para preservar o conteúdo principal. Use /navigation para ocultar ou restaurar o trilho de navegação esquerdo em terminais largos. /sidebar oculta ou restaura a barra lateral direita da sessão da mesma forma. Em terminais mais estreitos, /navigation abre um seletor de sessão e de agente. Uma barra visível de Sessões oferece a mesma ação sempre que o trilho de navegação está ausente. A ação Pendentes aparece quando pedidos conhecidos precisam de entrada; um asterisco marca uma contagem em cache durante a desconexão. /sessions continua abrindo o seletor normal de sessão. /attention está disponível em qualquer largura. Durante a desconexão, a lista dele é rotulada como em cache; abrir entradas em cache ainda é possível, mas os pedidos podem já ter sido respondidos em outro lugar. A ação Pedidos conhecidos da barra lateral abre pedidos pendentes entre os workspaces conhecidos, enquanto a árvore de sessão permanece limitada ao projeto atual. Todas estas vistas são delimitadas pela instância conectada e pelos dados de sessão carregados; esta contagem não é um inventário completo de outros servidores ou de workspaces não carregados.

Rascunhos não enviados são isolados por projeto e por sessão dentro da TUI em execução. Trocar de sessão preserva texto, anexos, posição do cursor e modo de shell; voltar restaura o rascunho correspondente. Estes rascunhos ficam só na memória e não sobrevivem ao fechamento da TUI.

A notificação opcional de conclusão agora diz Session idle. Ela segue o trabalho observado na subárvore da sessão vista e espera que descendentes ativos observados fiquem explicitamente ociosos, sem pedidos pendentes. Desconexões, ressincronizações, estado ausente, erros e cancelamento podem suprimir o aviso. É uma notificação de ciclo de vida, não evidência de que testes passaram ou de que uma meta foi concluída.

Tarefas novas e configuração

A partida normal abre a superfície de trabalho Tarefa nova, com um compositor embaixo e navegação de sessão. Abri-la ou digitar um rascunho não cria uma sessão salva; uma sessão é criada quando você envia. Use /sessions ou a navegação esquerda para retomar trabalho existente. O comportamento explícito de --session, --continue e --prompt continua disponível; a partida não ativa a retomada automática.

A configuração de provedor não abre sozinha. Use a ação visível /connect na área de trabalho quando nenhum provedor está configurado. Com um provedor configurado, mas sem um modelo válido selecionado, a ação muda para /models. Descoberta de provedor que falhou aponta para /status; /connect e /providers continuam disponíveis para reparar a configuração. Um modelo selecionado é uma escolha de configuração, não uma checagem de credencial nem de prontidão do runtime. As dicas também aparecem para quem volta e cuja configuração precisa de atenção.