الانتقال إلى المحتوى الرئيسي

أدوات مدمجة

الفروقات

diffs هي أداة إضافية اختيارية مع توجيه نظام مدمج مختصر ومهارة مرافقة تحول محتوى التغيير إلى نتيجة فروقات للقراءة فقط للوكلاء. تقبل إما:

  • نص before و after
  • patch موحد

يمكنها إرجاع:

  • رابط عارض عبر البوابة لعرضه في لوحة العمل
  • مسار ملف مُعرض (PNG أو PDF) لتسليم الرسائل
  • كلا المخرجات في استدعاء واحد

عند التمكين، تضيف الإضافة توجيهات استخدام موجزة إلى مسار توجيه النظام وتعرض أيضًا مهارة مفصلة للحالات التي يحتاج فيها الوكيل إلى تعليمات أكثر اكتمالاً.

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

  1. قم بتمكين الإضافة.
  2. استدعِ diffs مع mode: "view" لسير العمل التي تعطي الأولوية للوحة العمل.
  3. استدعِ diffs مع mode: "file" لسير العمل التي تتطلب تسليم ملفات في المحادثة.
  4. استدعِ diffs مع mode: "both" عندما تحتاج إلى كلا النتيجتين.

تمكين الإضافة​

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

تعطيل توجيه النظام المدمج​

إذا كنت تريد إبقاء أداة diffs مفعلة ولكن تعطيل توجيه نظامها المدمج، عيّن plugins.entries.diffs.hooks.allowPromptInjection إلى false:

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

هذا يمنع خطاف before_prompt_build الخاص بإضافة الفروقات مع إبقاء الإضافة والأداة والمهارة المرافقة متاحة. إذا كنت تريد تعطيل كل من التوجيه والأداة، قم بتعطيل الإضافة بدلاً من ذلك.

سير عمل الوكيل النموذجي​

  1. يستدعي الوكيل diffs.
  2. يقرأ الوكيل حقول details.
  3. إما أن يقوم الوكيل بـ:
    • فتح details.viewerUrl باستخدام canvas present
    • إرسال details.filePath مع message باستخدام path أو filePath
    • القيام بكليهما

أمثلة على المدخلات​

قبل وبعد:

{
  "before": "# Hello\n\nOne",
  "after": "# Hello\n\nTwo",
  "path": "docs/example.md",
  "mode": "view"
}

تصحيح (Patch):

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

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

جميع الحقول اختيارية ما لم يُذكر خلاف ذلك:

  • before (string): النص الأصلي. مطلوب مع after عند حذف patch.
  • after (string): النص المحدث. مطلوب مع before عند حذف patch.
  • patch (string): نص الفروقات الموحد. لا يمكن جمعه مع before و after.
  • path (string): اسم الملف المعروض لوضعية قبل وبعد.
  • lang (string): تلميح تجاوز اللغة لوضعية قبل وبعد.
  • title (string): تجاوز عنوان العارض.
  • mode ("view" | "file" | "both"): وضعية الإخراج. الافتراضي هو الإعداد الافتراضي للإضافة defaults.mode.
  • theme ("light" | "dark"): سمة العارض. الافتراضي هو الإعداد الافتراضي للإضافة defaults.theme.
  • layout ("unified" | "split"): تخطيط الفروقات. الافتراضي هو الإعداد الافتراضي للإضافة defaults.layout.
  • expandUnchanged (boolean): توسيع الأقسام غير المتغيرة عندما يكون السياق الكامل متاحًا. خيار لكل استدعاء فقط (ليس مفتاحًا افتراضيًا للإضافة).
  • fileFormat ("png" | "pdf"): تنسيق الملف المُعرض. الافتراضي هو الإعداد الافتراضي للإضافة defaults.fileFormat.
  • fileQuality ("standard" | "hq" | "print"): إعداد جودة مسبق لعرض PNG أو PDF.
  • fileScale (number): تجاوز مقياس الجهاز (1-4).
  • fileMaxWidth (number): أقصى عرض للعرض بالبكسل CSS (640-2400).
  • ttlSeconds (number): مدة صلاحية نتيجة العارض بالثواني. الافتراضي 1800، الحد الأقصى 21600.
  • baseUrl (string): تجاوز أصل رابط العارض. يجب أن يكون http أو https، بدون استعلام أو هاش.

التحقق من الصحة والحدود:

  • before و after بحد أقصى 512 كيلوبايت لكل منهما.
  • patch بحد أقصى 2 ميجابايت.
  • path بحد أقصى 2048 بايت.
  • lang بحد أقصى 128 بايت.
  • title بحد أقصى 1024 بايت.
  • حد تعقيد التصحيح: بحد أقصى 128 ملف و 120000 سطر إجمالي.
  • يتم رفض patch مع before أو after معًا.
  • حدود أمان الملفات المعروضة (تنطبق على PNG و PDF):
    • fileQuality: "standard": بحد أقصى 8 ميجابكسل (8,000,000 بكسل معروض).
    • fileQuality: "hq": بحد أقصى 14 ميجابكسل (14,000,000 بكسل معروض).
    • fileQuality: "print": بحد أقصى 24 ميجابكسل (24,000,000 بكسل معروض).
    • PDF أيضًا بحد أقصى 50 صفحة.

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

تُرجع الأداة بيانات وصفية منظمة تحت details. الحقول المشتركة للأوضاع التي تنشئ عارضًا:

  • artifactId
  • viewerUrl
  • viewerPath
  • title
  • expiresAt
  • inputKind
  • fileCount
  • mode

حقول الملف عند عرض PNG أو PDF:

  • filePath
  • path (نفس قيمة filePath، لتوافق أداة الرسائل)
  • fileBytes
  • fileFormat
  • fileQuality
  • fileScale
  • fileMaxWidth

ملخص سلوك الوضعية:

  • mode: "view": حقول العارض فقط.
  • mode: "file": حقول الملف فقط، بدون نتيجة عارض.
  • mode: "both": حقول العارض بالإضافة إلى حقول الملف. إذا فشل عرض الملف، لا يزال العارض يُرجع مع fileError.

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

  • يمكن للعارض عرض صفوف مثل N unmodified lines.
  • عناصر التحكم في التوسيع على تلك الصفوف مشروطة وغير مضمونة لكل نوع مدخلات.
  • تظهر عناصر التحكم في التوسيع عندما يكون للفروقات المعروضة بيانات سياق قابلة للتوسيع، وهو أمر نموذجي لمدخلات قبل وبعد.
  • بالنسبة للعديد من مدخلات التصحيح الموحد، لا تكون أجسام السياق المحذوفة متاحة في أجزاء التصحيح المحللة، لذلك يمكن أن يظهر الصف بدون عناصر تحكم للتوسيع. هذا سلوك متوقع.
  • expandUnchanged ينطبق فقط عندما يكون هناك سياق قابل للتوسيع.

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

عيّن الإعدادات الافتراضية على مستوى الإضافة في ~/.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

معلمات الأداة الصريحة تتجاوز هذه الإعدادات الافتراضية.

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

  • security.allowRemoteViewer (boolean، الافتراضي false)
    • false: يتم رفض الطلبات غير loopback إلى مسارات العارض.
    • true: يُسمح بالعرض عن بُعد إذا كان المسار المميز صالحًا.

مثال:

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

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

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

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

مسار العارض:

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

موارد العارض:

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

سلوك إنشاء الرابط:

  • إذا تم توفير baseUrl، يتم استخدامه بعد التحقق الصارم.
  • بدون baseUrl، يكون رابط العارض الافتراضي هو loopback 127.0.0.1.
  • إذا كان وضع ربط البوابة هو custom وتم تعيين gateway.customBindHost، يتم استخدام ذلك المضيف.

قواعد baseUrl:

  • يجب أن يكون http:// أو https://.
  • يتم رفض الاستعلام والهاش.
  • يُسمح بالأصل بالإضافة إلى المسار الأساسي الاختياري.

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

تعزيز أمان العارض:

  • loopback فقط بشكل افتراضي.
  • مسارات العارض المميزة مع التحقق الصارم من المعرف والرمز المميز.
  • سياسة أمان المحتوى (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. الاحتياطي لاكتشاف الأمر/المسار على النظام الأساسي.

نص الفشل الشائع:

  • 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 (...)
    • قلل حجم الحمولة.
  • رفض التصحيح الكبير
    • قلل عدد ملفات التصحيح أو إجمالي الأسطر.

مشكلات إمكانية الوصول إلى العارض:

  • رابط العارض يحل إلى 127.0.0.1 بشكل افتراضي.
  • لسيناريوهات الوصول عن بُعد، إما:
    • مرر baseUrl لكل استدعاء أداة، أو
    • استخدم gateway.bind=custom و gateway.customBindHost
  • قم بتمكين security.allowRemoteViewer فقط عندما تنوي الوصول الخارجي إلى العارض.

صف الأسطر غير المتغيرة ليس لديه زر توسيع:

  • يمكن أن يحدث هذا لمدخلات التصحيح عندما لا يحمل التصحيح سياقًا قابلًا للتوسيع.
  • هذا متوقع ولا يشير إلى فشل في العارض.

النتيجة غير موجودة:

  • انتهت صلاحية النتيجة بسبب TTL.
  • تغير الرمز المميز أو المسار.
  • التنظيف أزال البيانات القديمة.

التوجيهات التشغيلية​

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

محرك عرض الفروقات:

وثائق ذات صلة​

Perplexity Sonarأداة PDF