# API ورودی کانال

ورودی کانال مرز آزمایشی کنترل دسترسی برای رویدادهای ورودی کانال است. برای مسیرهای دریافت از openclaw/plugin-sdk/channel-ingress-runtime استفاده کنید. زیربخش قدیمی‌تر openclaw/plugin-sdk/channel-ingress همچنان به‌عنوان نمای سازگاری منسوخ‌شده برای Pluginهای شخص ثالث صادر می‌ماند.

Pluginها مالک واقعیت‌های پلتفرم و اثرات جانبی هستند. هسته مالک سیاست عمومی است: فهرست‌های مجاز DM/گروه، ورودی‌های DM در pairing-store، دروازه‌های مسیر، دروازه‌های فرمان، احراز رویداد، فعال‌سازی با منشن، عیب‌یابی‌های پوشیده‌شده، و پذیرش.

# حل‌کننده زمان اجرا

  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,
});

فهرست‌های مجاز مؤثر، مالکان فرمان، یا گروه‌های فرمان را از پیش محاسبه نکنید. حل‌کننده آن‌ها را از فهرست‌های مجاز خام، callbackهای ذخیره‌گاه، توصیف‌گرهای مسیر، گروه‌های دسترسی، سیاست، و نوع مکالمه استخراج می‌کند.

# نتیجه

Pluginهای همراه باید projectionهای مدرن را مستقیماً مصرف کنند:

• ingress: تصمیم مرتب‌شده دروازه و پذیرش
• senderAccess: فقط مجوز فرستنده/مکالمه
• routeAccess: projection مسیر و فرستنده مسیر
• commandAccess: مجوز فرمان؛ وقتی هیچ دروازه فرمانی اجرا نشده باشد false است
• activationAccess: نتیجه منشن/فعال‌سازی

مجوز رویداد همچنان روی ingress.graph مرتب‌شده و ingress.reasonCode تعیین‌کننده در دسترس می‌ماند؛ هیچ projection جداگانه‌ای برای رویداد منتشر نمی‌شود.

کمک‌کننده‌های منسوخ SDK شخص ثالث می‌توانند شکل‌های قدیمی‌تر را به‌صورت داخلی بازسازی کنند. مسیرهای دریافت همراه جدید نباید نتایج مدرن را دوباره به DTOهای محلی تبدیل کنند.

# گروه‌های دسترسی

ورودی‌های accessGroup:<name> پوشیده‌شده باقی می‌مانند. هسته خودش گروه‌های ایستای message.senders را حل می‌کند و resolveAccessGroupMembership را فقط برای گروه‌های پویایی فراخوانی می‌کند که به جست‌وجوی پلتفرم نیاز دارند. گروه‌های ناموجود، پشتیبانی‌نشده، و ناموفق به‌صورت بسته شکست می‌خورند.

# حالت‌های رویداد

authMode	معنی
inbound	دروازه‌های عادی فرستنده ورودی
command	دروازه‌های فرمان برای callbackها یا دکمه‌های scoped
origin-subject	کنشگر باید با subject پیام اصلی مطابقت داشته باشد
route-only	فقط دروازه‌های مسیر برای رویدادهای مورد اعتماد scoped به مسیر
none	رویدادهای داخلی متعلق به Plugin از احراز مشترک عبور می‌کنند

برای واکنش‌ها، دکمه‌ها، callbackها، و فرمان‌های بومی از mayPair: false استفاده کنید.

# مسیرها و فعال‌سازی

برای سیاست اتاق، موضوع، guild، thread، یا مسیر تودرتو از توصیف‌گرهای مسیر استفاده کنید:

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

وقتی یک Plugin چند توصیف‌گر مسیر اختیاری دارد از channelIngressRoutes(...) استفاده کنید؛ شاخه‌های غیرفعال را فیلتر می‌کند و در عین حال واقعیت‌های مسیر را عمومی و مطابق precedence هر توصیف‌گر مرتب نگه می‌دارد.

دروازه‌گذاری منشن یک دروازه فعال‌سازی است. نبود منشن admission: "skip" برمی‌گرداند تا هسته turn یک turn فقط مشاهده‌ای را پردازش نکند. بیشتر کانال‌ها باید فعال‌سازی را پس از دروازه‌های فرستنده و فرمان باقی بگذارند. سطوح گفت‌وگوی عمومی که باید ترافیک بدون منشن را پیش از نویز فهرست مجاز فرستنده ساکت کنند، وقتی عبور فرمان متنی غیرفعال است، می‌توانند activation.order: "before-sender" را انتخاب کنند. کانال‌هایی با فعال‌سازی ضمنی، مانند پاسخ‌ها در threadهای بات، می‌توانند activation.allowedImplicitMentionKinds را ارسال کنند؛ سپس activationAccess.shouldBypassMention projected گزارش می‌دهد چه زمانی فرمان یا فعال‌سازی ضمنی از منشن صریح عبور کرده است.

# پوشاندن

مقادیر خام فرستنده و ورودی‌های خام فهرست مجاز فقط ورودی حل‌کننده هستند. آن‌ها نباید در وضعیت حل‌شده، تصمیم‌ها، عیب‌یابی‌ها، snapshotها، یا واقعیت‌های سازگاری ظاهر شوند. از شناسه‌های opaque برای subject، شناسه‌های ورودی، شناسه‌های مسیر، و شناسه‌های عیب‌یابی استفاده کنید.

# راستی‌آزمایی

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