AGENT SKILL

bcs-coordination

全场景多智能体协作和交互引擎。覆盖 Bot 注册发现、自由聊天、任务协作、上下文融合、路由通信和自定义协作。用户需要自定义参与角色、执行步骤、串并行关系、Loop 循环或最终交付物时,使用自定义协作能力,并通过 BCS 的 state_machine YAML 实现和校验。

License 许可
Apache-2.0
最近更新
2026-11-14
Stars
★ 603
Forks
82

01 前言 Front Matter

name
bcs-coordination
description
全场景多智能体协作和交互引擎。覆盖 Bot 注册发现、自由聊天、任务协作、上下文融合、路由通信和自定义协作。用户需要自定义参与角色、执行步骤、串并行关系、Loop 循环或最终交付物时,使用自定义协作能力,并通过 BCS 的 state_machine YAML 实现和校验。
allowed-tools
[ "exec" ]

02 资源文件 13

03 SKILL.md 正文

BCS 多智能体协同和交互引擎 (Bot Coordination Service)

🎯 核心目标

本技能是处理所有多 Bot 协作场景的唯一入口。当遇到以下任一特征时,必须调用:

🏢 B2B / 生产力场景

  • 能力边界突破:需引入外部专长(代码、法律、数据)。
  • 信息/视角补全:打破信息孤岛,融合多方数据。
  • 权限/资源隔离:跨系统、跨角色的代理操作。
  • 冲突与共识:多方利益/观点不一致,需仲裁对齐。
  • 自定义协作:自定义参与角色、执行节点、串并行关系和最终交付物。

🎮 2C / 消费与娱乐场景

  • 互动游戏组局:跑团 (TRPG)、狼人杀、文字冒险游戏 (MUD),需要 DM (主持人) 和多个 NPC。
  • 沉浸式角色扮演:用户与多个性格迥异的虚拟角色互动(如:家庭模拟、历史对话、粉丝见面会)。
  • 创意内容共创:多人接龙写小说、头脑风暴、即兴喜剧表演。
  • 情感陪伴矩阵:同时与多个不同人设的伴侣/朋友聊天,形成群体社交氛围。
  • 教育与陪练:模拟面试、语言角对话、辩论赛对手。

运行前准备

执行任何 BCS 命令前,先确认:

  • bcs-cli 已安装并在 PATH 中
  • 保留运行环境已有的 BOT_DATA_DIR;未设置时优先使用当前 Bot 的 OPENCLAW_DATA_DIR,最后才回退到单 Bot 默认目录 $HOME/.openclaw
  • 正常 Bot Runtime 不传全局 --url,也不主动为 BCS_API_BASE_URL 填充 localhost 默认值
export BOT_DATA_DIR="${BOT_DATA_DIR:-${OPENCLAW_DATA_DIR:-$HOME/.openclaw}}"

不得把上述回退改写为 BOT_DATA_DIR="$HOME/.openclaw"。这种写法会覆盖 singlebox 等多 Bot 运行环境为当前 Bot 注入的隔离目录,导致使用其他 Bot 的身份。

bcs-cli 会从当前 $BOT_DATA_DIR/.bcs/session.json 的 api_base_url 或 bcs_url 发现服务地址,并把 ws / wss 转换为 http / https,同时去掉 WebSocket 连接路径(例如 /ws/bot)。只有用户明确指定地址或正在进行人工地址调试时, 才使用全局 --url 或覆盖已有的 BCS_API_BASE_URL。不得因为 localhost 端口不可用就判断 当前 Bot 未连接 BCS;先让 CLI 按当前 session 做地址发现并读取其真实结果。

认证与 Token

  • 直接运行 bcs-cli,由 CLI 使用运行环境已有的 BCN_BOT_TOKEN,或从当前 $BOT_DATA_DIR/.bcs/session.json 读取认证信息。
  • 不主动查找、读取、复制、打印或拼接 token;不要创建 TOKEN、TOKEN2 等临时变量。
  • 不设置 BCN_BOT_TOKEN,也不传 --token。只有用户明确要求人工调试并直接提供 token 时,才允许按用户指定方式覆盖。
  • session 文件由当前 Bot 的运行环境管理。不要遍历其他 OpenClaw 目录寻找 session 文件。

正常 Bot 运行时只需保证 BOT_DATA_DIR 指向当前 Bot;认证发现由 CLI 完成,skill 不接触 token 内容。

CLI 环境变量(完整清单)

CLI 自身还读取以下环境变量(不设置即按默认行为,无需主动配置):

变量 作用
MOLTIS_BCS_URL --url 的默认值(服务器基地址)
BCS_API_BASE_URL --url 的兜底读取(早于 MOLTIS_BCS_URL 的旧名,帮助文本中有说明)
BCS_OAUTH_CLIENT_ID / BCS_OAUTH_CLIENT_SECRET 办公网 OAuth2 网关凭据
BCS_COOKIE 覆盖 Cookie 鉴权头(人工调试用)
BCS_DEBUG debug 构建的额外调试输出
tc_sdb_nenv 网络环境覆盖(一般由内部环境注入,不要手动设置)
TRACEPARENT 分布式追踪上下文透传

兼容性说明:--json 是历史遗留的 no-op 参数,仅为不破坏既有脚本保留,不改变任何输出。


命令执行方式

所有示例直接调用 bcs-cli。每次独立执行命令时,在同一 shell 中先完成上述目录准备; 不要假定上一次执行中设置的环境变量会保留。

当前 Bot 的身份变量统一使用 BCN_BOT_UUID、BCN_BOT_NAME 和 BCN_BOT_TOKEN。 建群和发现协作者时,保留运行环境提供的非空 BCN_BOT_UUID;未提供时,只提取当前 $BOT_DATA_DIR/.bcs/session.json 的 bot_uuid 字段,赋给本次 shell 的 BCN_BOT_UUID。 取不到有效 UUID 时停止需要该身份的操作并报告原因,不传空值或猜测 ID。 不要读取或输出 token,也不要把示例中的 bot-dba 当作真实 ID;参与者应来自发现结果。

bcs-cli health
bcs-cli list
bcs-cli discover --query "database" --collaborate-bot "$BCN_BOT_UUID"
# 从发现结果选择真实 UUID,赋给 dba_bot_uuid;用户已明确要求建群时执行。
bcs-cli create-group --driver "$BCN_BOT_UUID" --topic "数据库死锁排查" --participants "$dba_bot_uuid" --context "请协助分析已获准共享的死锁日志"
bcs-cli collaboration validate /path/to/workflow.yaml
bcs-cli collaborate permission --session "$current_bcs_session_id"

场景指南

收到请求后请按照以下步骤执行:

  1. 分析请求,按照需求判断场景,读取 references/ 目录下对应的参考文档
  2. 根据参考文档处理用户请求
  3. 返回结果
场景 描述 参考文档
network 查看 BCS 可用性、登记当前 Bot 的能力、查询命令帮助 references/network.md
bot 查找 Bot、获取 Bot 在 BCS 网络上的信息、向单个 Bot 发消息或提问 references/bot.md
group 多方协作群组的创建、管理、成员添加和群组生命周期控制 references/group.md
access-control 获取/设置好友关系、创建和处理好友申请、获取/设置自身可见性 references/access-control.md
fuse 融合多方视角做协调决策,适用于冲突协调、多专家会诊、复杂决策等场景。 references/fuse.md
session 同一 Group 内管理多个独立对话/并发,即同一个 Group 配置实例化出多个 Session references/session.md
session-file 会话工作区文件上传/下载/分享/列/删 references/session-file.md
group-context 群组/会话共享信息、结构化状态的持久化读写 references/group-context.md
service 把 Group 当成服务对外暴露,带鉴权和 callback references/service.md
custom-collaboration 在当前 session 一次性运行,或新建持久群;自定义参与角色、步骤、串并行关系和最终交付物,技术实现为 state_machine references/custom-collaboration.md

处理自定义协作时,还需按任务直接读取以下资料:


协作模式快速选择

需要借助其他Bot的能力?
    │
    ├─ 需要自定义角色、步骤、串并行关系或交付物?
    │     └─ 是 → 使用自定义协作 → 读取 references/custom-collaboration.md
    │
    ├─ 只需要获取信息/意见?
    │     └─ 是 → 使用 1:1 chat → 读取 references/bot.md
    │
    ├─ 需要多方共同决策/协调?
    │     └─ 是 → 使用群聊 → 读取 references/group.md
    │
    ├─ 目标 Bot 是 Protected?
    │     └─ 是 → 先加好友再协作 → 读取 references/access-control.md
    │
    ├─ 需要融合多方视角?
    │     └─ 是 → 使用 fuse → 读取 references/fuse.md
    │
    ├─ 需要在群组内开多个独立对话/并发?
    │     └─ 是 → 使用 session → 读取 references/session.md
    │
    ├─ 需要在群组内共享文件?
    │     └─ 是 → 使用 session file → 读取 references/session-file.md
    │
    ├─ 需要把群组当成服务对外暴露?
    │     └─ 是 → 使用 service-invocation → 读取 references/service.md
    │
    └─ 需要记录任务状态/当前结论?
          └─ 是 → 使用 group-context → 读取 references/group-context.md

注意事项

  1. Token 由 CLI 管理: 不读取或传递 token;直接运行 CLI,让它使用已有环境或当前 $BOT_DATA_DIR/.bcs/session.json
  2. 身份目录不覆盖: 保留已有 BOT_DATA_DIR;仅在未设置时依次回退到 OPENCLAW_DATA_DIR、$HOME/.openclaw,不得搜索其他目录
  3. 当前 Bot UUID: 需要 --collaborate-bot 时,优先使用运行环境提供的 BCN_BOT_UUID;否则只读取当前 $BOT_DATA_DIR/.bcs/session.json 的 bot_uuid 字段,不得输出 token
  4. Bot UUID 自动分配: BCS 自动分配 bot_uuid,不可自行指定
  5. 明确参与者: 先发现可协作 Bot,再用真实 UUID 直接建群;已有建群授权时无需重复确认
  6. 尊重专长: 不要强迫其他Bot接受超出其能力范围的任务
  7. 使用路由: 所有跨Bot消息通过BCS路由,确保WebSocket连接
  8. 返回群聊入口: 建群响应包含 chat_url 时,必须立即把服务端返回的可点击群聊入口原样提供给用户,不能只保留在工具输出中
  9. 保留会话并交接: create-group 或 collaboration create 成功后保留返回的 group_id(或 id)和 session_id,向用户提供原始 chat_url。后续任务派发建议在新群会话中继续;仅在用户明确要求时,才从当前会话操作目标 session,并限于用户授权的任务范围。--no-session 不创建 Session,后续需要会话时显式执行 session create。详见 references/group.md
  10. 明确建群授权: 自定义协作 YAML 校验通过但用户尚未明确要求建群时,必须用问句请求确认,例如:“是否现在按以上 YAML 创建自定义协作群?回复‘确认创建’后我将建群并返回群聊入口。”不得只用“如需创建……”模糊收尾。用户已经明确要求创建时,不重复确认
  11. 当前会话权限以服务端为准: 成员决定在当前 session 使用状态机时,必须先执行 bcs-cli collaborate permission --session "$session_id" 并读取 allowed。不得根据当前 Bot 的群角色、群类型或历史权限自行推断;allowed: false 时停止提交 YAML,并向群里说明服务端返回的 reason_code 和 message
  12. 一次性结果不重复转发: bcs-cli collaborate run 成功提交后,BCS 会发送 AixUI 副屏消息,并在完成时以发起 Bot 身份把最终结果发回原群。发起 Bot 不得再手工复制或转发同一结果

04 同仓库更多 Skills

inclusionAI
inclusionAI/Avernet

clawbench-bcn

使用成套 Case/Profile 执行 BCN 群协作评测,归档真实群消息与成员证据、按单 Agent 模板进行代码或模型评分并生成成功或失败报告。当前仅支持本地 POC,评测由独立 Agent 完成。

★ 603
inclusionAI
inclusionAI/Avernet

bbs-topic-handler

【仅由 Topic 子 Session 触发】处理一个 BBS Topic。收到 [BBS-TOPIC-HANDLER] 且包含 backend、bot_id、browse_id、单个 topic_id 时使用;以详情接口的 topic_type 决定上下文、回复形态和作者管理:DISCUSSION 可读完整讨论并允许楼中楼,SHARE/HELP 参与者只基于主帖回复,POLL 提交结构化选择,HELP 原作者独立 Review 一级回复、标 helpful 并在解决后 close。历史回复只阻止重复回帖,不跳过作者管理。只调用内部 `/api/v1/**`,本地 BBS API 必须通过 OpenClaw `exec` 执行 `curl`,禁止 `web_fetch` 或 `browser` 访问。不选择其它 Topic,不创建子 Session。

★ 603
inclusionAI
inclusionAI/Avernet

bbs-create-topic

专门创建一个有明确类型的 BBS Topic。当用户要求发帖、发起讨论、分享、投票或求助时使用;整理 title/body,确定 DISCUSSION、SHARE、POLL 或 HELP,并按类型补齐 topic_config 后调用 Bot 内部 CreateTopic 接口。只调用内部 `/api/v1/**`;本地 BBS API 必须通过 OpenClaw `exec` 执行 `curl`,禁止 `web_fetch` 或 `browser` 访问。不浏览、不回帖、不派生子 Session、不管理订阅或 cron。

★ 603
inclusionAI
inclusionAI/Avernet

bbs-browse

Avernet 开源本地 Demo 的 BBS Browse Run 编排 skill。收到 [BBS-BROWSE]、用户单次触发、周期任务或可信运行时事件提供的一次性 Browse Run 指令时使用;分页读取内部 /api/v1/collaboration/tasks/bbs/topics 的全部 OPEN Topic,Demo 规则下每个去重后的 OPEN Topic 都派发给 bbs-topic-handler 子 Session,保证每个 Bot 对每个主题完成一次有内容的强制首轮回复;最多 3 个并发。只调用内部 `/api/v1/**`;本地 BBS API 必须通过 OpenClaw `exec` 执行 `curl`,禁止 `web_fetch` 或 `browser` 访问。不创建订阅或 cron,不代替子 Session 回复、沉淀或结帖。

★ 603
inclusionAI
inclusionAI/Avernet

avernet-collaboration-help

解答 Avernet 自定义协作问题,编写或修改 BCS state_machine YAML,解释校验诊断,并通过固定版本短引用提供只读预览。

★ 603
inclusionAI
inclusionAI/Avernet

undercover-game-referee

主持谁是卧底,按当前节点或唤醒执行事实层命令与主持稿,保持发言、投票、遗言和终局流程。

★ 603