QQ 好友申请与被拉进群：两道审批交给同一个 Agent

场景

QQ 上的机器人大半时间不在聊天，而在处理两类「申请」：陌生人加好友，机器人被拉进群。两件事都是一次性的，用「收到消息 → 生成回复」的聊天流程去接，接不住：它们根本不是消息。

4.10 里 OneBot v11 是「协议」类适配器，能接 NapCat、Lagrange 这类协议端，但事件到了只有一条流水线兜住，想按事件分流得自己判断。4.11 把它提升为第一类事件驱动适配器，「申请」这类事件可以直接落在一个 Agent 上。

4.11 里怎么做

一个新包。 src/langbot/pkg/platform/adapters/aiocqhttp/ 是 v4.11.0 新增的独立适配器包；git diff --stat v4.10.11 v4.11.0 清单逐字（源码）：__init__.py (+5)、adapter.py (+243)、api_impl.py (+238)、event_converter.py (+275)、manifest.yaml (+149)、message_converter.py (+285)、onebot.png、platform_api.py (+84)、transport.py (+125)、types.py (+9)，连旧入口共 11 个文件、+1416 行、-1 行。

旧配置降级。 旧的 src/langbot/pkg/platform/sources/aiocqhttp.yaml 只改了 4 行：新增 spec.legacy: true、spec.categories 由 [protocol] 变成 [popular, protocol]（源码）。向导因此给新机器人生成反向 WS 地址，旧 host/port 配置被标成旧版适配器。

一行一个事件。 机器人详情页存一张「事件模式 → 处理器」的表，处理器可以是流水线、Agent 或插件处理器。判定按行顺序：启用 → 事件匹配 → 过滤条件 → 目标声明支持该事件，第一个全通过的行被选中，其余记为跳过（官方文档 docs/event-based-agents/04-event-routing.md §3）。

事件范围决定可用工具。 勾了 friend.request_received 才有「处理好友请求（敏感）」，勾了 bot.invited_to_group 才有「处理入群邀请（敏感）」，两者在源码里都带事件限定、风险等级 dangerous（源码 LangBot/src/langbot/pkg/agent/runner/platform_tools.py:176-203）。审批一放行就生效，不要开给不需要它的 Agent。具体支持取决于适配器/平台，请先核对支持矩阵。

动手：步骤

先起一个本地演示实例：

bash 复制代码

docker network create a4
docker run -d --name a4-core --network a4 --restart on-failure -e TZ=Asia/Shanghai \
  -e BOX__ENABLED=false -e SPACE__DISABLE_TELEMETRY=true -p 15800:5300 \
  -v "$PWD/deploy/a4/data:/app/data" rockchin/langbot:v4.11.0
docker run -d --name a4-runtime --network a4 --network-alias langbot_plugin_runtime --restart on-failure \
  -e TZ=Asia/Shanghai -e SPACE__DISABLE_TELEMETRY=true -v "$PWD/deploy/a4/data/plugins:/app/data/plugins" \
  rockchin/langbot:v4.11.0 uv run --no-sync -m langbot_plugin.cli.__init__ rt

管理员 demo@langbot.local / LangBot411!demo（本地演示值，请自行替换 ）；示例机器人 QQ 演示机器人，适配器 onebot-v11。

向导第 2 步选 OneBot v11，卡片描述逐字「OneBot v11 适配器，用于接入 QQ 兼容协议端，支持事件驱动编排」。

配适配器 ：连接模式 反向 WS --- 协议端连接 LangBot；协议端连接地址保存后自动生成；访问令牌 demo-onebot-token-replace-me（本地演示值，请自行替换 ）；预期机器人账号 10001。保存按钮是 保存并启用，点击后提示 保存成功、徽标 已启用。生成的连接地址与同一个访问令牌，要填回你自己的 NapCat / Lagrange。

认清事件边界 ：事件路由卡片显示支持的事件「共 12 类」，分「机器人状态 · 4」「好友 · 2」「群组 · 3」「消息 · 2」几组，另有 1 类；完整名单见适配器 manifest.yaml 的 supported_events。具体支持取决于适配器/平台，请先核对支持矩阵。

第 1 条路由用预设 审核好友请求 。添加行为 的「常用场景」共 6 项：回复收到的消息 / 欢迎新成员 / 处理成员离群 / 审核好友请求 / 处理群管理事件 / 配置其他事件；菜单按适配器声明的事件取交集（源码 LangBot/web/src/app/home/bots/components/bot-form/EventBindingsEditor.tsx:1554-1559），Telegram 上被过滤掉的那一项在这里保留。选中后得到 收到好友请求 / friend.request_received 的路由。

就地建 Agent ：点 创建新处理器，运行器选 本地 Agent（plugin:langbot-team/LocalAgent/default），名称填 qq-approvals-agent，提交后提示 创建成功，第 1 条路由的处理器变成 ⚙️ qq-approvals-agent。

第 2 条路由 ：添加行为 → 配置其他事件 → 机器人被邀入群（bot.invited_to_group），处理器选同一个 ⚙️ qq-approvals-agent（候选只出现声明了该事件的 Agent）；保存 后重载页面，两条路由仍在。

回 Agent 定死事件范围 ：初始只有一个通配 chip 全部事件 *，加入那两个事件后卡片显示「共 2 项」，* chip 被替换（不是追加），每个事件各带 3 个自动可用的工具：

friend.request_received → 回复当前会话（操作）/ 查询事件发起者（只读）/ 处理好友请求（敏感）
bot.invited_to_group → 查询事件发起者（只读）/ 查询当前群组（只读）/ 处理入群邀请（敏感）

同页「其他工具」计数逐字：平台工具14 沙盒0 MCP0 插件0 已选 0。

先做一件事 ：运行器配置里得先选好模型------本例 Agent 的 模型 是 请选择模型，保存 会先弹 运行器配置待完善，随后才 保存成功。

验证

其一，路由落库。 保存后读回 bot 230bc250-ff68-462b-b330-fd7711cae509：enable=1，event_bindings 两条（逐字，截取关键字段）：

复制代码

{"id": "3bd3b8d7-6412-4a2e-9451-d6a80a37d8a5", "event_pattern": "friend.request_received", "target_type": "agent", "target_uuid": "69159ec4-3941-4a1a-994f-45c0b532d01d", "filters": [], "priority": 0, "enabled": true, "order": 0}
{"id": "bcaed4a9-01c6-4255-9db0-6dfe8175566e", "event_pattern": "bot.invited_to_group", "target_type": "agent", "target_uuid": "69159ec4-3941-4a1a-994f-45c0b532d01d", "filters": [], "priority": 0, "enabled": true, "order": 1}

两个 target_uuid 指向同一个 qq-approvals-agent。

其二，检查路由命中两次。 检查事件路由 对话框的事件下拉是 12 项，与适配器声明一一对应；本次实测（2026-10-16）两次选择逐字：

复制代码

事件 = 收到好友请求 → 已命中路由 | 目标处理器 | Agent · qq-approvals-agent | 命中规则 | 第 1 条路由 | 诊断步骤：已选择第 1 条路由。第 2 条路由已跳过。事件与此路由不匹配。
事件 = 机器人被邀入群 → 已命中路由 | 目标处理器 | Agent · qq-approvals-agent | 命中规则 | 第 2 条路由 | 诊断步骤：第 1 条路由已跳过。事件与此路由不匹配。已选择第 2 条路由。

其三，事件范围与工具清单对得上。 第 7 步卡片里那 3 个工具，正是源码中按事件限定的那一组：event_respond_friend_request 只绑 friend.request_received，event_respond_group_invite 只绑 bot.invited_to_group。

边界与注意

没有真实 QQ 收发，也没跑 运行测试。 实例里没有 QQ 协议端（无 NapCat / Lagrange），访问令牌是本地演示值（本地演示值，请自行替换）；Agent 未选模型，跑测试既会失败也是无效消耗。验证到的是四件事：适配器配置可保存并启用、两条事件路由落库、检查路由命中正确的处理器、事件范围决定可用工具。
平台工具走 Mock。 说明藏在 事件调试 卡片信息图标的 tooltip 里，逐字：「平台工具使用 Mock：Agent 真实调用工具，回复、发送等平台动作模拟执行，不发送真实消息。其他工具仍按实际配置执行。」同意好友请求、同意入群在真实协议端上却是立即生效的动作。

保存前先选模型。 运行器配置里没有模型时，保存先提示 运行器配置待完善。
旧配置换了地方。 反向 WS 由协议端连接 LangBot 主服务端口，无需额外监听端口；不支持 HTTP。旧 host/port 配置已降级为旧版适配器。
菜单不等于能力。 事件菜单按适配器声明渲染，本适配器声明 12 类，所以保留了「审核好友请求」。具体支持取决于适配器/平台，请先核对支持矩阵（官方文档 docs/event-based-agents/01-event-system.md:453-476）。
待确认：只在本地配置层验证，未连真实协议端观测真实审批往返；同意 / 拒绝的取舍属于提示词与模型表现，未评测。
$推断$ 「一个事件同时交给两个处理器」不在实测范围内：实测确认的是仲裁只选一条（第 1 条命中时第 2 条被跳过）。

小结与下一步

QQ 上这两道审批的接法不是把提示词写长，而是两行「事件模式 → 处理器」：friend.request_received 与 bot.invited_to_group 各自叫醒同一个 qq-approvals-agent，事件范围收成这两条，两个敏感工具就只落在它身上。

从 4.10 升上来，先看迁移配置对照文档 docs/pipeline-migration-config-map.zh-CN.md；v4.11.0 release 页是版本入口，运行器插件源码在 langbot-plugins 仓库。不想自己维护实例时，托管服务 space.langbot.app 是另一个可选方向，是否合适取决于你的部署约束。