DeepSeek Harness Python SDK-Aufruf

Die Web-UI ist für Menschen zum Anschauen gedacht, aber wenn Sie sie aus einem Programm aufrufen müssen,dshdann ist das SDK genau das, was Sie brauchen.

Dieses Kapitel behandelt das Python SDK: wie man es installiert, wie man die integrierten Beispiele im Repository ausführt und wie man es in eigenen Programmen aufruft.


Welches Problem löst das Python SDK?

Das SDK macht dsh zu einem Einzeilenaufruf innerhalb Ihres Programms statt zu einer Seite im Browser.

DeepSeekHarnessEs ist die Kernklasse des Python SDK und verwendet einen Kontextmanager, um den Lebenszyklus der Laufzeit zu verwalten.

Beim Betreten des with-Blocks wird die integrierte Laufzeit verzögert gestartet; beim Verlassen wird sie automatisch freigegeben, und dazwischen kann run wiederholt aufgerufen werden.

Geeignete Szenarien: Batchverarbeitungsaufgaben, die Integration von dsh in Ihr eigenes Produkt und das Ansteuern von Agents in Tests.

Sobald das SDK installiert ist, muss das System Node.js nicht bereitstellen—der Python-Prozess bringt eine eigene Kopie mit.


Voraussetzungen

Das SDK hat explizite Systemanforderungen—prüfen Sie sie zuerst.

AbhängigkeitVoraussetzung
Python3.10 oder höher
GitInstalliert
BetriebssystemLinux x64, Linux arm64 oder macOS 14+ arm64
API-EndpunktDeepSeek-kompatibler API-Endpunkt und Zugangsdaten
ArbeitsbereichIsolierter Arbeitsbereich, den der Agent ändern kann

SDK installieren

Klonen Sie das Repository, um ausführbare Beispiele zu erhalten, erstellen Sie eine virtuelle Umgebung und installieren Sie dann das SDK und die integrierte Laufzeit derselben Version.

$ git clone https://github.com/deepseek-ai/deepseek-harness.git
$ cd deepseek-harness
$ python -m venv .venv
$ . .venv/bin/activate
$ python -m pip install deepseek-harness-sdk

Eine virtuelle Umgebung isoliert das SDK von anderen Python-Paketen auf dem System – der offiziell empfohlene Ansatz.

Nach der Installation benötigt die Laufzeit kein vom System bereitgestelltes Node.js.


Integrierte Beispiele aus dem Repository ausführen

Das Repository enthält ein minimal.py-Beispiel; es zum Laufen zu bringen entspricht der Überprüfung der gesamten SDK-Pipeline.

Legen Sie zuerst die Zugangsdaten in der Umgebung fest.

$ export DEEPSEEK_API_KEY=sk-your-key-here
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# export DSH_MODEL=deepseek-v4-flash
# export DSH_SYSTEM_PROMPT='You are a helpful software engineer assistant.'

Wenn das Modell nicht vom standardmäßigen DeepSeek-Endpunkt, sondern über einen OpenAI-kompatiblen Proxy bereitgestellt wird, müssen Sie außerdem DEEPSEEK_BASE_URL festlegen.

Führen Sie dann eine Aufgabe gegen einen isolierten Arbeitsbereich und ein isoliertes Sitzungsverzeichnis aus.

$ python examples/jsonrpc-agent/minimal.py \
  --workspace /absolute/path/to/workspace \
  --session-root /absolute/path/to/sessions \
  --session-id example-001 \
  "Inspect the repository and fix the failing tests."

Das Skript gibt die endgültige Antwort des Assistenten aus.

Das Sitzungsverzeichnis empfängt JSONL-Protokolle, die die zusammengesetzten Modellanfragen und Tool-Aufrufe enthalten.


Verwendung des SDK in Ihrem eigenen Programm

Das integrierte Beispiel im Repository ist tatsächlich ein leichtgewichtiger Wrapper um den unten stehenden SDK-Aufruf; der Kern besteht aus nur zwei Schritten.

Beispiel

# Dateipfad: äquivalente Schreibweise von examples/jsonrpc-agent/minimal.py
from pathlib import Path

from deepseek_harness import DeepSeekHarness

# Absoluter Pfad der kombinierten Konfigurationsdatei des Beispiels (.cordis.yml beschreibt, welche Plugins gestartet werden sollen)
config = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()

# Der für den Agenten zugängliche Arbeitsbereich muss ein absoluter Pfad sein.
workspace = Path("/absolute/path/to/workspace").resolve()

Verzeichnis zum Speichern von Sitzungsprotokollen und Status, muss ein absoluter Pfad sein
sessions = Path("/absolute/path/to/sessions").resolve()

# Kontextmanager: integrierte Laufzeitumgebung beim Eintritt verzögert starten und beim Austritt automatisch freigeben.
with DeepSeekHarness(
    provider="deepseek-official",   # Den offiziellen DeepSeek-Provider verwenden
    model="deepseek-v4-flash",      # Modellname, auch der SDK-Standard
    max_tokens=49_152,              # Maximale Anzahl von Tokens pro einzelner Antwort
    cwd=str(workspace),             # workspace als Arbeitsverzeichnis des Agenten festlegen
    session_root=str(sessions),     # Wohin Sitzungsprotokolle geschrieben werden
    cordis=str(config),             # Mit welcher Bundle-Konfiguration gestartet werden soll
) as harness:
    # Aufgabe senden; session_id wird verwendet, um diese persistente Konversation zu identifizieren
    result = harness.run(
        "Untersuche das example-demo-Repository und behebe die fehlschlagenden Tests.",
        session_id="example-001",
    )

# Gib die endgültige Antwort des Assistenten aus
print(result.final_response)

DeepSeekHarness startet die integrierte Laufzeitumgebung verzögert und verwendet sie weiter, bis der Kontextmanager verlassen wird.

Dieselbe Harness kann run innerhalb des with-Blocks mehrmals aufrufen, und die Laufzeitumgebung startet nur einmal.


Session-ID wiederverwenden: Bash-Prozesse beibehalten

Dies ist die am leichtesten zu übersehende und nützlichste Regel des SDK.

Die Wiederverwendung derselben Harness und Session-ID erhält die Bash-Prozesse, die zu dieser Sitzung gehören.

Einschließlich ihres Arbeitsverzeichnisses, exportierter Variablen und Shell-Funktionen — alles wird auf den nächsten Aufruf übertragen.

Beispiel

# Erster Aufruf: eine Variable in example-workspace exportieren
result = harness.run(
    "Führe `cd /repo && export EXAMPLE_MODE=dev` aus und bestätige.",
    session_id="example-session",
)
print(result.final_response)

# Zweiter Aufruf: dieselbe Session-ID wiederverwenden, die exportierte Variable ist weiterhin vorhanden
result = harness.run(
    "Gib den Wert von EXAMPLE_MODE aus.",
    session_id="example-session",
)
print(result.final_response)

Unabhängige Aufgaben sollten eine neue Session-ID verwenden; die ursprüngliche ID nur dann wiederverwenden, wenn der nächste Aufruf dieselbe persistente Konversation fortsetzen muss.


Überblick über Beispielkombinationen

Die Kombination hinter minimal.py ist eine bewusst minimale Konfiguration; gehen wir jeden Eintrag durch, um zu sehen, was er bewirkt.

EigenschaftWert
System-PromptDSH_SYSTEM_PROMPT;未SettingswhenUsage Du bist ein hilfreicher Assistent für Softwareentwicklung.
Von minimal.py verwendetes Modell--model, dann DSH_MODEL und schließlich deepseek-v4-flash
Modellorientierte ToolsNur persistente bash und str_replace_editor
Bash-Timeout300 Sekunden
Editor-Ausgabelimit16,000 Zeichen
KontextkomprimierungGeschlossen
DateisystemNacktes lokales Backend; der Editor verwendet absolute Pfade und kann auf jeden Pfad zugreifen, der für den Laufzeitprozess sichtbar ist.
KonversationspersistenzUnkomprimiertes JSONL unter DSH_SESSION_ROOT

Diese Kombination lässt Plugins wie Harness-Identität, Workspace-Prompt-Text, Skills, One-Shot-Bash, Task-Tools und Kontextkomprimierung weg.

Der gesamte Aufrufablauf ist wie folgt.

Python SDK 调用流程图


Grenze von danger-full-access

Diese Beispielkombination verwendet die Berechtigungsvoreinstellung danger-full-access, und Sie müssen sich über deren Grenzen im Klaren sein.

danger-full-access kann nur in einem wegwerfbaren Checkout oder Container ausgeführt werden.

Bash und der Editor können jeden für den Laufzeitprozess zugänglichen Pfad verändern; es gibt keine Sandbox als Sicherheitsnetz.

Das persistente PTY-Backend kann nur in einer POSIX-Terminalumgebung ausgeführt werden, daher unterstützt diese Kombination keine Windows-Agenten.

Mit anderen Worten: Bevor du es zum Ausführen echter Projekte verwendest, sei dir zuerst sicher, dass es dir nichts ausmacht, wenn diese Umgebung beschädigt wird.


Zusammenfassung Selbsttest

Zusammenfassung in einem Satz: Das Python SDK umschließt die Laufzeit mit dem DeepSeekHarness-Kontextmanager und sendet Aufgaben über run(prompt, session_id).

Teste dein Verständnis mit drei kurzen Fragen.

  1. Was bleibt erhalten, wenn dieselbe session id wiederverwendet wird?
  2. In welchen Situationen solltest du eine neue Sitzung verwenden?
  3. Welche Tools aktiviert minimal.py standardmäßig für das Modell?

Referenzantwort: Der Bash-Prozess für diese Sitzung bleibt erhalten, einschließlich des Arbeitsverzeichnisses, exportierter Variablen und Shell-Funktionen.

Verwende eine neue ID für unabhängige Aufgaben; verwende sie nur dann wieder, wenn du dieselbe persistente Konversation fortsetzen musst.

Nur die beiden Tools beibehalten: bash und str_replace_editor

Weitere Erweiterungen