Avernet

手把手复现 WAIC 现场演示全流程

这是一份面向第一次接触 Avernet、甚至不熟悉命令行的 macOS 教程。完成后,你会在自己的电脑上启动 Avernet、接入 6 个世界杯内容 Bot,从前端选择内置的“世界杯比赛前瞻内容生产”模板,绑定角色,提交一次自定义协作,并看到多 Bot 按固定流程完成内容生产。

部分截图来自旧版本;启动命令、配置文件和目录路径以本页正文及代码框为准。

本教程使用的模板源码是:

产品文案统一使用“自定义协作”。代码中的 state machine 是它的实现方式;旧资料里的“结构化协同”或“自定义协同”在本教程中都按“自定义协作”理解。

1. 最终会复现出什么

运行成功后,本机包含三部分:

  1. BCS:负责 Bot 接入、群组、路由和自定义协作执行。
  2. Avernet 前端:在浏览器中选择模板、绑定 Bot、提交任务和查看结果。
  3. 世界杯内容小队:6 个各司其职的 Bot。

6 个 Bot 分别是:

Bot 在流程中的职责
世界杯运营总监 明确选题目标、受众、平台、时长和整体制作方向
世界杯内容主编 整理任务简报并验收最终发布包
世界杯战术解说 设计战术看点、关键对位和通俗表达
世界杯赛事数据核查 核验赛程、球队、球员、历史交锋和数据口径
世界杯短视频编导 生成指定时长的口播稿和纯文字分镜
世界杯增长运营 生成标题、封面文案、发布包装和互动方案

模板执行顺序如下。战术分析和事实核查会并行进行,完成后再汇合到短视频脚本节点:

flowchart LR
    A["世界杯运营总监<br/>安排制作方向"] --> B["世界杯内容主编<br/>整理任务简报"]
    B --> C["世界杯战术解说<br/>设计战术洞察"]
    B --> D["世界杯赛事数据核查<br/>核验选题事实"]
    C --> E["世界杯短视频编导<br/>创作两分钟脚本"]
    D --> E
    D --> F["世界杯增长运营<br/>包装分发素材"]
    E --> F
    F --> G["世界杯内容主编<br/>验收最终发布包"]

2. 开始前必须准备什么

2.1 电脑和网络

仓库没有在本教程中规定更具体的 macOS 最低版本;建议使用仍在 Apple 安全支持范围内的版本。

2.2 一个可用的模型配置

要看到 6 个 Bot 真正生成内容,必须准备以下两种方式之一:

如果只选择 mock 模式,Bot 可以接入协作网络,但不会产生真实模型回复,因此不能完整复现这次演示。

请不要把 API Key 发到群聊、截图中或提交到 Git。手工配置时,只把它写入仓库中的 singlebox/.env.local;该文件用于本机配置,不应提交。

2.3 本机端口

默认需要以下本机端口空闲:

端口 用途
8000 Avernet 前端
21000 BCS
30401 世界杯运营总监
30411 世界杯内容主编
30421 世界杯赛事数据核查
30431 世界杯战术解说
30441 世界杯短视频编导
30451 世界杯增长运营

如果你不确定端口是否空闲,后面的检查命令会帮你确认。不要直接结束不认识的进程;先确认它属于哪个应用。

2.4 认识“终端”

后续命令都在 macOS 的“终端”中执行:

  1. 按 Command + 空格打开聚焦搜索。
  2. 输入“终端”或 Terminal。
  3. 按回车打开。
  4. 每个代码框里的命令可以逐行复制,粘贴后按回车。

代码框中不包含终端最左侧的提示符,不需要额外输入美元符号。

打开终端并检查基础环境

3. 第一步:安装 Git

先检查 Git 是否已经存在:

git --version

如果看到类似 git version 2.x.x,说明可以继续。

如果提示 command not found,可运行:

xcode-select --install

macOS 会弹出安装窗口。完成 Command Line Tools 安装后,关闭并重新打开终端,再次运行 git –version。

4. 第二步:克隆 Avernet

在终端中运行:

git clone https://github.com/inclusionAI/Avernet.git
cd Avernet

第二行非常重要:它会让终端进入刚下载的项目目录。后续所有以 ./singlebox 开头的命令,都必须在这个目录中运行。

可以用下面两条命令确认当前位置和当前分支:

pwd
git branch --show-current

pwd 输出的最后一段应是 Avernet。仓库默认分支是 dev;如果功能尚未合入你当前的分支,请切换到包含本教程和世界杯模板的分支后再继续。

确认模板文件确实存在:

test -f apps/bcs/seeds/collaboration-templates/zh-CN/world-cup-preview-content-production.yaml && echo "世界杯模板已找到"
test -f singlebox/agents/6bots_world_cup_creator_profile/bots.json && echo "世界杯 Bot 配置已找到"

两行都应显示“已找到”。

当前 singlebox 默认使用本机隔离的运行目录,无需添加 --local 或 --standalone;--local 已移除。本教程使用默认的 legacy 前端(apps/frontend)。如果之前在 singlebox/.env.local 中选择了其他前端,请改为 FRONTEND_VARIANT=legacy 后再执行下文的 bcs_frontend 命令。

5. 第三步:安装开发工具

推荐让仓库脚本检查并安装缺失工具:

./singlebox/singlebox.sh install-tools

这个过程是交互式的。脚本可能会:

看到确认问题时,先阅读它准备安装的内容,再根据提示输入 y 或 n。为了完成本教程,Rust 1.91+、Cargo、protoc、Node.js 22+、npm、OpenClaw 2026.3.28+、jq、curl、lsof、pkg-config、OpenSSL 和 SQLite 开发库都需要可用。

第一次安装和构建会花较长时间,具体取决于网络和电脑性能。只要终端仍持续输出下载或编译信息,就先让它完成,不要关闭终端。

完成后执行依赖预检:

./singlebox/singlebox.sh check bcs_frontend

此时还没有编译 BCS,因此暂时不要执行 Bot 的完整预检;下一步编译完成后再检查。

更完整的工具说明见 macOS 依赖清单。

安装工具链 依赖预检

6. 第四步:编译 BCS 并安装前端依赖

运行:

./singlebox/singlebox.sh setup bcs_frontend

这一步会:

首次执行通常是整个教程中耗时最长的一步。成功结束时,应看到 BCS setup complete 和 Frontend ready 一类提示。

现在再检查世界杯 Bot 的启动条件:

./singlebox/singlebox.sh check bots --profile-dir singlebox/agents/6bots_world_cup_creator_profile

预检应识别到 6 Bot manifest,并检查 30401 至 30451 这 6 个端口。

7. 第五步:准备真实模型配置

下面两种方式二选一。已经使用 OpenClaw 的读者优先选方式 A;只有模型服务参数的读者选方式 B。

方式 A:复用现有 OpenClaw 配置

先确认文件存在:

test -f ~/.openclaw/openclaw.json && echo "OpenClaw 配置已找到"

稍后启动 Bot 时选择:

3) home

脚本会明确显示它准备读取的文件路径,并提示该文件可能包含本地模型地址和 API Key。确认路径正确后输入 y。脚本只抽取模型相关字段到 singlebox 的本地运行配置中。

方式 B:在 singlebox/.env.local 中手工填写

从示例文件生成本机配置:

test -f singlebox/.env.local || cp singlebox/.env.example singlebox/.env.local
open -e singlebox/.env.local

TextEdit 打开后,找到或加入下面三项,删除行首的 # 注释符号,并将等号右边替换成自己的真实值:

OPENCLAW_OPENAI_BASE_URL=https://your-model-service.example/v1
OPENCLAW_OPENAI_API_KEY=your-api-key
OPENCLAW_OPENAI_MODEL_ID=your-model-id

启动脚本自动读取的是 singlebox/.env.local,不会自动读取仓库根目录的 .env.local。如果你已有旧的根目录配置,请将需要的模型配置项复制到 singlebox/.env.local。三项均需填写非空值;选择 manual 只选择配置来源,不会交互式询问这些参数。

保存并关闭文件。稍后启动 Bot 时选择:

2) manual

不要把上面的 example 地址原样当成可用服务,也不要把真实 Key 写进教程截图。

选择模型配置方式

8. 第六步:启动 BCS 和前端

运行:

./singlebox/singlebox.sh start bcs_frontend

这个命令只启动 BCS 和前端,不会启动默认 5 Bot,也不会询问模型配置。前端启动时会再次检查依赖;依赖已经是最新状态时会跳过安装,缺失或过期时会自动执行一次安装。

成功后,终端会显示本地服务已经就绪。可以另外确认状态:

./singlebox/singlebox.sh status bcs_frontend

预期结果:

BCS 和前端启动成功

9. 第七步:启动世界杯 6 Bot

保持 BCS 正在运行,然后执行:

./singlebox/singlebox.sh start bots --profile-dir singlebox/agents/6bots_world_cup_creator_profile

终端会出现:

Choose model config mode:
  1) mock     Use fixed-format local model replies
  2) manual   Use values from singlebox/.env.local
  3) home     Import model fields from ~/.openclaw/openclaw.json

脚本随后会准备 6 份隔离的 OpenClaw profile、连接 BCS、注册 Bot,并把它们设为可发现。等待命令成功结束后检查状态:

./singlebox/singlebox.sh status bots --profile-dir singlebox/agents/6bots_world_cup_creator_profile

6 个 Bot 都应显示 Running,并各自带有端口和 bot_uuid。

6 个世界杯 Bot 全部运行

10. 第八步:进入 Avernet 前端

在浏览器打开:

http://127.0.0.1:8000/

在首页点击“进入 Avernet”。页面会在新标签页打开“我的协作”,实际地址通常是:

http://127.0.0.1:8000/bcn/chat/list

页面顶部会显示已接入的 Bot 标签。选择“世界杯运营总监”作为当前 Bot 视角。这样后面可以自然地把发起方绑定到 operations_director 角色。

如果顶部没有看到 6 个 Bot:

  1. 等待 10 至 20 秒后刷新页面。
  2. 再运行一次 Bot 状态命令,确认 6 个 Bot 均为 Running。
  3. 确认当前打开的是 8000 端口,而不是另一个旧前端。

进入 Avernet 并选择运营总监

11. 第九步:从模板创建自定义协作群

11.1 打开创建窗口

在“我的协作”页面左侧点击“拉起协作”。

在弹窗顶部填写:

界面上“自定义协作”旁会显示“状态机编排”,这是实现说明,不是另一个产品模式。

11.2 选择内置模板

在“协同剧本”区域:

  1. 选择“模板”,不要选“自由编辑”。
  2. 打开右侧“选择模板”下拉框。
  3. 选择“世界杯比赛前瞻内容生产”。
  4. 等待 YAML 内容加载完成。
  5. 点击“校验 YAML”。

校验成功后,界面会显示“已解析 6 个角色”,并进入“角色绑定”区域。

这个模板不是手工上传的。BCS 本地模式会直接读取仓库中的模板目录,默认语言是 zh-CN,因此只要你使用的是包含该文件的最新代码并成功启动 BCS,它就会出现在前端模板下拉框中。

创建协作群

选择世界杯模板并校验 YAML

12. 第十步:把 6 个逻辑角色绑定到 6 个 Bot

模板中的 participant 是逻辑角色,不存储某次运行生成的 bot_uuid。创建协作群时,需要在前端完成下面的绑定:

模板角色 key 应绑定的 Bot
operations_director 世界杯运营总监
content_editor 世界杯内容主编
tactics_analyst 世界杯战术解说
script_director 世界杯短视频编导
fact_researcher 世界杯赛事数据核查
growth_operator 世界杯增长运营

对每个角色重复以下操作:

  1. 点击上方对应的角色 key。
  2. 切换到“可协作Bot”。
  3. 选择“按名称筛选”。
  4. 在搜索框中输入中文 Bot 名称。
  5. 点击搜索结果右侧的加号完成绑定。
  6. 确认角色卡显示已绑定 1 个 Bot,再处理下一个角色。

特别检查:

当每个角色绑定按钮后面的“必填”标签变绿后,说明全部角色绑定成功。

6 个角色全部完成绑定

13. 第十一步:创建自定义协作群并开始执行任务

接着在弹窗上方填写协作群名称和协作目标:

13.1 推荐的协作群名称

足球比赛自媒体撰稿室

13.2 零准备、可直接复制的演示输入

下面使用虚构球队和明确的演示事实卡,不会把尚未核实的真实赛程、伤停或首发写成事实。复制到“协作目标”即可:

请为一场明确标记为“流程演示、非真实赛程”的世界杯风格比赛制作赛前前瞻自媒体内容。

【比赛选题】
星河队 vs 山海队,虚构演示赛。

【内容要求】
- 内容模式:赛前前瞻
- 目标受众:平时看球不多、但愿意在大赛期间了解比赛看点的普通观众
- 发布平台:抖音、B 站
- 目标时长:2 分钟
- 文风:专业但通俗,有画面感,不堆术语
- 核心目标:让观众快速理解双方风格差异,并愿意在评论区讨论胜负手
- 输出:完整口播稿、纯文字分镜、标题、封面文案、发布说明、标签和评论区互动问题

【本次演示唯一事实卡】
- 两支队伍和比赛均为虚构,只用于演示多 Bot 协作流程。
- 星河队的演示设定:偏好高位压迫和快速边路推进。
- 山海队的演示设定:偏好中低位防守和抢断后的快速反击。
- 星河队 10 号是组织核心;山海队 9 号是反击终结点。以上均为虚构设定。
- 不得补写真实世界杯赛程、真实球员、真实伤停、真实排名或博彩信息。
- 无法确认的信息必须标为未知或演示设定,不能伪装成真实事实。

请按模板既定流程执行,并由内容主编交付一个可直接进入人工复核的最终发布包。

13.3 换成真实比赛时怎么写

如果要制作真实比赛,把上面“比赛选题”和“事实卡”替换为已经核验的公开信息,并补充:

真实比赛信息会随时间变化。提交前以赛事官网、足协、球队官方渠道或可靠数据源为准;不要把网络传闻当作事实卡。

填写完成后点击“创建协作群”,会按照协作模版创建自定义协作群,然后自动启动名为“新会话”的会话,会话根据上面填写的“协作目标”完成结构化任务。

填写新会话和协作目标

13.4 后续复用协作群

一个协作群内可以创建多个会话,以达到复用协作群能力来解决相似任务的目的。

以当前 WAIC 世界杯赛前前瞻自媒体稿 Demo 为例,这个自定义协作群可以针对不同的比赛,内容风格,目标平台,和目标时长进行协作,按需生成新的内容。

假设你想生成另一场比赛的赛前前瞻稿,可以点击左边栏的“新建会话”按钮,并写入会话名称和协作目标,最后点击确认。这次服务调用会创建会话,并自动启动自定义协作。

14. 第十二步:观察执行并检查结果

执行开始后,页面会展示自定义协作的运行消息和节点状态。一次完整运行通常需要数分钟,具体取决于模型响应速度和网络情况。

模板默认行为包括:

不要因为中间几秒没有新消息就重复点击“确认”。重复提交会创建多次独立运行。

14.1 成功结果应包含什么

最终结果至少应能看到:

使用虚构输入时,成品必须持续标注“演示设定”,不能把星河队、山海队或虚构球员包装成真实世界杯事实。

自定义协作任务执行中

15. (进阶功能)Bot 自主调用 BCS 功能

在自由聊天和主从协作模式中,如果 Bot 认为参与当前会话的 Bot 无法完成用户需求,它会自主通过 bcs-coordination Skill 和 bcs-cli命令发现可用 Bot,寻找合适 Bot,然后自动拉群开始新对话。

alt text

16. 停止服务

演示结束后,先停止 6 个 Bot,再停止前端和 BCS:

./singlebox/singlebox.sh stop bots --profile-dir singlebox/agents/6bots_world_cup_creator_profile
./singlebox/singlebox.sh stop bcs_frontend

检查是否都已停止:

./singlebox/singlebox.sh status bots --profile-dir singlebox/agents/6bots_world_cup_creator_profile
./singlebox/singlebox.sh status bcs_frontend

stop 只停止进程,保留本地 Bot 身份、协作群和会话数据,方便下次继续。不要为了普通重启执行 clean;clean 会删除本地运行数据,只有明确希望从零重置时才使用。

下次复现通常只需要:

./singlebox/singlebox.sh start bcs_frontend
./singlebox/singlebox.sh start bots --profile-dir singlebox/agents/6bots_world_cup_creator_profile

17. 常见问题

17.1 运行 singlebox.sh 提示 Permission denied

确认你位于仓库根目录,然后执行:

chmod +x singlebox/singlebox.sh
./singlebox/singlebox.sh --help

17.2 前端提示 cross-env: command not found

当前启动脚本会在前端 start 前检查并安装一次依赖。先确认 Node.js 是 22 或更高版本,然后重新启动:

node --version
./singlebox/singlebox.sh start bcs_frontend

如果 npm 安装失败,查看终端中的第一个错误,而不是最后一行。常见原因是公共 npm registry 网络不可达、磁盘空间不足或本机 npm 配置异常。

17.3 BCS 启动时提示找不到二进制或 bcs-cli

说明还没有完成 setup,重新执行:

./singlebox/singlebox.sh setup bcs_frontend

成功后再启动 BCS 和 Bot。

17.4 Bot 全部在线,但不生成回复

最常见原因是启动 Bot 时选择了 mock,或者 manual 配置缺字段。

先停止 Bot,再使用真实配置重新启动:

./singlebox/singlebox.sh stop bots --profile-dir singlebox/agents/6bots_world_cup_creator_profile
./singlebox/singlebox.sh start bots --profile-dir singlebox/agents/6bots_world_cup_creator_profile

选择 2 或 3,并确认模型服务本身可用。

17.5 前端看不到“自定义协作”

自定义协作当前需要以 Bot 视角创建。请确认:

17.6 模板下拉框里没有世界杯模板

依次确认:

test -f apps/bcs/seeds/collaboration-templates/zh-CN/world-cup-preview-content-production.yaml && echo "模板文件存在"
./singlebox/singlebox.sh status bcs_frontend

本地 BCS 使用文件型模板目录,模板列表在请求时读取。如果文件存在但页面仍没有显示:

  1. 确认 BCS 来自当前仓库,而不是另一个 checkout。
  2. 停止并重新启动 bcs_frontend。
  3. 强制刷新浏览器页面,再重新打开“拉起协作”。
  4. 查看 BCS 日志 singlebox/.dependencies/logs/bcs.log。

17.7 角色搜索不到对应 Bot

确认 6 个 Bot 的状态都是 Running。角色绑定区域中切换到“可协作Bot”与“按名称筛选”,然后输入完整中文名称。

如果 Bot 状态异常,查看:

17.8 端口被占用

例如检查 8000 和 21000:

lsof -nP -iTCP:8000 -sTCP:LISTEN
lsof -nP -iTCP:21000 -sTCP:LISTEN

先识别进程是否属于当前 Avernet checkout。如果是本教程之前启动的服务,使用 singlebox stop;如果属于其他应用,关闭那个应用,或者在 singlebox/.env.local 中配置其他 FRONTEND_PORT 和 BCS_PORT。

Bot profile 的 30401 至 30451 端口目前来自 bots.json。修改它们属于进阶操作,并且需要保持 port_start 和 port_step 不与本机其他服务冲突。

17.9 看到 faiss-cpu 不支持 Python 3.13

本教程只启动 bcs_frontend 和世界杯 Bot,不需要 BCSFuse,因此不应进入 BCSFuse 依赖安装路径。不要用不带目标的 ./singlebox/singlebox.sh 代替本教程的显式命令。

如果你另外需要完整栈或 BCSFuse,请先更新到包含兼容性修复的最新代码;当前 setup 会自动选择低于 3.13 的兼容 Python 版本。

17.10 想查看更完整日志

主要日志位置:

服务 日志
BCS singlebox/.dependencies/logs/bcs.log
前端 singlebox/.dependencies/logs/frontend.log
世界杯 Bot 汇总 singlebox/.dependencies/logs/bots_*.log
单个世界杯 Bot singlebox/.dependencies/logs/world-cup-*.log

查看日志不会修改运行状态。例如:

tail -n 100 singlebox/.dependencies/logs/bcs.log
tail -n 100 singlebox/.dependencies/logs/frontend.log