مارک ڈاؤن فارمیٹنگ¶

OpenClaw آؤٹ باؤنڈ Markdown کو ایک مشترکہ انٹرمیڈیٹ representation (IR) میں تبدیل کر کے فارمیٹ کرتا ہے، اس سے پہلے کہ چینل کے مطابق آؤٹ پٹ رینڈر ہو۔ IR ماخذ متن کو برقرار رکھتا ہے جبکہ style/link spans لے کر چلتا ہے تاکہ chunking اور rendering چینلز میں یکساں رہیں۔

اہداف¶

• یکسانیت: ایک ہی پارسنگ مرحلہ، متعدد رینڈررز۔
• محفوظ چنکنگ: رینڈرنگ سے پہلے متن کو تقسیم کریں تاکہ اِن لائن فارمیٹنگ کبھی بھی چنکس کے درمیان نہ ٹوٹے۔
• چینل کے مطابق: ایک ہی IR کو دوبارہ مارک ڈاؤن پارس کیے بغیر Slack mrkdwn، Telegram HTML، اور Signal کے اسٹائل رینجز میں میپ کریں۔

پائپ لائن¶

1. مارک ڈاؤن پارس کریں -> IR - IR سادہ متن کے ساتھ اسٹائل اسپینز (بولڈ/اٹالک/اسٹرائک/کوڈ/اسپوئلر) اور لنک اسپینز پر مشتمل ہوتا ہے۔ - آف سیٹس UTF-16 کوڈ یونٹس میں ہوتے ہیں تاکہ Signal کے اسٹائل رینجز اس کی API کے ساتھ ہم آہنگ رہیں۔ - ٹیبلز صرف اسی صورت پارس کی جاتی ہیں جب کوئی چینل ٹیبل کنورژن کے لیے آپٹ اِن کرے۔
2. IR کو چنک کریں (فارمیٹ-فرسٹ) - چنکنگ رینڈرنگ سے پہلے IR کے متن پر ہوتی ہے۔ - اِن لائن فارمیٹنگ چنکس کے درمیان تقسیم نہیں ہوتی؛ اسپینز ہر چنک کے مطابق کاٹے جاتے ہیں۔
3. ہر چینل کے لیے رینڈر کریں - Slack: mrkdwn ٹوکنز (بولڈ/اٹالک/اسٹرائک/کوڈ)، لنکس بطور <url|label>۔ - Telegram: HTML ٹیگز (<b>, <i>, <s>, <code>, <pre><code>, <a href>)۔ - Signal: سادہ متن + text-style رینجز؛ جب لیبل مختلف ہو تو لنکس label (url) بن جاتے ہیں۔

IR کی مثال¶

ان پٹ مارک ڈاؤن:

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.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>؛ سادہ URLs سادہ ہی رہتی ہیں۔ Autolink parse کے دوران غیر فعال ہوتا ہے تاکہ ڈبل-لنکنگ سے بچا جا سکے۔
• Telegram: [label](url) -> <a href="url">label</a> (HTML پارس موڈ)۔
• Signal: [label](url) -> label (url)، الا یہ کہ لیبل URL سے مطابقت رکھتا ہو۔

اسپوئلرز¶

اسپوئلر مارکرز (||spoiler||) صرف Signal کے لیے پارس کیے جاتے ہیں، جہاں وہ میپ ہوتے ہیں SPOILER style ranges. Other channels treat them as plain text.

چینل فارمیٹر کیسے شامل یا اپڈیٹ کریں¶

1. ایک بار پارس کریں: مشترکہ markdownToIR(...) ہیلپر کو چینل کے مطابق اختیارات (آٹو لنک، ہیڈنگ اسٹائل، بلاک کوٹ پری فکس) کے ساتھ استعمال کریں۔
2. رینڈر کریں: renderMarkdownWithMarkers(...) اور ایک اسٹائل مارکر میپ (یا Signal اسٹائل رینجز) کے ساتھ رینڈرر نافذ کریں۔
3. چنک کریں: رینڈرنگ سے پہلے chunkMarkdownIR(...) کال کریں؛ ہر چنک کو رینڈر کریں۔
4. اڈاپٹر جوڑیں: چینل آؤٹ باؤنڈ اڈاپٹر کو نئے چنکر اور رینڈرر کے استعمال کے لیے اپڈیٹ کریں۔
5. جانچ: فارمیٹ ٹیسٹس شامل یا اپڈیٹ کریں اور اگر چینل چنکنگ استعمال کرتا ہے تو آؤٹ باؤنڈ ڈیلیوری ٹیسٹ شامل کریں۔

عام مسائل¶

• Slack کے اینگل بریکٹ ٹوکنز (<@U123>, <#C123>, <https://...>) کو محفوظ رکھنا لازم ہے؛ خام HTML کو محفوظ طریقے سے ایسکیپ کریں۔
• Telegram HTML میں ٹیگز کے باہر متن کو ایسکیپ کرنا ضروری ہے تاکہ مارک اپ خراب نہ ہو۔
• Signal کے اسٹائل رینجز UTF-16 آف سیٹس پر منحصر ہوتے ہیں؛ کوڈ پوائنٹ آف سیٹس استعمال نہ کریں۔
• فینسڈ کوڈ بلاکس کے لیے اختتامی نئی سطریں محفوظ رکھیں تاکہ بند کرنے والے مارکر اپنی الگ سطر پر آئیں۔