تفاوت‌ها

diffs یک ابزار اختیاری Plugin با راهنمایی کوتاه داخلی در system و یک skill همراه است که محتوای تغییرات را به یک artifact فقط‌خواندنی diff برای agentها تبدیل می‌کند.

این ابزار یکی از این موارد را می‌پذیرد:

• متن before و after
• یک patch یکپارچه

می‌تواند این موارد را برگرداند:

• یک URL نمایشگر Gateway برای ارائه در canvas
• یک مسیر فایل رندرشده (PNG یا PDF) برای تحویل پیام
• هر دو خروجی در یک فراخوانی

وقتی فعال باشد، Plugin راهنمایی کاربردی مختصر را به فضای system-prompt اضافه می‌کند و همچنین برای مواردی که agent به دستورالعمل‌های کامل‌تر نیاز دارد، یک skill تفصیلی ارائه می‌دهد.

# شروع سریع

openclaw plugins install diffs

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

# غیرفعال‌سازی راهنمایی داخلی system

اگر می‌خواهید ابزار diffs فعال بماند اما راهنمایی داخلی system-prompt آن غیرفعال شود، plugins.entries.diffs.hooks.allowPromptInjection را روی false تنظیم کنید:

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

این کار hook با نام before_prompt_build در Pluginِ diffs را مسدود می‌کند، در حالی که Plugin، ابزار و skill همراه همچنان در دسترس می‌مانند.

اگر می‌خواهید هم راهنمایی و هم ابزار را غیرفعال کنید، خود Plugin را غیرفعال کنید.

# گردش‌کار معمول agent

# نمونه‌های ورودی

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

# مرجع ورودی ابزار

همه فیلدها اختیاری هستند، مگر اینکه ذکر شده باشد.

# قرارداد جزئیات خروجی

ابزار metadata ساخت‌یافته را زیر details برمی‌گرداند.

خلاصه رفتار حالت‌ها:

# بخش‌های بدون تغییر جمع‌شده

• نمایشگر می‌تواند ردیف‌هایی مانند N unmodified lines نشان دهد.
• کنترل‌های باز کردن روی آن ردیف‌ها شرطی هستند و برای هر نوع ورودی تضمین نمی‌شوند.
• کنترل‌های باز کردن زمانی ظاهر می‌شوند که diff رندرشده داده زمینه قابل باز شدن داشته باشد، که برای ورودی قبل و بعد معمول است.
• برای بسیاری از ورودی‌های patch یکپارچه، بدنه‌های زمینه حذف‌شده در hunkهای patch تجزیه‌شده در دسترس نیستند، بنابراین ردیف می‌تواند بدون کنترل‌های باز کردن ظاهر شود. این رفتار مورد انتظار است.
• expandUnchanged فقط وقتی اعمال می‌شود که زمینه قابل باز شدن وجود داشته باشد.

# پیش‌فرض‌های Plugin

پیش‌فرض‌های سراسری Plugin را در ~/.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",
          },
        },
      },
    },
  },
}

پیش‌فرض‌های پشتیبانی‌شده:

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

پارامترهای صریح ابزار این پیش‌فرض‌ها را بازنویسی می‌کنند.

# پیکربندی URL نمایشگر پایدار

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

# پیکربندی امنیت

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

# چرخه عمر و ذخیره‌سازی artifact

• artifactها زیر زیرپوشه موقت ذخیره می‌شوند: $TMPDIR/openclaw-diffs.
• metadata مربوط به artifact نمایشگر شامل این موارد است:
  • شناسه artifact تصادفی (20 کاراکتر hex)
  • token تصادفی (48 کاراکتر hex)
  • createdAt و expiresAt
  • مسیر ذخیره‌شده viewer.html
• وقتی مشخص نشده باشد، TTL پیش‌فرض artifact برابر با 30 دقیقه است.
• بیشینه TTL پذیرفته‌شده برای نمایشگر 6 ساعت است.
• پاک‌سازی پس از ایجاد artifact به‌صورت فرصت‌طلبانه اجرا می‌شود.
• artifactهای منقضی‌شده حذف می‌شوند.
• پاک‌سازی fallback وقتی metadata موجود نباشد، پوشه‌های کهنه‌تر از 24 ساعت را حذف می‌کند.

# URL نمایشگر و رفتار شبکه

route نمایشگر:

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

assetهای نمایشگر:

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

سند نمایشگر این assetها را نسبت به URL نمایشگر resolve می‌کند، بنابراین پیشوند مسیر اختیاری baseUrl برای درخواست‌های asset نیز حفظ می‌شود.

رفتار ساخت URL:

• اگر baseUrl در فراخوانی ابزار ارائه شده باشد، پس از اعتبارسنجی سخت‌گیرانه استفاده می‌شود.
• در غیر این صورت، اگر viewerBaseUrl در Plugin پیکربندی شده باشد، از آن استفاده می‌شود.
• بدون هیچ‌یک از بازنویسی‌ها، URL نمایشگر به‌صورت پیش‌فرض به loopback 127.0.0.1 تنظیم می‌شود.
• اگر حالت bind در Gateway برابر custom باشد و gateway.customBindHost تنظیم شده باشد، از آن host استفاده می‌شود.

قواعد baseUrl:

• باید http:// یا https:// باشد.
• query و hash رد می‌شوند.
• origin به‌همراه مسیر پایه اختیاری مجاز است.

# مدل امنیتی

# نیازمندی‌های مرورگر برای حالت فایل

mode: "file" و mode: "both" به مرورگر سازگار با Chromium نیاز دارند.

ترتیب حل‌وفصل:

متن رایج خطا:

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

برای رفع، Chrome، Chromium، Edge یا Brave را نصب کنید، یا یکی از گزینه‌های مسیر فایل اجرایی بالا را تنظیم کنید.

# عیب‌یابی

# راهنمای عملیاتی

• برای بازبینی‌های تعاملی محلی در canvas، mode: "view" را ترجیح دهید.
• برای کانال‌های گفت‌وگوی خروجی که به پیوست نیاز دارند، mode: "file" را ترجیح دهید.
• allowRemoteViewer را غیرفعال نگه دارید، مگر اینکه deployment شما به URLهای نمایشگر راه دور نیاز داشته باشد.
• برای diffهای حساس، ttlSeconds کوتاه و صریح تنظیم کنید.
• وقتی لازم نیست، از ارسال اسرار در ورودی diff خودداری کنید.
• اگر کانال شما تصاویر را شدیداً فشرده می‌کند (برای مثال Telegram یا WhatsApp)، خروجی PDF (fileFormat: "pdf") را ترجیح دهید.

# مرتبط

• مرورگر
• Plugins
• نمای کلی ابزارها