Différences

diffs est un outil de Plugin optionnel avec de brèves instructions système intégrées et un Skills compagnon qui transforme le contenu de changements en artefact diff en lecture seule pour les agents.

Il accepte soit :

• du texte before et after
• un patch unifié

Il peut renvoyer :

• une URL de visualiseur Gateway pour une présentation canvas
• un chemin de fichier rendu (PNG ou PDF) pour l’envoi par message
• les deux sorties en un seul appel

Lorsqu’il est activé, le Plugin ajoute des instructions d’utilisation concises dans l’espace du prompt système et expose aussi un Skills détaillé pour les cas où l’agent a besoin d’instructions plus complètes.

Démarrage rapide

openclaw plugins install diffs

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

Désactiver les instructions système intégrées

Si vous souhaitez garder l’outil diffs activé mais désactiver ses instructions intégrées de prompt système, définissez plugins.entries.diffs.hooks.allowPromptInjection sur false :

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

Cela bloque le hook before_prompt_build du plugin diffs tout en gardant disponibles le Plugin, l’outil et le Skills compagnon.

Si vous souhaitez désactiver à la fois les instructions et l’outil, désactivez plutôt le Plugin.

Flux de travail typique de l’agent

Exemples d’entrée

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

Référence de l’entrée de l’outil

Tous les champs sont optionnels, sauf indication contraire.

Coloration syntaxique

OpenClaw inclut la coloration syntaxique pour les langages courants de code source, de configuration et de documentation :

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 et toml.

Les alias courants tels que js, ts, bash, md, yml, c++, dockerfile, rb, kt et ps1 sont normalisés vers ces langages par défaut.

Installez le plugin Diff Viewer Language Pack pour mettre en évidence d’autres langages :

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

Avec le pack de langage disponible, OpenClaw peut mettre en évidence beaucoup plus de langages. Si le pack n’est pas installé, les fichiers hors de la liste par défaut sont tout de même affichés sous forme de texte brut lisible. Exemples : 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 et fichiers diff.

Consultez le plugin Diffs Language Pack pour plus de détails et les langages Shiki pour le catalogue amont des langages et alias de Shiki.

Contrat des détails de sortie

L’outil renvoie des métadonnées structurées sous details.

Résumé du comportement des modes :

Sections inchangées réduites

• La visionneuse peut afficher des lignes comme N unmodified lines.
• Les contrôles d’expansion sur ces lignes sont conditionnels et ne sont pas garantis pour chaque type d’entrée.
• Les contrôles d’expansion apparaissent lorsque le diff généré dispose de données de contexte extensibles, ce qui est typique pour une entrée avant/après.
• Pour de nombreuses entrées de correctif unifié, les corps de contexte omis ne sont pas disponibles dans les hunks du correctif analysé ; la ligne peut donc apparaître sans contrôles d’expansion. C’est le comportement attendu.
• expandUnchanged s’applique uniquement lorsqu’un contexte extensible existe.

Valeurs par défaut du plugin

Définissez les valeurs par défaut à l’échelle du plugin dans ~/.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,          },        },      },    },  },}

Valeurs par défaut prises en charge :

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

Les paramètres explicites de l’outil remplacent ces valeurs par défaut.

Configuration de l’URL de visionneuse persistante

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

Configuration de sécurité

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

Cycle de vie et stockage des artefacts

• Les artefacts sont stockés dans le sous-dossier temporaire : $TMPDIR/openclaw-diffs.
• Les métadonnées d’artefact de la visionneuse contiennent :
  • un ID d’artefact aléatoire (20 caractères hexadécimaux)
  • un jeton aléatoire (48 caractères hexadécimaux)
  • createdAt et expiresAt
  • le chemin viewer.html stocké
• La TTL d’artefact par défaut est de 30 minutes lorsqu’elle n’est pas spécifiée.
• La TTL maximale acceptée pour la visionneuse est de 6 heures.
• Le nettoyage s’exécute de manière opportuniste après la création d’un artefact.
• Les artefacts expirés sont supprimés.
• Le nettoyage de secours supprime les dossiers obsolètes de plus de 24 heures lorsque les métadonnées sont manquantes.

URL de la visionneuse et comportement réseau

Route de la visionneuse :

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

Ressources de la visionneuse :

• /plugins/diffs/assets/viewer.js
• /plugins/diffs/assets/viewer-runtime.js
• /plugins/diffs-language-pack/assets/viewer.js lorsque le diff utilise une langue du pack de langue de la visionneuse de diff

Le document de la visionneuse résout ces ressources relativement à l’URL de la visionneuse ; un préfixe de chemin baseUrl facultatif est donc également conservé pour les deux requêtes de ressources.

Comportement de construction d’URL :

• Si le baseUrl d’appel d’outil est fourni, il est utilisé après validation stricte.
• Sinon, si le viewerBaseUrl du Plugin est configuré, il est utilisé.
• Sans l’une ou l’autre surcharge, l’URL de la visionneuse utilise par défaut le bouclage 127.0.0.1.
• Si le mode de liaison du Gateway est custom et que gateway.customBindHost est défini, cet hôte est utilisé.

Règles de baseUrl :

• Doit être http:// ou https://.
• Les requêtes et les fragments sont rejetés.
• L’origine avec un chemin de base facultatif est autorisée.

Modèle de sécurité

Exigences du navigateur pour le mode fichier

mode: "file" et mode: "both" nécessitent un navigateur compatible Chromium.

Ordre de résolution :

Texte d’erreur courant :

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

Corrigez en installant Chrome, Chromium, Edge ou Brave, ou en définissant l’une des options de chemin d’exécutable ci-dessus.

Dépannage

Conseils opérationnels

• Préférez mode: "view" pour les revues interactives locales dans le canvas.
• Préférez mode: "file" pour les canaux de discussion sortants qui nécessitent une pièce jointe.
• Gardez allowRemoteViewer désactivé sauf si votre déploiement nécessite des URL de visionneuse distantes.
• Définissez un ttlSeconds court explicite pour les diffs sensibles.
• Évitez d’envoyer des secrets dans l’entrée de diff lorsque ce n’est pas nécessaire.
• Si votre canal compresse les images de manière agressive (par exemple Telegram ou WhatsApp), préférez la sortie PDF (fileFormat: "pdf").

Connexe

• Navigateur
• Plugins
• Vue d’ensemble des outils