让对话、规划与感知并行，让物理执行有序且可追踪。
面向机器人与实时人机交互的事件驱动多智能体运行时。
简体中文 · English
界面 · 框架 · 记忆 · 实验记录 · 快速开始 · 机器人集成
取扳手、放滚柱、整理料箱，任务内容不同，却会反复经历相似的职责：理解要求、观察目标、选择动作、执行、检查结果、向用户解释。BusAgent 把这些稳定职责做成节点，把它们之间的协作交给事件协议。 每个节点可以由语言模型、视觉模型、传统算法或设备服务实现。
这套设计关注三个同时发生的问题：用户不能因机械臂正在运动而失去对话；多个任务可以提前感知和规划，但不能争抢同一只机械臂；一次失败要能定位到具体阶段，再依据实际状态决定下一步。为此，BusAgent 采用 节点自治、总线协调、资源保序、结果驱动恢复 的组织方式。
| 项目 | 核心问题 | 提供什么 |
|---|---|---|
| BusAgent · 协作框架 | 谁处理这条消息？任务如何关联？何时允许执行？失败后如何继续？ | 节点与 App 契约、事件路由、任务队列、上下文、模型配置、执行轨迹与工作台 |
| LiuGongArm · 机器人应用与验证环境 | 目标在哪里？如何抓取与放置？物体是否真的到位？ | 视觉、快慢运动路径、Arena / Panda 适配、物理反馈与场景试验 |
开发新应用时，可以复用 BusAgent 的协作机制，替换感知和设备适配器。LiuGongArm 则把这些机制放进有遮挡、持物、接触和失败的机器人场景中检验。
当前阶段：研究预览。 主线是 NestJS / TypeScript Host、MySQL 持久化和 React 工作台，已接通 Arena / Panda。节点契约面向扩展；当前交付的主要应用是机器人助手。机器人动作需要独立控制器与模型服务。
图中展示职责关系，不表示所有节点在每条指令中都被调用。
| 部分 | 负责什么 | 如何限制自由度 |
|---|---|---|
| 节点 | 完成一个稳定职责，发布结果，并可建议下一跳 | 受 Package 能力声明、App 允许集合和事件输入契约约束 |
| 总线 | 维护事件身份、因果关联、路由、投递及记录 | 路由器检查接收契约、活动租约与权限；业务推理由能力节点承担 |
| 执行协调 | 将已验证的动作交给设备，维护队列与当前任务 | 核对任务版本；同一机械臂进入独占车道；物理副作用消息不盲目自动重试 |
| 监督与记忆 | 保存事实、检查结果、为需要判断的阶段提供上下文 | 监督参与异常与检查点；确定性的执行门和控制器检查持续生效 |
“自治”具体指在声明的范围内选择与协作。当前 路由器 同时支持静态 App 路由和受约束的节点建议；执行门 核验计划状态与任务版本；重试策略 对物理消息禁用自动重复投递。这些机制各自处理一类约束，模型无需独自承担全部调度职责。
| 原则 | 在机器人任务中的含义 |
|---|---|
| 总线驱动 | 一个观察结果可被多个已声明消费者使用，无需让主模型逐一转述 |
| 职责明确 | 理解、规划、对话、感知与设备执行分别维护输入和输出契约 |
| 并行优先 | 无依赖的信息处理可并行；动作按物理资源与阶段依赖排序 |
| 流式优先 | 语音和对话持续交付增量内容，不要求整个动作任务结束后才回应 |
| 有序可追踪 | 关联会话、任务、版本与因果事件；保序范围由任务和资源确定 |
| 上下文按需 | 按角色与预算读取当前任务、历史证据和观测引用，原始归档可追查 |
| 监督而非包办 | 在检查点和失败时做判断；正常动作由既定任务与执行机制推进 |
收益来自减少不必要的等待、重复推理与状态混淆。节点拆分也增加了契约、消息记录和调试工作；总 token、吞吐和延迟需要分别测量，不能由“并行”推断所有成本都下降。
这是 2026-09-18 本地运行当前前端采集的真实首页，未连接 GPU 后端；不是任务完成截图。完整执行的仿真截图和结果见 LiuGongArm 演示区。效果录屏待接入，素材说明 记录了采集与替换方式。
flowchart TB
U[用户 · 文字 / 流式语音] --> B[BusAgent Event Bus]
B --> D[对话节点]
D --> TTS[流式文本 / TTS]
B --> T[任务路由]
T -->|明确简单任务| Q[结构化动作列表]
T -->|复杂任务| P[高级规划 + 当前场景图像]
P --> Q
Q --> X[执行协调 · 独占运动队列]
X --> A[设备适配器 → Arena / Panda]
A --> E[执行状态与物理结果]
E --> B
B --> M[不可变事件归档 / 任务账本]
M --> C[按预算装配上下文]
C --> T
E -->|失败 / 检查点| S[监督与恢复]
S --> Q
classDef core fill:#142c36,color:#fff,stroke:#54ddc0
classDef device fill:#332c20,color:#fff,stroke:#ffbd66
class B,D,T,TTS,P,Q,M,C,S core
class X,A,E device
事件传递身份、因果关系、引用和状态。原始音频走 WebSocket；图像、深度和点云留在感知服务。正常连续动作无需每步重新调用模型，异常、语义检查点或最终复核再进入监督路径。
sequenceDiagram
participant U as 用户
participant D as 对话 / 查询
participant Q as 任务队列
participant R as 机器人适配器
U->>Q: 把零件放入托盘
par 即时沟通
Q-->>D: 任务已接收
D-->>U: 返回接收与当前状态
and 执行动作
Q->>R: 当前任务版本的结构化命令
R-->>Q: started → completed / failed / unknown
end
U->>D: 现在进行到哪里了？
D->>Q: 读取账本
Q-->>D: 当前阶段与阻塞原因
D-->>U: 返回事实状态
该时序图表示职责与并行关系，不表示实测时间比例。
“环”是一组依据反馈继续运行的职责组合。同一套感知、规划与执行节点可以参与不同的环，任务根据目标、观测质量和执行结果选择路径。BusAgent 保存任务关联并传递所需模式，LiuGongArm 的视觉与运动服务完成具体的快慢路径选择。
| 环 | 关注的问题 | 与其他工作的关系 |
|---|---|---|
| 交互环 | 用户在说什么，需要回应、澄清还是查询进度？ | 可以在机械臂动作期间继续；状态查询读取任务账本 |
| 快速感知与常规动作 | 已知目标能否重新定位，普通抓放能否直接完成？ | 优先复用轻量跟踪、当前参考与常规控制器 |
| 增强感知与操作 | 遮挡、实例冲突、复杂姿态是否需要更强能力？ | 按失败阶段调用定位、抓取或放置服务，再返回正常路径 |
| 校验与恢复 | 动作是否真正完成，还有哪些步骤需要继续？ | 利用新观测和物理反馈；保留完成结果，只修复剩余任务 |
例如，两条指令“把零件放入托盘”和“查一下扳手在哪里”可有独立的对话与观察过程；当后者也请求移动机械臂时，才竞争同一个执行资源。取消后仍需核对持物状态，不能把取消等同于松爪或安全放回。业务取消、控制器停止和硬件急停有不同职责。
工作上下文需要及时反映任务和持物变化，完整历史则需要保留供追查。当前 robot.memory 从事件归档生成会话记忆，robot.context_compression 为不同角色生成有预算的抽取式视图；压缩过程不调用模型。任务与持物状态在使用时重新读取，旧缓存不能替代当前事实。
flowchart LR
E[用户输入 / 回复 / 执行结果] --> A[不可变事件归档]
A --> M[会话记忆]
M --> C[按角色与预算生成上下文]
Q[实时任务账本 / 持物状态] --> C
C --> P[规划 / 对话节点]
P -. 查询完整历史与证据 .-> A
长期经验按来源拆开，是后续迁移复用的重要设计：
| 经验类型 | 有价值的内容 | 当前实现与扩展边界 |
|---|---|---|
| 视觉记忆 | 目标外观、参考帧、掩码、相机与来源 | LiuGongArm 已有视觉参考存储与 YOLOE 提示复用；通用跨工位类别共享仍需验证 |
| 机械经验 | 成功抓取姿态、路径、接触条件与失败位置 | 当前保留执行证据和运行时持物状态；跨任务路径学习、可迁移机械记忆与 FLE 接入属于扩展方向 |
| 用户记忆 | 用户要求、澄清答复、别名与偏好 | 当前有会话事件与历史检索；独立用户偏好库及分项导入导出尚未作为完整功能交付 |
这样，新产线未来可以复用外观知识，同时保留本地机器人、夹爪和标定约束。记忆命中仍需经过现场观测核对，不能凭旧经验直接授予动作执行许可。实现见 记忆节点 与 上下文服务。
跨任务学习的一个研究方向是 FLE（Failure-Localized Reward Evolution）：把失败所在的轨迹阶段、末端空间区域与间隙整理为局部反馈，用于评估策略或奖励修正，再将验证后的经验用于后续同类任务。这对应两个时间尺度：任务内恢复处理眼前的异常，跨任务学习改善之后的策略。当前 README 将后者列为研究扩展，不把运行日志自动等同于已训练出的机械经验。
VLA 可以成为操作策略的一个 Provider。 框架负责请求、结果、上下文和执行边界；具体动作能力由接入的策略提供。当前主线使用 Panda 控制器、GraspGenX 与 AnyPlace，通用 VLA Provider 是设计扩展点。能力增强后，可把更多阶段交给学习策略，继续保留对话、任务状态和过程追踪。
部署设计则允许把每工位持续需要的能力放在本地，把按需调用的重模型做成共享服务。容量模型是 N × C_fast + k × C_slow：N 为工位数，k 为满足实际负载与响应期限的慢环实例数。k 需要根据峰值并发、服务时间、P95 排队等待及故障余量确定，不能直接等于慢环调用率。
当前仓库提供单部署的运行时与机器人集成。RK3588 边缘适配、多工位推理池和共享容量压测是后续方向；没有据此宣称“一台服务器承载上百台机械臂”或固定成本降幅。更完整的分层与迁移设计见 节点与插件设计。
图表来自 2026-09-07 的同句输入修复前后开发审计：WebSocket 文字输入至最终文字输出，不含语音识别和音频播放。状态查询原路径经历模型超时，修复后直接读账本、零 LLM 请求。它说明一次具体故障路径的改善，不是与其他框架的性能比较，也不是重复采样基准或 P95。
| 观察 | 结果 | 边界 |
|---|---|---|
| 状态查询分流 | 原记录约 42.15 s → 0.536 s，修复后零 LLM 请求 | 原记录含渠道超时；不能推广到所有输入 |
| 场景概览简化 | 原记录约 21.27 s → 9.274 s | 仍有云端视觉推理等待，不等于实时视觉 |
| 次日三个状态查询 | 662 / 406 / 507 ms，均不创建目标、无 LLM 调用 | 三个开发样例，无吞吐与负载结论 |
来源：9 月 7 日审计、9 月 8 日复测、图表数据与生成脚本。这是 LiuGongArm 集成中的历史数据，不代表独立框架通用性能；本次 README 更新未重新执行这些实验。
| 组件 | 职责 | 代码入口 |
|---|---|---|
| Host / Event Bus | 加载配置、事件投递、路由、重试与因果关联 | bus |
| Package / App | 声明能力、选择节点和允许的事件连接 | 机器人 App |
| 任务与模型层 | Mastra 工具调用、分阶段规划、模型配置、恢复 | intelligence |
| 持久化 | MySQL / Drizzle 保存事件、任务及审计事实 | 后端架构 |
| 工作台 | 对话、场景、模型设置与执行轨迹 | WorkbenchPage |
当前队列采用进程内投递，MySQL 负责持久化；不要据此假定已经实现多机分布式消息中间件。后端默认假设可信网络，远程使用需配置访问边界。BusAgent 不替代机器人控制器的急停、碰撞保护与功能安全。
需要 Node.js ≥22.13、pnpm 11.9，以及 Docker Compose 或可用的 MySQL 实例。使用语音需要自己的 DashScope Key；规划与对话模型可在前端设置中配置。
git clone https://github.com/yibent/BusAgent.git
cd BusAgent
docker compose up -d mysqlCompose 默认数据库为 busagent，宿主机端口 3307，开发账号为 root / root。这些是本地开发配置，部署时应替换凭据并限制访问。
cd backend
pnpm install --frozen-lockfile
export BUSAGENT_MYSQL_URL='mysql://root:root@127.0.0.1:3307/busagent'
export DASHSCOPE_API_KEY='your-dashscope-key'
# 连接 LiuGongArm 的 Arena / Panda 时启用此适配模式：
export BUSAGENT_ROBOT=franka_panda
pnpm dev后端默认监听 3000。机器人控制器默认位于 127.0.0.1:7861，完整服务栈见 LiuGongArm 安装指南。没有 GPU 控制器时可以启动界面和配置模型，机器人动作需要等待控制器就绪。
另开终端，从仓库根目录执行：
cd frontend
pnpm install --frozen-lockfile
pnpm dev打开 http://localhost:5173。Vite 将 /v1 代理到后端 3000，/api 代理到 Arena 7861；使用其他端口时：
BUSAGENT_PROXY_TARGET=http://127.0.0.1:3100 \
ARENA_PROXY_TARGET=http://127.0.0.1:7861 pnpm dev在工作台设置中填写自己的模型服务地址、模型名、视觉能力和密钥。需要图像的角色应选择支持视觉的 Profile。首次运行不会自动提供模型额度或下载机器人权重。
测试与生产构建
在仓库根目录执行：
pnpm --dir backend test
pnpm --dir backend build
pnpm --dir frontend test
pnpm --dir frontend build前端产物位于 frontend/dist，由 Vite 预览服务器或独立 Web 服务器提供；后端不负责托管前端。远程语音访问需要浏览器允许麦克风的 HTTPS 上下文。
- 后端架构：事件协议、能力声明与运行时边界；部分章节记录早期方案，以当前代码和本主页启动说明为准。
- 节点与插件设计：能力节点、技能插件和控制环。
- 交互与执行反馈、语义定位。
- LiuGongArm：机器人适配、感知、模型服务与仿真验收。
- Issues：欢迎提交带复现步骤、任务事件与脱敏配置的问题。
贡献优先方向：可复现安装、故障恢复测试、外部 Agent / 设备适配、真实演示素材，以及固定条件的延迟与可靠性基准。提交新节点时说明输入、输出、并发和失败语义；涉及物理动作时保留实际执行状态，不把模型文本当作完成依据。
原创贡献采用 Apache License 2.0。依赖、模型、外部服务和媒体保留各自授权，详见 第三方来源索引。感谢 NestJS、Mastra、React、Vite、Drizzle、Radix UI、shadcn/ui 与 Lucide 等上游项目。