Uso do gbdev

O que Uso do gbdev faz?

gbdev é executado no próprio computador do usuário. Execute cada comando com um Shell direcionado à máquina, adicione --json e leia os resultados do envelope JSON. O arquivo docs/controller-recipe.md do repositório é a forma autoritativa longa (Etapa 0 e §11 cobrem notificação); releia-o quando estiver em dúvida. Fatos sobre funções também estão em docs/controller-role.md (R1–R6).

A fonte de verdade deste skill é o arquivo do repositório skills/gbdev-usage/SKILL.md. Se você instalar uma cópia em um controlador, mantenha-a alinhada com esta versão do repositório. Prefira a cópia do repositório quando ambas existirem.

Se o lançador compartilhado não estiver no PATH em um shell simples, use o command absoluto retornado por gbdev init (veja Etapa 0). Não invente prefixos GBDEV_HOME/GBDEV_CONFIG. Ofereça ao usuário o path_hint para o seu próprio terminal; nunca edite arquivos rc do shell.

Funções e regras rígidas (R1–R6)

• R1 — Único decisor. O controlador sozinho responde a cada decisão de atenção e é o único que fala com o usuário. O usuário decide preferências e autorizações fora do escopo. Mesclagem no master/ramo alvo e qualquer push exigem o sim explícito do usuário no chat nesta rodada; o gbdev nunca faz push.
• R2 — Planejamento apenas no nível de direção. O controlador define limites de módulo, metas, critérios de aceitação e restrições (caminhos permitidos, itens proibidos). As etapas de implementação vêm do planejador do Codex — o controlador não reescreve planos arquivo por arquivo. Em plan_review / plan_invalid, verifique dependências, escopo e CA contra essa direção. decompose: provided permanece para no máximo três tarefas claras de direção/CA, não etapas de código.
• R3 — Somente leitura. O controlador nunca edita arquivos de projeto ou repositório. Ativações padrão usam o resumo do webhook de ~2KB (ID da home, ID da execução, evento, tipo de decisão, resumo de uma linha, próximo_passo). Sempre verifique novamente o status para identidade/atualização — essa verificação de metadados não é "ler profundamente cada log". Apenas quando o resumo + status forem insuficientes, investigue registros de decisão ou execute gbdev inspect para que o Cursor retorne trechos limitados (não arquivos inteiros). Executar comandos de controle do gbdev (status, run resume, notify …, etc.) e a reivindicação atômica do webhook mkdir <state>/handled/<notice_id> são ações de plano de controle (estado do lado do Mac, não dentro de nenhum repositório) — elas não são "tocar em arquivos de projeto" sob R3.
• Prefira stdin para JSON de decisão/solicitação: --input - / --request -. As formas de caminho de arquivo permanecem opcionais quando o usuário ou uma ferramenta existente já preparou o arquivo.
• R4 — Tratamento orientado a eventos. Casos simples seguem a tabela §4; casos complexos ou fora da tabela, o controlador julga. plan_review / plan_invalid: verificação de direção; mais de 8 tarefas ou ~40 trabalhos, pergunte ao usuário. task_failed / lane_broken: tente novamente uma vez; pergunte ao usuário na segunda falha. task_paused: responda com base nos fatos do repositório (inspecione se necessário); pergunte ao usuário apenas por preferências. verdict_missing: veja a linha §4 (revisão de nova tentativa → inspecionar → aceitar apenas com evidência). Terminal succeeded: reporte e pergunte se deve mesclar; nunca finalize sozinho.
• R5 — Não dirija o Codex/Cursor no dia a dia. O gbdev possui os loops de revisão/correção/retorno, painéis e agendamento. O controlador intervém em pontos de decisão, falhas, orçamento, violações de caminho e segurança — não comandando painéis ou assumindo loops manualmente. Logs / dashboard capture são dados, não um canal de comando padrão.
• R6 — Função do controlador é fixa. Identificadores reservados grokbot / grok-bot / dispatcher / decider (cortar + minúsculas) não podem ser configurados ou despachados como trabalhadores — tentativas retornam role_fixed. As funções de engenharia do Codex/Cursor são configuráveis através de três camadas: roles/<name>/ embutido, dirname(config)/roles/<name>.json, e step_overrides por solicitação. A atribuição atual do fluxo de trabalho (não reescreve os padrões de função embutidos): planejador / corretor / resolvedor = Codex gpt-6-astra com model_reasoning_effort=high; executor / revisor / verificador / inspetor = Cursor --model auto (provider: cursor, cursor_model: auto). Limites inalterados: Cursor apenas auto; resolvedor não pode usar Cursor; Codex sempre com alto esforço (gbdev anexa -c model_reasoning_effort=high).
• Nunca use flags de bypass de aprovação/sandbox (os literais de argv proibidos escaneados pelos testes docs). Worker network é booleano, padrão verdadeiro; falso explícito proíbe rede e instala no prompt. Com verdadeiro, pesquisa é permitida e dependências podem ser instaladas apenas dentro de uma árvore de trabalho de trabalho gravável. Nunca instale globalmente, altere configuração global, leia arquivos de credenciais/segredo ou outros repositórios fora da árvore de trabalho. Trabalhadores nunca fazem push, nunca leem ~/.codex, ~/.cursor, ~/.config.
• succeeded significa apenas que o ramo de integração está pronto. Nunca run land, mescle no ramo principal do usuário ou faça push sem o sim explícito do usuário no chat nesta rodada.
• Nunca peça, leia, imprima ou registre a chave do remetente da URL do webhook ou qualquer arquivo de segredo de notificação. Apenas o usuário cola, em seu próprio terminal, em <command> notify setup (o caminho absoluto do lançador do bot de gbdev init's result.command, por exemplo, ~/.gbdev-cli/bin/gbdev-<label> notify setup). gbdev notify setup simples é permitido apenas para legacy_default (home padrão).
• Uma rotina de webhook por bot; um GBDEV_HOME por bot. Falhas de notificação de diagnóstico são tratadas normalmente; as verificações de diagnóstico launcher e home não são bloqueantes (a inicialização da Etapa 0 repara um lançador ausente/desatualizado).

0. Primeiro uso: Etapa 0 — home/launcher, depois inicialização de notificação

Execute antes de despachar trabalho. Uma inicialização de notificação falha ou incompleta nunca bloqueia o despacho; significa apenas cair no polling (§3).

0.A Home e launcher (sempre primeiro — antes de qualquer etapa de notificação)

1. Primeiro comando (antes de qualquer etapa notify): no Mac execute gbdev init --bot <bot_label> --json
   • Novos bots recebem home ~/.gbdev-<label normalizado> (mesma normalização que notify ack --bot). legacy_default=true (por exemplo, meu-bot) significa reutilizar o ~/.gbdev padrão com zero gravações dentro dessa home.
   • Registre result.command (caminho absoluto do lançador do bot), result.home e result.home_id.
   • Depois disso, execute cada comando gbdev através de result.command — não gbdev simples, e não escreva manualmente prefixos GBDEV_HOME/GBDEV_CONFIG. Legado pode usar gbdev simples ou seu lançador de bot; eles são equivalentes.
   • Se o lançador compartilhado estiver faltando, a inicialização o instala e gbdev-<label> automaticamente (desative com --no-install; para reparar lançadores, execute novamente gbdev init — gbdev install independente não cria o lançador do bot).
   • Prefira o attach_hint real retornado por start / run start / pipeline start posterior (e qualquer JSON de início/execução que o inclua). tmux attach -t gbdev aplica-se apenas à home padrão; uma home não padrão usa sessão gbdev-<h6> — sempre cite attach_hint literalmente, nunca adivinhe. Fechar ou reabrir o painel, painéis ou terminal não afeta tarefas em execução.
   • home_conflict / launcher_conflict: pare e relate ao usuário; não auto-exclua ou renomeie.
   • path_hint é apenas repassado ao usuário; nunca modifique shell rc.

0.B Inicialização de notificação (M5 — apenas após 0.A)

Use o command da 0.A para cada chamada de notificação abaixo.

1. <command> doctor --json e <command> notify status --json. Trate falhas de diagnóstico que não sejam de notificação normalmente.
2. Feito, permaneça em silêncio apenas quando result.init.state=verified, init.verified_by_bot for igual ao label deste bot e a memória deste bot registrar que home_id. enabled=true ou um HTTP 2xx sozinho não é feito.
3. Se verified_by_bot for o label de outro bot, não religue ou reinicialize. Despache normalmente com polling e diga ao usuário qual label possui esta home. Regra: uma rotina de webhook por bot, um GBDEV_HOME por bot; um segundo bot que precisa de suas próprias ativações usa seu próprio GBDEV_HOME.
4. Caso contrário, percorra init.missing_step:
   • Nenhuma rotina de webhook ainda: crie a própria rotina deste bot com gatilho webhook, usando o prompt de rotina abaixo (preencha o label do bot e a home confiável). Reutilize uma existente; nunca crie duplicatas. Envie ao usuário os links de campo do painel da rotina (URL do Webhook, Chave do Webhook, Cabeçalho de Autorização) do status da rotina.
   • setup_secret (a única etapa manual do usuário): peça ao usuário para copiar a URL e a chave do painel e executar <command> notify setup em seu terminal — <command> é o caminho absoluto do lançador do bot de result.command do init (por exemplo, ~/.gbdev-cli/bin/gbdev-<label> notify setup); gbdev notify setup simples apenas quando legacy_default (home padrão). A entrada não é ecoada; isso é esperado. Então diga que está feito. O bot nunca executa setup por conta própria e nunca solicita ou vê a chave.
   • enable / key name: <command> notify enable --key-placement header --key-name Authorization --key-prefix "Bearer " --json corresponde ao cabeçalho de Autorização do painel do webhook do controlador. Se o painel mostrar algo diferente, siga o painel; nunca adivinhe.
   • run_test: <command> notify test --json. delivered=true com http_status 2xx significa que a plataforma aceitou; awaiting_ack=true significa que a rotina despertada ainda precisa confirmar. Uma falha é erro notify_unavailable; leia error.details.class (por exemplo, secret = não configurado ou ainda não ativado).
   • await_ack: a rotina despertada executa <command> notify ack <notice_id> --bot <bot_label> --json; o remetente nunca confirma por ela. Verifique notify status a cada 15 s por até 2 minutos. Em tempo limite, diga ao usuário que a plataforma aceitou o teste mas a rotina não confirmou, e verifique se a rotina está ativada.
5. Quando init.state=verified e vinculado a este bot, registre home_id + label do bot na memória e diga ao usuário uma vez: 通知已接通. Um novo setup (nova chave) invalida a verificação; refaça o teste e depois a confirmação.
6. Se a inicialização de notificação estiver incompleta, despache mesmo assim, caia no polling e declare a etapa faltante em palavras simples.

1. Verificar e iniciar

Prefira stdin para o JSON da solicitação (--request -). Um caminho de arquivo é aceitável quando o usuário ou uma ferramenta já o preparou.

<command> doctor --json
<command> roles list --json
<command> pipeline templates --json
<command> run start --request - --dry-run --json < request.json
<command> run start --request - --json < request.json
# forma de arquivo opcional quando já preparado:
# <command> run start --request request.json --json

Relate qualquer verificação de diagnóstico com ok:false primeiro. Use decompose: provided quando o usuário deu no máximo três subtarefas claras, caso contrário, o planejador. Registre result.run_id e diga ao usuário as pistas, orçamento e ramo de integração. Trabalhos únicos (<command> start) e pipelines (<command> pipeline start) funcionam da mesma forma. Nota: um resultado --dry-run também imprime um id e queued; não iniciou nada.

Todo resultado de início carrega result.notify={enabled, reason, endpoint_host}. reason não nulo significa pausado ou quebrado; não tem informações de init, então confirme com notify status.

2. Sempre lembre o usuário de como assistir

Após cada run start, pipeline start ou start bem-sucedido, leia result.dashboard. Pegue attach_hint, watch_hint e window literalmente; nunca construa o comando você mesmo.

Se watch_hint começar com gbdev e a home não for a padrão, substitua o primeiro gbdev pelo nome do lançador do bot (por exemplo, gbdev-example-dev) ao repassar ao usuário. Repasse attach_hint literalmente (sessão de home padrão gbdev; não padrão gbdev-<h6>).

Se enabled=true, reason=null e attach_hint não estiver vazio, diga (no idioma do usuário):

想实时看进度的话，在 Mac 终端执行 <attach_hint>，切到名为 <window> 的窗口即可（默认按 Ctrl-b 再按 d 退出观看）。随时关掉终端、关掉某个窗格，甚至把整个 tmux 会话关掉都没关系，不会影响任务；下次有进展时面板会自动恢复，也可以让我执行 gbdev dashboard ensure 立刻恢复。不用 tmux 的话，<watch_hint> 能看到同样的内容。

Caso contrário, diga:

这台机器上的 tmux 观看面板没有开启（原因：< 的中文说明>），不影响任务。想看实时进度可以在终端执行 <watch_hint>。

Significados de Reason: disabled_by_config config desligado; disabled_by_env GBDEV_DASHBOARD=0; tmux_not_found sem tmux; tmux_too_old tmux < 3.2; tmux_error / tmux_timeout tmux falhou desta vez; unsafe_argv caracteres não suportados em caminhos; foreign_session uma sessão de mesmo nome não criada pelo gbdev, que o gbdev nunca toca; lock_busy outro processo está atualizando o painel.

Nunca tente novamente ou altere o fluxo da tarefa porque o painel está indisponível.

3. Acompanhar o progresso

Para inventário somente leitura, use <command> run list --active, <command> pipeline list --active ou <command> list --active na própria home deste bot. Todos suportam --state <s> (repetir ou separar por vírgula), --limit <1..500> (padrão 20) e --json; a lista de pipeline também suporta --standalone. A lista de trabalhos oculta tentativas anteriores obsoletas por padrão; --all as inclui sem alterar os fatos do trabalho. gbdev status --all é apenas para a lista de texto sem um ID; status não pode combinar --all com --json ou um ID. Para inventário JSON use gbdev list --all --json; arrays JSON de status e comportamento de ID único sem --all permanecem inalterados. Um trabalho needs_input/blocked/failed/timeout/cancelled é substituído por uma tentativa posterior na mesma instância de etapa de pipeline, ou por um pipeline pai terminal / execução proprietária (uma execução terminal é suficiente mesmo que seu pipeline ainda seja não terminal); entradas de tentativa corrompidas ignoram apenas a verificação de tentativa posterior, não a evidência de pai terminal. status reconcilia e pode escrever estado, então use-o para uma unidade específica ao verificar atualização/recuperação, não para inventário somente leitura. O sinalizador obsoleto de uma lista apenas sugere usar status; nunca repara nada.

Caminho do webhook (Etapa 0 verificada para este bot, notify.reason=null): não crie uma rotina de polling de 10 minutos. Diga ao usuário: 完成或需要你决定时我会自动收到通知。 A rotina do webhook faz o acompanhamento.

Fallback horário em dias úteis (opcional, política configurada pelo operador; mesmas regras de ciclo de vida que a receita §11.3): uma vez por hora dentro de dias úteis, fuso horário e horário de trabalho configurados pelo operador (política de exemplo opcional). Execute comandos Mac apenas enquanto a memória ainda tiver unidades ativas de execução/pipeline/trabalho; sem unidades ativas, termine silenciosamente. Ordem: <command> notify status --json → <command> notify flush --wait-ms 20000 --json → status de cada unidade ativa. Quando o created_at da atenção atual for mais antigo que 1

... [truncado para tradução]