API ورودی کانال

مسیرهای دریافت کانال از یک جریان پیروی می‌کنند:

رویداد پلتفرم -> واقعیت‌ها/زمینه ورودی -> پاسخ عامل -> تحویل پیام

برای نرمال‌سازی رویداد ورودی، قالب‌بندی، ریشه‌ها و هماهنگ‌سازی از openclaw/plugin-sdk/channel-inbound استفاده کنید. برای ارسال بومی، رسید، تحویل پایدار و رفتار پیش‌نمایش زنده از openclaw/plugin-sdk/channel-outbound استفاده کنید.

کمک‌تابع‌های اصلی

   buildChannelInboundEventContext,  runChannelInboundEvent,  dispatchChannelInboundReply,} from "openclaw/plugin-sdk/channel-inbound";

• buildChannelInboundEventContext(...): واقعیت‌های نرمال‌شده کانال را به زمینه اعلان/نشست نگاشت می‌کند. فراداده فرستنده/گفت‌وگوی تحت مالکیت کانال را از طریق channelContext عبور دهید که قلاب‌های Plugin آن را به‌صورت ctx.channelContext می‌بینند. برای فیلدهای مختص کانال، PluginHookChannelSenderContext یا PluginHookChannelChatContext را از این زیرمسیر تکمیل کنید.
• runChannelInboundEvent(...): دریافت، طبقه‌بندی، بررسی مقدماتی، حل، ثبت، توزیع و نهایی‌سازی را برای یک رویداد ورودی پلتفرم اجرا می‌کند.
• dispatchChannelInboundReply(...): یک پاسخ ورودی ازپیش‌ساخته‌شده را با یک آداپتور تحویل ثبت و توزیع می‌کند.

برای رویدادهای ورودی صرفاً رسانه‌ای، بدنه پیام و متن فرمان را خالی نگه دارید و به‌ازای هر پیوست بومی یک واقعیت ChannelInboundMediaInput عبور دهید. هنگامی که یک خط تاریخچه پیرامونی یا حامل صرفاً متنی دیگری باید آن واقعیت‌ها را توصیف کند، از formatMediaPlaceholderText(media) استفاده کنید. این تابع هر واقعیت را ابتدا بر اساس kind، سپس نوع MIME و بعد پسوند مسیر یا URL طبقه‌بندی می‌کند؛ پیوست‌های بومی بارگیری‌نشده نیز باید هرکدام یک واقعیت صرفاً نوعی ایجاد کنند. از قالب‌بند برای ساخت بدنه اصلی ورودی استفاده نکنید.

رکوردهای پیوست تحت مالکیت Plugin را با toInboundMediaFacts(...) نرمال‌سازی کنید، سپس آرایه مرتب حاصل را از طریق فیلد media زمینه عبور دهید:

const media = toInboundMediaFacts([  { path: saved.path, url: nativeUrl, contentType: saved.contentType, messageId },]); const ctx = finalizeInboundContext({ Body: caption, media });

موقعیت در آرایه، هویت پیوست است. transcribed، messageId و workspaceDir هر واقعیت جایگزین فیلدهای قدیمی موازیِ شاخص/فضای کاری می‌شوند. فیلدهای زمینه MediaPath، MediaPaths، MediaUrl، MediaUrls، MediaType، MediaTypes، MediaTranscribedIndexes، MediaWorkspaceDir و MediaStaged، به‌همراه buildChannelInboundMediaPayload(...)، فقط به‌عنوان سازگاری منسوخ‌شده همچنان در دسترس هستند. Pluginهای جدید نباید آن‌ها را بسازند یا بخوانند.

کانال‌های همراه/بومی که از قبل شیء زمان‌اجرای تزریق‌شده Plugin را دریافت می‌کنند، می‌توانند به‌جای واردکردن مستقیم این زیرمسیر، همان کمک‌تابع‌ها را در runtime.channel.inbound.* فراخوانی کنند:

await runtime.channel.inbound.run({  channel: "demo",  accountId,  raw: platformEvent,  adapter: {    ingest: normalizePlatformEvent,    resolveTurn: resolveInboundReply,  },});

ورودی‌های dispatchChannelInboundReply(...) را برای توزیع‌کننده‌های سازگاری که تحویل پلتفرم را در آداپتور تحویل نگه می‌دارند، سرهم کنید. مسیرهای ارسال جدید باید به‌جای آن از آداپتورهای پیام و کمک‌تابع‌های پیام پایدارِ channel-outbound استفاده کنند.

قرارداد تسویه تحویل

ChannelInboundTurnPlan.delivery مالک ارسال بومی هر محموله پاسخ منطقی است. هسته مالک ترتیب قلاب‌های خروجی و، در صورت اعلام آمادگی آداپتور، مشاهده نهایی message_sent است. این مسئولیت‌ها را جدا نگه دارید تا یک محموله نتواند رویدادهای نهایی تکراری ایجاد کند.

فیلدهای نتیجه تحویل معانی زیر را دارند:

گزینه observeMessageSent آداپتور تحویل را روی true تنظیم کنید، هنگامی که هسته باید رویدادهای متعارف Plugin و داخلی message_sent را برای ارسال‌های غیرپایدار این آداپتور منتشر کند. این گزینه را از deliver برنگردانید و آن رویدادها را در Plugin نیز منتشر نکنید. ارسال‌های پایدار از قبل از طریق مالک خروجی مشترک منتشر می‌شوند و تکرار نمی‌شوند.

به‌ازای هر محموله منطقی یک نتیجه برگردانید. finalization یک ارسال دوم نیست و نباید reply_payload_sending یا message_sending را دوباره اجرا کند. به‌محض اینکه deliver برمی‌گردد، هسته ردشدن promise نهایی‌سازی را مشاهده می‌کند تا بدون رسیدگی نماند؛ هسته همچنان پس از تسویه توزیع پاسخ، منتظر promise اصلی می‌ماند. سپس به‌ازای هر محموله حداکثر یک مشاهده نهایی با محتوای نهایی‌شده و شناسه ارائه‌دهنده منتشر می‌کند. در صورت وجود onDelivered، نتیجه تسویه‌شده پس از آن مشاهده به آن داده می‌شود.

هنگام شکست تحویل بومی، deliver یا finalization را رد کنید. اگر هیچ ارسال ارائه‌دهنده‌ای تلاش نشد، PlatformMessageNotDispatchedError را از openclaw/plugin-sdk/error-runtime پرتاب کنید؛ هسته یک رویداد نادرست message_sent را سرکوب می‌کند. اگر یک ارسال بومی پیش از شکست یک عملیات بعدی قابل‌مشاهده شد، زیرمجموعه قابل‌مشاهده را در خطا حفظ کنید:

 throw createChannelPartialDeliveryError(cause, {  visibleReplySent: true,  content: finalizedVisibleText,  receipt,});

هسته یک مشاهده نهایی ناموفق را با آن محتوا و هویت قابل‌مشاهده برای ارائه‌دهنده منتشر می‌کند، سپس تحویل را ناموفق نگه می‌دارد تا فراخوان‌ها موفقیت جزئی را با یک ارسال بی‌نقص اشتباه نگیرند. پس از قابل‌مشاهده‌شدن هرگونه پیش‌نمایش، پیش‌نویس، پیوست یا پیام نهایی، visibleReplySent: false را گزارش نکنید.

هنگامی که reply_payload_sending یا message_sending ثبت شده است، آن قلاب‌ها باید پیش از ایجاد هر چیز قابل‌مشاهده برای ارائه‌دهنده تسویه شوند، زیرا هر قلاب می‌تواند محموله منطقی را بازنویسی یا لغو کند. یک پیش‌نمایش بومی زودهنگام، محتوای پیش از بازنویسی را افشا می‌کند یا یک پیش‌نویس لغوشده باقی می‌گذارد. محتوای پیش‌نمایش را تا زمانی که محموله پذیرفته‌شده به deliver می‌رسد، بافر کنید؛ توزیع‌کننده‌های سازگاری که پیش‌نمایش‌ها را زودتر آغاز می‌کنند باید تا زمانی که یکی از این قلاب‌ها ثبت شده است، آن پیش‌نمایش زودهنگام را سرکوب کنند. برای مسیرهای پیش‌نمایش جدید از کمک‌تابع‌های پیش‌نمایش زنده قابل‌نهایی‌سازی در API خروجی کانال استفاده کنید.

مهاجرت

نام‌های مستعار زمان‌اجرای runtime.channel.turn.* حذف شدند. استفاده کنید از:

• runtime.channel.inbound.run(...) برای رویدادهای ورودی خام.
• runtime.channel.inbound.dispatchReply(...) برای زمینه‌های پاسخ سرهم‌شده.
• runtime.channel.inbound.buildContext(...) برای محموله‌های زمینه ورودی.
• runtime.channel.inbound.runPreparedReply(...)، منسوخ‌شده، فقط برای مسیرهای توزیع آماده‌شده تحت مالکیت کانال که از قبل بستار توزیع خود را سرهم می‌کنند.

کد Plugin جدید نباید APIهای کانال با نام turn معرفی کند. واژگان نوبت مدل یا عامل را در کد عامل/ارائه‌دهنده نگه دارید؛ Pluginهای کانال از اصطلاحات ورودی، پیام، تحویل و پاسخ استفاده می‌کنند.