Różnice

diffs to opcjonalne narzędzie Plugin z krótkimi wbudowanymi wskazówkami systemowymi i towarzyszącą mu umiejętnością, która przekształca treść zmian w artefakt różnic tylko do odczytu dla agentów.

Przyjmuje jedno z poniższych:

• tekst before i after
• ujednolicony patch

Może zwrócić:

• adres URL przeglądarki Gateway do prezentacji na kanwie
• ścieżkę wyrenderowanego pliku (PNG lub PDF) do dostarczenia w wiadomości
• oba wyniki w jednym wywołaniu

Po włączeniu Plugin dodaje zwięzłe wskazówki użycia do przestrzeni promptu systemowego i udostępnia też szczegółową umiejętność dla przypadków, w których agent potrzebuje pełniejszych instrukcji.

# Szybki start

openclaw plugins install diffs

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

# Wyłączanie wbudowanych wskazówek systemowych

Jeśli chcesz pozostawić narzędzie diffs włączone, ale wyłączyć jego wbudowane wskazówki promptu systemowego, ustaw plugins.entries.diffs.hooks.allowPromptInjection na false:

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

Blokuje to hook before_prompt_build Plugin diffs, pozostawiając Plugin, narzędzie i towarzyszącą umiejętność dostępne.

Jeśli chcesz wyłączyć zarówno wskazówki, jak i narzędzie, wyłącz zamiast tego Plugin.

# Typowy przepływ pracy agenta

# Przykłady danych wejściowych

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

# Dokumentacja danych wejściowych narzędzia

Wszystkie pola są opcjonalne, chyba że zaznaczono inaczej.

# Kontrakt szczegółów wyjścia

Narzędzie zwraca ustrukturyzowane metadane w details.

Podsumowanie zachowania trybów:

# Zwinięte niezmienione sekcje

• Przeglądarka może pokazywać wiersze takie jak N unmodified lines.
• Elementy sterujące rozwijaniem w tych wierszach są warunkowe i nie są gwarantowane dla każdego rodzaju danych wejściowych.
• Elementy sterujące rozwijaniem pojawiają się, gdy wyrenderowany diff zawiera rozwijalne dane kontekstowe, co jest typowe dla danych wejściowych przed i po.
• W przypadku wielu danych wejściowych w postaci ujednoliconych łatek pominięte treści kontekstu nie są dostępne w sparsowanych hunkach łatki, więc wiersz może pojawić się bez elementów sterujących rozwijaniem. To oczekiwane zachowanie.
• expandUnchanged ma zastosowanie tylko wtedy, gdy istnieje rozwijalny kontekst.

# Wartości domyślne Plugin

Ustaw wartości domyślne dla całego Plugin w ~/.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",
          },
        },
      },
    },
  },
}

Obsługiwane wartości domyślne:

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

Jawne parametry narzędzia nadpisują te wartości domyślne.

# Konfiguracja trwałego adresu URL przeglądarki

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

# Konfiguracja bezpieczeństwa

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

# Cykl życia artefaktu i przechowywanie

• Artefakty są przechowywane w tymczasowym podfolderze: $TMPDIR/openclaw-diffs.
• Metadane artefaktu przeglądarki zawierają:
  • losowy identyfikator artefaktu (20 znaków szesnastkowych)
  • losowy token (48 znaków szesnastkowych)
  • createdAt i expiresAt
  • zapisaną ścieżkę viewer.html
• Domyślny TTL artefaktu wynosi 30 minut, gdy nie zostanie określony.
• Maksymalny akceptowany TTL przeglądarki wynosi 6 godzin.
• Czyszczenie uruchamia się oportunistycznie po utworzeniu artefaktu.
• Wygasłe artefakty są usuwane.
• Czyszczenie fallback usuwa nieaktualne foldery starsze niż 24 godziny, gdy brakuje metadanych.

# Adres URL przeglądarki i zachowanie sieci

Trasa przeglądarki:

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

Zasoby przeglądarki:

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

Dokument przeglądarki rozwiązuje te zasoby względem adresu URL przeglądarki, więc opcjonalny prefiks ścieżki baseUrl jest zachowywany także dla obu żądań zasobów.

Zachowanie konstruowania adresu URL:

• Jeśli podano baseUrl w wywołaniu narzędzia, jest ono używane po ścisłej walidacji.
• W przeciwnym razie, jeśli skonfigurowano viewerBaseUrl Plugin, jest ono używane.
• Bez żadnego z tych nadpisań adres URL przeglądarki domyślnie wskazuje loopback 127.0.0.1.
• Jeśli tryb bindowania Gateway to custom i ustawiono gateway.customBindHost, używany jest ten host.

Reguły baseUrl:

• Musi być http:// lub https://.
• Zapytanie i hash są odrzucane.
• Dozwolone jest źródło oraz opcjonalna ścieżka bazowa.

# Model bezpieczeństwa

# Wymagania przeglądarki dla trybu pliku

mode: "file" i mode: "both" wymagają przeglądarki zgodnej z Chromium.

Kolejność rozpoznawania:

Typowy tekst błędu:

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

Napraw to, instalując Chrome, Chromium, Edge albo Brave, lub ustawiając jedną z powyższych opcji ścieżki do pliku wykonywalnego.

# Rozwiązywanie problemów

# Wskazówki operacyjne

• Preferuj mode: "view" dla lokalnych interaktywnych przeglądów w canvas.
• Preferuj mode: "file" dla wychodzących kanałów czatu, które potrzebują załącznika.
• Pozostaw allowRemoteViewer wyłączone, chyba że wdrożenie wymaga zdalnych adresów URL viewer.
• Ustaw jawnie krótkie ttlSeconds dla wrażliwych diffów.
• Unikaj wysyłania sekretów w danych wejściowych diffu, gdy nie jest to wymagane.
• Jeśli Twój kanał agresywnie kompresuje obrazy (na przykład Telegram albo WhatsApp), preferuj wyjście PDF (fileFormat: "pdf").

# Powiązane

• Przeglądarka
• Plugins
• Przegląd narzędzi