Concept internals
تنسيق Markdown
يحوّل OpenClaw صيغة Markdown الصادرة إلى تمثيل وسيط مشترك (IR) قبل تصيير المخرجات الخاصة بكل قناة. يحتفظ IR بالنص العادي إلى جانب نطاقات الأنماط والروابط، بحيث تغذّي خطوة تحليل واحدة كل قناة، ولا يؤدي التقسيم مطلقًا إلى شطر التنسيق في منتصف النطاق.
مسار المعالجة
- تحليل Markdown إلى IR (
markdownToIR) - نص عادي إلى جانب نطاقات الأنماط (عريض، مائل، يتوسطه خط، شيفرة، كتلة شيفرة، محتوى مخفي، اقتباس كتلي، عناوين من 1 إلى 6) ونطاقات الروابط. الإزاحات بوحدات شيفرة UTF-16 كي تتوافق نطاقات أنماط Signal مباشرةً مع واجهة API الخاصة به. لا تُحلَّل الجداول إلا عندما تختار القناة وضعًا للجداول. - تقسيم IR (
chunkMarkdownIR/renderMarkdownIRChunksWithinLimit)- يحدث التقسيم على نص IR قبل التصيير، لذا تُجزّأ الأنماط المضمّنة والروابط لكل جزء بدلًا من انقطاعها عبر حدّ فاصل.
- التصيير لكل قناة (
renderMarkdownWithMarkers) - تحوّل خريطة علامات الأنماط النطاقات إلى ترميز القناة الأصلي.
| القناة | المصيّر | ملاحظات |
|---|---|---|
| Slack | رموز mrkdwn (*bold*، _italic_، `code`، أسوار الشيفرة) |
تتحول الروابط إلى <url|label>؛ يُعطّل الربط التلقائي أثناء التحليل لتجنب تكرار الربط |
| Telegram | وسوم HTML (<b>، <i>، <s>، <code>، <pre><code>، <a href>، <tg-spoiler>) |
يدعم أيضًا جداول الرسائل المنسّقة والعناوين (<h1>-<h6>) عند تفعيل richMessages |
| Signal | نص عادي + نطاقات text-style |
تُصيّر الروابط بصيغة label (url) عندما تختلف التسمية عن عنوان URL |
| Discord وWhatsApp وiMessage وMicrosoft Teams والقنوات الأخرى | نص عادي | لا تنسيق قائم على IR؛ يظل تحويل جداول Markdown يعمل عبر convertMarkdownTables |
مثال على IR
Markdown المُدخل: OC_I18N_900000 IR (تخطيطي): OC_I18N_900001
معالجة الجداول
يتحكم markdown.tables في كيفية تحويل القناة لجداول Markdown، لكل
قناة، واختياريًا لكل حساب:
| الوضع | السلوك |
|---|---|
code |
التصيير كجدول ASCII محاذى داخل كتلة شيفرة (الوضع الاحتياطي الافتراضي) |
bullets |
تحويل كل صف إلى نقاط تعداد بصيغة label: value |
block |
الاحتفاظ بالجداول الأصلية حيث تدعمها وسيلة النقل؛ والرجوع إلى code خلاف ذلك |
off |
تعطيل تحليل الجداول؛ يمر نص الجدول الخام دون تغيير |
الإعدادات الافتراضية للـ Plugin حسب القناة: تستخدم Signal وWhatsApp وMatrix
bullets افتراضيًا؛ ويستخدم Mattermost الوضع off افتراضيًا؛ وتستخدم Telegram الوضع block افتراضيًا (والذي
يُحل إلى code ما لم يكن richMessages مفعّلًا للحساب). تعود أي
قناة بلا إعداد افتراضي صريح للـ Plugin إلى code.
OC_I18N_900002
قواعد التقسيم
- تأتي حدود الأجزاء من مهايئات القنوات أو إعداداتها، وتنطبق على نص IR لا على المخرجات المصيّرة.
- يُحتفظ بكتل الشيفرة المسيّجة ككتلة واحدة مع سطر جديد لاحق كي تصيّر القنوات السياج الختامي بصورة صحيحة.
- بادئات القوائم والاقتباسات الكتلية جزء من نص IR، لذا لا يؤدي التقسيم مطلقًا إلى الشطر في منتصف البادئة.
- لا تنقسم الأنماط المضمّنة عبر الأجزاء مطلقًا؛ يعيد المصيّر فتح أي نمط مفتوح في بداية الجزء التالي.
راجع البث والتقسيم للاطلاع على حدود الأجزاء وسلوك التسليم عبر القنوات.
سياسة الروابط
- Slack:
[label](url)-><url|label>؛ تبقى عناوين URL المجرّدة كما هي. - Telegram:
[label](url)-><a href="url">label</a>(وضع تحليل HTML). - Signal:
[label](url)->label (url)ما لم تكن التسمية مطابقة لعنوان URL بالفعل.
المحتوى المخفي
تُحلّل علامات المحتوى المخفي (||spoiler||) في Signal (وتُحوّل إلى نطاقات نمط SPOILER)
وفي Telegram (وتُحوّل إلى <tg-spoiler>). تتعامل القنوات الأخرى مع
||...|| كنص عادي.
إضافة منسّق قناة أو تحديثه
- حلّل مرة واحدة باستخدام
markdownToIR(...)، مع تمرير الخيارات المناسبة للقناة (autolinkوheadingStyleوblockquotePrefixوtableMode). - صيّر باستخدام
renderMarkdownWithMarkers(...)وخريطة علامات أنماط (أو منطق مخصص لنطاقات الأنماط لوسائل نقل مثل Signal). - قسّم باستخدام
chunkMarkdownIR(...)أوrenderMarkdownIRChunksWithinLimit(...)قبل تصيير كل جزء. - اربط المهايئ لاستدعاء المقسّم والمصيّر الجديدين من مسار الإرسال الصادر.
- اختبر باختبارات التنسيق إلى جانب اختبار تسليم صادر إذا كانت القناة تقسّم الرسائل.
مشكلات شائعة
- يجب أن تبقى رموز Slack المحاطة بأقواس زاوية (
<@U123>و<#C123>و<https://...>) سليمة أثناء التخطي؛ ولا يزال يلزم تخطي HTML الخام بأمان. - يتطلب HTML في Telegram تخطي النص خارج الوسوم لتجنب تلف الترميز.
- تستخدم نطاقات الأنماط في Signal إزاحات UTF-16، لا إزاحات نقاط الشيفرة.
- احتفظ بالأسطر الجديدة اللاحقة في كتل الشيفرة المسيّجة كي تقع علامة الإغلاق في سطر مستقل.
