跳转至

提及策略

Decide when an inbound message counts as a mention, without reimplementing the shared policy. Part of the Building channel plugins guide.

入站提及策略

将入站提及处理拆分为两层:

  • 插件拥有的证据收集
  • 共享策略评估

使用 openclaw/plugin-sdk/channel-mention-gating 进行提及策略决策。 仅当需要更广泛的入站辅助 barrel 时使用 openclaw/plugin-sdk/channel-inbound。

适合插件本地逻辑的场景:

  • 回复机器人的检测
  • 引用机器人的检测
  • 线程参与检查
  • 机器人拥有线程的检测以及频道特定配置继承
  • 服务/系统消息排除
  • 证明机器人参与所需的平台原生缓存

适合共享辅助函数的场景:

  • requireMention
  • 显式提及结果
  • 隐式提及允许列表
  • 命令绕过
  • 最终跳过决策

对于符合条件的群线程条目,使用来自 openclaw/plugin-sdk/channel-inbound 的 resolveGroupThreadMentionFacts({ cfg, channel, peerId, text, sessionKey, acpBinding }) 计算一次显式参与者提及事实,包括直接会话。传入解析后的会话密钥以及已配置的 ACP 绑定是否拥有该路由。对于独占的 ACP 路由或没有符合条件的条目时,它返回 undefined;否则返回解析后的群组以及 mentionedAgentIds。如果准备之后路由 发生变化,使用 isGroupThreadRouteExclusive({ sessionKey, acpBinding }) 丢弃 ACP 拥有目的地的参与者事实,并仅使用最终路由的普通提及和命令事实重新 评估准入。在普通门控之前,将非空的参与者匹配与路由代理的本地提及事实合并, 并将相同的选择事实带入分发。对未路由参与者的提及不得被单代理门控丢弃。 参与者选择需要 @ 样式匹配;仅名称或表情符号不会选择代理。保持发送者授权 和命令策略不变。

设置可选的 replyOptions.groupThreadReplyFormatter(text, participant),以将 适配器的参与者标签应用于源会话消息工具回复。参与者包含 agentId 和 name; 复用用于普通回复的同一传输格式化器,并附带参与者投递元数据。

对于插件拥有的发送,在投递入口从同一 SDK 读取 getGroupThreadDeliverySession()。 如果存在,使用其 agentId 和 sessionKey 作为媒体根目录、内部钩子和转录镜像, 包括未标记的单代理群组。保持传输账户所有权不变。共享持久投递在核心中选择活动 的参与者上下文和运行身份。

推荐流程:

  1. 计算本地提及事实。
  2. 将这些事实传入 resolveInboundMentionDecision({ facts, policy })。
  3. 在你的入站门控中使用 decision.effectiveWasMentioned、decision.shouldBypassMention 和 decision.shouldSkip。
import {
  implicitMentionKindWhen,
  matchesMentionWithExplicit,
  resolveInboundMentionDecision,
} from "openclaw/plugin-sdk/channel-inbound";
import { resolveChannelImplicitMentions } from "openclaw/plugin-sdk/channel-ingress-runtime";

const wasMentioned = matchesMentionWithExplicit({
  text,
  mentionRegexes,
  explicit: {
    hasAnyMention,
    isExplicitlyMentioned,
    canResolveExplicit,
  },
});

const facts = {
  canDetectMention: true,
  wasMentioned,
  hasAnyMention,
  implicitMentionKinds: [
    ...implicitMentionKindWhen("reply_to_bot", isReplyToBot),
    ...implicitMentionKindWhen("quoted_bot", isQuoteOfBot),
  ],
};

const implicitMentions = resolveChannelImplicitMentions({
  cfg,
  channel: channelId,
  accountId,
});

const decision = resolveInboundMentionDecision({
  facts,
  policy: {
    isGroup,
    requireMention,
    implicitMentions,
    allowTextCommands,
    hasControlCommand,
    commandAuthorized,
  },
});

if (decision.shouldSkip) return;

matchesMentionWithExplicit(...) 返回布尔值。hasAnyMention、 isExplicitlyMentioned 和 canResolveExplicit 来自频道自身的原生提及元数据 (消息实体、回复机器人标志等);当你的平台无法检测它们时,提供 false/undefined 值。

api.runtime.channel.mentions 为已经依赖运行时注入的捆绑频道插件公开相同的 共享提及辅助函数:buildMentionRegexes、matchesMentionPatterns、 matchesMentionWithExplicit、implicitMentionKindWhen、 resolveInboundMentionDecision。

如果你只需要 implicitMentionKindWhen 和 resolveInboundMentionDecision, 请从 openclaw/plugin-sdk/channel-mention-gating 导入,以避免加载无关的入站 运行时辅助函数。

机器人拥有的线程

具有原生线程所有权的频道可以公开 requireMentionInBotThreads。省略该值会保留 频道现有的提及行为。false 允许在由已配置机器人启动的线程中发送不带提及的 消息。true 要求在那里进行提及,即使普通 requireMention 设置为 false 也是如此;回复或引用机器人以及机器人先前的参与都不满足该要求。显式提及、原生 提及证据和已授权的命令绕过保留其普通行为。

插件负责证明当前机器人启动了线程,并在调用 openclaw/plugin-sdk/channel-mention-gating 中的 resolveBotThreadMentionPolicy 之前解析最具体的配置值。仅机器人参与并不构成 所有权。对于未知所有权、外部线程和普通频道消息,传入 isBotOwnedThread: false 以保留现有行为。

在收集提及证据之后、共享决策之前应用该辅助函数:

const threadPolicy = resolveBotThreadMentionPolicy({
  isBotOwnedThread,
  requireMentionInBotThreads,
  requireMention,
  implicitMentionKinds: facts.implicitMentionKinds,
});

const decision = resolveInboundMentionDecision({
  facts: { ...facts, implicitMentionKinds: threadPolicy.implicitMentionKinds },
  policy: { ...policy, requireMention: threadPolicy.requireMention },
});

此覆盖仅更改提及准入。请保留现有的发送者允许列表、频道访问策略和命令授权。对于没有可靠原生所有权证据的频道,不应根据缓存的参与记录推断所有权,也不应暴露其无法强制执行的覆盖。

在将回合交给共享分发之前,重新检查可变准入规则。准入之后,应保留该回合已捕获的策略用于其回复,而不是使用提及或发送者门控来取消投递。账户、运行和传输存活状态仍分别由其现有负责人负责。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw