Differenze

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

Accetta uno tra:

• testo before e after
• una patch unificata

Può restituire:

• un URL del viewer del Gateway per la presentazione su canvas
• un percorso di file renderizzato (PNG o PDF) per la consegna nei messaggi
• entrambi gli output in una singola 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 ha 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 per il 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 complementare.

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.

# Contratto dei dettagli di output

Lo strumento restituisce metadati strutturati sotto details.

Riepilogo del comportamento delle modalità:

# Sezioni non modificate compresse

• Il viewer può mostrare righe come N unmodified lines.
• I controlli di espansione su quelle righe sono condizionali e non garantiti per ogni tipo di input.
• I controlli di espansione appaiono quando il diff renderizzato contiene dati di contesto espandibili, cosa tipica per l’input before and after.
• Per molti input di patch unificate, i corpi del contesto omessi non sono disponibili negli hunk della patch analizzata, quindi la riga può apparire senza controlli di espansione. Questo è il comportamento previsto.
• expandUnchanged si applica solo quando esiste contesto espandibile.

# Default del Plugin

Imposta i default 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",
          },
        },
      },
    },
  },
}

Default supportati:

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

I parametri espliciti dello strumento sovrascrivono questi default.

# Configurazione persistente dell’URL del viewer

{
  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 viewer contengono:
  • ID artefatto casuale (20 caratteri esadecimali)
  • token casuale (48 caratteri esadecimali)
  • createdAt e expiresAt
  • percorso viewer.html archiviato
• Il TTL predefinito dell’artefatto è 30 minuti quando non specificato.
• Il TTL massimo accettato per il viewer è 6 ore.
• La pulizia viene eseguita opportunisticamente dopo la creazione dell’artefatto.
• Gli artefatti scaduti vengono eliminati.
• La pulizia di fallback rimuove le cartelle obsolete più vecchie di 24 ore quando i metadati sono mancanti.

# URL del viewer e comportamento di rete

Route del viewer:

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

Asset del viewer:

• /plugins/diffs/assets/viewer.js
• /plugins/diffs/assets/viewer-runtime.js

Il documento viewer risolve questi asset in modo relativo all’URL del viewer, quindi un prefisso di percorso baseUrl opzionale viene preservato anche per entrambe le richieste degli asset.

Comportamento di costruzione dell’URL:

• Se viene fornito baseUrl nella chiamata dello strumento, viene usato dopo una validazione rigorosa.
• Altrimenti, se viewerBaseUrl del Plugin è configurato, viene usato.
• Senza nessuno dei due override, l’URL del viewer usa per default 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.
• È consentita l’origine più un percorso base opzionale.

# 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...

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

# Risoluzione dei problemi

# Indicazioni operative

• Preferisci mode: "view" per revisioni interattive locali nel canvas.
• Preferisci mode: "file" per canali di chat in uscita che richiedono un allegato.
• Mantieni allowRemoteViewer disabilitato a meno che la tua distribuzione non richieda URL remoti del visualizzatore.
• Imposta ttlSeconds brevi ed 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