openJiuwen agent-core 团队交互路由:严格 `@<member>` 收件人匹配与未知提及折叠回文本的实现解析

原创2026-10-11 23:12:351,871 阅读
文章标签:人工智能大模型AI AgentAgent 框架Agent 编排多智能体工作流自动化RAGEmbeddingRerank向量数据库MCP 服务提示工程可观测性后端

openJiuwen agent-core 团队交互路由:严格 @<member> 收件人匹配与未知提及折叠回文本的实现解析

导读:本文聚焦 openJiuwen agent-core 中 openjiuwen/agent_teams 团队模块的一个关键交互语义——interact(str) 输入中的 @<member> 前缀如何被严格校验并路由。核心解决一个真实缺陷:用户敲出指向不存在成员的 @ghost 时,旧实现会在消息总线里凭空写入一条发给 ghost 的消息(# 类 Operator 路径)或整体丢弃用户输入($ 类 HumanAgent 路径)。本文将以特性文档 F_23_strict-recipient-match-fold-unknown-mentions.md 为骨架,结合 router.py、manager.py 与两套单元测试,完整剖析"严格匹配 roster、未知提及折叠回文本"的设计决策、实现原理与行为契约,读者读完可以掌握该路由层从语法解析到派发的完整链路,并能据此扩展或排查团队交互行为。

背景:两条派发路径的行为不一致

在 openJiuwen 的团队运行时中,外部用户通过 interact(str, ...) 向团队投递输入。输入的前缀语法由 parse_interact_str 解析(见 router.py),它是一个纯语法(pure syntax)函数:不查 roster(成员名册),只是把每个 @<member> token 直接 fan-out(扇出)成带 target 字段的 payload,把成员是否存在的校验留给后续派发阶段。

问题在于:两条派发路径行为不一致,且都不符合预期。

  • # 类(Operator,外部用户视角):UserInbox.direct 完全不校验成员存在,直接调用 send_message 写消息总线。用户敲一个不存在的 @ghost,就会在 DB 里凭空生成一条发给 ghost 的消息——这是该特性要修复的核心 bug。从源码看,user_inbox.py 的 direct 方法 docstring 明确写着 "Caller is responsible for validating that target exists in the roster",即校验责任外置,但历史上 interact 并未落实。
  • $ 类(HumanAgent,团队成员视角):deliver_direct 校验了成员存在(返回 unknown_member:<target> 失败 token),但没有降级处理——不存在时整条输入被丢弃,不写库但用户内容也丢了。

预期行为统一为:严格匹配 roster;匹配不到的 @ 不是路由指令,按"无 @ 的一般输入"处理——# 投给 leader 的 DeepAgent,$ 投给该 avatar,使 $/# 两类行为一致。

该特性实现的核心代码路径为:

核心数据模型:消除"特殊情况"

特性的设计核心是一条统一模型:

每个 @mention 要么是有效路由指令(消费成一条点对点消息),要么无效(它就是普通文本,折回到 leader/avatar 的一条"无 @ 消息"里)。

围绕这个模型,router.py 新增/复用了三个关键构件:

1. resolve_targets(payloads, *, member_exists):解析后的 roster 校验步骤

这是一个 async 函数(roster 查询是异步的),签名如下:

async def resolve_targets(
    payloads: list["InteractPayload"],
    *,
    member_exists: MemberExistsCheck,
) -> list["InteractPayload"]:

核心逻辑:

  • 复用文件内既有的 MemberExistsCheck 谓词模式(与 deliver_direct 并列使用)。MemberExistsCheck 定义为 Callable[[str], Awaitable[bool]],即"名字是否指向真实 roster 成员"的异步谓词;调用方注入闭包,谓词归属由调用方决定。
  • 已知 recipient 的点对点 payload 原样保留;未知 recipient 折回;god-view / avatar-drive / broadcast(@all/@*,无 named target)直接 passthrough(它们不查 roster)。
  • 全部已知 → 原样返回;否则返回 <已知点对点 payloads> + [<一条折回的无 @ payload>]。
unknown: list["InteractPayload"] = []
kept: list["InteractPayload"] = []
for payload in payloads:
    name = _named_target(payload)
    if name is None or await member_exists(name):
        kept.append(payload)
    else:
        unknown.append(payload)

if not unknown:
    return payloads
return kept + [_fold_unknown_mentions(unknown)]

2. _named_target(payload):识别"真正的点名"

取出 payload 的点对点 recipient;god-view / avatar-drive / broadcast 返回 None(它们不查 roster)。实现上检查 payload 是否为 OperatorMessage 或 HumanAgentMessage,且 target 非空且不在 BROADCAST_TARGETS(frozenset({"all", "*"}))中。

3. _fold_unknown_mentions(unknown):把未知提及拼回正文

把未知 mention 重新拼回正文("@g1 @g2 <body>"),按 channel 折成 GodViewMessage(Operator 来源)或 HumanAgentMessage(sender=..., target=None)(HumanAgent 来源):

sample = unknown[0]
mentions = " ".join(f"@{p.target}" for p in unknown)
general_body = f"{mentions} {sample.body}" if sample.body else mentions
if isinstance(sample, HumanAgentMessage):
    return HumanAgentMessage(body=general_body, sender=sample.sender)
return GodViewMessage(body=general_body)

注意:当 @ghost 后面没有正文时,折回消息体就是纯 @ghost;有正文时保持 @ghost <body> 的原文顺序。

4. manager.py:_resolve_recipients(agent, payloads):backend 到谓词的适配

manager.py 中的 _resolve_recipients 把 backend.get_member(name) is not None 适配成 member_exists 布尔谓词,再调 resolve_targets;当 backend 为 None(纯 god-view agent)时没有 roster 可匹配,直接 passthrough:

backend = agent.team_backend
if backend is None:
    return payloads

async def _member_exists(name: str) -> bool:
    return await backend.member_exists(name)

return await resolve_targets(payloads, member_exists=_member_exists)

这里实际调用的是 TeamBackend.member_exists(team.py),它比 get_member 更轻量——只查 DB 判断成员是否存在,不加载 agent_card / prompt / options 等完整行数据,专为 recipient 校验这类"只要存在性"的调用设计。

关键时序:持有 gate ticket 之后才校验

resolve_targets 被调用在 interact 持有 gate ticket 之后(与 dispatch 串行;gate 关闭时不触达 agent)。见 manager.py:

ticket = await entry.interact_gate.admit()
if ticket is None:
    return DeliverResult.failure("gate_closed")
try:
    # Strict-match ``@<member>`` recipients against the live roster...
    return await self.dispatch_payloads(entry.agent, payloads, entry=entry)
finally:
    await entry.interact_gate.consume_done(ticket)

InteractGate(gate.py)是每个 ActiveTeam 持有的"运行/交互并发契约"闸门:run 在途时可以 admit 新 payload,run 退出时关闭闸门并排空在途请求。收件人校验放在持票之后,保证了校验与派发在同一把并发锁内完成,避免竞态。

而 dispatch_payloads 则是把 _resolve_recipients 与逐条 _dispatch_payload 串起来的入口(manager.py):

payloads = await TeamRuntimeManager._resolve_recipients(agent, payloads)
last_result: DeliverResult = DeliverResult.success(None)
for entry_payload in payloads:
    last_result = await TeamRuntimeManager._dispatch_payload(agent, entry_payload, entry=entry)
    if not last_result.ok:
        return last_result
return last_result

决策剖析:为什么"折叠回文本"而不是丢弃或报错

决策 1:未知 @ 折回为文本,而非丢弃 / 报错

理由与既有语义一致:parse_interact_str("@dev-1")(无 body,不构成合法 mention)本就把 @dev-1 当纯文本保留。"@ 指向不存在的成员"同理——它不是合法路由,就是文本。报错会破坏"用户随便敲"的体验;丢弃会无声吞掉用户内容。

决策 2:降级正文保留原文(含失效 @ 前缀)

# @ghost ship it → leader 收到 @ghost ship it,而非 ship it。不丢用户内容;leader 能看到用户本想找谁(可能是 typo)。这一点由 _fold_unknown_mentions 的 general_body = f"{mentions} {sample.body}" 保证。

决策 3:部分匹配 = 有效照常点对点 + 无效折回一条

# @m1 @ghost on it(m1 在、ghost 不在)→ m1 收到点对点 on it,同时 leader 收到 @ghost on it。这是用户明确要求("无效的 @ 也同时投递给 leader 或 $ 的成员,作为一般输入")。注意折回正文是"原文去掉已成功路由的 mention"——已路由的 @m1 被消费,未路由的 @ghost 作为文本留下。

决策 4:校验落在 interact(组级),不落在 _dispatch_payload(逐条)

"一个都没匹配上才整体降级 / 部分匹配如何拆分"需要看整组 recipient;逐条 dispatch 看不到兄弟 recipient。因此 _dispatch_payload 保持"哑路由",只按 payload 类型分发——直接调它的单测仍然有效(这正是 test_dispatch_payload.py 中 test_operator_message_direct_routes_to_member 等测试仍然成立的原因)。

决策 5:str 与结构化 payload 统一走 resolve_targets

结构化入参(SDK 直传 OperatorMessage(target=...))同样受严格匹配保护,不再有"绕过 str 解析就能给不存在成员写库"的洞。从代码看,interact 中无论是 str 经过 parse_interact_str 得到的 payload 列表,还是直接传入的结构化 payload,都走同一个 dispatch_payloads → _resolve_recipients → resolve_targets 链路。

决策 6:逻辑归属 router.py

这是"按 roster 解释 interact 语法",属于 routing/grammar 的家,不埋进 runtime manager;manager._resolve_recipients 只做 backend → 谓词的适配。分层清晰:纯语法解析(parse)→ 异步 roster 解析(resolve)→ 哑派发(dispatch)。

拒绝的方案:为什么不做这两件事

该特性在设计时明确排除了两个候选方案:

  1. 把校验塞进 _dispatch_payload:逐条无法实现"整组判断",多 recipient 部分匹配会错误地既发点对点又重复投 leader;且会让哑路由长出业务分支。
  2. 重构 parse_interact_str 让它直接产出已校验 payload:parse 是 sync 纯函数、roster 查询是 async;把 roster 揉进 parse 会污染纯语法层,并破坏其 ~30 条既有单测契约。改为"纯解析 + 独立 async 解析(resolve)"两段式,parse 完全不动。

从测试文件可以看到,parse_interact_str 的语法契约(god-view、多收件人 fan-out、inline 分段、@all/@* 广播折叠、$name@m1@m2 粘连形式、无 body 的 fallback 等)确实由大量 level0 单测锁定,改动它代价极高。

完整行为契约:从语法到派发的每一层

第一层:parse_interact_str 语法(纯函数,不查 roster)

router.py 文档化定义了语法:

input := channel? recipients? body
channel := "# " | "$" name (" " | "@")  # default "# " when absent
recipients := ("@" name " ")*           # zero or more
body := <remaining text after consuming channel + recipients>

典型映射结果(均可从 test_router.py 找到断言):

输入 解析结果
# what is the plan? GodViewMessage(body="what is the plan?")
just a plain question GodViewMessage(...)(无前缀默认 #)
# @dev-1 ship the patch OperatorMessage(body="ship the patch", target="dev-1")
# @m1 @m2 @m3 stand-up in 5 3 个 OperatorMessage,body 相同
# @m1 ship backend @m2 update docs 2 个 OperatorMessage,body 按 inline 分段不同
# @all heads up / # @* heads up 单个 OperatorMessage(body=..., target=None)(广播)
$alice please summarise design.md HumanAgentMessage(body=..., sender="alice")
$alice @dev-1 ping me when done HumanAgentMessage(body=..., sender="alice", target="dev-1")
$alice@dev-1 ping me(@ 粘连) sender/target 正确拆分
@dev-1(无 body) 不构成 mention,作为纯文本进 GodViewMessage
#hashtag(# 后无空格) 是正文不是 channel 标记

关于 payload 类型,见 payload.py:GodViewMessage(直连 leader DeepAgent)、OperatorMessage(外部用户视角,target=None 表示广播)、HumanAgentMessage(团队成员视角,sender 必填)、GroupChatMessage、HumanAgentToolCall、ExternalTeamEvent 等组成 InteractPayload 判别联合。DeliverResult 统一承载派发结果(ok / message_id / reason)。

第二层:resolve_targets roster 校验(异步)

行为由 test_router.py 完整锁定:

  • 全部已知 → 原样返回(test_resolve_targets_keeps_known_recipients)。
  • 单个未知(# 类)→ 折回 GodViewMessage(body="@ghost ship it"),文本原样保留(test_resolve_targets_folds_unknown_operator_to_god_view)。
  • 单个未知($ 类)→ 折回 HumanAgentMessage(body="@ghost hi", sender="alice")(test_resolve_targets_folds_unknown_human_agent_to_avatar)。
  • 部分匹配 → 已知的保持点对点,未知的折回一条(test_resolve_targets_partial_match_keeps_known_and_folds_unknown)。
  • 多个未知 → 合并成 @g1 @g2 stand-up in 5 一条(test_resolve_targets_multiple_unknown_rejoin_in_one_message)。
  • god-view / broadcast 不含 named target → 永不触达 roster,原样通过(test_resolve_targets_passes_through_broadcast_and_god_view)。

第三层:_dispatch_payload 哑派发(按类型分发)

manager.py 中 _dispatch_payload 按类型处理:

  • GodViewMessage → UserInbox.deliver_to_leader,正文直达 leader DeepAgent,不做任何 @ 再解析(test_god_view_always_goes_to_leader 验证了 body 里的 @dev-1 不会被解析)。
  • OperatorMessage(target=...) → 先 auto_start_member(target) 再 UserInbox.direct 写消息(start→write 顺序,确保成员 agent 在 MessageEvent 发布前订阅事件 bus);target=None → 先 auto_start_all 再 broadcast。
  • HumanAgentMessage → 无 target 时驱动 avatar(_drive_agent,经 render_controller_input 标记 from="controller");target="all"/"*" 时广播;有 target 时走 HumanAgentInbox.send → deliver_direct(human_agent_inbox.py),后者在写库前仍会校验 member_exists 并返回 unknown_member:<target>。
  • HumanAgentToolCall → 走 PassiveToolExecutor 透传执行(不在本特性范围)。

端到端行为验证

test_dispatch_payload.py 通过 _make_agent(known_members=...) 构造带 roster 谓词的假 agent,验证 manager.interact(str) 的完整链路:

  • @ghost ship it(空 roster)→ result.ok,deliver_input.assert_awaited_once_with("@ghost ship it"),send_message 不被调用(test_interact_str_unknown_member_folds_to_god_view)。
  • # @g1 @g2 stand-up in 5 → 全部折回成一条 god-view(test_interact_str_multiple_unknown_members_fold_into_one_message)。
  • $alice @ghost hi → 驱动 alice 的 avatar,body 含 @ghost hi,不写消息(test_interact_str_unknown_member_dollar_drives_avatar)。
  • # @m1 @ghost on it(m1 已知)→ send_message(content="on it", to_member_name="m1") 被调用一次,同时 deliver_input("@ghost on it")——部分匹配双投(test_interact_str_partial_match_routes_known_and_folds_unknown)。

已知遗留与边界说明

按特性文档声明,本次实现有两处明确不在范围内、保持现状:

  1. UserInbox.direct 的 docstring 仍写"调用方负责校验 target 存在"——现在该校验由其调用方 interact(经 resolve_targets)落实,inbox 本身保持哑写入,语义未变,未改文案。
  2. TeamAgent.broadcast() / human_agent_say() 等不经 @ recipient 解析的入口不在本次范围,它们不经过 resolve_targets。

另外两个值得注意的边界:

  • 无 backend 的纯 god-view agent:_resolve_recipients 直接 passthrough,不存在 roster 匹配问题。
  • swarmflow human-session 回复:目标地址按 correlation id(swarmflow:<run_id>:<correlation_id>)而非 roster 成员寻址,在 manager.py 中于 roster 匹配之前就被旁路路由到回复 topic,避免被当作未知 mention 折叠。

测试基线

特性文档记录的测试基线为:pytest tests/unit_tests/agent_teams/:1207 passed, 16 skipped(对应 Refs #751)。该特性的关键行为由上述两套单测锁定,读者可运行 pytest tests/unit_tests/agent_teams/interaction/test_router.py tests/unit_tests/agent_teams/runtime/test_dispatch_payload.py 独立验证语法层与派发层的契约。

小结:设计模式的可复用点

从本项目这一特性中,可以提炼出值得复用的工程模式:

  1. 两段式解析:同步纯语法解析与异步语义校验分离,各自保持单一职责、独立可测——这是本特性拒绝"把 roster 揉进 parse"的根本原因。
  2. 谓词注入:member_exists 由调用方注入,router.py 不感知具体 roster 来源(DB backend、内存 mock 均可),极大提升了可测试性。
  3. 降级不丢数据:无法路由的输入折叠回默认通道并保留原文,宁可让 leader 看到"疑似 typo 的 @ghost",也不静默吞掉或写脏数据——这既是数据完整性决策,也是用户体验决策。
  4. 校验位置选在"能看见整组"的层次:组级校验解决逐条派发无法感知兄弟 recipient 的局限,让底层 _dispatch_payload 保持哑路由。
登录后查看全文
agent-core