Diferencias

diffs es una herramienta de plugin opcional con una guía breve integrada del sistema y una skill complementaria que convierte el contenido de cambios en un artefacto diff de solo lectura para agentes.

Acepta cualquiera de estos:

• texto before y after
• un patch unificado

Puede devolver:

• una URL del visor del gateway para presentación en canvas
• una ruta de archivo renderizado (PNG o PDF) para entrega por mensaje
• ambas salidas en una sola llamada

Cuando está habilitado, el plugin antepone una guía concisa de uso en el espacio del prompt del sistema y también expone una skill detallada para casos en los que el agente necesita instrucciones más completas.

# Inicio rápido

openclaw plugins install diffs

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

# Deshabilitar la guía integrada del sistema

Si quieres mantener habilitada la herramienta diffs pero deshabilitar su guía integrada del prompt del sistema, establece plugins.entries.diffs.hooks.allowPromptInjection en false:

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

Esto bloquea el hook before_prompt_build del plugin diffs mientras mantiene disponibles el plugin, la herramienta y la skill complementaria.

Si quieres deshabilitar tanto la guía como la herramienta, deshabilita el plugin en su lugar.

# Flujo de trabajo típico del agente

# Ejemplos de entrada

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

# Referencia de entrada de la herramienta

Todos los campos son opcionales salvo que se indique lo contrario.

# Contrato de detalles de salida

La herramienta devuelve metadatos estructurados bajo details.

Resumen del comportamiento por modo:

# Secciones sin cambios contraídas

• El visor puede mostrar filas como N unmodified lines.
• Los controles de expansión en esas filas son condicionales y no están garantizados para todos los tipos de entrada.
• Los controles de expansión aparecen cuando el diff renderizado tiene datos de contexto expandibles, lo que es habitual para entradas before y after.
• Para muchas entradas de patch unificado, los cuerpos de contexto omitidos no están disponibles en los hunks del patch analizados, por lo que la fila puede aparecer sin controles de expansión. Este es el comportamiento esperado.
• expandUnchanged se aplica solo cuando existe contexto expandible.

# Valores predeterminados del plugin

Establece valores predeterminados para todo el plugin en ~/.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",
          },
        },
      },
    },
  },
}

Valores predeterminados admitidos:

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

Los parámetros explícitos de la herramienta anulan estos valores predeterminados.

# Configuración persistente de URL del visor

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

# Configuración de seguridad

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

# Ciclo de vida y almacenamiento de artefactos

• Los artefactos se almacenan bajo la subcarpeta temporal: $TMPDIR/openclaw-diffs.
• Los metadatos del artefacto de visor contienen:
  • ID de artefacto aleatorio (20 caracteres hexadecimales)
  • token aleatorio (48 caracteres hexadecimales)
  • createdAt y expiresAt
  • ruta viewer.html almacenada
• El TTL predeterminado del artefacto es de 30 minutos cuando no se especifica.
• El TTL máximo aceptado del visor es de 6 horas.
• La limpieza se ejecuta de forma oportunista después de la creación del artefacto.
• Los artefactos caducados se eliminan.
• La limpieza de respaldo elimina carpetas obsoletas de más de 24 horas cuando faltan metadatos.

# URL del visor y comportamiento de red

Ruta del visor:

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

Recursos del visor:

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

El documento del visor resuelve esos recursos de forma relativa a la URL del visor, por lo que también se conserva un prefijo de ruta opcional de baseUrl para ambas solicitudes de recursos.

Comportamiento de construcción de URL:

• Si se proporciona baseUrl en la llamada de herramienta, se usa después de una validación estricta.
• De lo contrario, si está configurado viewerBaseUrl del plugin, se usa.
• Sin ninguna de las dos anulaciones, la URL del visor usa de forma predeterminada loopback 127.0.0.1.
• Si el modo de vinculación del gateway es custom y gateway.customBindHost está configurado, se usa ese host.

Reglas de baseUrl:

• Debe ser http:// o https://.
• Se rechazan consulta y hash.
• Se permite origen más ruta base opcional.

# Modelo de seguridad

# Requisitos del navegador para el modo de archivo

mode: "file" y mode: "both" necesitan un navegador compatible con Chromium.

Orden de resolución:

Texto común de error:

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

Soluciónalo instalando Chrome, Chromium, Edge o Brave, o configurando una de las opciones de ruta de ejecutable anteriores.

# Solución de problemas

# Guía operativa

• Prefiere mode: "view" para revisiones interactivas locales en el lienzo.
• Prefiere mode: "file" para canales de chat salientes que necesitan un adjunto.
• Mantén allowRemoteViewer deshabilitado salvo que tu implementación requiera URL de visor remotas.
• Configura valores explícitos y cortos de ttlSeconds para diffs sensibles.
• Evita enviar secretos en la entrada del diff cuando no sea necesario.
• Si tu canal comprime imágenes agresivamente (por ejemplo, Telegram o WhatsApp), prefiere la salida PDF (fileFormat: "pdf").

# Relacionado

• Navegador
• Plugins
• Resumen de herramientas