AgentTape

Machen Sie aus einem fehlgeschlagenen Codex-Lauf einen portablen Regressionstest.

AgentTape ist ein quelloffenes Codex-Plugin, das nach dem Local-First-Prinzip arbeitet und unterstützte Tool-Fehler als geschwärzte, versionierte .tape-Belege aufzeichnet. Untersuchen Sie, was fehlgeschlagen ist, forken Sie den erfassten Lauf an einem kontrollierten Punkt und speichern Sie das Ergebnis als Offline-Regressionstest, der ohne einen weiteren Modellaufruf in CI ausgeführt werden kann.

Die meisten Trace-Tools helfen Ihnen, einen Fehler zu beobachten. AgentTape wurde dafür gebaut, genau diesen Fehler in ein kleines, überprüfbares Artefakt zu verwandeln, das verhindert, dass derselbe Bug wiederkommt.

Codex tool failure
        ↓
redacted .tape evidence
        ↓
inspect → inject one condition → compare branches
        ↓
save assertions → run offline in CI

Warum AgentTape

• Fehler-Artefakt, kein weiteres Dashboard. Ein .tape ist ein portabler Beleg, den Sie ansehen, prüfen, teilen und zusammen mit einem Bugfix committen können.

• Codex-native Aufzeichnung. Mitgelieferte Hooks zeichnen unterstützte Lebenszyklus-, Berechtigungs- und Tool-Ereignisse auf, sobald der Benutzer sie überprüft und als vertrauenswürdig eingestuft hat – ganz ohne Anwendungsinstrumentierung.

• Lokal und datenschutzbewusst. Laufzeitaufzeichnungen bleiben im aktiven Projekt, und gängige geheimnistragende Felder werden vor dem Export rekursiv geschwärzt.

• Kontrollierte Fehlerinjektion. Forken Sie aufgezeichnete Belege mit verweigerter Berechtigung, Timeout, fehlerhaftem JSON oder gekürzter Antwort.

• Offline-Regressionstests. Strukturelles Replay und Assertions verwenden aufgezeichnetes Material – ohne Modellaufrufe und ohne Live-Tool-Aufrufe.

• Ehrliche Replay-Konfidenz. AgentTape weist auf Abdeckung und Grenzen hin, statt zu behaupten, jedes externe System lasse sich bitgenau reproduzierbar.

Related MCP server: MCP QA Lab

Install aus GitHub

Voraussetzungen: Codex und Node.js 20 oder neuer.

codex plugin marketplace add jiangkoumo/agenttape
codex plugin add agenttape@agenttape

Starten Sie nach der Installation eine neue Codex-Aufgabe und überprüfen Sie die mitgelieferten Hooks, bevor Sie ihnen vertrauen. Aufzeichnungen werden danach im Verzeichnis .agent-tape/ des aktiven Projekts gespeichert.

Zwei-Minuten-Workflow

Gehen Sie zuerst wie gewohnt mit Codex vor, bis ein unterstützter lokaler Tool-Aufruf fehlschlägt. Stellen Sie dann die Anfrage:

Use tool search to find AgentTape. List captured runs, inspect the latest
failed run, and explain the first recorded failure and replay confidence.

AgentTape stellt vier MCP-Tools bereit:

Führen Sie eine gespeicherte Regression lokal oder in CI aus:

node plugins/agenttape/scripts/agenttape.mjs test \
  tests/agenttape/fixture_permission_denied-timeout.tape

Erfolgreiche Assertions liefern den Exit-Code 0. Validierungs- oder Assertions-Fehler führen zu einem Exit-Code ungleich null; in der Fehlerausgabe werden erfasste Vergleichswerte weggelassen.

Was ein .tape erfasst

Tape v1 enthält die Belege, die für strukturelles Debugging gebraucht werden:

• Laufidentität, Zeitstempel, Quellabdeckung und ausdrückliche Einschränkungen.

• Geordnete Ereignisse zu Lebenszyklus, Berechtigungen und unterstützten lokalen Tool-Aufrufen.

• Tool-Eingaben, -Ausgaben, eindeutige Fehler und die erste Fehlergrenze.

• Ein Schwärzungsmanifest, das festhält, wo Werte entfernt wurden.

• Optionale Fork-Metadaten, injizierte Fehlerbedingungen und strukturellen Assertions.

• Replay-Konfidenzwerte, mit denen Konsumenten solide Belege von reinen Wiedergabespuren unterscheiden können.

Das Tape-Schema ist von UI- und Recorder-Implementierung unabhängig. Siehe Tape-Schema v1.

Regressions-Assertions

AgentTape unterstützt derzeit deterministische Prüfungen für:

• dass ein Feld einem erwarteten Wert entspricht.

• dass ein Tool vorhanden oder nicht vorhanden ist.

• dass die Anzahl der Versuche unter einem Maximum bleibt.

• dass der endgültige Status dem erwarteten Status entspricht.

• dass die Replay-Konfidenz einen Mindestwert erreicht.

Geprüfte Regressions-Artefakte werden unter tests/agenttape/ gespeichert und standardmäßig nicht überschrieben.

Replay-Grenzen

AgentTape bietet derzeit structural replays, aber keine vollständig erneute Agentenausführung. Es nutzt erfassten Zustand wieder, ersetzt ein einzelnes aufgezeichnetes Tool-Ergebnis und stoppt an der injizierten Grenze. Es erzeugt keine nachgelagerten Modellüberlegungen neu.

Gehostete Tools, nicht aufgezeichneter externer Zustand und Störstellen in Drittsystemen können fehlen. Ein Schwärzungsmarker beweist, dass der Schwärzungsprozess von AgentTape gelaufen ist; er kann nicht beweisen, dass ein beliebiplatzierter Freitext keine Geheimnisse enthält. Prüfen Sie jede .tape, bevor Sie sie teilen.

Zur vollständigen Vertrauensgrenze siehe Datenschutz und Sicherheit.

Repository-Struktur

plugins/agenttape/
  .codex-plugin/plugin.json   # Codex plugin manifest
  hooks/hooks.json            # Recorder lifecycle hooks
  skills/capture-failure/     # Guided capture workflow
  dist/mcp-server.mjs         # Self-contained bundled MCP server
  scripts/                    # Recorder, schema, and assertion CLI
  schemas/                    # Versioned .tape schema

Das Repository enthält darüber hinaus einen optionalen Branch-Canvas-Prototyp unter src/ und einen experimentellen zustandslosen HTTP-MCP unter remote/. Beide verwenden dieselben Tape- und Replay-Konzepte, sie sind aber nicht für die Installation oder Verwendung des Codex-Plugins erforderlich.

Lokale Entwicklung

git clone https://github.com/jiangkoumo/agenttape.git
cd agenttape
npm ci
npm run test:plugin-release
npm run build:plugin
codex plugin marketplace add .
codex plugin add agenttape@agenttape

Die eingecheckte Stelle plugins/agenttape/dist/mcp-server.mjs erlaubt Marketplace-Installationen ohne einen Repository-Build. Bauen Sie sie neu und committen Sie sie, wenn sich der MCP-Quellcode ändert.

Führen Sie npm test und npm run build aus, sobald die optionalen Branch- Canvas-, Stations-Adapter- oder Remote-HTTP-MCP-Oberflächen ändern.

Deinstallation

codex plugin remove agenttape@agenttape
codex plugin marketplace remove agenttape

Mitwirken

Issues und Pull Requests sind willkommenmeldung. Siehe Contributing, Verhaltenskodex und Changelog.

Lizenz

MIT. Siehe LICENSE.