Différences

diffs est un outil de Plugin facultatif avec de courtes consignes système intégrées et une Skills compagnon qui transforme le contenu des modifications en artefact de 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 sur canvas
• un chemin de fichier rendu (PNG ou PDF) pour l’envoi dans un message
• les deux sorties dans un seul appel

Lorsqu’il est activé, le Plugin ajoute des consignes d’utilisation concises dans l’espace de prompt système et expose aussi une Skills détaillée 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 consignes système intégrées

Si vous voulez garder l’outil diffs activé mais désactiver ses consignes 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 le Plugin, l’outil et la Skills compagnon disponibles.

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

# Workflow d’agent typique

# 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 des entrées de l’outil

Tous les champs sont facultatifs sauf indication contraire.

# 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 repliées

• Le visualiseur peut afficher des lignes comme N unmodified lines.
• Les contrôles de développement sur ces lignes sont conditionnels et ne sont pas garantis pour chaque type d’entrée.
• Les contrôles de développement apparaissent lorsque le diff rendu contient des données de contexte développables, ce qui est typique pour une entrée avant et après.
• Pour de nombreuses entrées de patch unifié, les corps de contexte omis ne sont pas disponibles dans les hunks de patch analysés, la ligne peut donc apparaître sans contrôles de développement. C’est le comportement attendu.
• expandUnchanged s’applique uniquement lorsqu’un contexte développable 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",
          },
        },
      },
    },
  },
}

Valeurs par défaut prises en charge :

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

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

# Configuration persistante de l’URL du visualiseur

{
  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 de l’artefact du visualiseur 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 le visualiseur 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 repli supprime les dossiers obsolètes de plus de 24 heures lorsque les métadonnées sont absentes.

# URL du visualiseur et comportement réseau

Route du visualiseur :

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

Ressources du visualiseur :

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

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

Comportement de construction de l’URL :

• Si le baseUrl de l’appel d’outil est fourni, il est utilisé après une validation stricte.
• Sinon, si le viewerBaseUrl du Plugin est configuré, il est utilisé.
• Sans l’un ou l’autre remplacement, l’URL du visualiseur utilise par défaut le loopback 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 plus 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 avec Chromium.

Ordre de résolution :

Texte d’échec courant :

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

Corrigez le problème 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 canevas.
• 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 visualiseur distant.
• Définissez des ttlSeconds courts explicites 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 fortement les images (par exemple Telegram ou WhatsApp), préférez la sortie PDF (fileFormat: "pdf").

# Connexe

• Navigateur
• Plugins
• Vue d’ensemble des outils