Concept internals
قالببندی Markdown
OpenClaw پیش از رندر خروجی مختص هر کانال، Markdown خروجی را به یک نمایش میانی مشترک (IR) تبدیل میکند. IR متن ساده را همراه با گسترههای سبک/پیوند نگه میدارد؛ بنابراین یک مرحله تجزیه برای همه کانالها استفاده میشود و قطعهبندی هرگز قالببندی را در میانه یک گستره نمیشکند.
خط لوله
- تجزیه Markdown به IR (
markdownToIR) - متن ساده بههمراه گسترههای سبک (پررنگ، مورب، خطخورده، کد، بلوک کد، متن پنهان، نقلقول بلوکی، سرفصلهای ۱ تا ۶) و گسترههای پیوند. آفستها واحدهای کد UTF-16 هستند تا محدودههای سبک Signal مستقیماً با API آن همتراز شوند. جدولها فقط زمانی تجزیه میشوند که کانال یک حالت جدول را فعال کرده باشد. - قطعهبندی IR (
chunkMarkdownIR/renderMarkdownIRChunksWithinLimit)- تقسیم پیش از رندر روی متن IR انجام میشود؛ بنابراین سبکهای درونخطی و پیوندها برای هر قطعه برش میخورند، نه اینکه در مرز قطعه شکسته شوند.
- رندر برای هر کانال (
renderMarkdownWithMarkers) - یک نگاشت نشانگر سبک، گسترهها را به نشانهگذاری بومی کانال تبدیل میکند.
| کانال | رندرکننده | نکات |
|---|---|---|
| Slack | توکنهای mrkdwn (*bold*، _italic_، `code`، حصارهای کد) |
پیوندها به <url|label> تبدیل میشوند؛ برای جلوگیری از پیونددهی دوباره، autolink هنگام تجزیه غیرفعال است |
| Telegram | تگهای HTML (<b>، <i>، <s>، <code>، <pre><code>، <a href>، <tg-spoiler>) |
وقتی richMessages روشن باشد، از جدولهای پیام غنی و سرفصلها (<h1>-<h6>) نیز پشتیبانی میکند |
| Signal | متن ساده + محدودههای text-style |
وقتی برچسب با URL متفاوت باشد، پیوندها بهشکل label (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 است (که مگر در صورت فعالبودن richMessages برای حساب، به code
تبدیل میشود). هر کانالی که پیشفرض صریحی در 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 استفاده میکنند، نه آفستهای نقطه کد.
- نویسههای خط جدید انتهایی بلوکهای کد حصاردار را حفظ کنید تا نشانگر پایانی در خط مستقل خود قرار گیرد.
