Communitygithub.com

Observer Kit

Un panel de control local y habilidad para agentes que permite flujos de trabajo de transformación de datos visibles y revisables.

¿Qué es Observer Kit?

Observer Kit es una habilidad para agentes de IA (compatible con Codex, Claude, Pi, Command Code, Goose y otros) que transforma cualquier flujo de trabajo de transformación de datos en un proceso local observable y duradero. Combina un panel de control en vivo con un sistema de registro basado en JSONL, garantizando que cada operación sea visible (liveness) y que los resultados se conserven incluso si el agente se reinicia (durability). La habilidad guía al usuario paso a paso: desde cargar el contexto correcto hasta mapear el flujo de trabajo real, proponer una vista de operador, cablear el harness, probar con una muestra y ejecutar la versión completa solo después de aprobación explícita. También incluye mecanismos de recuperación ante fallos, control de concurrencia, límites de gasto/escritura y una interfaz de panel que permite al operador supervisar filas, métricas y errores en tiempo real.

Compatible con✓Claude Code✓Codex CLI~Cursor
npx skills add edsmkt/observer-kit

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace Observer Kit?

Usa Observer Kit como un arnés de flujo de trabajo local. La sesión actual del agente (Codex, Claude, Pi, Command Code, Goose u otro) sigue siendo el cerebro. La habilidad proporciona juicio, la CLI proporciona tuberías repetibles, el script realiza el trabajo y el vigilante transporta los mensajes del operador de vuelta a la sesión activa.

Construye cada ejecución basándote en dos garantías separadas:

  • Actividad (Liveness): Los eventos JSONL avanzan mientras el trabajo se realiza, por lo que el panel se mantiene actualizado.
  • Durabilidad: Los resultados completados llegan a un sumidero re-legible en un límite duradero, por lo que un reinicio continúa desde el trabajo guardado.

1. Cargar el Contexto Correcto

Resuelve las rutas relativas desde el directorio que contiene este SKILL.md.

Lee el README de Observer Kit desde la primera ubicación disponible:

Úsalo para conocer la promesa del producto, la división habilidad/CLI, el recorrido del operador y las expectativas del panel.

Elige la rama activa y carga su referencia:

  • Escribir o adaptar un flujo de trabajo de producción: lee references/pattern.md en su totalidad. Es la única fuente de verdad para la identidad de la fuente, filas, límites duraderos, escrituras externas, carriles de ejecución, controles, vigilantes, concurrencia y eventos del panel.
  • Responder a un flujo de trabajo en ejecución: lee las secciones de carril de ejecución, controles, vigilante y recuperación de references/pattern.md, luego inspecciona el JSONL actual, el destino duradero, el estado del proceso y el script.
  • Cambiar Observer Kit en sí mismo: lee references/build-guide.md, luego ejecuta la suite de aceptación completa después del cambio.

Lee el script objetivo y su configuración antes de diseñar el arnés.

Completado cuando: puedas indicar qué rama está activa, qué espera supervisar el usuario y qué archivos definen la implementación.

2. Mapear el Flujo de Trabajo Real

Traza el script desde la entrada hasta el destino y registra:

  • la identidad inmutable de la fuente: ruta resuelta, ID de hoja, tabla más consulta, ID de exportación o equivalente;
  • la clave estable para cada entidad fuente y cada entidad derivada;
  • cada bucle lento, grupo, página, reintento, llamada a proveedor y llenado de caché;
  • cada mutación de destino y su señal de confirmación;
  • el almacén duradero que lee la reanudación;
  • los límites de gasto, escritura, tasa, política y calidad;
  • el carril de ejecución solicitado: actualizar la vista actual o crear una vista separada.

Preserva la lógica de negocio funcional y la CLI del script mientras colocas el arnés en estas rutas de ejecución reales.

Completado cuando: cada gasto y mutación pertenece a un bucle, fuente, clave estable, almacén duradero, destino y límite mapeados.

3. Proponer la Vista del Operador

Propón una forma compacta de panel antes de cablear los registros:

  • tablas y claves estables;
  • campos de fuente, transformación, razonamiento, resultado, destino y error;
  • la tabla fuente utilizada para el progreso;
  • de tres a cinco métricas principales elegidas para este flujo de trabajo;
  • un tamaño de muestra representativo para prueba en seco, normalmente de 5 a 25 filas;
  • si un enriquecimiento posterior actualizará estas filas o abrirá un carril de comparación.

Invita al usuario a confirmar o editar la propuesta. Establece error como un mensaje conciso para una fila que necesita atención humana; un reintento exitoso emite error='' con la fila actualizada para que la vista de Atención refleje el estado actual de la fila.

Completado cuando: el usuario pueda visualizar las tablas, columnas, contadores, muestra y carril antes de que comience la ejecución.

4. Cablear el Arnés

Usa start_observed_run() alrededor del trabajo real y pasa los valores reales de source=, dry_run, description, todo, progress_table y summary_metrics concisos.

Aplica los contratos de producción de references/pattern.md:

  1. Adquiere el bloqueo derivado de la fuente antes del primer gasto o mutación.
  2. Registra la instantánea de entrada, la identidad del script/configuración, el destino y la versión de transformación en el manifiesto.
  3. Exige --dry-run más un límite de muestra y haz que --full-run sea intencional.
  4. Emite cada entidad con valores estables de table= y key= desde el bucle o callback de finalización donde aterriza su trabajo.
  5. Usa el orden de límite duradero: realiza el trabajo, persiste el resultado real, emite la fila, luego marca el punto de control de la clave o fragmento completado.
  6. Envuelve cada entrega externa con validación, verificaciones de política, intención de escritura, llamada de sumidero confirmada y recibo de escritura. Actualiza el campo de destino de la misma fila de negocio de pendiente a su resultado confirmado.
  7. Verifica los controles del panel en los límites del bucle y después de las escrituras completadas.
  8. Regula las cuentas de proveedor compartidas con throttle() y aplica límites estrictos de gasto/escritura en el código.

Para un pipeline por lotes por fases, persiste cada elemento finalizado o fragmento delimitado tan pronto como esa fase produce una salida autorizada. La reanudación lee ese mismo almacén y selecciona el trabajo restante.

Cuando una unidad delimitada usa paginación interna, mantén el acumulador dentro del ámbito de esa unidad y persístelo inmediatamente después de su página final, antes de que comience la siguiente unidad. La reproducción al inicio puede reconstruir mapas de trabajo a partir de este almacén duradero; esa lectura restaura el trabajo completado y conserva el punto de control existente.

Completado cuando: detener el proceso una línea antes de su declaración final pierde como máximo el elemento activo o fragmento delimitado, y la reanudación selecciona el trabajo restante mientras preserva el gasto y las escrituras confirmados.

5. Probar la Muestra

Inicia el panel de larga duración antes de la muestra para que el usuario vea llegar las filas:

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

Ejecuta la verificación estática de emisión/durabilidad desde el directorio de la habilidad:

python3 references/lint_emit.py /ruta/absoluta/hacia/workflow.py

Ejercita la muestra real y verifica todas estas superficies:

  • Los eventos JSONL y las filas del panel avanzan durante cada fase lenta;
  • el almacén de resultados duradero avanza con el trabajo completado;
  • las claves estables actualizan las filas existentes y retienen campos anteriores;
  • los recibos de destino coinciden con el estado real del destino;
  • un fallo forzado a mitad de la muestra se reanuda en el mismo carril desde el trabajo guardado;
  • un inicio simultáneo en la misma fuente recibe la advertencia de ejecución duplicada;
  • pausa o detención alcanza un punto de control del script, registra el acuse de recibo y abre un canal para el contexto del operador;
  • el panel sigue siendo utilizable mientras llegan los registros, incluida la posición de desplazamiento, filtros, línea de tiempo, contadores y filas de Atención.

Resume las escrituras planificadas, saltos, errores, hallazgos de esquema, gasto estimado y el límite de reinicio observado.

Completado cuando: el linter sale con cero, cada verificación anterior tiene evidencia directa y el usuario ha revisado el panel de muestra.

6. Ejecutar después de Aprobación Explícita

Pide confirmación explícita después de presentar el resumen de la muestra. Comienza el conjunto de datos completo a través del indicador intencional de ejecución completa después de la aprobación.

Mantén un servidor de panel conectado al directorio de estado. Deja que observer-kit run se conecte a él e inicie el vigilante del ámbito de ejecución, o mantén un vigilante para todas las ejecuciones en un proyecto de larga duración:

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

Trata la salida del vigilante como transporte hacia la sesión activa del agente. Inspecciona el script, el JSONL, el sumidero duradero y el destino antes de responder o cambiar la ejecución.

Completado cuando: la ejecución completa tiene una aprobación explícita del operador, monitoreo en vivo, un evento de libro mayor terminal, recibos conciliados y un resumen de resultado conciso.

7. Adaptar o Recuperar de Forma Deliberada

Usa la misma fuente, carril, tabla y clave para reintentar un fallo, corregir el script o agregar enriquecimiento a filas ya mostradas. Agrega campos actualizados para que el panel retenga el historial y presente el estado más reciente de la fila.

Usa un nuevo nombre de sesión estable o --session auto para una rehacer limpio, comparación o lote genuinamente separado. Ejecuta fuentes en paralelo cuando sus registros sean demostrablemente disjuntos; usa la regulación de proveedor compartido entre esas ejecuciones.

Cuando exista una escritura pendiente, concilia el destino y agrega el recibo correspondiente antes de continuar. Cuando exista un bloqueo de fuente activo, espera a ese proceso o detén deliberadamente el PID nombrado antes de comenzar de nuevo.

Completado cuando: los reintentos reutilizan el estado duradero autoritativo, los cambios de la fila actual aparecen en su lugar y el trabajo intencionalmente separado aparece en su propia vista del panel.

Mapa de Referencia

  • references/pattern.md: contrato de integración y operación de producción; léelo completo para el diseño y adaptación del flujo de trabajo.
  • references/lint_emit.py: verificación estática para vaciados finales y progreso emparejado con resultados almacenados en búfer de memoria; ejecútalo antes de cada conjunto de datos completo.
  • references/build-guide.md: núcleo de Observer Kit, panel, empaquetado y contrato de prueba de aceptación.
  • runguard.py: tiempo de ejecución integrado utilizado por el script de flujo de trabajo.
  • run_dashboard.py: servidor de panel localhost para un directorio de estado.
  • watch_chat.py: transporte de mensajes del panel para el arnés del agente activo.
  • EXPLAIN.md: declaración de intención específica del proyecto mostrada al operador.

Ejecuta observer-kit doctor . después de la configuración del proyecto. Ejecuta observer-kit test después de cambiar el tiempo de ejecución, la CLI, el linter, el vigilante o el panel de Observer Kit.

Skills relacionados