Skip to main content
diffs هي أداة Plugin مضمّنة اختيارية تحوّل نص ما قبل/ما بعد أو تصحيحًا موحّدًا إلى ناتج فرق للقراءة فقط. كما تضيف إرشادات موجزة للوكيل في بداية مطالبة النظام، وتأتي مع مهارة مصاحبة لتوفير تعليمات أشمل. الإدخال: نص before + after، أو patch موحّد (وهما متنافيان). الإخراج: عنوان URL لعارض Gateway للعرض على اللوحة، أو مسار ملف PNG/PDF معروض لتسليمه في رسالة، أو كلاهما.

​
البدء السريع

1

تثبيت Plugin

2

تمكين Plugin

3

اختيار وضع

تدفقات تفضّل اللوحة: تستدعي الوكلاء diffs باستخدام mode: "view" وتفتح details.viewerUrl باستخدام canvas present.

​
تعطيل إرشادات النظام المضمّنة

للاحتفاظ بالأداة مع حذف الإرشادات المضافة في بداية مطالبة النظام، اضبط plugins.entries.diffs.hooks.allowPromptInjection على false:
يؤدي هذا إلى حظر خطاف before_prompt_build الخاص بالـPlugin مع إبقاء الأداة والمهارة متاحتين. لتعطيل الإرشادات والأداة معًا، عطّل Plugin بدلًا من ذلك.

​
مرجع إدخال الأداة

جميع الحقول اختيارية ما لم يُذكر خلاف ذلك.
​
string
النص الأصلي. مطلوب مع after عند إغفال patch.
​
string
النص المحدّث. مطلوب مع before عند إغفال patch.
​
string
نص فرق موحّد. يتنافى مع before وafter.
​
string
اسم الملف المعروض لوضع ما قبل/ما بعد.
​
string
تلميح لتجاوز اللغة في وضع ما قبل/ما بعد. تعود القيم غير المعروفة واللغات الخارجة عن مجموعة العارض الافتراضية إلى النص العادي ما لم يكن Plugin حزمة لغات عارض الفروق مثبتًا.
​
string
تجاوز عنوان العارض.
​
"view" | "file" | "both"
وضع الإخراج. يستخدم افتراضيًا إعداد Plugin الافتراضي defaults.mode ‏(both). اسم بديل مهمل: يتصرف "image" بالطريقة نفسها تمامًا مثل "file".
​
"light" | "dark"
سمة العارض. تستخدم افتراضيًا إعداد Plugin الافتراضي defaults.theme.
​
"unified" | "split"
تخطيط الفرق. يستخدم افتراضيًا إعداد Plugin الافتراضي defaults.layout.
​
boolean
توسيع الأقسام غير المتغيرة عند توفر السياق الكامل. خيار لكل استدعاء فقط (وليس مفتاحًا افتراضيًا للـPlugin).
​
"png" | "pdf"
تنسيق الملف المعروض. يستخدم افتراضيًا إعداد Plugin الافتراضي defaults.fileFormat.
​
"standard" | "hq" | "print"
إعداد مسبق للجودة لعرض PNG/PDF.
​
number
تجاوز مقياس الجهاز (1-4).
​
number
أقصى عرض للتصيير بوحدات بكسل CSS ‏(640-2400).
​
number
افتراضي:"1800"
مدة بقاء الناتج بالثواني لمخرجات العارض والملفات المستقلة. الحد الأقصى 21600.
​
string
تجاوز أصل عنوان URL للعارض. يتجاوز viewerBaseUrl الخاص بالـPlugin. يجب أن يكون http أو https، من دون استعلام/تجزئة.
  • before/after: بحد أقصى 512 KiB لكل منهما.
  • patch: بحد أقصى 2 MiB.
  • path: بحد أقصى 2048 بايت.
  • lang: بحد أقصى 128 بايت.
  • title: بحد أقصى 1024 بايت.
  • حد تعقيد التصحيح: بحد أقصى 128 ملفًا و120000 سطر إجمالًا.
  • يُرفض patch مع before/after.
  • حدود أمان الملف المعروض (PNG وPDF):
    • fileQuality: "standard": بحد أقصى 8 MP ‏(8,000,000 بكسل معروض).
    • fileQuality: "hq": بحد أقصى 14 MP.
    • fileQuality: "print": بحد أقصى 24 MP.
    • يقتصر PDF أيضًا على 50 صفحة.

​
تمييز الصياغة

اللغات المضمّنة: 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 حزمة لغات عارض الفروق لمزيد من اللغات (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 للاطلاع على الكتالوج الأساسي.

​
عقد تفاصيل الإخراج

تتضمن جميع النتائج الناجحة changed: يعيد إدخال ما قبل/ما بعد المتطابق false من دون إنشاء ناتج؛ وتعيد النتائج المعروضة true.
  • changed
  • artifactId
  • viewerUrl
  • viewerPath
  • title
  • expiresAt
  • inputKind
  • fileCount
  • mode
  • context ‏(agentId، sessionId، messageChannel، agentAccountId عند توفرها)
  • changed
  • artifactId
  • expiresAt
  • filePath
  • path (القيمة نفسها لـfilePath، للتوافق مع أداة الرسائل)
  • fileBytes
  • fileFormat
  • fileQuality
  • fileScale
  • fileMaxWidth

​
الأقسام غير المتغيرة المطوية

يعرض العارض صفوفًا مثل N unmodified lines. لا تظهر عناصر تحكم التوسيع إلا عندما يحتوي الفرق المعروض على بيانات سياق قابلة للتوسيع (وهو المعتاد لإدخال ما قبل/ما بعد). تحذف كثير من التصحيحات الموحّدة نصوص السياق من مقاطعها، لذلك قد يظهر الصف من دون عنصر تحكم للتوسيع؛ وهذا متوقع وليس خطأ. لا ينطبق expandUnchanged إلا عند وجود سياق قابل للتوسيع.

​
التنقل بين ملفات متعددة

تبدأ التصحيحات التي تمس أكثر من ملف ببطاقة ملخص للملفات المتغيرة: إجمالي أعداد +N / -N، والأعداد لكل ملف، وشارات الإضافة/الحذف/إعادة التسمية، وروابط ارتساء تنتقل إلى كل ملف. تحتفظ ملفات PNG/PDF المعروضة بأعداد ترويسة كل ملف، لكنها تحذف مفاتيح تبديل العرض التفاعلية لأنها عناصر تحكم غير فعالة في ملف ثابت.

​
الإعدادات الافتراضية للـPlugin

عيّن الإعدادات الافتراضية على مستوى Plugin في ~/.openclaw/openclaw.json:
مفاتيح defaults المدعومة: fontFamily، fontSize، lineSpacing، layout، showLineNumbers، diffIndicators، wordWrap، background، theme، fileFormat، fileQuality، fileScale، fileMaxWidth، mode، ttlSeconds. تتجاوز معاملات استدعاء الأداة الصريحة هذه الإعدادات.

​
إعداد عنوان URL الدائم للعارض

​
string
الخيار الاحتياطي المملوك للـPlugin لروابط العارض المعادة عندما لا يمرر استدعاء الأداة baseUrl. يجب أن يكون http أو https، من دون استعلام/تجزئة.

​
إعداد الأمان

​
boolean
افتراضي:"false"
false: تُرفض الطلبات الواردة إلى مسارات العارض من عناوين غير الاسترجاع المحلي. true: يُسمح بالعارضات البعيدة إذا كان المسار المرمّز صالحًا.

​
دورة حياة الناتج وتخزينه

  • توجد النواتج ضمن $TMPDIR/openclaw-diffs.
  • تخزّن بيانات العارض الوصفية معرّف ناتج عشوائيًا من 20 محرفًا سداسيًا عشريًا، ورمزًا عشوائيًا من 48 محرفًا سداسيًا عشريًا، وcreatedAt/expiresAt، ومسار viewer.html المخزّن.
  • مدة بقاء الناتج الافتراضية: 30 دقيقة. أقصى مدة بقاء مقبولة: 6 ساعات.
  • تُشغّل عملية التنظيف انتهازيًا بعد كل استدعاء لإنشاء ناتج؛ وتُحذف النواتج المنتهية.
  • تزيل عملية المسح الاحتياطية المجلدات القديمة التي يزيد عمرها على 24 ساعة عند غياب البيانات الوصفية.

​
عنوان URL للعارض وسلوك الشبكة

مسار العارض: /plugins/diffs/view/{artifactId}/{token} أصول العارض:
  • /plugins/diffs/assets/viewer.js
  • /plugins/diffs/assets/viewer-runtime.js
  • /plugins/diffs-language-pack/assets/viewer.js (فقط عندما يستخدم الفرق لغة حزمة لغات)
يحلّ مستند العارض هذه الأصول نسبةً إلى عنوان URL للعارض، لذا تُطبَّق أيضًا بادئة المسار الاختيارية baseUrl على طلبات الأصول. ترتيب حل عنوان URL: ‏baseUrl لاستدعاء الأداة (بعد التحقق الصارم) -> ‏viewerBaseUrl للـ Plugin -> القيمة الافتراضية للاسترجاع الحلقي 127.0.0.1. إذا كان وضع ربط Gateway هو custom وكانت gateway.customBindHost مضبوطة، فسيُستخدم ذلك المضيف بدلًا من الاسترجاع الحلقي. قواعد baseUrl: يجب أن تكون http:// أو https://؛ تُرفض سلسلة الاستعلام والتجزئة؛ ويُسمح بالأصل مع مسار أساسي اختياري.

​
نموذج الأمان

  • الاسترجاع الحلقي فقط افتراضيًا.
  • مسارات عارض مزوّدة برموز مميزة مع تحقق صارم من أنماط المعرّفات والرموز المميزة.
  • سياسة CSP لاستجابة العارض: default-src 'none'؛ لا تُحمَّل البرامج النصية/الأصول إلا من المصدر نفسه؛ ولا يُسمح باتصالات connect-src الصادرة.
  • تقييد حالات الإخفاق البعيدة عند تمكين الوصول البعيد: يؤدي حدوث 40 إخفاقًا خلال 60 ثانية إلى حظر لمدة 60 ثانية (429 Too Many Requests).
  • يُرفض توجيه طلبات متصفح لقطات الشاشة افتراضيًا.
  • لا يُسمح إلا بأصول العارض المحلية من http://127.0.0.1/plugins/diffs/assets/*.
  • تُحظر طلبات الشبكة الخارجية.

​
متطلبات المتصفح لوضع الملفات

تحتاج mode: "file" وmode: "both" إلى متصفح متوافق مع Chromium. ترتيب الحل:
1

الإعداد

browser.executablePath في إعداد OpenClaw.
2

متغيرات البيئة

  • OPENCLAW_BROWSER_EXECUTABLE_PATH
  • BROWSER_EXECUTABLE_PATH
  • PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH
3

الخيار الاحتياطي للنظام الأساسي

مسارات التثبيت الشائعة وعمليات البحث عبر PATH عن Chrome وChromium وEdge وBrave.
نص الإخفاق الشائع: Diff PNG/PDF rendering requires a Chromium-compatible browser.... أصلح ذلك بتثبيت Chrome أو Chromium أو Edge أو Brave، أو بضبط أحد خيارات مسار الملف التنفيذي أعلاه.

​
استكشاف الأخطاء وإصلاحها

  • Provide patch or both before and after text. — أدرج كلًا من before وafter، أو وفّر patch.
  • Provide either patch or before/after input, not both. — لا تخلط بين أوضاع الإدخال.
  • Invalid baseUrl: ... — استخدم أصل http(s) مع مسار اختياري، ومن دون استعلام/تجزئة.
  • {field} exceeds maximum size (...) — قلّل حجم الحمولة.
  • رفض التصحيح الكبير — قلّل عدد ملفات التصحيح أو إجمالي الأسطر.
  • يُحل عنوان URL للعارض إلى 127.0.0.1 افتراضيًا.
  • للوصول البعيد، اضبط إما viewerBaseUrl للـ Plugin، أو مرّر baseUrl لكل استدعاء، أو استخدم gateway.bind=custom مع gateway.customBindHost.
  • إذا تضمنت gateway.trustedProxies الاسترجاع الحلقي لوكيل على المضيف نفسه (مثل Tailscale Serve)، فستُرفض طلبات العارض المباشرة عبر الاسترجاع الحلقي التي لا تحتوي على ترويسات عنوان IP المُمرَّر للعميل، وذلك عن قصد.
  • لطوبولوجيا الوكيل هذه، يُفضّل استخدام mode: "file"/"both" لمرفق، أو تمكين security.allowRemoteViewer عمدًا إلى جانب viewerBaseUrl للـ Plugin/‏baseUrl للوكيل للحصول على رابط عارض قابل للمشاركة.
  • لا تمكّن security.allowRemoteViewer إلا عندما يكون الوصول الخارجي إلى العارض مقصودًا.
هذا متوقع لإدخال تصحيح يفتقر إلى سياق قابل للتوسيع؛ وليس إخفاقًا في العارض.
  • انتهت صلاحية الأثر بسبب مدة البقاء.
  • تغيّر الرمز المميز أو المسار.
  • أزالت عملية التنظيف البيانات القديمة.

​
إرشادات التشغيل

  • يُفضّل mode: "view" للمراجعات التفاعلية المحلية في اللوحة.
  • يُفضّل mode: "file" لقنوات الدردشة الصادرة التي تحتاج إلى مرفق.
  • أبقِ allowRemoteViewer معطّلة ما لم يتطلب نشرك عناوين URL بعيدة للعارض.
  • اضبط مدة ttlSeconds قصيرة وصريحة للفروق الحساسة.
  • تجنّب إرسال الأسرار في إدخال الفرق عندما لا تكون مطلوبة.
  • إذا كانت قناتك تضغط الصور بشدة (مثل Telegram أو WhatsApp)، فيُفضّل إخراج PDF ‏(fileFormat: "pdf").
يعمل محرك عرض الفروق بواسطة Diffs.

​
ذو صلة