واجهة برمجة تطبيقات استقبال القناة

دخول القنوات هو حد تجريبي للتحكم في الوصول إلى أحداث القنوات الواردة. تمتلك Plugins حقائق المنصة والآثار الجانبية؛ بينما تمتلك النواة السياسة العامة: قوائم السماح للرسائل المباشرة/المجموعات، وإدخالات الرسائل المباشرة في مخزن الاقتران، وبوابات المسارات، وبوابات الأوامر، وتخويل الأحداث، والتفعيل عند الإشارة، والتشخيصات المنقّحة، و القبول.

استخدم openclaw/plugin-sdk/channel-ingress-runtime لمسارات الاستقبال.

محلّل وقت التشغيل

   defineStableChannelIngressIdentity,  resolveChannelMessageIngress,} from "openclaw/plugin-sdk/channel-ingress-runtime"; const identity = defineStableChannelIngressIdentity({  key: "platform-user-id",  normalize: normalizePlatformUserId,  sensitivity: "pii",}); const result = await resolveChannelMessageIngress({  channelId: "my-channel",  accountId,  identity,  subject: { stableId: platformUserId },  conversation: { kind: isGroup ? "group" : "direct", id: conversationId },  event: { kind: "message", authMode: "inbound", mayPair: !isGroup },  policy: {    dmPolicy: config.dmPolicy,    groupPolicy: config.groupPolicy,    groupAllowFromFallbackToAllowFrom: true,  },  allowFrom: config.allowFrom,  groupAllowFrom: config.groupAllowFrom,  accessGroups: cfg.accessGroups,  route,  readStoreAllowFrom,  command: hasControlCommand ? { allowTextCommands: true, hasControlCommand } : undefined,});

لا تحسب مسبقًا قوائم السماح الفعلية أو مالكي الأوامر أو مجموعات الأوامر. يشتقها المحلّل من قوائم السماح الأولية، واستدعاءات المخزن، وواصفات المسارات، ومجموعات الوصول، والسياسة، ونوع المحادثة.

النتيجة

ينبغي أن تستهلك Plugins المضمّنة الإسقاطات الحديثة مباشرةً:

يظل تخويل الأحداث متاحًا في ingress.graph المرتّب وفي ingress.reasonCode الحاسم؛ ولا يُصدر إسقاط مستقل للأحداث.

يجوز لأدوات SDK الخارجية المهملة إعادة إنشاء الأشكال الأقدم داخليًا. ينبغي ألا تحوّل مسارات الاستقبال المضمّنة الجديدة النتائج الحديثة مجددًا إلى كائنات DTO محلية.

مجموعات الوصول

تظل إدخالات accessGroup:<name> منقّحة. تحل النواة مجموعات message.senders الثابتة بنفسها، ولا تستدعي resolveAccessGroupMembership إلا للمجموعات الديناميكية التي تتطلب بحثًا في المنصة. تفشل المجموعات المفقودة وغير المدعومة والتي تعذّر حلها بصورة مغلقة.

أوضاع الأحداث

استخدم mayPair: false للتفاعلات والأزرار وعمليات رد النداء والأوامر الأصلية.

المسارات والتفعيل

استخدم واصفات المسارات لسياسة الغرفة أو الموضوع أو الخادم أو سلسلة الرسائل أو المسارات المتداخلة:

route: {  id: "room",  allowed: roomAllowed,  enabled: roomEnabled,  senderPolicy: "replace",  senderAllowFrom: roomAllowFrom,  blockReason: "room_sender_not_allowlisted",}

استخدم channelIngressRoutes(...) عندما يحتوي Plugin على عدة واصفات مسارات اختيارية؛ فهو يرشّح الفروع المعطّلة مع إبقاء حقائق المسارات عامة ومرتبة وفق precedence لكل واصف.

بوابة الإشارة هي بوابة تفعيل. يؤدي غياب الإشارة إلى إرجاع admission: "skip" حتى لا تعالج نواة الدور دورًا مخصصًا للمراقبة فقط. ينبغي لمعظم القنوات وضع التفعيل بعد بوابات المرسل والأوامر. ويمكن لواجهات المحادثة العامة التي يجب أن تكتم حركة البيانات غير المشار إليها قبل ضوضاء قائمة سماح المرسل اختيار activation.order: "before-sender" عند تعطيل تجاوز الأوامر النصية. ويمكن للقنوات ذات التفعيل الضمني، مثل الردود في سلاسل رسائل البوت، تمرير activation.allowedImplicitMentionKinds؛ وعندئذ يبيّن activationAccess.shouldBypassMention المسقَط متى تجاوز الأمر أو التفعيل الضمني إشارة صريحة.

التنقيح

قيم المرسل الأولية وإدخالات قائمة السماح الأولية هي مدخلات للمحلّل فقط. ويجب ألا تظهر في الحالة المحلولة أو القرارات أو التشخيصات أو اللقطات أو حقائق التوافق. استخدم معرّفات موضوعات وإدخالات ومسارات و تشخيصات مبهمة.

التحقق

pnpm test src/channels/message-access/message-access.test.ts src/plugin-sdk/channel-ingress-runtime.test.tspnpm plugin-sdk:api:check