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:
- checkout do repositório:
../../README.md - instalação independente:
github.com/edsmkt/observer-kit/README.md
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.mdna í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.mde, 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:
- Adquira o bloqueio derivado da fonte antes do primeiro gasto ou mutação.
- Registre o snapshot de entrada, a identidade do script/configuração, o destino e a versão da transformação no manifesto.
- Exija
--dry-runmais um limite de amostra e torne--full-runintencional. - Emita cada entidade com valores estáveis de
tabela=echave=do loop ou callback de conclusão onde seu trabalho termina. - 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.
- 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
pendentepara seu resultado confirmado. - Verifique os controles do painel nos limites do loop e após escritas concluídas.
- 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.