Các khác biệt

diffs là một công cụ Plugin tùy chọn với hướng dẫn hệ thống tích hợp ngắn gọn và một skill đi kèm, dùng để biến nội dung thay đổi thành một artifact diff chỉ đọc cho agent.

Nó chấp nhận một trong hai dạng:

• văn bản before và after
• một patch hợp nhất

Nó có thể trả về:

• URL trình xem Gateway để trình bày trên canvas
• đường dẫn tệp đã render (PNG hoặc PDF) để gửi qua tin nhắn
• cả hai đầu ra trong một lần gọi

Khi được bật, Plugin sẽ thêm hướng dẫn sử dụng ngắn gọn vào không gian system-prompt và cũng cung cấp một skill chi tiết cho các trường hợp agent cần hướng dẫn đầy đủ hơn.

# Bắt đầu nhanh

openclaw plugins install diffs

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

# Tắt hướng dẫn hệ thống tích hợp

Nếu bạn muốn giữ công cụ diffs được bật nhưng tắt hướng dẫn system-prompt tích hợp của nó, hãy đặt plugins.entries.diffs.hooks.allowPromptInjection thành false:

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

Thao tác này chặn hook before_prompt_build của Plugin diffs trong khi vẫn giữ Plugin, công cụ và skill đi kèm khả dụng.

Nếu bạn muốn tắt cả hướng dẫn lẫn công cụ, hãy tắt Plugin thay vào đó.

# Quy trình agent điển hình

# Ví dụ đầu vào

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

# Tham chiếu đầu vào công cụ

Tất cả các trường đều là tùy chọn trừ khi có ghi chú.

# Hợp đồng chi tiết đầu ra

Công cụ trả về metadata có cấu trúc trong details.

Tóm tắt hành vi chế độ:

# Các phần không thay đổi được thu gọn

• Trình xem có thể hiển thị các hàng như N unmodified lines.
• Các điều khiển mở rộng trên những hàng đó là có điều kiện và không được bảo đảm cho mọi loại đầu vào.
• Các điều khiển mở rộng xuất hiện khi diff đã render có dữ liệu ngữ cảnh có thể mở rộng, điều này thường gặp với đầu vào trước và sau.
• Với nhiều đầu vào patch hợp nhất, nội dung ngữ cảnh bị bỏ qua không có trong các hunk patch đã phân tích, vì vậy hàng có thể xuất hiện mà không có điều khiển mở rộng. Đây là hành vi dự kiến.
• expandUnchanged chỉ áp dụng khi tồn tại ngữ cảnh có thể mở rộng.

# Giá trị mặc định của Plugin

Đặt các giá trị mặc định trên toàn Plugin trong ~/.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",
          },
        },
      },
    },
  },
}

Các giá trị mặc định được hỗ trợ:

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

Các tham số công cụ được chỉ định rõ sẽ ghi đè những giá trị mặc định này.

# Cấu hình URL trình xem bền vững

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

# Cấu hình bảo mật

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

# Vòng đời và lưu trữ artifact

• Artifact được lưu dưới thư mục con tạm thời: $TMPDIR/openclaw-diffs.
• Metadata artifact trình xem chứa:
  • ID artifact ngẫu nhiên (20 ký tự hex)
  • token ngẫu nhiên (48 ký tự hex)
  • createdAt và expiresAt
  • đường dẫn viewer.html đã lưu
• TTL artifact mặc định là 30 phút khi không được chỉ định.
• TTL trình xem tối đa được chấp nhận là 6 giờ.
• Dọn dẹp chạy theo thời cơ sau khi tạo artifact.
• Artifact hết hạn sẽ bị xóa.
• Dọn dẹp dự phòng xóa các thư mục cũ hơn 24 giờ khi thiếu metadata.

# URL trình xem và hành vi mạng

Route trình xem:

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

Asset trình xem:

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

Tài liệu trình xem phân giải các asset đó tương đối với URL trình xem, vì vậy tiền tố đường dẫn baseUrl tùy chọn cũng được giữ lại cho cả các yêu cầu asset.

Hành vi xây dựng URL:

• Nếu baseUrl trong lần gọi công cụ được cung cấp, nó sẽ được dùng sau khi xác thực nghiêm ngặt.
• Ngược lại, nếu viewerBaseUrl của Plugin được cấu hình, nó sẽ được dùng.
• Khi không có ghi đè nào, URL trình xem mặc định là loopback 127.0.0.1.
• Nếu chế độ bind của Gateway là custom và gateway.customBindHost được đặt, host đó sẽ được dùng.

Quy tắc baseUrl:

• Phải là http:// hoặc https://.
• Query và hash bị từ chối.
• Origin cộng với đường dẫn cơ sở tùy chọn được cho phép.

# Mô hình bảo mật

# Yêu cầu trình duyệt cho chế độ tệp

mode: "file" và mode: "both" cần trình duyệt tương thích với Chromium.

Thứ tự phân giải:

Văn bản lỗi thường gặp:

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

Khắc phục bằng cách cài đặt Chrome, Chromium, Edge hoặc Brave, hoặc đặt một trong các tùy chọn đường dẫn tệp thực thi ở trên.

# Khắc phục sự cố

# Hướng dẫn vận hành

• Ưu tiên mode: "view" cho đánh giá tương tác cục bộ trong canvas.
• Ưu tiên mode: "file" cho các kênh trò chuyện gửi ra ngoài cần tệp đính kèm.
• Giữ allowRemoteViewer tắt trừ khi triển khai của bạn yêu cầu URL trình xem từ xa.
• Đặt ttlSeconds ngắn rõ ràng cho các diff nhạy cảm.
• Tránh gửi bí mật trong đầu vào diff khi không cần thiết.
• Nếu kênh của bạn nén hình ảnh mạnh (ví dụ Telegram hoặc WhatsApp), hãy ưu tiên đầu ra PDF (fileFormat: "pdf").

# Liên quan

• Trình duyệt
• Plugins
• Tổng quan về công cụ