BossAgents BossAgents

5端协同架构与实现文档

👤 BossAgents 团队 📅 2026-08-30 👁️ 阅读 9 👍 点赞 0 ☕ 91 分钟阅读

5端协同架构与实现文档

文档版本: v1.0

最后更新: 2026-08-23

维护者: BossAgents 团队

状态: 边端(Edge)+网端(Network)已实现，5端协同闭环完成

一、架构总览

1.1 五端定义

端代号角色职责实现状态模块路径
云端Cloud中心服务器全量数据、重推理、编排、规则引擎✅ 已实现server.js + server/boss-scheduler/
边端Edge边缘节点实时推理、预处理、数据缓存、离线队列✅ 已实现server/edge/edge-node-manager.js
端侧Device设备/浏览器交互、采集、MTClaw端侧执行✅ 已实现src/ 前端 + bossagents-miniapp/ 小程序 + MTClaw/ 端侧脚本
网端Network网络层连接管理、路由策略、QoS、消息可靠性✅ 已实现server/network/network-manager.js
人侧Human人工审批决策放行、质量把关✅ 已实现local.yaml taskForces gate 节点

1.2 架构图

                    ┌─────────────────────────────────────────┐
                    │           云端 (Cloud)                    │
                    │  server.js (PORT=3006)                   │
                    │  ├── boss-scheduler/ (调度核心)           │
                    │  │   ├── index.js (统一入口)              │
                    │  │   ├── a2a-protocol.js (A2A/MACP)      │
                    │  │   ├── edge/ (边端管理)                 │
                    │  │   └── network/ (网端管理)              │
                    │  ├── 规则引擎 (190条规则)                 │
                    │  └── SCSAI PLM 对接                      │
                    └──────────┬──────────────────┬────────────┘
                               │                  │
                    ┌──────────▼─────────┐  ┌────▼─────────────┐
                    │   网端 (Network)    │  │  A2A 协议         │
                    │  network-manager.js │  │  a2a-protocol.js  │
                    │  ├── 链路注册       │  │  ├── 点对点消息    │
                    │  ├── 路由选择       │  │  ├── 广播          │
                    │  ├── QoS保障        │  │  ├── 协同触发      │
                    │  └── 断线重连       │  │  └── MACP会话     │
                    └──────────┬──────────┘  └────┬─────────────┘
                               │                   │
                    ┌──────────▼───────────────────▼───────────┐
                    │           边端 (Edge)                      │
                    │  edge-node-manager.js                     │
                    │  ├── 节点注册/心跳                         │
                    │  ├── 任务分派 (云→边)                      │
                    │  ├── 结果回传 (边→云)                      │
                    │  ├── 负载均衡                              │
                    │  └── 本地缓存/离线队列                     │
                    └──────────┬───────────────────────────────┘
                               │
                    ┌──────────▼───────────────────────────────┐
                    │           端侧 (Device)                    │
                    │  ├── 前端 Vue3 (src/)                     │
                    │  ├── 小程序 (bossagents-miniapp/)         │
                    │  └── MTClaw 端侧脚本 (MTClaw/scripts/)    │
                    └────────────────────────────────────────────┘

                    ┌────────────────────────────────────────────┐
                    │           人侧 (Human)                     │
                    │  taskForces gate 节点 (local.yaml)        │
                    │  ├── 质量经理放行                          │
                    │  ├── 车间主任复产决策                      │
                    │  └── 技术总监评审                          │
                    └────────────────────────────────────────────┘

1.3 数据流

用户意图 → 端侧(Device) → 网端(Network)路由 → 云端(Cloud)编排
                                                    ↓
                                            需要边缘计算?
                                           ↙        ↘
                                     是               否
                                      ↓                ↓
                              网端→边端(Edge)      云端直接执行
                              边端预处理           ↓
                                      ↓           A2A触发下游
                              边端→网端→云端      ↓
                                      ↓           人侧审批(gate)
                              云端合并结果        ↓
                                      ↓           最终结果
                                      ↓             ↓
                                      └─────→ 端侧展示 ←──┘

二、模块详细设计

2.1 边端 Edge — server/edge/edge-node-manager.js

#### 设计目标

将轻量推理和预处理任务从云端下放到边缘节点，降低延迟、节省带宽、支持离线场景。

#### 核心接口

| 函数 | 参数 | 返回 | 说明 |

|---|---|---|---|

| registerNode(node) | {id, host, port, capabilities, location, weight} | node对象 | 注册边缘节点 |

| unregisterNode(nodeId) | nodeId | void | 注销节点 |

| heartbeat(nodeId, stats) | nodeId, {taskCount, avgLatency} | bool | 心跳更新 |

| findBestNode(capability) | capability字符串 | node/null | 查找最优节点 |

| dispatch(capability, payload) | capability, payload | {nodeId, result, latency} | 分派任务到边缘 |

| getNodes() | - | 节点列表 | 获取所有节点 |

| getStats() | - | 统计对象 | 获取统计信息 |

#### 节点选择策略

load = weight × (1 + taskCount) × (1 + avgLatency / 1000)
选择 load 最小的在线节点

#### 心跳机制

  • 节点每 10s 发送心跳
  • 超过 30s 未心跳 → 标记为 offline
  • offline 节点不参与任务分派

#### 当前能力映射

const workerMap = {
  'spc_check':       () => require('../workers/spc-worker'),
  'qcc_inspect':     () => require('../workers/qcc-worker'),
  'data_preprocess': () => require('../workers/data-clerk'),
  'inspect':         () => require('../workers/inspect-worker'),
};

#### 扩展指南

  1. 在 workerMap 中添加新的能力映射
  2. 实际部署时将 _executeOnEdge 替换为 HTTP/gRPC 调用：
   async function _executeOnEdge(node, capability, payload) {
     const resp = await fetch(`http://${node.host}:${node.port}/execute`, {
       method: 'POST',
       body: JSON.stringify({ capability, payload })
     });
     return resp.json();
   }

2.2 网端 Network — server/network/network-manager.js

#### 设计目标

管理端云/边云之间的网络连接，提供路由选择、QoS保障和消息可靠性。

#### 核心接口

| 函数 | 参数 | 返回 | 说明 |

|---|---|---|---|

| registerLink(linkId, config) | linkId, {from, to, bandwidth, latency, reliability, cost} | link对象 | 注册网络链路 |

| unregisterLink(linkId) | linkId | void | 注销链路 |

| selectRoute(from, to, opts) | from, to, {priority, maxLatency, minBandwidth} | link/null | 路由选择 |

| send(link, payload, opts) | link, payload, {timeout, retry} | {success, roundTrip, result} | 发送消息 |

| createConnection(connId, config) | connId, {from, to, type, onMessage} | conn对象 | 建立持久连接 |

| getTopology() | - | 拓扑对象 | 获取网络拓扑 |

| getStats() | - | 统计对象 | 获取网络统计 |

#### 路由选择公式

score = (bandwidth × reliability × qosLevel) / (latency × cost)
选择 score 最高的活跃链路

QoS级别：high=3, normal=2, low=1

#### 消息可靠性

  • 自动重试（默认3次，指数退避）
  • 超时控制（默认30s）
  • ACK确认（通过success/failed统计追踪）
  • 传输失败模拟（基于reliability概率）

#### 扩展指南

  1. 实际部署时将 _transmit 替换为真实网络传输：
   async function _transmit(link, payload, timeout) {
     const controller = new AbortController();
     setTimeout(() => controller.abort(), timeout);
     const resp = await fetch(`http://${link.to}/receive`, {
       method: 'POST',
       body: JSON.stringify(payload),
       signal: controller.signal
     });
     return resp.json();
   }
  1. 添加WebSocket支持用于实时消息
  2. 添加消息加密（TLS/自定义加密）

2.3 A2A/MACP 协议 — server/boss-scheduler/a2a-protocol.js

#### A2A (Agent-to-Agent) — 员工间点对点通信

| 函数 | 说明 |

|---|---|

| sendMessage(from, to, content) | 发送点对点消息 |

| broadcast(from, targets, content) | 广播给多个员工 |

| requestCollaboration(from, result, config) | 基于collaboration配置自动触发下游 |

| getMessages(staffId, opts) | 获取员工消息历史 |

#### MACP (Multi-Agent Communication Protocol) — 多智能体会话

| 函数 | 说明 |

|---|---|

| createSession(participants, context) | 创建多智能体会话 |

| sendInSession(sessionId, from, content) | 会话内消息（自动广播给其他参与者） |

| closeSession(sessionId) | 关闭会话 |

| listActiveSessions() | 列出活跃会话 |

#### 自动触发机制

runStaffOnce 完成任务后自动检查 staff.collaboration.onComplete 配置：

// boss-scheduler/index.js runStaffOnce
const result = await scheduler.runOnce(staffId, intent, parameters);
const staff = staffList.find(s => s.id === staffId);
if (staff && staff.collaboration && result) {
  a2a.requestCollaboration(staffId, result, staff.collaboration);
}

2.4 人侧 Human — taskForces gate 节点

在 local.yaml 的 taskForces 中定义，gate 节点为人工审批：

taskForces:
  - id: TF-COMPLAINT
    members:
      - key: gate
        type: human          # 人侧节点
        role: 质量经理放行审批
        approver: 质量经理
        dependsOn: [proc, sched]
        gate:
          question: 是否批准该整改方案并放行受影响批次？
          options: [批准放行, 有条件放行, 驳回重做]

当前4个taskForce共有4个人侧gate节点：

  • TF-COMPLAINT: 质量经理放行
  • TF-LINE-STOP: 车间主任复产决策
  • TF-NEW-PRODUCT: 技术总监评审
  • TF-COST-ALERT: 无gate（全自动）

三、API 接口文档

3.1 边端 API

#### GET /api/edge/nodes

获取所有边缘节点及统计。

响应:

{
  "nodes": [{ "id": "edge-01", "host": "192.168.1.100", "port": 8081, "status": "online", "capabilities": ["spc_check"] }],
  "stats": { "total": 1, "online": 1, "totalTasks": 5, "completedTasks": 5 }
}

#### POST /api/edge/nodes

注册边缘节点。

请求体:

{ "id": "edge-01", "host": "192.168.1.100", "port": 8081, "capabilities": ["spc_check", "qcc_inspect"], "weight": 1 }

#### DELETE /api/edge/nodes/:id

注销边缘节点。

#### POST /api/edge/heartbeat

心跳更新。

请求体: { "nodeId": "edge-01", "stats": { "taskCount": 5, "avgLatency": 12 } }

#### POST /api/edge/dispatch

分派任务到边缘节点。

请求体: { "capability": "spc_check", "payload": { "data": "..." } }

响应: { "nodeId": "edge-01", "result": {...}, "latency": 15 }

#### GET /api/edge/stats

边缘节点统计。

3.2 网端 API

#### GET /api/network/topology

获取网络拓扑。

响应:

{
  "links": [{ "id": "cloud-edge-01", "from": "cloud", "to": "edge-01", "status": "active", "bandwidth": 100, "latency": 5 }],
  "connections": []
}

#### POST /api/network/links

注册网络链路。

请求体: { "linkId": "cloud-edge-01", "from": "cloud", "to": "edge-01", "bandwidth": 100, "latency": 5, "reliability": 0.99 }

#### POST /api/network/send

通过网络发送消息。

请求体: { "from": "cloud", "to": "edge-01", "payload": { "type": "task", "data": "..." }, "priority": "high" }

#### GET /api/network/stats

网络统计。

3.3 5端总览 API

#### GET /api/five-ends/status

获取5端协同状态总览。

响应:

{
  "cloud": { "status": "online", "role": "中心服务器", "host": "ylxt.chat" },
  "edge": { "status": "online", "total": 1, "online": 1, "totalTasks": 5, "completedTasks": 5 },
  "device": { "status": "online", "role": "前端+小程序+MTClaw端侧" },
  "network": { "status": "online", "links": 1, "activeLinks": 1, "deliveryRate": "100.0%" },
  "human": { "status": "online", "role": "taskForces gate审批" },
  "a2a": { "sessions": 0 }
}

四、部署指南

4.1 云端部署（当前已运行）

# 启动云端服务器
cd C:\bossagents
node server.js  # 默认端口 3006

4.2 边端部署

#### 方式一：本地模拟（开发/测试）

无需额外部署，edge-node-manager.js 的 _executeOnEdge 直接调用本地worker。

#### 方式二：独立边缘节点（生产）

  1. 在边缘机器上部署轻量Node.js服务：
   // edge-server.js (边缘节点上的服务)
   const http = require('http');
   http.createServer((req, res) => {
     // 接收云端分派的任务并执行
   }).listen(8081);
  1. 在云端注册边缘节点：
   curl -X POST http://cloud:3006/api/edge/nodes \
     -H 'Content-Type: application/json' \
     -d '{"id":"edge-01","host":"192.168.1.100","port":8081,"capabilities":["spc_check","qcc_inspect"]}'
  1. 注册网络链路：
   curl -X POST http://cloud:3006/api/network/links \
     -H 'Content-Type: application/json' \
     -d '{"linkId":"cloud-edge-01","from":"cloud","to":"edge-01","bandwidth":100,"latency":5,"reliability":0.99}'

4.3 网端配置

网端为云端内置模块，无需独立部署。通过API注册链路即可建立端云/边云连接。

4.4 人侧配置

在 local.yaml 的 taskForces 中定义gate节点，无需额外部署。

五、接手说明

5.1 代码结构

server/
├── boss-scheduler/
│   ├── index.js              # 统一入口，导出 a2a/edge/network
│   ├── a2a-protocol.js       # A2A/MACP 通信协议
│   ├── edge/
│   │   └── edge-node-manager.js  # 边端节点管理
│   ├── network/
│   │   └── network-manager.js    # 网端管理
│   └── workers/              # 67个worker实现
├── edge/                     # edge模块（被boss-scheduler引用）
│   └── edge-node-manager.js
├── network/                  # network模块
│   └── network-manager.js
└── boss-scheduler/
    └── profiles/
        └── local.yaml        # 含taskForces(人侧gate节点) + collaboration配置

5.2 关键文件清单

| 文件 | 作用 | 修改场景 |

|---|---|---|

| server/edge/edge-node-manager.js | 边端节点管理 | 添加新能力映射、替换为真实HTTP调用 |

| server/network/network-manager.js | 网端管理 | 添加传输协议、QoS策略 |

| server/boss-scheduler/a2a-protocol.js | A2A/MACP协议 | 添加消息类型、持久化 |

| server/boss-scheduler/index.js:99 | runStaffOnce+A2A集成 | 修改协同触发逻辑 |

| server/boss-scheduler/staff-router.js:191 | type过滤 | 调整哪些type参与用户匹配 |

| server.js:5827 | 5端协同API路由 | 添加新API端点 |

| server/boss-scheduler/profiles/local.yaml | taskForces+collaboration | 添加协同链路、审批节点 |

5.3 常见扩展场景

#### 场景1：添加新的边缘能力

  1. 在 edge-node-manager.js 的 workerMap 中添加映射
  2. 实现对应的worker文件
  3. 注册边缘节点时在 capabilities 中声明

#### 场景2：添加新的协同链路

  1. 在 local.yaml 对应员工下添加 collaboration.onComplete 配置
  2. 运行 node scripts/sync-collab-to-db.js 同步到DB
  3. 重启服务器

#### 场景3：添加新的人侧审批节点

  1. 在 local.yaml 的 taskForces 中添加 type: human 的member
  2. 设置 gate.question 和 gate.options

#### 场景4：替换为真实网络传输

  1. 修改 edge-node-manager.js 的 _executeOnEdge → HTTP调用
  2. 修改 network-manager.js 的 _transmit → HTTP/WebSocket调用
  3. 在边缘节点上部署对应的服务端

5.4 验证命令

# 验证5端协同状态
curl https://ylxt.chat/api/five-ends/status

# 注册边缘节点
curl -X POST https://ylxt.chat/api/edge/nodes -H 'Content-Type: application/json' -d '{"id":"edge-01","host":"localhost","port":8081,"capabilities":["spc_check"]}'

# 分派任务到边缘
curl -X POST https://ylxt.chat/api/edge/dispatch -H 'Content-Type: application/json' -d '{"capability":"spc_check","payload":{"data":"test"}}'

# 查看网络拓扑
curl https://ylxt.chat/api/network/topology

5.5 注意事项

  1. edge-node-manager.js 有两份：server/edge/ 和 server/boss-scheduler/edge/，前者被直接引用，后者通过boss-scheduler导出。修改时两份都要改，或统一引用路径。
  2. 心跳定时器：edge-node-manager.js 的心跳检测使用 setInterval，在测试脚本中需调用 edge.stop() 清理。
  3. A2A消息队列：当前为内存存储（最大1000条），重启后清空。生产环境需替换为持久化存储。
  4. network模拟传输：_transmit 当前为模拟（基于latency延迟+reliability概率失败），生产部署需替换为真实网络调用。
  5. type过滤：staff-router.js 的 matchStaff 过滤非 digital_worker 类型，新增面向用户的员工需确保 type 为空或 digital_worker。

六、与标准文档的对应关系

| 标准文档07要求 | 实现位置 | 状态 |

|---|---|---|

| 5端协同（云·边·端·网·人） | 本文档 | ✅ 全端实现 |

| A2A/MACP协议 | a2a-protocol.js | ✅ |

| 边端部署 | edge-node-manager.js | ✅ |

| 网端连接管理 | network-manager.js | ✅ |

| 人侧gate审批 | local.yaml taskForces | ✅ |

| 端云协同 | MTClaw端侧 + 网端路由 | ✅ |

| 边云协同 | 边端分派 + 网端链路 | ✅ |

| 一致性保障 | 同一对象模型(469元模型)贯穿五端 | ✅ |

七、变更记录

日期变更负责人
2026-08-23初始实现：Edge+Network+A2A/MACP+API路由+本文档BossAgents团队

八、TODO / 未来改进

  • [ ] 边端 _executeOnEdge 替换为真实HTTP/gRPC调用
  • [ ] 网端 _transmit 替换为真实网络传输
  • [ ] A2A消息队列持久化（Redis/SQLite）
  • [ ] 边端离线队列持久化
  • [ ] 网端WebSocket实时通信
  • [ ] 网端消息加密（TLS）
  • [ ] 边端自动发现（mDNS/consul）
  • [ ] 5端健康看板（前端可视化）
← 返回案例列表
分享：
🤖 Try Now →
🤖
🎁