boshu2/usando-gc

Usando a GC

Use a Gas City apenas quando o solicitante a selecionar explicitamente. Trate-a como um adaptador de execução substituível, não como um limite de correção ou conclusão. O adaptador não pode selecionar semânticas de AgentOps, emitir um veredito de vinculação ou transformar a conclusão da fábrica em prova de entrega ou validação.

Escolha a fábrica primeiro

O AgentOps suporta tanto a Gas City quanto o Agentic Coding Flywheel como ambientes de execução de fábrica de software externos. Use esta skill apenas para a Gas City. Se o solicitante selecionar o Flywheel, mude para usando-flywheel e seu fluxo de trabalho nativo, em vez de encapsulá-lo na Gas City.

O AgentOps fornece skills e contratos de evidência para qualquer uma das fábricas. Ele não precisa de sua própria fórmula ou pacote de função da Gas City. Instale ou vincule as skills do AgentOps no ambiente de execução do provedor antes de iniciar os workers; o Prefeito upstream, o coordenador e os workers podem então descobrir e selecionar plan, implement, test, validate e outras skills do AgentOps normalmente.

Modelo operacional da Gas City 1.4

A Gas City 1.4 é centrada em execuções. O supervisor serve o painel e APIs de sessão/execução tipada e paginada. Cada escopo de cidade ou rig que possui um grafo precisa de seu próprio core.control-dispatcher; esse worker determinístico avança as contas de controle da fórmula. Workers agentes reivindicam trabalho roteado. A skill gc.mayor upstream é o coordenador guiado; gc.run-operator inicia e supervisiona fórmulas.

O caminho normal do AgentOps é:

1. Instale e fixe o fluxo de trabalho gascity upstream e as importações de função de rig.
2. Adicione o projeto como uma rig, prepare seu ambiente de execução de mantenedor padrão e torne as skills do AgentOps visíveis para suas sessões de provedor.
3. Crie uma conta de intenção de origem de propriedade do solicitante e entregue seu id ao Prefeito, que redige as contas do fluxo de trabalho e despacha a fórmula build-basic, de continuação, revisão ou implementação upstream que corresponda aos artefatos disponíveis.
4. Leia o estado da execução, sessão, conta, artefato e veredito. A conclusão nunca é inferida de bate-papo ou prosa de painel.

Prepare e qualifique uma rig antes de sua primeira compilação com a CLI do AgentOps enviada (nenhum checkout de repositório necessário):

ao gc prepare --city /caminho/para/cidade --rig /caminho/para/rig
ao gc check --city /caminho/para/cidade --rig /caminho/para/rig

O comando verifica os pins exatos do fluxo de trabalho e função oficiais, tira um instantâneo dos scripts de validação e esquemas upstream inalterados dentro do ambiente de execução .gc da rig, instala apenas pequenos wrappers de propriedade do AgentOps nos caminhos de verificação da fórmula, seleciona um Python existente que possa importar PyYAML e vincula as skills do AgentOps nos sumidouros de Codex da cidade e da rig. As skills vêm do checkout do AgentOps circundante quando presente, caso contrário, da raiz das skills instaladas; passe --skills-source para fixar um diretório diferente. Ele nunca modifica o binário GC, cache, fórmulas, funções ou pacote upstream. check emite apenas comandos de inspeção nativos, não escreve arquivos de adaptador e falha antes do gasto do modelo quando esse contrato de ambiente de execução está ausente ou divergente.

prepare também pré-preenche a confiança do Codex para cada diretório de sessão que existe quando é executado — as raízes da cidade e da rig, cada diretório inicial de sessão .gc/agents/** e cada raiz de árvore de trabalho da rig — para que uma sessão do Codex em um desses diretórios não bloqueie no diálogo de confiança interativo. Ambas as camadas persistidas são semeadas em $CODEX_HOME/config.toml: confiança do espaço de trabalho ([projects."<dir>"] trust_level = "trusted"), sem a qual o Codex relata silenciosamente que esse diretório não tem hooks, e confiança por hook ([hooks.state."<hooks.json>:<event>:<m>:<h>"] trusted_hash = "sha256:..."), que é o que o hooks.json do pacote por provedor solicitaria. Os dígitos do hook são lidos de volta da própria hooks/list do Codex, nunca recomputados.

A confiança é julgada pelo valor, não pela presença de uma tabela. prepare anexa apenas entradas que estão faltando e recusa, nomeando a entrada, quando uma existe mas não confere confiança — um trust_level = "untrusted" explícito, um hook que o Codex relata como alterado desde que foi confiado, um hook gravado que o Codex ainda rejeita ou um hook gravado como enabled = false (um hook desabilitado não é um hook de trabalho confiável). Ele nunca sobrescreve uma decisão do operador, e reexecutar é um no-op. Também falha em vez de continuar se o Codex retornar uma lista de hooks vazia ou não reconhecida. O armazenamento de confiança em si nunca é editado no local: o conteúdo mesclado é analisado na memória primeiro, depois instalado com o gravador atômico durável da CLI, para que nenhum caminho de falha possa deixar uma configuração do Codex parcialmente escrita.

ao gc check verifica o mesmo pré-preenchimento apenas a partir do estado local — ele executa nenhum subprocesso do Codex e não escreve nada, derivando cada chave de hook esperada do próprio hooks.json do diretório — e nomeia o diretório ou hook específico deficiente usando a mesma regra que prepare usa para preencher.

Duas limitações nomeadas.

1. check não pode detectar um hash obsoleto. Como nunca pergunta ao Codex, um trusted_hash gravado que não corresponde mais ao conteúdo atual do hook é lido como satisfeito e ainda levanta o diálogo de confiança em uma sessão real. Apenas prepare vê isso — o Codex relata o hook como alterado e prepare recusa. Um check verde significa, portanto, "a confiança está registrada", não "a confiança é nova".
2. Diretórios iniciais criados após prepare não são cobertos. A descoberta é por marcador do sistema de arquivos, então a garantia cobre os diretórios de sessão que existem no momento de prepare. Um diretório inicial de sessão que a Gas City materializa depois ainda carrega hooks não confiáveis em sua primeira inicialização; prepare nomeia os agentes configurados que ainda não têm diretório inicial.

A regra operacional que segue de ambos: execute prepare, inicie a cidade, então execute prepare novamente (é idempotente) antes de despachar.

Pacote e registros preferidos

O registro main integrado cataloga pacotes oficiais. O registro da comunidade é configuração opcional:

gc pack registry list
gc pack registry refresh
gc pack registry search --all
gc pack registry show main:gascity
gc pack registry add community https://registry.gascity.com/registry.toml
gc pack registry search --registry community --all

search lê o cache do registro local; show relata proveniência de lançamento e comandos de importação exatos. gc import add declara uma fonte/versão e gc import install o resolve em packs.lock. Prefira um lançamento aceito exato para cidades reproduzíveis.

O AgentOps prefere o pacote de compilação gascity oficial, a família de fluxos de trabalho visível na fábrica pública Maintainer City. A referência aceita atual é gascity 0.1.6 no commit 3b3b89f2011e06d84459aa7bea1552382f13930a:

• painel: https://factory.gascity.com;
• fluxos de trabalho: build-basic, build-from-*, implement, review, issue e PR;
• funções de rig padrão: gc.run-operator, gc.implementation-worker, planejadores, revisores e publicador;
• controle de fórmula de escopo local: core.control-dispatcher;
• coordenação guiada: a skill upstream gc.mayor.

Instale o pacote de fluxo de trabalho no escopo da cidade e seu pacote de funções irmão em cada rig que executa trabalho, seguindo os comandos exatos retornados por gc pack registry show main:gascity. Mantenha o namespace gc.* padrão; não aninhe ou renomeie as funções atrás de um pacote AgentOps.

O trabalho entra na cidade através do Prefeito. O solicitante cria UMA conta de intenção de origem com aceitação e então entrega seu id ao Prefeito — o Prefeito decompõe, redige as contas do fluxo de trabalho e despacha. O solicitante nunca executa gc sling sozinho; uma execução iniciada pelo operador contorna o coordenador que gerencia novas tentativas, redespacho e manutenção para esse fluxo de trabalho.

gc bd create "Adicionar um sinalizador --json ao comando export"
gc mail send mayor -s "Compilar ago-XXXX" \
  -m "Decompor e iniciar build-basic para a conta ago-XXXX com push=true open_pr=true." --notify

Ou, em uma sessão interativa do Prefeito:

Use skill gc.mayor

gc sling direto continua sendo uma ferramenta de depuração para uma cidade sem um Prefeito ativo; uma execução iniciada dessa forma não tem coordenador e o operador herda sua manutenção.

As skills do AgentOps são ferramentas disponíveis para esses agentes da fábrica, não um fluxo de trabalho substituto. Nomeie explicitamente uma skill na conta ou prompt quando seu comportamento for necessário. A decomposição upstream atual não propaga automaticamente uma seção Required Skills de forma livre da conta de intenção de origem para cada item de trabalho gerado. Inspecione a decomposição antes da implementação; coloque um nome de skill obrigatório no item de trabalho real ou prompt do worker quando seu uso for uma condição de aceitação. Presença de skill e invocação de skill são fatos diferentes.

Atualizar uma cidade existente para 1.4

Antes de iniciar seu orquestrador, execute uma vez por cidade:

gc doctor --fix
gc import install
gc supervisor stop --wait   # macOS quando um supervisor direto mais antigo permanece
gc start

Em seguida, confirme:

• gc version relata 1.4.0 do caminho pretendido;
• gc doctor não tem falhas de bloqueio;
• cada rig que possui um grafo tem um core.control-dispatcher não suspenso;
• as importações e packs.lock resolvem;
• ao gc check aceita o ambiente de execução de mantenedor contido e os links de skill do AgentOps;
• no macOS, o LaunchAgent do supervisor resolve para o mesmo executável que o binário gc selecionado;
• os marcadores ou proxies reversos do painel autônomo antigo são removidos.

Uma cidade registrada obsoleta pode bloquear todas as inicializações. Repare essa cidade com gc doctor --fix, ou cancele o registro explicitamente se ela estiver intencionalmente aposentada.

Aposente um HQ/canário antigo pelo nome ou caminho registrado exato, sem parar o supervisor de toda a máquina necessário para seu substituto:

gc cities --json
gc stop /caminho/para/cidade-antiga --timeout 45s
gc unregister /caminho/para/cidade-antiga
gc cities --json

unregister falha em vez de aceitar silenciosamente um alvo desconhecido. Preserve o diretório da cidade até que seu estado de Beads seja copiado ou confirmado como descartável. Crie o substituto a partir do modelo Gas City upstream, instale suas importações fixadas e verifique com gc cities --json, gc --city <nova-cidade> status, e gc --city <nova-cidade> doctor --json.

Orquestrando através do Prefeito: o loop de manutenção

Depois de entregar a intenção ao Prefeito, o orquestrador executa cinco verbos. Cada verbo tem um dono; cruzar donos é a classe de falha recorrente que esta seção existe para interromper.

Verbo	Dono	Superfície
Monitorar	orquestrador	$API/runs/census e $API/runs/<id-da-execução> em uma cadência fixa, mais gc mail inbox para respostas do Prefeito. failed > 0 no censo, uma execução em failed/canceled ou e-mail não lido do Prefeito é o sinal de ação; todo o resto é um tique.
Observar	orquestrador	Em um sinal de ação, percorra as camadas de visibilidade na ordem — censo, detalhes da execução, grafo de contas, lista de sessões, verdade do painel — e pare na primeira camada que explica. Não comece pela verdade do painel.
Cutucar	orquestrador, uma vez	Uma conta ready: despache uma vez para seu gc.run_target. Uma conta roteada com uma sessão ativa: gc session wake <run_target> uma vez. Um segundo cutucão no mesmo assunto significa que o diagnóstico está errado — envie um e-mail ao Prefeito.
Redirecionar	Prefeito	Mudanças de prioridade, escopo, cancelamento ou modelo/provedor viajam por e-mail com ids de conta/execução. O orquestrador nunca re-inicia, edita contas de fluxo de trabalho ou corrige uma execução ativa.
Refazer	GC primeiro, depois Prefeito	Descobertas de revisão com falha reentram na execução através de seu loop de correção nativo (review_fix_formula, padrão fix-loop-base); novas tentativas limitadas são loops gc converge. Apenas uma execução TERMINAL failed/canceled — ou uma execução concluída cujo resultado perde a aceitação do solicitante — volta: envie um e-mail ao Prefeito com o id da execução e a evidência de falha para redecomposição e relançamento.

Refazer que o orquestrador realiza manualmente (editando a árvore de trabalho de uma execução com falha, re-iniciando sua fórmula, fechando suas contas) cria um segundo autor não coordenado para a mesma intenção; o relançamento do Prefeito então compete com ele.

Protocolo de travamento

Primeiro classifique a conta.

• Ainda ready: despache-a uma vez para seu gc.run_target e então pare e inspecione.

• Já roteada/em andamento: re-iniciar é um NO-OP. Acorde seu worker proprietário uma vez:

  gc session wake <run_target>
  

Em seguida, capture o painel tmux exato nomeado pelo estado da sessão e execute gc doctor. Nunca repare uma cidade de dentro dessa cidade.

Nunca crie sessões de propriedade de pacote manualmente. gc session new para um agente único ou dimensionado (core.control-dispatcher, workers de função) cria uma sessão com escopo incorreto que ocupa o nome canônico em start-pending e bloqueia o reconciliador de gerar a real — estendendo exatamente o travamento que está sendo reparado. O ciclo de vida da sessão pertence ao reconciliador e ao dimensionamento sob demanda. Quando a própria cidade precisa de manutenção (um reconciliador travado, sessões que nunca saem de draining, religação de modelo ou provedor), envie a solicitação ao Prefeito:

gc mail send mayor -s "<assunto>" -m "<solicitação com ids de conta>" --notify

O pacote upstream pode deixar uma etapa futura vinculada a afinidade atribuída a uma sessão que já confirmou drenagem. Diagnostique isso apenas de fora da cidade:

ao gc recover-affinity --city /caminho/para/cidade --rig /caminho/para/rig

O padrão é uma execução de teste. Se cada atribuição listada estiver correta, repita com --apply. O reparo limitado apenas limpa o responsável em uma conta de fórmula atualmente ready cuja sessão gc.session_affinity=require não está mais ativa. Ele não inicia, tenta novamente, fecha, reinicia ou seleciona trabalho.

Visibilidade: quatro camadas

1. Estado do supervisor/execução — gc dashboard, detalhes da execução, gc status e gc session list --json. O detalhe da execução unifica a escada de estágios, transcrições estruturadas, taxa de tokens e taxa de queima estimada. Uma lista pode ainda relatar ativo enquanto um provedor está travado.

   O status programático da execução vem da API de execução tipada do supervisor — os mesmos dados que o painel renderiza. gc status imprime a base da API; nem gc status --json nem qualquer outro subcomando CLI carrega objetos de execução.

   API="http://127.0.0.1:<porta>/v0/city/<nome-da-cidade>"
   curl -s "$API/runs/<id-da-execução>"   # {run_id, title, status, target, scope, started_at, updated_at}
   curl -s "$API/runs/census"     # {status_counts: {pending, active, completed, failed, canceled}}
   

   Um censo failed > 0 é um sinal de ação. Apenas completed é final para a fábrica; ela ainda pode não atender aos critérios de aceitação do solicitante.

2. Grafo de contas e beads — Cada execução contém um plano de contas e contas de fluxo de trabalho. Contas são os blocos de construção. gc bd list <id-da-execução> mostra a árvore; gc bd show <id-da-conta> mostra o grafo de dependência completo e dados vinculados. Preencha o contexto completo: gc knowledge pull <id-da-execução> torna cada artefato anexado disponível localmente.

   gc bd list <id-da-execução>
   gc bd show <id-da-conta>
   gc knowledge pull <id-da-execução>
   

3. Estado da sessão e do worker — gc session list --json relata a função, fórmula, provedor, modelo, status, tempo de atividade, fila, thread, agentes e atribuições. A habilidade gc.session_affinity controla onde uma conta é executada.

   Uma visão rápida: gc doctor --focus city varre a cidade para obter integridade, conectividade e estado do concorrente. gc doctor --focus rig faz o mesmo por rig. Em caso de travamento, bounded check executa uma varredura de sintoma limitada sem intervenção. O método de diagnóstico de fallback é executar uma verificação de saúde padrão no painel da cidade primeiro, nunca no worker.

   gc doctor --focus city
   

gc doctor --focus rig gc doctor --bounded-check

4. **Verdade do painel** — Apenas o conteúdo do painel que um agente produz durante um único
`wake` ou dispatch é imutável. Todo o outro texto do painel pode ser preterido, irrelevante
ou de uma execução anterior. Para capturar o conteúdo atual do painel de um agente:

```sh
gc session capture <id-da-sessão> /caminho/para/saída

capture extrai o buffer de rolagem do painel nomeado do estado da sessão. O caminho de saída é um diretório que contém um arquivo por painel.