Diferenças

diffs é uma ferramenta opcional de Plugin com orientação de sistema integrada curta e uma skill complementar que transforma conteúdo de alterações em um artefato de diff somente leitura para agentes.

Ela aceita:

• texto before e after
• um patch unificado

Ela pode retornar:

• uma URL do visualizador do Gateway para apresentação em canvas
• um caminho de arquivo renderizado (PNG ou PDF) para entrega por mensagem
• ambas as saídas em uma única chamada

Quando ativado, o Plugin antepõe uma orientação de uso concisa no espaço do prompt de sistema e também expõe uma skill detalhada para casos em que o agente precisa de instruções mais completas.

# Início rápido

openclaw plugins install diffs

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

# Desativar a orientação de sistema integrada

Se você quiser manter a ferramenta diffs ativada, mas desativar sua orientação integrada de prompt de sistema, defina plugins.entries.diffs.hooks.allowPromptInjection como false:

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

Isso bloqueia o hook before_prompt_build do Plugin diffs, mantendo o Plugin, a ferramenta e a skill complementar disponíveis.

Se você quiser desativar tanto a orientação quanto a ferramenta, desative o Plugin.

# Fluxo de trabalho típico do agente

# Exemplos 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"
}

# Referência de entrada da ferramenta

Todos os campos são opcionais, salvo indicação em contrário.

# Contrato de detalhes de saída

A ferramenta retorna metadados estruturados em details.

Resumo do comportamento de modos:

# Seções inalteradas recolhidas

• O visualizador pode mostrar linhas como N unmodified lines.
• Os controles de expansão nessas linhas são condicionais e não são garantidos para todos os tipos de entrada.
• Os controles de expansão aparecem quando o diff renderizado tem dados de contexto expansíveis, o que é típico para entradas antes e depois.
• Para muitas entradas de patch unificado, corpos de contexto omitidos não estão disponíveis nos hunks do patch analisado, então a linha pode aparecer sem controles de expansão. Esse é o comportamento esperado.
• expandUnchanged se aplica somente quando existe contexto expansível.

# Padrões do Plugin

Defina padrões em todo o Plugin em ~/.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",
          },
        },
      },
    },
  },
}

Padrões compatíveis:

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

Parâmetros explícitos da ferramenta substituem esses padrões.

# Configuração persistente da URL do visualizador

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

# Configuração de segurança

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

# Ciclo de vida e armazenamento de artefatos

• Artefatos são armazenados na subpasta temporária: $TMPDIR/openclaw-diffs.
• Metadados do artefato do visualizador contêm:
  • ID de artefato aleatório (20 caracteres hexadecimais)
  • token aleatório (48 caracteres hexadecimais)
  • createdAt e expiresAt
  • caminho armazenado de viewer.html
• O TTL padrão do artefato é de 30 minutos quando não especificado.
• O TTL máximo aceito do visualizador é de 6 horas.
• A limpeza é executada de forma oportunista após a criação do artefato.
• Artefatos expirados são excluídos.
• A limpeza de fallback remove pastas obsoletas com mais de 24 horas quando metadados estão ausentes.

# URL do visualizador e comportamento de rede

Rota do visualizador:

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

Recursos do visualizador:

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

O documento do visualizador resolve esses recursos em relação à URL do visualizador, então um prefixo de caminho opcional de baseUrl também é preservado para ambas as solicitações de recursos.

Comportamento de construção de URL:

• Se baseUrl da chamada de ferramenta for fornecido, ele será usado após validação estrita.
• Caso contrário, se viewerBaseUrl do Plugin estiver configurado, ele será usado.
• Sem nenhuma dessas substituições, a URL do visualizador usa como padrão o loopback 127.0.0.1.
• Se o modo de bind do Gateway for custom e gateway.customBindHost estiver definido, esse host será usado.

Regras de baseUrl:

• Deve ser http:// ou https://.
• Consulta e hash são rejeitados.
• Origem mais caminho base opcional é permitido.

# Modelo de segurança

# Requisitos de navegador para modo de arquivo

mode: "file" e mode: "both" precisam de um navegador compatível com Chromium.

Ordem de resolução:

Texto comum de falha:

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

Corrija instalando Chrome, Chromium, Edge ou Brave, ou configurando uma das opções de caminho do executável acima.

# Solução de problemas

# Orientações operacionais

• Prefira mode: "view" para revisões interativas locais no canvas.
• Prefira mode: "file" para canais de chat de saída que precisam de um anexo.
• Mantenha allowRemoteViewer desabilitado, a menos que sua implantação exija URLs remotas de visualizador.
• Defina ttlSeconds curtos e explícitos para diffs confidenciais.
• Evite enviar segredos na entrada de diff quando não for necessário.
• Se seu canal compacta imagens de forma agressiva (por exemplo, Telegram ou WhatsApp), prefira saída em PDF (fileFormat: "pdf").

# Relacionado

• Navegador
• Plugins
• Visão geral das ferramentas