Communitygithub.com

Observer Kit

Um dashboard local e skill de agente para fluxos de trabalho de transformação de dados visíveis e revisáveis.

O que é Observer Kit?

Observer Kit é um skill para agentes de IA (como Codex, Claude, Coder, etc.) que transforma qualquer script de transformação de dados em um fluxo de trabalho gerenciado, supervisionado e recuperável. Ele separa a lógica de negócios do script da orquestração, fornecendo um painel (dashboard) local, um CLI para repetibilidade e um watcher que transporta mensagens do operador de volta à sessão ativa do agente. O sistema garante duas propriedades fundamentais: *liveness* (eventos JSONL avançam em tempo real durante a execução) e *durabilidade* (resultados concluídos são persistidos em um armazenamento durável que permite retomada após interrupções). Os casos de uso típicos incluem escrever ou adaptar workflows de produção, responder a execuções em andamento ou modificar o próprio Observer Kit. O skill impõe contratos como bloqueio de fonte, manifesto de execução, dry-run obrigatório, limites de gastos, verificação de controles do dashboard e checkpoints duráveis, garantindo que cada execução seja visível, auditável e segura.

Funciona com✓Claude Code✓Codex CLI~Cursor
npx skills add edsmkt/observer-kit

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Observer Kit faz?

Use o Observer Kit como uma estrutura de workflow local. A sessão atual do Codex, Claude, Pi, Command Code, Goose ou outro agente continua sendo o cérebro. O skill fornece o julgamento, a CLI fornece a tubulação repetível, o script executa o trabalho e o watcher transporta as mensagens do operador de volta para a sessão ativa.

Construa cada execução em torno de duas garantias separadas:

  • Liveness: Eventos JSONL avançam enquanto o trabalho acontece, então o painel permanece atual.
  • Durabilidade: Resultados concluídos alcançam um destino legível novamente em um limite durável, de modo que uma reinicialização continue a partir do trabalho salvo.

1. Carregue o Contexto Correto

Resolva caminhos relativos a partir do diretório que contém este SKILL.md.

Leia o README do Observer Kit do primeiro local disponível:

Use-o para aprender a promessa do produto, a divisão skill/CLI, a jornada do operador e as expectativas do painel.

Escolha o branch ativo e carregue sua referência:

  • Escrever ou adaptar um workflow de produção: leia references/pattern.md na íntegra. É a fonte única de verdade para identidade da fonte, linhas, limites duráveis, gravações externas, pistas de execução, controles, watchers, concorrência e eventos do painel.
  • Responder a um workflow em execução: leia as seções de pista de execução, controles, watcher e recuperação de references/pattern.md, depois inspecione o JSONL atual, o destino durável, o estado do processo e o script.
  • Alterar o próprio Observer Kit: leia references/build-guide.md e, em seguida, execute a suíte de aceitação completa após a alteração.

Leia o script de destino e sua configuração antes de projetar a estrutura.

Completo quando: você pode informar qual branch está ativo, o que o usuário espera supervisionar e quais arquivos definem a implementação.

2. Mapeie o Workflow Real

Trace o script da entrada ao destino e registre:

  • a identidade imutável da fonte: caminho resolvido, ID da planilha, tabela mais consulta, ID de exportação ou equivalente;
  • a chave estável para cada entidade fonte e cada entidade derivada;
  • cada loop lento, pool, página, nova tentativa, chamada de provedor e preenchimento de cache;
  • cada mutação de destino e seu sinal de confirmação;
  • o armazenamento durável que a retomada lê;
  • os limites de gasto, escrita, taxa, política e qualidade;
  • a pista de execução solicitada: atualizar a visualização atual ou criar uma visualização separada.

Preserve a lógica de negócios e a CLI do script enquanto coloca a estrutura nesses caminhos de execução reais.

Completo quando: cada gasto e mutação pertence a um loop, fonte, chave estável, armazenamento durável, destino e limite mapeados.

3. Proponha a Visualização do Operador

Proponha uma forma compacta de painel antes de conectar os registros:

  • tabelas e chaves estáveis;
  • campos de fonte, transformação, raciocínio, resultado, destino e erro;
  • a tabela fonte usada para progresso;
  • três a cinco métricas principais escolhidas para este workflow;
  • um tamanho de amostra representativo de execução simulada, geralmente 5 a 25 linhas;
  • se o enriquecimento posterior atualiza essas linhas ou abre uma pista de comparação.

Convide o usuário a confirmar ou editar a proposta. Defina erro como uma mensagem concisa para uma linha que precisa de atenção humana; uma nova tentativa bem-sucedida emite erro='' com a linha atualizada para que a visualização de Atenção reflita o estado atual da linha.

Completo quando: o usuário pode visualizar as tabelas, colunas, contadores, amostra e pista antes do início da execução.

4. Conecte a Estrutura

Use start_observed_run() ao redor do trabalho real e passe os valores reais de fonte=, dry_run, descrição, tarefas, tabela_progresso e métricas_resumo concisas.

Aplique os contratos de produção de references/pattern.md:

  1. Adquira o bloqueio derivado da fonte antes do primeiro gasto ou mutação.
  2. Registre o snapshot de entrada, a identidade do script/configuração, o destino e a versão da transformação no manifesto.
  3. Exija --dry-run mais um limite de amostra e torne --full-run intencional.
  4. Emita cada entidade com valores estáveis de tabela= e chave= do loop ou callback de conclusão onde seu trabalho termina.
  5. Use a ordem do limite durável: execute o trabalho, persista o resultado real, emita a linha e, em seguida, faça checkpoint da chave ou bloco concluído.
  6. Envolva cada entrega externa com validação, verificações de política, intenção de escrita, chamada de sink confirmada e recibo de escrita. Atualize o campo de destino da mesma linha de negócios de pendente para seu resultado confirmado.
  7. Verifique os controles do painel nos limites do loop e após escritas concluídas.
  8. Acompanhe contas de provedor compartilhadas com throttle() e aplique limites rígidos de gasto/escrita no código.

Para um pipeline em lote por fases, persista cada item finalizado ou bloco limitado assim que essa fase produzir saída autoritativa. A retomada lê esse mesmo armazenamento e seleciona o trabalho restante.

Quando uma unidade limitada usa paginação interna, mantenha o acumulador com escopo nessa unidade e persista-o imediatamente após sua página final, antes que a próxima unidade comece. A reprodução na inicialização pode reconstruir mapas de trabalho a partir deste armazenamento durável; essa leitura restaura o trabalho concluído e preserva o checkpoint existente.

Completo quando: interromper o processo uma linha antes de sua declaração final perde no máximo o item ativo ou bloco limitado, e a retomada seleciona o trabalho restante enquanto preserva gastos e escritas confirmados.

5. Prove a Amostra

Inicie o painel de longa duração antes da amostra para que o usuário veja as linhas chegarem:

observer-kit init .
observer-kit dashboard .runguard
observer-kit run --state-dir .runguard -- python3 workflow.py --dry-run --limit 10

Execute a verificação estática de emissão/durabilidade a partir do diretório do skill:

python3 references/lint_emit.py /caminho/absoluto/para/workflow.py

Execute a amostra real e verifique todas as seguintes superfícies:

  • Os eventos JSONL e as linhas do painel avançam durante cada fase lenta;
  • o armazenamento de resultados durável avança com o trabalho concluído;
  • as chaves estáveis atualizam linhas existentes e retêm campos anteriores;
  • os recibos de destino correspondem ao estado real do destino;
  • uma falha forçada no meio da amostra é retomada na mesma pista a partir do trabalho salvo;
  • uma inicialização simultânea na mesma fonte recebe o aviso de execução duplicada;
  • pausa ou parada atinge um checkpoint do script, registra o reconhecimento e abre um canal para o contexto do operador;
  • o painel permanece utilizável enquanto os registros chegam, incluindo posição de rolagem, filtros, linha do tempo, contadores e linhas de Atenção.

Resuma as escritas planejadas, pulos, erros, descobertas de esquema, gasto estimado e o limite de reinicialização observado.

Completo quando: o linter sai com zero, cada verificação acima tem evidência direta e o usuário revisou o painel de amostra.

6. Execute Após Aprovação Explícita

Peça confirmação explícita após apresentar o resumo da amostra. Inicie o conjunto de dados completo através do sinalizador intencional de execução completa após a aprovação.

Mantenha um servidor de painel conectado ao diretório de estado. Deixe observer-kit run anexar a ele e iniciar o watcher com escopo de execução, ou mantenha um watcher de todas as execuções para um projeto de longa duração:

observer-kit watch .runguard --all --follow
observer-kit run --state-dir .runguard -- python3 workflow.py --full-run

Trate a saída do watcher como transporte para a sessão atual do agente. Inspecione o script, JSONL, sink durável e destino antes de responder ou alterar a execução.

Completo quando: a execução completa tem aprovação explícita do operador, monitoramento ao vivo, um evento de razão terminal, recibos reconciliados e um resumo conciso do resultado.

7. Adapte ou Recupere de Forma Deliberada

Use a mesma fonte, pista, tabela e chave para tentar novamente uma falha, corrigir o script ou adicionar enriquecimento às linhas já mostradas. Anexe campos atualizados para que o painel retenha o histórico e apresente o estado mais recente da linha.

Use um novo nome de sessão estável ou --session auto para um refazer limpo, comparação ou lote genuinamente separado. Execute fontes paralelas quando seus registros forem comprovadamente disjuntos; use o acelerador de provedor compartilhado entre essas execuções.

Quando existir uma escrita pendente, reconcilie o destino e anexe o recibo correspondente antes de continuar. Quando existir um bloqueio de fonte ativo, aguarde esse processo ou pare deliberadamente o PID nomeado antes de começar do zero.

Completo quando: as novas tentativas reutilizam o estado durável autoritativo, as alterações da linha atual aparecem no lugar e o trabalho intencionalmente separado aparece em sua própria visualização do painel.

Mapa de Referência

  • references/pattern.md: contrato de integração e operação de produção; leia na íntegra para design e adaptação de workflow.
  • references/lint_emit.py: verificação estática para descargas finais e progresso combinado com resultados armazenados em buffer de memória; execute antes de cada conjunto de dados completo.
  • references/build-guide.md: núcleo do Observer Kit, painel, empacotamento e contrato de teste de aceitação.
  • runguard.py: runtime incluído usado pelo script do workflow.
  • run_dashboard.py: servidor de painel localhost para um diretório de estado.
  • watch_chat.py: transporte de mensagens do painel para a estrutura ativa do agente.
  • EXPLAIN.md: declaração de intenção específica do projeto mostrada ao operador.

Execute observer-kit doctor . após a configuração do projeto. Execute observer-kit test após alterar o runtime, CLI, linter, watcher ou painel do Observer Kit.

Habilidades Relacionadas