18 KiB
18 KiB
| read_when | sidebarTitle | summary | title | x-i18n | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Diffs | Schreibgeschützter Diff-Viewer und Dateirenderer für Agenten (optionales Plugin-Tool) | Unterschiede |
|
diffs ist ein optionales Plugin-Tool mit kurzer integrierter Systemanleitung und einer begleitenden Skill, die Änderungsinhalte in ein schreibgeschütztes Diff-Artefakt für Agenten umwandelt.
Es akzeptiert entweder:
- Text für
beforeundafter - einen vereinheitlichten
patch
Es kann zurückgeben:
- eine Gateway-Viewer-URL für die Canvas-Darstellung
- einen gerenderten Dateipfad (PNG oder PDF) für die Nachrichtenzustellung
- beide Ausgaben in einem Aufruf
Wenn aktiviert, stellt das Plugin dem System-Prompt-Bereich eine knappe Nutzungsanleitung voran und stellt außerdem eine ausführliche Skill für Fälle bereit, in denen der Agent vollständigere Anweisungen benötigt.
Schnellstart
```bash openclaw plugins install diffs ``` ```json5 { plugins: { entries: { diffs: { enabled: true, }, }, }, } ``` Canvas-zentrierte Abläufe: Agenten rufen `diffs` mit `mode: "view"` auf und öffnen `details.viewerUrl` mit `canvas present`. Chat-Dateizustellung: Agenten rufen `diffs` mit `mode: "file"` auf und senden `details.filePath` mit `message` unter Verwendung von `path` oder `filePath`. Kombiniert: Agenten rufen `diffs` mit `mode: "both"` auf, um beide Artefakte in einem Aufruf zu erhalten.Integrierte Systemanleitung deaktivieren
Wenn Sie das Tool diffs aktiviert lassen, aber seine integrierte System-Prompt-Anleitung deaktivieren möchten, setzen Sie plugins.entries.diffs.hooks.allowPromptInjection auf false:
{
plugins: {
entries: {
diffs: {
enabled: true,
hooks: {
allowPromptInjection: false,
},
},
},
},
}
Dadurch wird der Hook before_prompt_build des diffs-Plugins blockiert, während Plugin, Tool und begleitende Skill verfügbar bleiben.
Wenn Sie sowohl die Anleitung als auch das Tool deaktivieren möchten, deaktivieren Sie stattdessen das Plugin.
Typischer Agenten-Workflow
Der Agent ruft das Tool `diffs` mit Eingabe auf. Der Agent liest die Felder aus `details` aus der Antwort. Der Agent öffnet entweder `details.viewerUrl` mit `canvas present`, sendet `details.filePath` mit `message` unter Verwendung von `path` oder `filePath`, oder führt beides aus.Eingabebeispiele
```json { "before": "# Hello\n\nOne", "after": "# Hello\n\nTwo", "path": "docs/example.md", "mode": "view" } ``` ```json { "patch": "diff --git a/src/example.ts b/src/example.ts\n--- a/src/example.ts\n+++ b/src/example.ts\n@@ -1 +1 @@\n-const x = 1;\n+const x = 2;\n", "mode": "both" } ```Referenz für Tool-Eingaben
Alle Felder sind optional, sofern nicht anders angegeben.
Ursprünglicher Text. Erforderlich mit `after`, wenn `patch` weggelassen wird. Aktualisierter Text. Erforderlich mit `before`, wenn `patch` weggelassen wird. Vereinheitlichter Diff-Text. Gegenseitig ausgeschlossen mit `before` und `after`. Anzuzeigender Dateiname für den Vorher-Nachher-Modus. Hinweis zur Sprachüberschreibung für den Vorher-Nachher-Modus. Unbekannte Werte fallen auf Nur-Text zurück. Überschreibung des Viewer-Titels. Ausgabemodus. Standardmäßig der Plugin-Standardwert `defaults.mode`. Veralteter Alias: `"image"` verhält sich wie `"file"` und wird aus Gründen der Abwärtskompatibilität weiterhin akzeptiert. Viewer-Theme. Standardmäßig der Plugin-Standardwert `defaults.theme`. Diff-Layout. Standardmäßig der Plugin-Standardwert `defaults.layout`. Unveränderte Abschnitte erweitern, wenn vollständiger Kontext verfügbar ist. Nur Option pro Aufruf (kein Plugin-Standardschlüssel). Gerendertes Dateiformat. Standardmäßig der Plugin-Standardwert `defaults.fileFormat`. Qualitätsvorgabe für PNG- oder PDF-Rendering. Überschreibung der Geräteskalierung (`1`-`4`). Maximale Renderbreite in CSS-Pixeln (`640`-`2400`). Artefakt-TTL in Sekunden für Viewer- und eigenständige Dateiausgaben. Maximal 21600. Überschreibung des Viewer-URL-Ursprungs. Überschreibt Plugin `viewerBaseUrl`. Muss `http` oder `https` sein, ohne Query/Hash. Aus Gründen der Abwärtskompatibilität weiterhin akzeptiert:- `format` -> `fileFormat`
- `imageFormat` -> `fileFormat`
- `imageQuality` -> `fileQuality`
- `imageScale` -> `fileScale`
- `imageMaxWidth` -> `fileMaxWidth`
Vertrag für Ausgabedetails
Das Tool gibt strukturierte Metadaten unter details zurück.
- `artifactId`
- `viewerUrl`
- `viewerPath`
- `title`
- `expiresAt`
- `inputKind`
- `fileCount`
- `mode`
- `context` (`agentId`, `sessionId`, `messageChannel`, `agentAccountId`, sofern verfügbar)
- `artifactId`
- `expiresAt`
- `filePath`
- `path` (derselbe Wert wie `filePath`, für Kompatibilität mit dem Nachrichtentool)
- `fileBytes`
- `fileFormat`
- `fileQuality`
- `fileScale`
- `fileMaxWidth`
- `format` (derselbe Wert wie `fileFormat`)
- `imagePath` (derselbe Wert wie `filePath`)
- `imageBytes` (derselbe Wert wie `fileBytes`)
- `imageQuality` (derselbe Wert wie `fileQuality`)
- `imageScale` (derselbe Wert wie `fileScale`)
- `imageMaxWidth` (derselbe Wert wie `fileMaxWidth`)
Zusammenfassung des Modusverhaltens:
| Modus | Was zurückgegeben wird |
|---|---|
"view" |
Nur Viewer-Felder. |
"file" |
Nur Dateifelder, kein Viewer-Artefakt. |
"both" |
Viewer-Felder plus Dateifelder. Wenn das Datei-Rendering fehlschlägt, wird der Viewer weiterhin mit dem Alias fileError und imageError zurückgegeben. |
Eingeklappte unveränderte Abschnitte
- Der Viewer kann Zeilen wie
N unmodified linesanzeigen. - Erweiterungssteuerelemente in diesen Zeilen sind bedingt und nicht für jede Eingabeart garantiert.
- Erweiterungssteuerelemente erscheinen, wenn der gerenderte Diff erweiterbare Kontextdaten enthält, was für Vorher-Nachher-Eingaben typisch ist.
- Bei vielen vereinheitlichten Patch-Eingaben sind ausgelassene Kontextkörper in den geparsten Patch-Hunks nicht verfügbar, sodass die Zeile ohne Erweiterungssteuerelemente erscheinen kann. Dies ist erwartetes Verhalten.
expandUnchangedgilt nur, wenn erweiterbarer Kontext vorhanden ist.
Plugin-Standardeinstellungen
Legen Sie Plugin-weite Standardeinstellungen in ~/.openclaw/openclaw.json fest:
{
plugins: {
entries: {
diffs: {
enabled: true,
config: {
defaults: {
fontFamily: "Fira Code",
fontSize: 15,
lineSpacing: 1.6,
layout: "unified",
showLineNumbers: true,
diffIndicators: "bars",
wordWrap: true,
background: true,
theme: "dark",
fileFormat: "png",
fileQuality: "standard",
fileScale: 2,
fileMaxWidth: 960,
mode: "both",
},
},
},
},
},
}
Unterstützte Standardeinstellungen:
fontFamilyfontSizelineSpacinglayoutshowLineNumbersdiffIndicatorswordWrapbackgroundthemefileFormatfileQualityfileScalefileMaxWidthmode
Explizite Tool-Parameter überschreiben diese Standardeinstellungen.
Persistente Viewer-URL-Konfiguration
Plugin-eigener Fallback für zurückgegebene Viewer-Links, wenn ein Tool-Aufruf kein `baseUrl` übergibt. Muss `http` oder `https` sein, ohne Query/Hash.{
plugins: {
entries: {
diffs: {
enabled: true,
config: {
viewerBaseUrl: "https://gateway.example.com/openclaw",
},
},
},
},
}
Sicherheitskonfiguration
`false`: Nicht-loopback-Anfragen an Viewer-Routen werden verweigert. `true`: Remote-Viewer sind erlaubt, wenn der tokenisierte Pfad gültig ist.{
plugins: {
entries: {
diffs: {
enabled: true,
config: {
security: {
allowRemoteViewer: false,
},
},
},
},
},
}
Artefakt-Lebenszyklus und Speicherung
- Artefakte werden im temporären Unterordner gespeichert:
$TMPDIR/openclaw-diffs. - Viewer-Artefaktmetadaten enthalten:
- zufällige Artefakt-ID (20 Hex-Zeichen)
- zufälliges Token (48 Hex-Zeichen)
createdAtundexpiresAt- gespeicherter Pfad
viewer.html
- Die Standard-Artefakt-TTL beträgt 30 Minuten, wenn nicht angegeben.
- Die maximal akzeptierte Viewer-TTL beträgt 6 Stunden.
- Die Bereinigung wird nach der Artefakterstellung opportunistisch ausgeführt.
- Abgelaufene Artefakte werden gelöscht.
- Die Fallback-Bereinigung entfernt veraltete Ordner, die älter als 24 Stunden sind, wenn Metadaten fehlen.
Viewer-URL und Netzwerkverhalten
Viewer-Route:
/plugins/diffs/view/{artifactId}/{token}
Viewer-Assets:
/plugins/diffs/assets/viewer.js/plugins/diffs/assets/viewer-runtime.js
Das Viewer-Dokument löst diese Assets relativ zur Viewer-URL auf, sodass ein optionales baseUrl-Pfadpräfix auch für beide Asset-Anfragen erhalten bleibt.
Verhalten bei der URL-Erstellung:
- Wenn
baseUrlim Tool-Aufruf angegeben ist, wird es nach strenger Validierung verwendet. - Andernfalls wird, wenn Plugin
viewerBaseUrlkonfiguriert ist, dieser Wert verwendet. - Ohne eine der beiden Überschreibungen verwendet die Viewer-URL standardmäßig loopback
127.0.0.1. - Wenn der Gateway-Bindemodus
customist undgateway.customBindHostgesetzt ist, wird dieser Host verwendet.
baseUrl-Regeln:
- Muss
http://oderhttps://sein. - Query und Hash werden abgelehnt.
- Ursprung plus optionaler Basispfad ist erlaubt.
Sicherheitsmodell
- Standardmäßig nur Loopback. - Tokenisierte Viewer-Pfade mit strenger ID- und Token-Validierung. - CSP für Viewer-Antworten: - `default-src 'none'` - Skripte und Assets nur von self - kein ausgehendes `connect-src` - Drosselung von Remote-Fehlschlägen, wenn Remote-Zugriff aktiviert ist: - 40 Fehlschläge pro 60 Sekunden - 60 Sekunden Sperre (`429 Too Many Requests`) - Das Request-Routing des Screenshot-Browsers ist standardmäßig ablehnend. - Nur lokale Viewer-Assets aus `http://127.0.0.1/plugins/diffs/assets/*` sind zulässig. - Externe Netzwerkanfragen werden blockiert.Browser-Anforderungen für den Dateimodus
mode: "file" und mode: "both" benötigen einen Chromium-kompatiblen Browser.
Auflösungsreihenfolge:
`browser.executablePath` in der OpenClaw-Konfiguration. - `OPENCLAW_BROWSER_EXECUTABLE_PATH` - `BROWSER_EXECUTABLE_PATH` - `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` Fallback für die Erkennung von Plattformbefehl/-pfad.Häufiger Fehlertext:
Diff PNG/PDF rendering requires a Chromium-compatible browser...
Beheben Sie dies, indem Sie Chrome, Chromium, Edge oder Brave installieren oder eine der oben genannten Optionen für den ausführbaren Pfad festlegen.
Fehlerbehebung
- `Provide patch or both before and after text.` — geben Sie sowohl `before` als auch `after` an oder stellen Sie `patch` bereit. - `Provide either patch or before/after input, not both.` — mischen Sie keine Eingabemodi. - `Invalid baseUrl: ...` — verwenden Sie einen `http(s)`-Origin mit optionalem Pfad, ohne Query/Hash. - `{field} exceeds maximum size (...)` — reduzieren Sie die Payload-Größe. - Ablehnung großer Patches — reduzieren Sie die Anzahl der Patch-Dateien oder die Gesamtzahl der Zeilen. - Die Viewer-URL wird standardmäßig zu `127.0.0.1` aufgelöst. - Für Szenarien mit Remote-Zugriff gilt entweder: - setzen Sie Plugin `viewerBaseUrl`, oder - übergeben Sie `baseUrl` pro Tool-Aufruf, oder - verwenden Sie `gateway.bind=custom` und `gateway.customBindHost` - Wenn `gateway.trustedProxies` Loopback für einen Proxy auf demselben Host enthält (zum Beispiel Tailscale Serve), schlagen rohe Loopback-Viewer-Anfragen ohne weitergeleitete Client-IP-Header konstruktionsbedingt geschlossen fehl. - Für diese Proxy-Topologie: - bevorzugen Sie `mode: "file"` oder `mode: "both"`, wenn Sie nur einen Anhang benötigen, oder - aktivieren Sie bewusst `security.allowRemoteViewer` und setzen Sie Plugin `viewerBaseUrl` oder übergeben Sie eine Proxy-/öffentliche `baseUrl`, wenn Sie eine teilbare Viewer-URL benötigen - Aktivieren Sie `security.allowRemoteViewer` nur, wenn Sie externen Viewer-Zugriff beabsichtigen. Dies kann bei Patch-Eingaben passieren, wenn der Patch keinen erweiterbaren Kontext enthält. Dies ist erwartet und weist nicht auf einen Viewer-Fehler hin. - Artefakt ist aufgrund von TTL abgelaufen. - Token oder Pfad wurde geändert. - Bereinigung hat veraltete Daten entfernt.Betriebliche Hinweise
- Bevorzugen Sie
mode: "view"für lokale interaktive Reviews im Canvas. - Bevorzugen Sie
mode: "file"für ausgehende Chat-Kanäle, die einen Anhang benötigen. - Lassen Sie
allowRemoteViewerdeaktiviert, sofern Ihre Bereitstellung keine Remote-Viewer-URLs erfordert. - Legen Sie explizit kurze
ttlSecondsfür sensible Diffs fest. - Vermeiden Sie es, Secrets in Diff-Eingaben zu senden, wenn dies nicht erforderlich ist.
- Wenn Ihr Kanal Bilder stark komprimiert (zum Beispiel Telegram oder WhatsApp), bevorzugen Sie PDF-Ausgabe (
fileFormat: "pdf").