Differenze

diffs è uno strumento Plugin opzionale con una breve guida di sistema integrata e una Skill associata che trasforma il contenuto delle modifiche in un artefatto diff di sola lettura per gli agenti.

Accetta alternativamente:

• testo before e after
• una patch unificata

Può restituire:

• un URL del visualizzatore Gateway per la presentazione su canvas
• un percorso di file renderizzato (PNG o PDF) per la consegna dei messaggi
• entrambi gli output in una sola chiamata

Quando è abilitato, il Plugin antepone una guida d'uso concisa nello spazio del prompt di sistema ed espone anche una Skill dettagliata per i casi in cui l'agente abbia bisogno di istruzioni più complete.

Avvio rapido

openclaw plugins install diffs

{  plugins: {    entries: {      diffs: {        enabled: true,      },    },  },}

Disabilitare la guida di sistema integrata

Se vuoi mantenere abilitato lo strumento diffs ma disabilitare la sua guida integrata nel prompt di sistema, imposta plugins.entries.diffs.hooks.allowPromptInjection su false:

{  plugins: {    entries: {      diffs: {        enabled: true,        hooks: {          allowPromptInjection: false,        },      },    },  },}

Questo blocca l'hook before_prompt_build del Plugin diffs mantenendo disponibili il Plugin, lo strumento e la Skill associata.

Se vuoi disabilitare sia la guida sia lo strumento, disabilita invece il Plugin.

Flusso di lavoro tipico dell'agente

Esempi di input

{  "before": "# Hello\n\nOne",  "after": "# Hello\n\nTwo",  "path": "docs/example.md",  "mode": "view"}

{  "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"}

Riferimento dell'input dello strumento

Tutti i campi sono opzionali, salvo diversa indicazione.

Evidenziazione della sintassi

OpenClaw include l'evidenziazione della sintassi per linguaggi comuni di sorgente, configurazione e documentazione:

javascript, typescript, tsx, jsx, json, markdown, yaml, css, html, sh, python, go, rust, java, c, cpp, csharp, php, sql, docker, ruby, swift, kotlin, r, dart, lua, powershell, xml e toml.

Alias comuni come js, ts, bash, md, yml, c++, dockerfile, rb, kt e ps1 sono normalizzati a quei linguaggi predefiniti.

Installa il Plugin Diff Viewer Language Pack per evidenziare altri linguaggi:

openclaw plugins install clawhub:@openclaw/diffs-language-pack

Con il pacchetto linguistico disponibile, OpenClaw può evidenziare molti più linguaggi. Se il pacchetto non è installato, i file al di fuori dell'elenco predefinito vengono comunque visualizzati come testo semplice leggibile. Gli esempi includono Astro, Vue, Svelte, MDX, GraphQL, Terraform/HCL, Nix, Clojure, Elixir, Haskell, OCaml, Scala, Zig, Solidity, Verilog/VHDL, Fortran, MATLAB, LaTeX, Mermaid, Sass/Less/SCSS, Nginx, Apache, CSV, dotenv, INI e file diff.

Consulta il Plugin Diffs Language Pack per i dettagli e i linguaggi Shiki per il catalogo upstream di linguaggi e alias di Shiki.

Contratto dei dettagli di output

Lo strumento restituisce metadati strutturati sotto details.

Riepilogo del comportamento delle modalità:

Sezioni invariate compresse

• Il visualizzatore può mostrare righe come N unmodified lines.
• I controlli di espansione su tali righe sono condizionali e non garantiti per ogni tipo di input.
• I controlli di espansione vengono visualizzati quando il diff renderizzato contiene dati di contesto espandibili, cosa tipica per input prima e dopo.
• Per molti input patch unificati, i corpi del contesto omessi non sono disponibili negli hunk della patch analizzata, quindi la riga può comparire senza controlli di espansione. Questo è il comportamento previsto.
• expandUnchanged si applica solo quando esiste un contesto espandibile.

Valori predefiniti del Plugin

Imposta i valori predefiniti a livello di Plugin in ~/.openclaw/openclaw.json:

{  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",            ttlSeconds: 21600,          },        },      },    },  },}

Valori predefiniti supportati:

• fontFamily
• fontSize
• lineSpacing
• layout
• showLineNumbers
• diffIndicators
• wordWrap
• background
• theme
• fileFormat
• fileQuality
• fileScale
• fileMaxWidth
• mode
• ttlSeconds

I parametri espliciti dello strumento sovrascrivono questi valori predefiniti.

Configurazione URL persistente del visualizzatore

{  plugins: {    entries: {      diffs: {        enabled: true,        config: {          viewerBaseUrl: "https://gateway.example.com/openclaw",        },      },    },  },}

Configurazione di sicurezza

{  plugins: {    entries: {      diffs: {        enabled: true,        config: {          security: {            allowRemoteViewer: false,          },        },      },    },  },}

Ciclo di vita e archiviazione degli artefatti

• Gli artefatti sono archiviati nella sottocartella temporanea: $TMPDIR/openclaw-diffs.
• I metadati dell'artefatto del visualizzatore contengono:
  • ID artefatto casuale (20 caratteri esadecimali)
  • token casuale (48 caratteri esadecimali)
  • createdAt ed expiresAt
  • percorso viewer.html archiviato
• La TTL predefinita dell'artefatto è di 30 minuti quando non specificata.
• La TTL massima accettata per il visualizzatore è di 6 ore.
• La pulizia viene eseguita in modo opportunistico dopo la creazione dell'artefatto.
• Gli artefatti scaduti vengono eliminati.
• La pulizia di fallback rimuove le cartelle obsolete più vecchie di 24 ore quando mancano i metadati.

URL del visualizzatore e comportamento di rete

Route del visualizzatore:

• /plugins/diffs/view/{artifactId}/{token}

Asset del visualizzatore:

• /plugins/diffs/assets/viewer.js
• /plugins/diffs/assets/viewer-runtime.js
• /plugins/diffs-language-pack/assets/viewer.js quando il diff usa una lingua del Diff Viewer Language Pack

Il documento del visualizzatore risolve questi asset in modo relativo all'URL del visualizzatore, quindi un prefisso di percorso baseUrl facoltativo viene preservato anche per entrambe le richieste di asset.

Comportamento di costruzione dell'URL:

• Se viene fornito baseUrl della tool-call, viene usato dopo una validazione rigorosa.
• Altrimenti, se è configurato viewerBaseUrl del Plugin, viene usato.
• Senza nessuna delle due sostituzioni, l'URL del visualizzatore usa per impostazione predefinita il loopback 127.0.0.1.
• Se la modalità di bind del Gateway è custom e gateway.customBindHost è impostato, viene usato quell'host.

Regole di baseUrl:

• Deve essere http:// o https://.
• Query e hash vengono rifiutati.
• Sono consentiti origin più percorso base facoltativo.

Modello di sicurezza

Requisiti del browser per la modalità file

mode: "file" e mode: "both" richiedono un browser compatibile con Chromium.

Ordine di risoluzione:

Testo di errore comune:

• Diff PNG/PDF rendering requires a Chromium-compatible browser...

Correggi installando Chrome, Chromium, Edge o Brave, oppure impostando una delle opzioni di percorso dell'eseguibile sopra indicate.

Risoluzione dei problemi

Indicazioni operative

• Preferisci mode: "view" per revisioni interattive locali nel canvas.
• Preferisci mode: "file" per canali chat in uscita che richiedono un allegato.
• Mantieni allowRemoteViewer disabilitato salvo che il tuo deployment richieda URL del visualizzatore remoti.
• Imposta ttlSeconds brevi espliciti per diff sensibili.
• Evita di inviare segreti nell'input del diff quando non necessario.
• Se il tuo canale comprime le immagini in modo aggressivo (ad esempio Telegram o WhatsApp), preferisci l'output PDF (fileFormat: "pdf").

Correlati

• Browser
• Plugin
• Panoramica degli strumenti