Apidog CLI in DeepSeek Harness nutzen: Eine Anleitung

DeepSeek Harness arbeitet in einem Kreislauf: Der Agent liest Ihren Arbeitsbereich, bearbeitet Dateien, führt Befehle über sein Bash-Tool aus und entscheidet anhand der Ausgabe über den nächsten Schritt. Ihre API-Tests sollten Teil dieses Kreislaufs sein. Mit der Apidog CLI führen Sie Testszenarien direkt im Terminal aus, statt sie nur über die GUI zu starten.

Apidog jetzt ausprobieren

Die Lösung besteht aus einem Konfigurationsblock. Die Apidog CLI ist das npm-Paket apidog-cli und führt Testszenarien aus Apidog direkt über die Shell aus. Sobald die CLI installiert ist und DeepSeek Harness davon weiß, kann der Agent ein Apidog-Szenario wie einen Unit-Test ausführen:

1. Befehl ausführen
2. Exit-Code prüfen
3. Fehlerbericht lesen
4. Code korrigieren
5. Test erneut ausführen

Ein Agent, der die Funktionsfähigkeit einer API durch erneutes Lesen des Handler-Codes und die Analyse von Antworten bestätigt, verbraucht bei jedem Durchlauf viel Kontext. Ein CLI-Aufruf liefert die Ground Truth in wenigen Zeilen. Die CLI reduziert die Frage „Ist die API korrekt?“ auf einen Exit-Code, sodass der Agent seinen Kontext für die Fehlerbehebung verwenden kann.

Dieser Leitfaden zeigt den Harness-spezifischen Teil:

• Welche Anweisungsdatei DeepSeek Harness liest
• Wie das Bash-Tool apidog run ausführt
• Wie Sie den Kreislauf anhand von Exit-Code und Bericht überprüfen
• Wie Sie optional über MCP auf die API-Spezifikation zugreifen

Wenn Sie die CLI noch nicht installiert haben, folgen Sie zuerst der Anleitung So installieren Sie die Apidog CLI mit einem KI-Codierungsagenten. Dieser Artikel setzt voraus, dass apidog --version eine Versionsnummer ausgibt und der Rechner authentifiziert ist.

Worum geht es bei diesem DeepSeek Harness?

DeepSeek Harness, auf der Befehlszeile dsh, ist ein Open-Source-Agenten-Harness, das DeepSeek am 13. August 2026 veröffentlichte, zusammen mit V4-Pro für die API. Das Projekt steht unter MIT-Lizenz und befindet sich auf github.com/deepseek-ai/deepseek-harness. Bis zum 20. August hatte es über 169.000 Sterne erreicht.

Sie starten es mit:

npx @deepseek-ai/dsh web

Dadurch wird eine lokale Weboberfläche unter http://127.0.0.1:3080 bereitgestellt. Wählen Sie dort einen Arbeitsbereich aus – normalerweise das Projektverzeichnis, in dem Sie den Befehl gestartet haben. Der Agent kann darin Dateien lesen und bearbeiten, Befehle ausführen und vor Operationen mit erforderlicher Berechtigung nachfragen.

Beachten Sie zwei Einschränkungen:

1. DeepSeek Harness ist eine Entwicklervorschau. Laut README sind abwärtsinkompatible Änderungen möglich.
2. Die Komponenten von dsh sind Plugins auf Basis der Cordis-Architektur.

Behandeln Sie Dateinamen und Konfigurationsschlüssel daher als versionsabhängig. Falls etwas nicht geladen wird, prüfen Sie die Repo-Dokumentation. Einen allgemeinen Überblick finden Sie in Was ist DeepSeek Harness. Für einen Vergleich siehe DeepSeek Harness vs. Claude Code.

Schritt 1: Die CLI in AGENTS.md konfigurieren

DeepSeek Harness liest Arbeitsbereichsanweisungen über das Plugin @deepseek-ai/dsh-agent-instructions.

Laut Plugin-Quelle und Konfigurationskatalog sucht der Loader vom Arbeitsverzeichnis der Session aufwärts bis zum Projektstamm. Als Projektstamm gilt typischerweise ein Verzeichnis mit .git.

Dabei werden folgende Dateien berücksichtigt:

• AGENTS.md
• CLAUDE.md als Fallback
• AGENTS.local.md
• CLAUDE.local.md
• Eine globale AGENTS.md unter $DSH_HOME, standardmäßig ~/.dsh

Dateien über 1 MiB werden ignoriert. Eine normale Regelsdatei sollte diese Grenze nicht erreichen.

Wenn Ihr Repository bereits eine AGENTS.md für Codex oder eine CLAUDE.md für Claude Code enthält, kann DeepSeek Harness diese ohne weitere Einrichtung verwenden. Ergänzen Sie einen Apidog-Block mit dem tatsächlichen Befehl:

## API-Tests mit der Apidog CLI

- Führe zum Testen der API das Apidog-Szenario aus. Verwende nicht die GUI.
- Befehl: `apidog run -t <scenario_id> -e <env_id> -r cli`
- Exit-Code 0 bedeutet, dass alle Assertions erfolgreich waren.
- Ein Exit-Code ungleich 0 bedeutet einen Fehler. Lies den Bericht und korrigiere den Code.
- Der Rechner ist bereits authentifiziert. Verwende niemals `--access-token` und speichere kein Token in dieser Datei.

Eine Regelsdatei ist zuverlässiger als eine Anweisung im Chat. Eine Szenario-ID im Session-Composer geht nach dem Ende der Session verloren. Eine ID in AGENTS.md wird dagegen in neue Sessions geladen und steht jedem Teammitglied zur Verfügung, das das Repository klont.

Für mehrere Projekte können Sie die globale Datei ~/.dsh/AGENTS.md verwenden, um die allgemeine Regel festzuhalten:

API-Änderungen immer mit dem Apidog-Befehl des Projekts überprüfen.

Die projektspezifische AGENTS.md enthält anschließend die konkreten Szenario- und Umgebungs-IDs.

Schritt 2: Den korrekten Befehl aus Apidog kopieren

Raten Sie die IDs nicht. Öffnen Sie das Testszenario in Apidog, wechseln Sie zum Tab CI/CD und kopieren Sie den generierten Befehl.

Beispiel:

apidog run -t 123456 -e 789012 -r cli

Die Optionen bedeuten:

• -t: ID des Testszenarios
• -e: ID der Umgebung
• -r cli: Inline-Reporter für die Terminalausgabe

Tragen Sie die echten Werte in AGENTS.md ein:

## API-Tests mit der Apidog CLI

- Befehl: `apidog run -t 123456 -e 789012 -r cli`
- Exit-Code 0 bedeutet Erfolg.
- Jeder andere Exit-Code bedeutet einen Fehler.

So führt der Agent den von Apidog erzeugten Befehl aus und verwendet keine erfundenen oder veralteten IDs.

Schritt 3: Den Agenten den Test ausführen lassen

Starten Sie eine Session in der dsh-Weboberfläche und wählen Sie den Arbeitsbereich aus. Der Anweisungs-Loader lädt AGENTS.md automatisch in den Agentenkontext.

Nehmen Sie anschließend eine API-relevante Änderung vor oder bitten Sie den Agenten direkt:

Führe das Apidog-Testszenario aus und nenne mir den Exit-Code.

Der Agent führt den Befehl über sein Bash-Tool aus.

Verhalten des Bash-Tools

Laut Tool-Katalog startet das Standard-Bash-Tool jeden Befehl in einer neuen Shell:

• Das Arbeitsverzeichnis bleibt nicht zwischen Aufrufen erhalten.
• Umgebungsvariablen bleiben nicht erhalten.
• Shell-Funktionen bleiben nicht erhalten.
• Befehle werden standardmäßig im Session-Arbeitsbereich ausgeführt.
• Ein anderes Verzeichnis muss über workdir angegeben werden.

Für den einzelnen, vollständigen Befehl apidog run ist das normalerweise kein Problem. Der Agent kann jedoch nicht in einem Aufruf cd ausführen und den Test in einem zweiten Aufruf starten.

Wenn der Test aus einem Unterverzeichnis laufen muss, verwenden Sie eine vollständige Zeile in AGENTS.md:

- Befehl: `cd services/api && apidog run -t 123456 -e 789012 -r cli`

Nicht-Null-Exit-Codes werden als expliziter Marker zurückgegeben:

[exit code: 1]

Dadurch bleibt das Pass/Fail-Signal erhalten, selbst wenn eine lange Ausgabe gekürzt wird.

Befehle können außerdem durch eine Dateisandbox eingeschränkt werden. Eine blockierte Operation wird als Richtlinienverweigerung und nicht als normaler Befehlsfehler gemeldet. Ein reiner Lese-Testlauf löst dies selten aus. Ein HTML-Reporter, der nach ./apidog-reports schreibt, kann abhängig von der aktiven Richtlinie eine Genehmigung benötigen.

Ob eine Bestätigung erforderlich ist, hängt von der Berechtigungsrichtlinie ab. Die Weboberfläche fragt vor Operationen nach, die laut Benutzerhandbuch eine Genehmigung erfordern. Wenn dsh für apidog run nachfragt, genehmigen Sie den Befehl nach Prüfung des Ziels und der Umgebung.

Schritt 4: Den Testbericht auswerten

Bei einem fehlgeschlagenen Lauf enthält der Bericht die relevanten Details. Mit -r cli erhält der Agent eine lesbare Ausgabe direkt im Terminal:

apidog run -t 123456 -e 789012 -r cli

Die Ausgabe enthält normalerweise:

• Jede ausgeführte Anfrage
• Jede Assertion
• Erwartete Werte
• Tatsächliche Werte
• Den fehlgeschlagenen Statuscode oder das fehlerhafte Feld

Damit kann der Agent die Korrektur häufig direkt ableiten, ohne den Bericht manuell übersetzen zu müssen.

Für einen Bericht, den Sie im Browser öffnen oder an ein Teammitglied weitergeben können, ergänzen Sie den HTML-Reporter:

apidog run -t 123456 -e 789012 -r cli,html

Der html-Reporter schreibt eine eigenständige Datei nach:

./apidog-reports

Behalten Sie cli in der Reporter-Liste. So erhält der Agent weiterhin die Inline-Ausgabe, anhand derer er den nächsten Schritt entscheidet.

Der End-to-End-Kreislauf

Angenommen, der Agent bearbeitet einen Checkout-Handler. Ohne CLI endet der Ablauf möglicherweise bei: „Der Code sieht korrekt aus.“

Mit der Konfiguration in AGENTS.md sieht der Ablauf so aus:

1. Der Agent bearbeitet den Handler.
2. Er führt den Apidog-Befehl aus.
3. Er liest den Exit-Code.
4. Bei Erfolg arbeitet er weiter.
5. Bei einem Fehler liest er die fehlgeschlagene Assertion.
6. Er korrigiert den Handler.
7. Er startet den Test erneut.

Beispiel für einen Fehler:

[exit code: 1]

Expected status: 200
Actual status: 500

Assertion failed: response.body.total

Der Agent kann daraus ableiten, dass beispielsweise ein total-Feld fehlt oder der Handler einen internen Fehler verursacht. Nach der Korrektur führt er denselben Befehl erneut aus.

Die API-Vertragsprüfung wird dadurch Teil desselben Bearbeiten-Testen-Beheben-Zyklus wie Ihre Unit-Tests.

Der Agent muss nicht jede Routendatei erneut lesen, um sich von der Korrektheit der API zu überzeugen. Das Szenario enthält bereits das erwartete Verhalten. Der Agent delegiert die Verifizierung an ein deterministisches Tool und verwendet seinen Kontext für die Fehlerbehebung.

Das Muster ist klar:

• dsh schreibt und ändert Code.
• Die Apidog CLI überprüft die API-Schicht.
• Sie erstellen Testszenarien visuell in Apidog, ohne zusätzlichen Testcode schreiben zu müssen.

Überprüfen, ob dsh den Test wirklich ausgeführt hat

Agenten können Erfolge zusammenfassen, ohne den erwarteten Befehl ausgeführt zu haben. Bei einer Entwicklervorschau sollten Sie die Ausführung deshalb immer prüfen.

1. Den Bash-Aufruf kontrollieren

Die dsh-Weboberfläche zeigt die Tool-Aufrufe und deren Ausgaben in der Session.

Suchen Sie nach:

apidog run ...

und der zugehörigen Ausgabe. Wenn der Agent behauptet, den Test ausgeführt zu haben, aber kein solcher Aufruf sichtbar ist, wurde der Test wahrscheinlich nicht gestartet. Bitten Sie den Agenten in diesem Fall, den Befehl erneut auszuführen und die Rohausgabe anzuzeigen.

2. Den Exit-Code prüfen

Fragen Sie direkt:

Welchen Exit-Code hatte der Apidog-Befehl?

Bei einem Fehler liefert das Harness einen expliziten Marker:

[exit code: N]

Wenn die Zusammenfassung „Tests bestanden“ sagt, der Marker aber einen Wert ungleich 0 enthält, ist der Exit-Code maßgeblich.

3. Szenario und Umgebung vergleichen

Ein Fehler wie „Szenario nicht gefunden“ bedeutet meistens, dass eine falsche ID verwendet wurde.

Vergleichen Sie:

• den Wert von -t
• den Wert von -e
• die Werte in AGENTS.md
• den generierten Befehl im CI/CD-Tab von Apidog

Die IDs in Ihrer Regelsdatei und im Apidog-CI/CD-Befehl sind die Referenz. Alles andere ist eine Vermutung.

Optional: Den Apidog-MCP-Server für Spezifikationszugriff hinzufügen

Die CLI deckt die Testausführung und Verifizierung ab. Wenn der Agent Ihre API-Spezifikation bereits beim Schreiben des Codes lesen soll, können Sie zusätzlich MCP verwenden.

Stand Ende August 2026 ist die MCP-Unterstützung nicht in der Core-README oder im Benutzerhandbuch von DeepSeek Harness dokumentiert. Es gibt jedoch das Community-Plugin hyqhyq3/dsh-mcp-manager, das über das GitHub-Thema dsh-plugin entdeckt wurde.

Das Plugin bietet unter anderem:

• Eine MCP-Seite in den Einstellungen
• Unterstützung für entfernte HTTP-Server
• Unterstützung für lokale stdio-Server
• Tool-Namen im Format mcp__<name>__*
• Projektspezifische Konfiguration unter <workspace>/.dsh/dshmm/mcp.json

Damit können Sie den Apidog MCP-Server verbinden. Der Agent kann dann das tatsächliche Schema eines Endpunkts prüfen, bevor er den Handler implementiert.

Behandeln Sie diese Integration als zusätzliche Ebene: Community-Plugin und Entwicklervorschau-Host können sich unabhängig voneinander ändern. Der CLI-Weg bleibt die zentrale Lösung, weil er nur eine Shell benötigt.

Vorschau-Einschränkungen und Übertragbarkeit

DeepSeek Harness entwickelt sich schnell und weist selbst auf mögliche Breaking Changes hin. Besonders wahrscheinlich sind Änderungen an:

• den Dateikandidaten des Anweisungs-Plugins
• der Sandbox-Behandlung des Bash-Tools
• der MCP-Integration des Community-Plugins

Das Grundmuster bleibt jedoch portabel:

1. Eine Regelsdatei beschreibt den vorgeschriebenen Testbefehl.
2. Die CLI führt das Testszenario aus.
3. Ein Exit-Code liefert ein eindeutiges Ergebnis.
4. Der Agent liest den Bericht und korrigiert den Code.

Dieses Muster funktioniert aus demselben Grund auch in Claude Code und anderen Agenten-Harnesses: Agenten können strukturierte Befehlsausgaben zuverlässig verarbeiten, während eine rein textbasierte Einschätzung der API-Korrektheit weniger belastbar ist.

Zusammenfassung

1. Installieren und authentifizieren Sie die Apidog CLI.
2. Erstellen Sie ein Testszenario in Apidog.
3. Kopieren Sie den Befehl aus dem CI/CD-Tab.
4. Fügen Sie den Befehl in AGENTS.md ein.
5. Lassen Sie DeepSeek Harness das Szenario über Bash ausführen.
6. Prüfen Sie Tool-Aufruf, Exit-Code und Szenario-IDs.
7. Lassen Sie den Agenten Fehler beheben und den Test wiederholen.

Sie können Apidog herunterladen, ein Testszenario erstellen und anschließend den apidog run-Befehl in die AGENTS.md Ihres Repositories eintragen. Danach überprüft DeepSeek Harness seine API-Änderungen, bevor es die Arbeit als abgeschlossen meldet.

FAQ

Liest DeepSeek Harness AGENTS.md nativ?

Ja. Das Plugin @deepseek-ai/dsh-agent-instructions lädt AGENTS.md aus dem Projektstamm und den übergeordneten Verzeichnissen des Session-Arbeitsverzeichnisses.

Zusätzlich werden berücksichtigt:

• CLAUDE.md als Fallback
• AGENTS.local.md
• CLAUDE.local.md
• Eine globale AGENTS.md unter ~/.dsh

Wenn Sie bereits eine AGENTS.md für andere Agenten verwenden, kann dsh sie unverändert übernehmen.

Benötige ich einen kostenpflichtigen DeepSeek-Plan?

Nein. DeepSeek Harness ist MIT-lizenziertes Open Source und unterstützt verschiedene Modellanbieter. Laut dieser Anleitung können Sie unter anderem Anthropic, OpenAI, Bedrock, Vertex und Azure konfigurieren. Benutzerdefinierte Gateways werden über settings.yaml eingebunden.

Die Apidog CLI ist ein npm-Paket. Sie benötigt ein Apidog-Testszenario und eine Authentifizierung, aber kein bestimmtes Modell.

Warum vergisst der Agent das Verzeichnis nach einem cd?

Das Standard-Bash-Tool startet jeden Aufruf in einer neuen Shell. Deshalb bleibt ein cd nicht für den nächsten Aufruf erhalten.

Verwenden Sie entweder den workdir-Parameter oder führen Sie den vollständigen Befehl in einer Zeile aus:

cd services/api && apidog run -t 123456 -e 789012 -r cli

Kann dsh das Szenario ohne Rückfrage ausführen?

Das hängt von der aktiven Berechtigungsrichtlinie ab. Die Weboberfläche fragt vor Operationen nach, die laut Richtlinie eine Genehmigung benötigen.

Prüfen Sie die Einstellungen Ihres Builds. Wenn eine Rückfrage erscheint, kontrollieren Sie den Befehl und das Zielsystem, bevor Sie einen apidog run gegen Staging genehmigen.