تفاوت‌ها

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

یا این‌ها را می‌پذیرد:

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

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

• یک URL نمایشگر Gateway برای ارائه روی canvas
• یک مسیر فایل رندرشده (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"}

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

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

برجسته‌سازی نحو

OpenClaw شامل برجسته‌سازی نحو برای زبان‌های رایج سورس، پیکربندی و مستندات است:

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, و toml.

نام‌های مستعار رایجی مانند js, ts, bash, md, yml, c++, dockerfile, rb, kt, و ps1 به آن زبان‌های پیش‌فرض نرمال‌سازی می‌شوند.

Plugin بسته زبانی Diff Viewer را نصب کنید تا زبان‌های دیگر برجسته‌سازی شوند:

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

با در دسترس بودن بسته زبانی، OpenClaw می‌تواند زبان‌های بسیار بیشتری را برجسته‌سازی کند. اگر بسته نصب نشده باشد، فایل‌های خارج از فهرست پیش‌فرض همچنان به‌صورت متن ساده و خوانا رندر می‌شوند. نمونه‌ها شامل 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 و فایل‌های diff هستند.

برای جزئیات، Plugin بسته زبانی Diffs و برای کاتالوگ زبان‌ها و نام‌های مستعار بالادستی Shiki، زبان‌های Shiki را ببینید.

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

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

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

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

• نمایشگر می‌تواند ردیف‌هایی مانند N unmodified lines را نشان دهد.
• کنترل‌های باز کردن روی آن ردیف‌ها شرطی هستند و برای هر نوع ورودی تضمین نمی‌شوند.
• کنترل‌های باز کردن زمانی ظاهر می‌شوند که diff رندرشده داده زمینه قابل گسترش داشته باشد؛ این حالت برای ورودی‌های قبل و بعد معمول است.
• برای بسیاری از ورودی‌های وصله یکپارچه، بدنه‌های زمینه حذف‌شده در hunkهای وصله تجزیه‌شده در دسترس نیستند، بنابراین ردیف می‌تواند بدون کنترل‌های باز کردن ظاهر شود. این رفتار مورد انتظار است.
• 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.
• فراداده آرتیفکت نمایشگر شامل موارد زیر است:
  • شناسه تصادفی آرتیفکت (۲۰ نویسه hex)
  • توکن تصادفی (۴۸ نویسه hex)
  • createdAt و expiresAt
  • مسیر ذخیره‌شده viewer.html
• TTL پیش‌فرض آرتیفکت، وقتی مشخص نشده باشد، ۳۰ دقیقه است.
• بیشترین TTL پذیرفته‌شده برای نمایشگر ۶ ساعت است.
• پاک‌سازی پس از ایجاد آرتیفکت به‌صورت فرصت‌طلبانه اجرا می‌شود.
• آرتیفکت‌های منقضی‌شده حذف می‌شوند.
• پاک‌سازی جایگزین، وقتی فراداده وجود ندارد، پوشه‌های کهنه‌تر از ۲۴ ساعت را حذف می‌کند.

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

مسیر نمایشگر:

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

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

• /plugins/diffs/assets/viewer.js
• /plugins/diffs/assets/viewer-runtime.js
• /plugins/diffs-language-pack/assets/viewer.js وقتی diff از زبانی در Diff Viewer Language Pack استفاده می‌کند

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

رفتار ساخت URL:

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

قواعد baseUrl:

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

مدل امنیتی

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

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

ترتیب resolve:

متن رایج خطا:

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

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

عیب‌یابی

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

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

مرتبط

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