تفاوت‌ها

diffs یک ابزار اختیاری Plugin است که راهنمای سیستمی کوتاه داخلی و یک Skill همراه دارد و محتوای تغییرات را به یک مصنوع diff فقط‌خواندنی برای عامل‌ها تبدیل می‌کند.

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

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

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

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

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

شروع سریع

openclaw plugins install diffs

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

غیرفعال کردن راهنمای سیستمی داخلی

اگر می‌خواهید ابزار 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 را غیرفعال کنید.

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

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

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

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

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

قرارداد details خروجی

ابزار فراداده ساختاریافته را زیر 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",            ttlSeconds: 21600,          },        },      },    },  },}

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

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

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

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

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

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

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

چرخه عمر و ذخیره‌سازی مصنوعات

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

رفتار URL مشاهده‌گر و شبکه

مسیر مشاهده‌گر:

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

دارایی‌های مشاهده‌گر:

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

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

رفتار ساخت URL:

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

قوانین 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 را غیرفعال نگه دارید مگر اینکه استقرار شما به URLهای نمایشگر راه‌دور نیاز داشته باشد.
• برای diffهای حساس، ttlSeconds کوتاه و صریح تنظیم کنید.
• وقتی لازم نیست، از ارسال secrets در ورودی diff خودداری کنید.
• اگر کانال شما تصاویر را شدیدا فشرده می‌کند (برای مثال Telegram یا WhatsApp)، خروجی PDF (fileFormat: "pdf") را ترجیح دهید.

مرتبط

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