Lorsque vous devez montrer des modifications sous forme de diff réel, préférez l'outil diffs plutôt que d'écrire un résumé manuel.
L'outil diffs accepte soit du texte before + after, soit une chaîne patch unifiée.
Vérifiez details.changed : une entrée identique avant/après retourne false sans créer d'artefact ; les résultats rendus retournent true.
Utilisez mode=view lorsque vous souhaitez un visualiseur interactif hébergé sur une passerelle. Une fois l'outil exécuté, présentez details.viewerUrl avec un outil de présentation de surface disponible.
Si le déploiement utilise un proxy de confiance en boucle locale (par exemple Tailscale Serve avec gateway.trustedProxies incluant 127.0.0.1), les requêtes brutes du visualiseur en boucle locale peuvent être rejetées sans en-têtes d'IP client transférées. Dans cette topologie, préférez mode=file / mode=both, ou utilisez un viewerBaseUrl configuré / un proxy explicite / baseUrl publique lorsque vous avez besoin d'une URL de visualiseur partageable.
Utilisez mode=file lorsque vous avez besoin d'un artefact fichier rendu. Définissez fileFormat=png (par défaut) ou fileFormat=pdf. Le résultat de l'outil inclut details.filePath.
Pour les fichiers volumineux ou de haute fidélité, utilisez fileQuality (standard|hq|print) et éventuellement fileScale/fileMaxWidth.
Lorsque vous devez livrer le fichier rendu à un utilisateur ou un canal, ne vous fiez pas au rendu brut du résultat de l'outil. Utilisez plutôt un outil d'envoi de fichier disponible pour envoyer details.filePath en pièce jointe.
Utilisez mode=both lorsque vous souhaitez à la fois l'URL du visualiseur de passerelle et l'artefact rendu.
Si l'utilisateur a configuré des valeurs par défaut pour le plugin diffs, préférez omettre mode, theme, layout et les options de présentation associées, sauf si vous devez les remplacer pour ce diff spécifique.
Incluez path pour le texte avant/après lorsque vous connaissez le nom du fichier.