مرجع تقني

نظافة النصوص

يصف هذا المستند الإصلاحات الخاصة بالمزود المطبقة على النصوص قبل تشغيل (بناء سياق النموذج). هذه تعديلات في الذاكرة تُستخدم لتلبية متطلبات المزود الصارمة. خطوات النظافة هذه لا تعيد كتابة ملف النص JSONL المخزن على القرص؛ ومع ذلك، قد تمر مرحلة إصلاح منفصلة لملفات الجلسة بإعادة كتابة ملفات JSONL المشوهة عن طريق إسقاط الأسطر غير الصالحة قبل تحميل الجلسة. عند حدوث إصلاح، يتم نسخ الملف الأصلي احتياطيًا بجانب ملف الجلسة. النطاق يشمل:

  • تعقيم معرف استدعاء الأداة
  • التحقق من صحة مدخلات استدعاء الأداة
  • إصلاح إقران نتائج الأداة
  • التحقق من صحة الدور / الترتيب
  • تنظيف توقيع التفكير
  • تعقيم حمولة الصور
  • وضع علامات على مصدر مدخلات المستخدم (للطلبات الموجهة بين الجلسات)

إذا كنت بحاجة إلى تفاصيل تخزين النصوص، راجع:

أين يعمل هذا

يتم تركيز كل نظافة النصوص في المُشغّل المضمن:

  • اختيار السياسة: src/agents/transcript-policy.ts
  • تطبيق التعقيم/الإصلاح: sanitizeSessionHistory في src/agents/pi-embedded-runner/google.ts

تستخدم السياسة provider و modelApi و modelId لتقرير ما سيتم تطبيقه. بشكل منفصل عن نظافة النصوص، يتم إصلاح ملفات الجلسة (إذا لزم الأمر) قبل التحميل:

  • repairSessionFileIfNeeded في src/agents/session-file-repair.ts
  • يتم استدعاؤها من run/attempt.ts و compact.ts (المُشغّل المضمن)

القاعدة العامة: تعقيم الصور

يتم دائمًا تعقيم حمولات الصور لمنع رفض المزود بسبب حدود الحجم (تقليص حجم/إعادة ضغط صور base64 كبيرة الحجم). هذا يساعد أيضًا في التحكم في ضغط الرموز المميزة الناتج عن الصور للنماذج القادرة على الرؤية. الأبعاد القصوى الأقل تقلل عمومًا من استخدام الرموز المميزة؛ الأبعاد الأعلى تحافظ على التفاصيل. التنفيذ:

  • sanitizeSessionMessagesImages في src/agents/pi-embedded-helpers/images.ts
  • sanitizeContentBlocksImages في src/agents/tool-images.ts
  • الحد الأقصى لجانب الصورة قابل للتكوين عبر agents.defaults.imageMaxDimensionPx (الافتراضي: 1200).

القاعدة العامة: استدعاءات الأدوات المشوهة

يتم إسقاط كتل استدعاء الأداة الخاصة بالمساعد التي تفتقر إلى كل من input و arguments قبل بناء سياق النموذج. هذا يمنع رفض المزود لاستدعاءات الأدوات المحفوظة جزئيًا (على سبيل المثال، بعد فشل حد المعدل). التنفيذ:

  • sanitizeToolCallInputs في src/agents/session-transcript-repair.ts
  • يتم تطبيقه في sanitizeSessionHistory في src/agents/pi-embedded-runner/google.ts

القاعدة العامة: مصدر المدخلات بين الجلسات

عندما يرسل وكيل طلبًا إلى جلسة أخرى عبر sessions_send (بما في ذلك خطوات الرد/الإعلان من وكيل إلى وكيل)، يحفظ OpenClaw دور المستخدم المنشأ مع:

  • message.provenance.kind = "inter_session"

يتم كتابة هذه البيانات الوصفية في وقت إلحاق النص ولا تغير الدور (role: "user" يبقى لتوافق المزود). يمكن للقراء استخدام هذا لتجنب معاملة الطلبات الداخلية الموجهة على أنها تعليمات من المستخدم النهائي. أثناء إعادة بناء السياق، يضيف OpenClaw أيضًا علامة قصيرة [رسالة بين الجلسات] مسبقًا إلى أدوار المستخدم تلك في الذاكرة حتى يتمكن النموذج من التمييز بينها وبين تعليمات المستخدم النهائي الخارجية.

مصفوفة المزودين (السلوك الحالي)

OpenAI / OpenAI Codex

  • تعقيم الصور فقط.
  • إسقاط توقيعات التفكير المنعزلة (عناصر التفكير المنفردة بدون كتلة محتوى تالية) لنصوص OpenAI Responses/Codex.
  • لا يوجد تعقيم لمعرف استدعاء الأداة.
  • لا يوجد إصلاح لإقران نتائج الأداة.
  • لا يوجد تحقق من صحة الدور أو إعادة ترتيب.
  • لا توجد نتائج أدوات اصطناعية.
  • لا يوجد تجريد لتوقيع التفكير.

Google (Generative AI / Gemini CLI / Antigravity)

  • تعقيم معرف استدعاء الأداة: أبجدي رقمي صارم.
  • إصلاح إقران نتائج الأداة ونتائج أدوات اصطناعية.
  • التحقق من صحة الدور (تبادل الأدوار على طراز Gemini).
  • إصلاح ترتيب أدوار Google (إضافة طلب تمهيدي صغير للمستخدم إذا بدأ التاريخ بمساعد).
  • Antigravity Claude: تطبيع توقيعات التفكير؛ إسقاط كتل التفكير غير الموقعة.

Anthropic / Minimax (متوافق مع Anthropic)

  • إصلاح إقران نتائج الأداة ونتائج أدوات اصطناعية.
  • التحقق من صحة الدور (دمج أدوار المستخدم المتتالية لتلبية التبادل الصارم).

Mistral (بما في ذلك الكشف القائم على معرف النموذج)

  • تعقيم معرف استدعاء الأداة: strict9 (طول أبجدي رقمي 9).

OpenRouter Gemini

  • تنظيف توقيع التفكير: تجريد قيم thought_signature غير base64 (الاحتفاظ بـ base64).

كل شيء آخر

  • تعقيم الصور فقط.

السلوك التاريخي (قبل 2026.1.22)

قبل إصدار 2026.1.22، طبق OpenClaw طبقات متعددة من نظافة النصوص:

  • امتداد transcript-sanitize كان يعمل في كل بناء سياق ويمكنه:
    • إصلاح إقران استخدام/نتيجة الأداة.
    • تعقيم معرفات استدعاء الأداة (بما في ذلك وضع غير صارم يحافظ على _/-).
  • قام المُشغّل أيضًا بتنفيذ تعقيم خاص بالمزود، مما أدى إلى تكرار العمل.
  • حدثت طفرات إضافية خارج سياسة المزود، بما في ذلك:
    • تجريد علامات <final> من نص المساعد قبل الحفظ.
    • إسقاط أدوار المساعد الفارغة للخطأ.
    • تقليم محتوى المساعد بعد استدعاءات الأدوات.

تسببت هذه التعقيدات في تراجعات عبر المزودين (ملحوظًا إقران call_id|fc_id لـ openai-responses). قام تنظيف 2026.1.22 بإزالة الامتداد، وتركيز المنطق في المُشغّل، وجعل OpenAI بدون لمس باستثناء تعقيم الصور.

استخدام API والتكاليفالتاريخ والوقت