Plugin SDK Channel 轮次内核

概述

Channel 轮次内核是共享的入站状态机，将规范化的平台事件转换为 Agent 轮次。Channel 插件提供平台事实和投递回调；核心拥有编排：摄取、分类、预检、解析、授权、组装、记录、派发和最终化。

通过注入的插件运行时访问：runtime.channel.turn.*。

核心 API

四个核心概念（刻意分离）

概念	含义
ConversationFacts	消息来自哪里
RouteFacts	哪个 Agent 和会话应处理它
ReplyPlanFacts	可见回复应发往哪里
MessageFacts	Agent 应看到的正文和补充上下文

阶段生命周期（固定流水线）

1. ingest — 适配器将原始平台事件转换为 NormalizedTurnInput
2. classify — 适配器声明此事件是否可以启动 Agent 轮次
3. preflight — 去重、自回声、水化、防抖、解密
4. resolve — 适配器返回完整组装的轮次
5. authorize — DM、群组、提及和命令策略
6. assemble — 从事实构建 FinalizedMsgContext
7. record — 持久化入站会话元数据和最后路由
8. dispatch — 通过缓冲块派发器执行 Agent 轮次
9. finalize — 适配器 onFinalize 即使在派发错误时也运行

准入类型

类型	含义
dispatch	轮次被接受，Agent 轮次运行
observeOnly	轮次端到端运行但投递适配器不发送可见内容
handled	平台事件被本地消费（生命周期、反应、按钮等）
drop	跳过路径，可选 recordHistory: true

入口点

runtime.channel.turn.run(...)          // 适配器驱动的完整流水线
runtime.channel.turn.runAssembled(...) // 已构建上下文 + 投递适配器
runtime.channel.turn.runPrepared(...)  // Channel 拥有派发；内核运行记录 + 最终化
runtime.channel.turn.buildContext(...) // 纯事实到 FinalizedMsgContext 映射

适配器契约

type ChannelTurnAdapter<TRaw> = {
  ingest(raw: TRaw): Promise<NormalizedTurnInput | null> | NormalizedTurnInput | null;
  classify?(input: NormalizedTurnInput): Promise<ChannelEventClass> | ChannelEventClass;
  preflight?(input, eventClass): Promise<PreflightFacts | ChannelTurnAdmission | null>;
  resolveTurn(input, eventClass, preflight): Promise<ChannelTurnResolved> | ChannelTurnResolved;
  onFinalize?(result: ChannelTurnResult): Promise<void> | void;
};

投递适配器

type ChannelTurnDeliveryAdapter = {
  deliver(payload: ReplyPayload, info: ChannelDeliveryInfo): Promise<ChannelDeliveryResult | void>;
  onError?(err: unknown, info: { kind: string }): void;
  durable?: false | DurableInboundReplyDeliveryOptions;
};

使用示例

await runtime.channel.turn.run({
  channel: "tlon",
  accountId,
  raw: platformEvent,
  adapter: {
    ingest(raw) {
      return { id: raw.messageId, timestamp: raw.timestamp, rawText: raw.body };
    },
    classify(input) {
      return { kind: "message", canStartAgentTurn: input.rawText.length > 0 };
    },
    async preflight(input) {
      if (await isDuplicate(input.id)) return { admission: { kind: "drop", reason: "dedupe" } };
      return {};
    },
    resolveTurn(input) { return buildAssembledTurn(input); },
    onFinalize(result) { clearPendingGroupHistory(result); },
  },
  log: (event) => runtime.log?.debug?.(`turn.${event.stage}:${event.event}`),
});

相关页面

• concepts/plugin-sdk-channel-plugins — Channel 插件构建指南
• concepts/plugin-sdk-channel-message — 消息生命周期 API
• concepts/plugin-sdk-runtime — 其他 runtime.* 面
• message-lifecycle-refactor — 消息生命周期重构设计