Communitygithub.com

Observer Kit – Lokales Dashboard & Agenten-Skill

Ein lokales Dashboard und Agenten-Skill für sichtbare, überprüfbare Datentransformations-Workflows.

Was ist Observer Kit – Lokales Dashboard & Agenten-Skill?

Observer Kit ist ein Agenten-Skill und lokales Dashboard, das Datenarbeits-Workflows sichtbar, überprüfbar und wiederherstellbar macht. Es eignet sich für Codex, Claude Code, Goose, Command Code und andere agentische Umgebungen, indem es dem Agenten ein strukturiertes Arbeitsmodell vorgibt, das aus einem CLI, einem Skript und einem Beobachter besteht. Der Skill stellt sicher, dass jeder Durchlauf zwei Garantien einhält: Liveness durch JSONL-Ereignisse, die während der Arbeit aktualisiert werden, und Dauerhaftigkeit durch persistierte Ergebnisse, die auch nach einem Neustart wieder verwendbar sind. Observer Kit unterstützt die vollständige Workflow-Planung, -Ausführung, -Überwachung und -Wiederherstellung und ist damit ideal für Produktions- und Ad-hoc-Workflows, bei denen Transparenz und Wiederaufsetzbarkeit entscheidend sind.

Funktioniert mit✓Claude Code✓Codex CLI~Cursor
npx skills add edsmkt/observer-kit

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Observer Kit

Verwenden Sie Observer Kit als lokale Workflow-Umgebung. Die aktuelle Codex-, Claude-, Pi-, Command Code-, Goose- oder andere Agenten-Sitzung bleibt das Gehirn. Der Skill liefert die Beurteilung, das CLI die wiederholbare Infrastruktur, das Skript die Ausführung und der Beobachter transportiert Operator-Nachrichten zurück in die aktive Sitzung.

Bauen Sie jeden Durchlauf um zwei getrennte Garantien auf:

  • Liveness: JSONL-Ereignisse schreiten voran, während die Arbeit läuft, sodass das Dashboard aktuell bleibt.
  • Dauerhaftigkeit: Abgeschlossene Ergebnisse erreichen eine erneut lesbare Senke an einer dauerhaften Grenze, sodass ein Neustart von gespeicherter Arbeit fortsetzt.

1. Den richtigen Kontext laden

Lösen Sie relative Pfade ausgehend von dem Verzeichnis auf, das diese SKILL.md enthält.

Lesen Sie die Observer Kit README von der ersten verfügbaren Quelle:

Nutzen Sie sie, um das Produktversprechen, die Aufteilung von Skill/CLI, die Operator-Reise und die Dashboard-Erwartungen zu verstehen.

Wählen Sie den aktiven Branch und laden Sie dessen Referenz:

  • Schreiben oder adaptieren Sie einen Produktions-Workflow: Lesen Sie references/pattern.md vollständig. Es ist die einzige Quelle der Wahrheit für Quellidentität, Zeilen, dauerhafte Grenzen, externe Schreibvorgänge, Ausführungsspuren, Steuerungen, Beobachter, Nebenläufigkeit und Dashboard-Ereignisse.
  • Reagieren Sie auf einen laufenden Workflow: Lesen Sie die Abschnitte zu Ausführungsspur, Steuerungen, Beobachter und Wiederherstellung von references/pattern.md, überprüfen Sie dann das aktuelle JSONL, das dauerhafte Ziel, den Prozessstatus und das Skript.
  • Ändern Sie Observer Kit selbst: Lesen Sie references/build-guide.md und führen Sie nach der Änderung die vollständige Akzeptanztestsuite aus.

Lesen Sie das Zielskript und seine Konfiguration, bevor Sie die Umgebung entwerfen.

Abgeschlossen, wenn: Sie angeben können, welcher Branch aktiv ist, was der Benutzer zu überwachen erwartet und welche Dateien die Implementierung definieren.

2. Den tatsächlichen Workflow abbilden

Verfolgen Sie das Skript von der Eingabe bis zum Ziel und zeichnen Sie auf:

  • die unveränderliche Quellidentität: aufgelöster Pfad, Sheet-ID, Tabelle plus Abfrage, Export-ID oder gleichwertig;
  • den stabilen Schlüssel für jede Quellentität und jede abgeleitete Entität;
  • jede langsame Schleife, jeden Pool, jede Seite, jeden Wiederholungsversuch, jeden Provider-Aufruf und jeden Cache-Füllvorgang;
  • jede Zieländerung und ihr Bestätigungssignal;
  • den dauerhaften Speicher, von dem aus fortgesetzt wird;
  • die Ausgaben-, Schreib-, Raten-, Richtlinien- und Qualitätsgrenzen;
  • die angeforderte Ausführungsspur: aktuelle Ansicht aktualisieren oder separate Ansicht erstellen.

Bewahren Sie die funktionierende Geschäftslogik und das CLI des Skripts, während Sie die Umgebung auf diese tatsächlichen Ausführungspfade setzen.

Abgeschlossen, wenn: jede Ausgabe und Mutation zu einer abgebildeten Schleife, Quelle, stabilem Schlüssel, dauerhaftem Speicher, Ziel und Grenze gehört.

3. Die Operator-Ansicht vorschlagen

Schlagen Sie eine kompakte Dashboard-Form vor, bevor Sie Ereignisse verdrahten:

  • Tabellen und stabile Schlüssel;
  • Quell-, Transformations-, Begründungs-, Ergebnis-, Ziel- und error-Felder;
  • die für den Fortschritt verwendete Quelltabelle;
  • drei bis fünf für diesen Workflow ausgewählte Hauptkennzahlen;
  • eine repräsentative Trockenlauf-Stichprobengröße, normalerweise 5 bis 25 Zeilen;
  • ob eine spätere Anreicherung diese Zeilen aktualisiert oder eine Vergleichsspur öffnet.

Laden Sie den Benutzer ein, den Vorschlag zu bestätigen oder zu bearbeiten. Setzen Sie error auf eine prägnante Nachricht für eine Zeile, die menschliche Aufmerksamkeit erfordert; ein erfolgreicher Wiederholungsversuch sendet error='' mit der aktualisierten Zeile, sodass die Aufmerksamkeitsansicht den aktuellen Zeilenstatus widerspiegelt.

Abgeschlossen, wenn: der Benutzer sich Tabellen, Spalten, Zähler, Stichproben und Spur vorstellen kann, bevor die Ausführung beginnt.

4. Die Umgebung verdrahten

Verwenden Sie start_observed_run() um den eigentlichen Auftrag und übergeben Sie die tatsächlichen source=, dry_run, description, todo, progress_table und prägnanten summary_metrics.

Wenden Sie die Produktionsverträge aus references/pattern.md an:

  1. Erwerben Sie die von der Quelle abgeleitete Sperre vor der ersten Ausgabe oder Mutation.
  2. Zeichnen Sie die Eingabemomentaufnahme, die Skript-/Konfigurationsidentität, das Ziel und die Transformationsversion im Manifest auf.
  3. Erfordern Sie --dry-run plus ein Stichprobenlimit und machen Sie --full-run beabsichtigt.
  4. Senden Sie jede Entität mit stabilen table=- und key=-Werten aus der Schleife oder dem Abschluss-Callback, in dem ihre Arbeit landet.
  5. Verwenden Sie die dauerhafte Grenzreihenfolge: Arbeit ausführen, das tatsächliche Ergebnis persistieren, die Zeile senden, dann den abgeschlossenen Schlüssel oder Block checkpointen.
  6. Umhüllen Sie jede externe Zustellung mit Validierung, Richtlinienprüfungen, Schreibabsicht, bestätigtem Senken-Aufruf und Schreibeingang. Aktualisieren Sie das Zielfeld derselben Geschäftszeile von pending auf sein bestätigtes Ergebnis.
  7. Überprüfen Sie die Dashboard-Steuerungen an Schleifengrenzen und nach abgeschlossenen Schreibvorgängen.
  8. Drosseln Sie gemeinsam genutzte Provider-Konten mit throttle() und erzwingen Sie harte Ausgaben-/Schreibgrenzen im Code.

Für eine phasenweise verarbeitete Pipeline persistieren Sie jedes abgeschlossene Element oder begrenzte Chunk, sobald diese Phase autoritative Ausgabe erzeugt. Die Wiederaufnahme liest denselben Speicher und wählt die verbleibenden Arbeiten aus.

Wenn eine begrenzte Einheit interne Paginierung verwendet, halten Sie den Akkumulator auf diese Einheit beschränkt und persistieren Sie ihn sofort nach ihrer letzten Seite, bevor die nächste Einheit beginnt. Die Startwiederholung kann Arbeitskarten aus diesem dauerhaften Speicher neu aufbauen; dieser Lesevorgang stellt abgeschlossene Arbeiten wieder her und bewahrt die vorhandenen Checkpoints.

Abgeschlossen, wenn: ein Stopp des Prozesses eine Zeile vor seiner letzten Anweisung höchstens das aktive Element oder den begrenzten Chunk verliert und die Wiederaufnahme verbleibende Arbeit auswählt, während bestätigte Ausgaben und Schreibvorgänge erhalten bleiben.

5. Die Stichprobe beweisen

Starten Sie das langlebige Dashboard vor der Stichprobe, damit der Benutzer eingehende Zeilen sieht:

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

Führen Sie die statische Sende-/Dauerhaftigkeitsprüfung aus dem Skill-Verzeichnis aus:

python3 references/lint_emit.py /absolute/path/to/workflow.py

Üben Sie die tatsächliche Stichprobe und überprüfen Sie alle diese Oberflächen:

  • JSONL-Ereignisse und Dashboard-Zeilen schreiten während jeder langsamen Phase voran;
  • der dauerhafte Ergebnisspeicher schreitet mit abgeschlossener Arbeit voran;
  • stabile Schlüssel aktualisieren vorhandene Zeilen und behalten frühere Felder bei;
  • Zieleingänge stimmen mit dem tatsächlichen Zielzustand überein;
  • ein erzwungener Ausfall während der Stichprobe wird in derselben Spur von gespeicherter Arbeit fortgesetzt;
  • ein gleichzeitiger Start auf derselben Quelle erhält die Doppellauf-Warnung;
  • Pause oder Stopp erreicht einen Skript-Checkpoint, zeichnet die Bestätigung auf und öffnet einen Kanal für den Operator-Kontext;
  • das Dashboard bleibt nutzbar, während Datensätze eingehen, einschließlich Bildlaufposition, Filter, Zeitachse, Zähler und Aufmerksamkeitszeilen.

Fassen Sie geplante Schreibvorgänge, Übersprünge, Fehler, Schemaerkenntnisse, geschätzte Ausgaben und die beobachtete Wiederaufnahmegrenze zusammen.

Abgeschlossen, wenn: der Linter null beendet, jede Überprüfung oben direkte Beweise hat und der Benutzer das Stichproben-Dashboard überprüft hat.

6. Nach expliziter Zustimmung ausführen

Bitten Sie nach der Präsentation der Stichprobenzusammenfassung um explizite Bestätigung. Beginnen Sie mit dem vollständigen Datensatz durch das beabsichtigte Vollausführungs-Flag nach der Zustimmung.

Halten Sie einen Dashboard-Server, der an das Zustandsverzeichnis gebunden ist. Lassen Sie observer-kit run sich mit ihm verbinden und den laufbereichsspezifischen Beobachter starten, oder behalten Sie einen übergreifenden Beobachter für ein langlebiges Projekt:

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

Behandeln Sie Beobachterausgaben als Transport in die aktuelle Agentensitzung. Überprüfen Sie das Skript, JSONL, die dauerhafte Senke und das Ziel, bevor Sie antworten oder den Lauf ändern.

Abgeschlossen, wenn: der vollständige Lauf eine explizite Operator-Zustimmung, Live-Überwachung, ein terminales Ledger-Ereignis, abgeglichene Eingänge und eine prägnante Ergebnisszusammenfassung hat.

7. Gezielt anpassen oder wiederherstellen

Verwenden Sie dieselbe Quelle, Spur, Tabelle und denselben Schlüssel, um einen Fehler zu wiederholen, das Skript zu korrigieren oder Anreicherungen zu bereits angezeigten Zeilen hinzuzufügen. Hängen Sie aktualisierte Felder an, sodass das Dashboard Verlauf beibehält und den aktuellen Zeilenstatus anzeigt.

Verwenden Sie einen neuen stabilen Sitzungsnamen oder --session auto für eine saubere Wiederholung, einen Vergleich oder eine wirklich separate Charge. Führen Sie parallele Quellen aus, wenn ihre Datensätze nachweislich überschneidungsfrei sind; verwenden Sie die gemeinsam genutzte Provider-Drosselung für diese Läufe.

Wenn ein ausstehender Schreibvorgang existiert, gleichen Sie das Ziel ab und hängen Sie den passenden Eingang an, bevor Sie fortfahren. Wenn eine aktive Quellsperre existiert, warten Sie auf diesen Prozess oder stoppen Sie gezielt die benannte PID, bevor Sie neu starten.

Abgeschlossen, wenn: Wiederholungen den autoritativen dauerhaften Zustand wiederverwenden, Änderungen an der aktuellen Zeile an Ort und Stelle erscheinen und gezielt separate Arbeit in ihrer eigenen Dashboard-Ansicht erscheint.

Referenzkarte

  • references/pattern.md: Produktionsintegrations- und Betriebsvertrag; vollständig lesen für Workflow-Design und -Anpassung.
  • references/lint_emit.py: statische Prüfung auf endgültige Leerungen und Fortschritt in Kombination mit speichergepufferten Ergebnissen; vor jedem vollständigen Datensatz ausführen.
  • references/build-guide.md: Observer Kit Kern, Dashboard, Paketierung und Akzeptanztests-Vertrag.
  • runguard.py: ausgelagerte Laufzeit, die vom Workflow-Skript verwendet wird.
  • run_dashboard.py: lokaler Dashboard-Server für ein Zustandsverzeichnis.
  • watch_chat.py: Dashboard-Nachrichtentransport für die aktive Agentenumgebung.
  • EXPLAIN.md: projektspezifische Absichtserklärung, die dem Operator angezeigt wird.

Führen Sie observer-kit doctor . nach der Projekteinrichtung aus. Führen Sie observer-kit test aus, nachdem Sie die Laufzeit, das CLI, den Linter, den Beobachter oder das Dashboard von Observer Kit geändert haben.

Verwandte Skills