GuidesOneMux

Cline in der Produktion: Sitzungen konfigurieren und sicher wiederherstellen

Praxisleitfaden zur Konfiguration von ClineCore-Sitzungen, zur Trennung von Laufzeit- und Provider-Einstellungen sowie zur Gestaltung sicherer Wiederholungs- und Wiederherstellungsregeln.

AI

Zusammenfassung · TL;DR

ClineCore trennt Laufzeitentscheidungen – etwa Backend-Modus, Funktionen, Tool-Richtlinien und Automatisierung – vom Provider und Modell, die für eine Sitzung konfiguriert werden. Dieser Leitfaden zeigt, wie Sie diese Trennung explizit gestalten und die Wiederherstellung anhand von Sitzungs-IDs und gespeichertem Zustand planen, statt Arbeit blind zu wiederholen.

Kernaussagen

  • Behandeln Sie Laufzeit, Tool-Berechtigungen und Provider-/Modellkonfiguration als separate Entscheidungen.
  • Nutzen Sie Sitzungs-IDs und gespeicherte Nachrichten, um Fehler zu untersuchen, bevor Sie einen erneuten Versuch starten.
  • Gehen Sie davon aus, dass Wiederholungen Nebenwirkungen duplizieren können, und legen Sie Prüfpunkte sowie Wiederherstellungsregeln für Ihren Workflow fest.
  • Die API-Referenz dokumentiert Sitzungsoperationen, aber keine Wiederholungssemantik, Prüfpunkte-Formate oder Garantien zur Provider-Kompatibilität.
Auf dieser Seite (9)

Mit ClineCore kann eine Anwendung die Erstellung von Sitzungen, die Auswahl der Laufzeit, Tool-Berechtigungen und den Sitzungsverlauf steuern. Bei Produktions-Workflows lautet die entscheidende Designfrage nicht einfach, ob ein fehlgeschlagener Aufruf wiederholt werden soll. Entscheidend ist vielmehr, wie Sie feststellen, was bereits geschehen ist, bevor Sie Arbeit erneut ausführen.

Die folgende Konfiguration dient der Veranschaulichung und ist keine getestete Bereitstellungsanleitung. Die ClineCore-API-Referenz dokumentiert die hier besprochenen Optionen und Methoden. Die genauen Typen und das Verhalten entnehmen Sie bitte der installierten SDK-Version.

Laufzeiteinstellungen von Modelleinstellungen trennen

Eine sinnvolle Konfigurationsgrenze umfasst drei Bereiche:

  • Laufzeit: Backend-Auswahl, Client-Identität und optionale Einstellungen für Remote- oder Hub-Verbindungen.
  • Ausführungsrichtlinien: Tool-Richtlinien, Funktionen und die Frage, ob Automatisierungs-APIs aktiviert sind.
  • Modellkonfiguration der Sitzung: Provider-ID, Modell-ID, Anmeldedaten, Workspace-Pfade und für eine bestimmte Sitzung verfügbare Tools.

So lässt sich die Laufzeitrichtlinie einfacher unabhängig von einem Modellwechsel verwalten. Provider-spezifische Felder werden dadurch jedoch nicht austauschbar: providerId, modelId und apiKey müssen weiterhin für den ausgewählten Provider gültig sein. Die API-Referenz garantiert keine Kompatibilität mit jedem Provider oder Endpunkt.

Laufzeit erstellen und Sitzung starten

Voraussetzungen: Installieren Sie die Cline-SDK-Version, die Sie bereitstellen möchten, hinterlegen Sie Anmeldedaten gemäß dem Geheimnisverwaltungsverfahren Ihrer Anwendung und legen Sie fest, welche Tools der Agent verwenden darf. Speichern Sie keine Anmeldedaten in Protokollen oder Sitzungsmetadaten.

import { ClineCore } from "@cline/sdk"

const cline = await ClineCore.create({
  clientName: "repo-maintenance-worker",
  backendMode: "auto",
  toolPolicies: {},
  automation: false,
})

const session = await cline.start({
  prompt: "Inspect the repository and report failing tests. Do not modify files.",
  source: "scheduled-check",
  interactive: false,
  sessionMetadata: { jobId: "job-123" },
  config: {
    providerId: "anthropic",
    modelId: "claude-sonnet-4-6",
    apiKey: process.env.ANTHROPIC_API_KEY,
    systemPrompt: "Follow the task scope and report actions taken.",
    cwd: process.cwd(),
    workspaceRoot: process.cwd(),
    enableTools: true,
    enableSpawnAgent: false,
    enableAgentTeams: false,
  },
})

console.log(session.sessionId)

Die oben angegebenen Provider- und Modellwerte entsprechen dem Beispiel in der API-Referenz. Sie sind weder eine Empfehlung noch eine Aussage zur Provider-Kompatibilität über dieses Beispiel hinaus. Die Referenz dokumentiert die Werte auto, local, hub und remote für backendMode sowie optionale Einstellungen für hub und remote. Sie legt nicht fest, welcher Modus für eine bestimmte Bereitstellung am besten geeignet ist. Wählen Sie den Modus bewusst aus und prüfen Sie die Konnektivität und Berechtigungen in Ihrer Umgebung.

Ein leeres toolPolicies-Objekt ist keine Sicherheitsrichtlinie. Legen Sie explizite Standardwerte und sitzungsspezifische Richtlinien entsprechend den vom installierten SDK unterstützten Richtlinientypen fest. Verwenden Sie capabilities, wenn der Client Tool-Ausführungen oder Freigabe-Callbacks bereitstellt, und testen Sie, ob eingeschränkte Aktionen tatsächlich abgewiesen werden.

Wiederholungsregeln am Sitzungszustand ausrichten

Ein Netzwerkfehler oder ein Worker-Timeout beweist nicht, dass der Agent seine Arbeit nicht abgeschlossen hat. Wird die ursprüngliche Eingabe wiederholt, können Änderungen, externe Aufrufe oder andere Nebenwirkungen doppelt ausgeführt werden. Die API-Referenz führt get, readMessages, getAccumulatedUsage, abort, stop und restore auf. Sie spezifiziert jedoch weder automatische Wiederholungen noch eine Exactly-once-Ausführung oder den Inhalt eines Prüfpunkts.

Ein sichereres Vorgehen im Betrieb:

  1. Sitzungs-ID sofort speichern. Speichern Sie sie zusammen mit der Job-ID, damit ein neu gestarteter Worker dieselbe Sitzung wiederfinden kann.
  2. Fehler einordnen. Unterscheiden Sie zwischen einem bestätigten endgültigen Fehler und einem Timeout oder Verbindungsverlust, bei dem unklar ist, ob die Arbeit abgeschlossen wurde.
  3. Vor dem erneuten Senden prüfen. Verwenden Sie get und readMessages, um Sitzungsmetadaten und gespeicherte Nachrichten zu überprüfen. Prüfen Sie gegebenenfalls die kumulierte Nutzung als betrieblichen Hinweis, nicht als Beweis dafür, dass eine bestimmte Aktion abgeschlossen wurde.
  4. Wiederherstellung bewusst wählen. Wenn die Sitzung noch aktiv ist, entscheiden Sie, ob Sie warten, abbrechen oder sie stoppen möchten. Soll die Arbeit fortgesetzt werden, akzeptiert send eine Sitzungs-ID und eine Folgeeingabe. Wenn ein Prüfpunkt verfügbar und geeignet ist, stellt die API restore bereit. Die erforderlichen Eingaben und die genaue Semantik entnehmen Sie bitte der SDK-Dokumentation.
  5. Nebenwirkungen wiederholbar machen. Verwenden Sie für Aktionen außerhalb des sitzungsinternen Agentenzustands gegebenenfalls Idempotenzschlüssel auf Anwendungsebene, Deduplizierung oder eine manuelle Freigabe.

Vermeiden Sie es, start in eine bedingungslose Wiederholungsschleife einzubetten. Wenn die erste Anfrage möglicherweise eine Sitzung erstellt hat, bevor die Antwort verloren ging, kann ein weiteres start eine separate Aufgabe anstoßen. Die API-Referenz dokumentiert für start keinen Idempotenzschlüssel. Gehen Sie daher nicht davon aus, dass es einen gibt.

Häufige Produktionsfehler beheben

Sitzung startet mit der falschen Laufzeit

Protokollieren Sie den ausgewählten Backend-Modus und nicht geheime Sitzungskennungen. Prüfen Sie die Optionen backendMode, hub und remote im Kontext der Umgebung, in der der Worker ausgeführt wird. Die Referenz beschreibt diese Optionen zur Laufzeitauswahl, dokumentiert jedoch kein automatisches Failover-Verhalten. Prüfen Sie daher, was auto in Ihrer SDK-Version tatsächlich bewirkt, statt sich auf einen angenommenen Fallback zu verlassen.

Tools sind nicht verfügbar oder unerwartet freigegeben

Prüfen Sie sowohl die config der Sitzung als auch die geltenden Standard- und sitzungsspezifischen toolPolicies oder capabilities. Die Referenz beschreibt diese als Richtlinien für Tools sowie als vom Client gesteuerte Ausführungs- und Freigabekontrollen. Die bereitgestellte API-Zusammenfassung erläutert nicht, welche Richtlinie Vorrang hat. Prüfen Sie daher die Prioritätsregeln in der Dokumentation des installierten SDK und testen Sie sowohl erlaubte als auch abgewiesene Fälle.

Ein Worker verliert während der Ausführung die Verbindung

Speichern Sie Sitzungs-ID und Job-ID dauerhaft im Anwendungszustand. Prüfen Sie nach einem Neustart die vorhandene Sitzung, bevor Sie entscheiden, ob Sie mit send fortfahren, sie stoppen oder anhand eines Prüfpunkts wiederherstellen. Leiten Sie aus einer fehlenden Antwort allein nicht ab, dass die Arbeit abgeschlossen ist.

Provider- oder Modellkonfiguration schlägt fehl

Prüfen Sie Provider-ID, Modell-ID, Anmeldedaten und mögliche Endpunktanforderungen anhand der Dokumentation des Providers und von Cline für die gewählte Konfiguration. Die ClineCore-Referenz zeigt ein Schema für Provider- und Modellkonfigurationen. Sie garantiert nicht, dass beliebige OpenAI-kompatible Endpunkte oder provider-spezifische Parameter unverändert funktionieren.

Checkliste für den Produktionseinsatz

  • Speichern Sie Sitzungs-IDs dauerhaft und halten Sie Geheimnisse aus Protokollen und Metadaten heraus.
  • Legen Sie Tool-Berechtigungen ausdrücklich fest und testen Sie Freigabe- und Ablehnungspfade.
  • Unterscheiden Sie zwischen einer fehlgeschlagenen Operation und einer Operation mit unklarem Ergebnis.
  • Prüfen Sie den Sitzungsverlauf, bevor Sie Arbeit erneut senden.
  • Gestalten Sie externe Nebenwirkungen idempotent oder verlangen Sie vor einer Wiederholung eine Freigabe.
  • Validieren Sie das Verhalten von Backend und Provider in der tatsächlichen Bereitstellungsumgebung.
  • Geben Sie Laufzeitressourcen beim ordnungsgemäßen Herunterfahren gemäß dem dokumentierten Lebenszyklus des SDK frei.

Die praktische Regel ist einfach: Wiederholen Sie nur, wenn Sie wissen, was Sie wiederholen. ClineCore bietet APIs für Sitzungen und die Wiederherstellung. Ein sicherer Betrieb in der Produktion hängt jedoch weiterhin von der dauerhaften Jobverfolgung, dem Berechtigungskonzept und dem Umgang Ihrer Anwendung mit doppelten Nebenwirkungen ab.

FAQ

Welche ClineCore-Einstellungen sind unabhängig vom Modell-Provider?

Laufzeitoptionen wie `clientName`, `backendMode`, optionale Hub- oder Remote-Einstellungen, Funktionen, Tool-Richtlinien und Automatisierung sind von den Provider- und Modellfeldern der Sitzung getrennt. Prüfen Sie das genaue Verhalten der Optionen anhand der verwendeten SDK-Version.

Sollte ich ClineCore.start nach einem Timeout erneut aufrufen?

Nicht blind. Ein Timeout zeigt nicht, ob eine Sitzung erstellt wurde. Speichern Sie die Sitzungs-ID, sobald sie verfügbar ist, und prüfen Sie vorhandene Sitzungen, bevor Sie neue Arbeit starten. Die bereitgestellte API-Referenz dokumentiert für `start` keinen Idempotenzschlüssel.

Kann ClineCore eine fehlgeschlagene Sitzung wiederherstellen?

Die API-Referenz führt eine Methode `restore` auf, aber die bereitgestellte Zusammenfassung spezifiziert weder die erforderliche Eingabe noch die Semantik von Prüfpunkten. Lesen Sie die Dokumentation des installierten SDK, bevor Sie Ihre Wiederherstellung darauf aufbauen.

Funktioniert diese Konfiguration mit jedem OpenAI-kompatiblen Provider?

Das geht aus der zitierten ClineCore-Referenz nicht hervor. Provider-Kompatibilität und akzeptierte Parameter hängen von der dokumentierten Unterstützung des Endpunkts und der ausgewählten Provider-Konfiguration ab. Prüfen Sie dies, statt von Austauschbarkeit auszugehen.

Ähnliche Artikel