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

​
تنسيق Markdown

تُنسِّق OpenClaw محتوى Markdown الصادر عبر تحويله إلى تمثيل وسيط مشترك (IR) قبل إخراج مخرجات خاصة بكل قناة. يحافظ الـ IR على النص المصدر كما هو، مع حمل نطاقات الأنماط/الروابط بحيث تبقى التجزئة والإخراج متسقين عبر القنوات.

​
الأهداف

  • الاتساق: خطوة تحليل واحدة، وعدة مُصيِّرات.
  • تجزئة آمنة: تقسيم النص قبل الإخراج بحيث لا ينكسر التنسيق المضمَّن عبر الأجزاء.
  • الملاءمة لكل قناة: تعيين الـ IR نفسه إلى mrkdwn في Slack، وHTML في Telegram، ونطاقات الأنماط في Signal دون إعادة تحليل Markdown.

​
أنابيب

  1. تحليل Markdown -> IR
    • الـ IR عبارة عن نص عادي مضافًا إليه نطاقات أنماط (غامق/مائل/مشطوب/كود/مُفسِد) ونطاقات روابط.
    • الإزاحات بوحدات UTF-16 بحيث تتوافق نطاقات أنماط Signal مع واجهة برمجته.
    • تُحلَّل الجداول فقط عندما تختار القناة تحويل الجداول.
  2. تجزئة الـ IR (تنسيق أولًا)
    • تتم التجزئة على نص الـ IR قبل الإخراج.
    • لا ينقسم التنسيق المضمَّن عبر الأجزاء؛ وتُقصّ النطاقات لكل جزء.
  3. الإخراج لكل قناة
    • Slack: رموز mrkdwn (غامق/مائل/مشطوب/كود)، والروابط كـ <url|label>.
    • Telegram: وسوم HTML (<b>، <i>، <s>، <code>، <pre><code>، <a href>).
    • Signal: نص عادي + نطاقات text-style؛ وتتحول الروابط إلى label (url) عندما يختلف الوسم.

​
مثال على IR

Markdown المُدخل: 
Hello **world** — see [docs](https://docs.openclaw.ai).
IR (تخطيطي): 
{
  "text": "Hello world — see docs.",
  "styles": [{ "start": 6, "end": 11, "style": "bold" }],
  "links": [{ "start": 19, "end": 23, "href": "https://docs.openclaw.ai" }]
}

​
أين يُستخدم

  • تُخرِج محوِّلات Slack وTelegram وSignal الصادرة من الـ IR.
  • القنوات الأخرى (WhatsApp، iMessage، MS Teams، Discord) لا تزال تستخدم نصًا عاديًا أو قواعد تنسيقها الخاصة، مع تطبيق تحويل جداول Markdown قبل التجزئة عند التمكين.

​
التعامل مع الجداول

لا تحظى جداول Markdown بدعم متسق عبر عملاء الدردشة. استخدم markdown.tables للتحكم في التحويل لكل قناة (ولكل حساب).
  • code: إخراج الجداول ككتل كود (الافتراضي لمعظم القنوات).
  • bullets: تحويل كل صف إلى نقاط تعداد (الافتراضي لـ Signal + WhatsApp).
  • off: تعطيل تحليل الجداول وتحويلها؛ يمر نص الجدول الخام كما هو.
مفاتيح التهيئة: 
channels:
  discord:
    markdown:
      tables: code
    accounts:
      work:
        markdown:
          tables: off

​
قواعد التجزئة

  • تأتي حدود التجزئة من محوِّلات القنوات/التهيئة وتُطبَّق على نص الـ IR.
  • تُحفَظ أسوار الكود ككتلة واحدة مع سطر جديد لاحق بحيث تُخرِجها القنوات بشكل صحيح.
  • بادئات القوائم وبادئات الاقتباس جزء من نص الـ IR، لذا لا تنقسم التجزئة في منتصف البادئة.
  • لا ينقسم أي تنسيق مضمَّن (غامق/مائل/مشطوب/كود مضمَّن/مُفسِد) عبر الأجزاء؛ ويُعيد المُصيِّر فتح الأنماط داخل كل جزء.
إذا احتجت المزيد حول سلوك التجزئة عبر القنوات، فاطّلع على Streaming + chunking.

​
سياسة الروابط

  • Slack: [label](url) -> <url|label>؛ وتبقى عناوين URL العارية كما هي. يُعطَّل الربط التلقائي أثناء التحليل لتجنب الازدواجية.
  • Telegram: [label](url) -> <a href="url">label</a> (وضع تحليل HTML).
  • Signal: [label](url) -> label (url) ما لم يطابق الوسم عنوان URL.

​
المفسدين

تُحلَّل علامات المُفسِد (||spoiler||) فقط في Signal، حيث تُطابِق نطاقات أنماط SPOILER. تتعامل القنوات الأخرى معها كنص عادي.

​
كيفية إضافة أو تحديث مُنسِّق قناة

  1. تحليل واحد: استخدم مُعين markdownToIR(...) المشترك مع خيارات مناسبة للقناة (الربط التلقائي، نمط العناوين، بادئة الاقتباس).
  2. الإخراج: نفّذ مُصيِّرًا باستخدام renderMarkdownWithMarkers(...) وخريطة علامات الأنماط (أو نطاقات أنماط Signal).
  3. التجزئة: استدعِ chunkMarkdownIR(...) قبل الإخراج؛ وأخرِج كل جزء.
  4. توصيل المحوِّل: حدِّث محوِّل القناة الصادر لاستخدام المُجزِّئ والمُصيِّر الجديدين.
  5. الاختبار: أضِف أو حدِّث اختبارات التنسيق واختبار تسليم صادر إذا كانت القناة تستخدم التجزئة.

​
الجوجات الشائعة

  • يجب الحفاظ على رموز الأقواس الزاوية في Slack (<@U123>، <#C123>، <https://...>)؛ واهرب HTML الخام بأمان.
  • يتطلب HTML في Telegram تهريب النص خارج الوسوم لتجنب كسر الوسم.
  • تعتمد نطاقات أنماط Signal على إزاحات UTF-16؛ لا تستخدم إزاحات نقاط الشيفرة.
  • احفظ الأسطر الجديدة اللاحقة لكتل الكود المسوَّرة بحيث تقع علامات الإغلاق في سطرها الخاص.