Diffs

diffs é uma ferramenta opcional de Plugin com orientação de sistema curta integrada e uma skill complementar que transforma conteúdo de alterações em um artefato 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 habilitado, o Plugin acrescenta orientações concisas de uso ao 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,      },    },  },}

Desabilitar a orientação de sistema integrada

Se você quiser manter a ferramenta diffs habilitada, mas desabilitar 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 desabilitar tanto a orientação quanto a ferramenta, desabilite o Plugin em vez disso.

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.

Realce de sintaxe

OpenClaw inclui realce de sintaxe para linguagens comuns de código-fonte, configuração e documentação:

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

Aliases comuns como js, ts, bash, md, yml, c++, dockerfile, rb, kt e ps1 são normalizados para essas linguagens padrão.

Instale o Plugin Diff Viewer Language Pack para destacar outras linguagens:

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

Com o pacote de linguagens disponível, o OpenClaw consegue destacar muito mais linguagens. Se o pacote não estiver instalado, arquivos fora da lista padrão ainda serão renderizados como texto simples legível. Exemplos incluem 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 e arquivos diff.

Veja o Plugin Diffs Language Pack para detalhes e linguagens do Shiki para o catálogo upstream de linguagens e aliases do Shiki.

Contrato de detalhes de saída

A ferramenta retorna metadados estruturados em details.

Resumo do comportamento dos 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 todo tipo 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, os 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 apenas quando existe contexto expansível.

Padrões do Plugin

Defina padrões para 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",            ttlSeconds: 21600,          },        },      },    },  },}

Padrões compatíveis:

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

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

Configuração persistente de 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

• Os artefatos são armazenados na subpasta temporária: $TMPDIR/openclaw-diffs.
• Os metadados do artefato do visualizador contêm:
  • ID aleatório do artefato (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 oportunisticamente 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 os metadados estão ausentes.

URL do visualizador e comportamento de rede

Rota do visualizador:

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

Assets do visualizador:

• /plugins/diffs/assets/viewer.js
• /plugins/diffs/assets/viewer-runtime.js
• /plugins/diffs-language-pack/assets/viewer.js quando o diff usa uma linguagem do Diff Viewer Language Pack

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

Comportamento de construção de URL:

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

Regras de baseUrl:

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

Modelo de segurança

Requisitos de navegador para o 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 definindo uma das opções de caminho de executável acima.

Solução de problemas

Orientação operacional

• 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 do visualizador.
• Defina ttlSeconds curto explícito para diffs sensíveis.
• Evite enviar segredos na entrada de diff quando não for necessário.
• Se seu canal comprime imagens de forma agressiva (por exemplo, Telegram ou WhatsApp), prefira saída em PDF (fileFormat: "pdf").

Relacionado

• Navegador
• Plugins
• Visão geral das ferramentas