SECTION 05
双方案验证
经过实际项目验证，确定两套控制方案并行发展、各司其职，适用于不同场景。
方案A
JZTArmAssembly 沙箱间接控制
Qclaw AI
工艺设计层
→
WebSocket
JSON-RPC 2.0
→
JZTArmAssembly
服务端
→
ctypes
DLL调用
→
硬件
Aubo i5 / Orbbec / Modbus
四大核心模块
| 模块 | 职责 | 关键方法 |
|---|---|---|
| modbusManager | Modbus TCP/RTU 通信 | 读写线圈/寄存器、脉冲控制、数据转换 |
| auboArmController | 机械臂运动控制 | moveJointByAxisArc、moveLineByEndPos、getCurrentPosByEndPos |
| tcpClientManager | TCP 客户端通信 | tcpConnect、tcpRead、tcpWrite |
| taskManager | 任务管理工具 | poseTrans、generateLinePosition、setGlobalVariables |
⚡ Modbus 外设扩展
框架支持所有符合 Modbus RTU/TCP 标准协议的设备接入（如夹爪、传送带、传感器等），通过提供地址表和控制指令即可灵活配置。
执行验证时间线
04-10 13:44
项目初始化
读取内部API文档与JsonRPC文档，识别核心模块
04-10 14:19
首次任务部署
V2格式任务上传、执行、状态监控成功
04-10 14:39
重复执行验证
连续10次执行全部成功，程序持久化验证通过
04-15 10:40
文档更新与规范化
Task Template API 规范化（setCurrentProgramBlockID、setProgramOutput）
04-20 17:55
Skill 封装完成
jzt-arm-task Skill 实现复用，支持部署/执行/监控
V2 任务格式规范
# @JZT_TASK_FORMAT_V2@
import random
def robot_quest_total():
setCurrentProgramBlockID("node_init")
a = random.randint(1, 100)
b = random.randint(1, 100)
setCurrentProgramBlockID("node_calc")
result = a + b
setCurrentProgramBlockID("node_save")
taskManager.setGlobalVariables("my_random", result)
setProgramOutput(f"a={a}, b={b}, a+b={result}, saved to my_random")Task Template API
| API | 功能 | 说明 |
|---|---|---|
| robot_quest_total() | 任务主入口 | 必须实现的任务入口函数 |
| setCurrentProgramBlockID(id) | 程序块控制 | 所有过程语句前必须调用，支持暂停/停止 |
| setProgramOutput(output) | 输出缓冲 | 替代 print()，可通过 RPC 读取 |
| wait_ms(ms) | 延时等待 | 阻塞等待（毫秒） |
| submitTask() / getTaskResult() | 异步任务 | 线程池异步任务接口 |
实际应用示例
示例 1
调用 Skill 创建任务（基础）
使用 jzt-arm-task Skill 部署执行任务，展示Skill封装的复用能力
📸 运行效果
💻 生成代码
示例 2
创建非标任务并控制外设
创建任务并通过Modbus协议控制外设，展示JZTArmAssembly的远程部署与外设控制能力
📸 运行效果
💻 生成代码
示例 3
完整机械臂 + 多外设协同控制
机械臂运动与多个Modbus外设协同控制，展示完整的自动化作业流程
📸 运行效果
💻 生成代码
方案B
Qclaw 自然语言直接控制
100%
命令执行成功率
≤30ms
SDK 指令响应延迟
6轴
机械臂关节数
2种
完整实现方案
技术栈
| 组件 | 版本/配置 | 说明 |
|---|---|---|
| Python | 3.14（Windows） | 运行环境 |
| Aubo SDK | C# DLL via ctypes | 机械臂控制 |
| Orbbec SDK | Gemini 335L | 深度相机 |
| 机械臂 IP | 192.168.30.146:8899 | 目标地址 |
相机输出类型
RGB
彩色图像
深度原始
16-bit Y16 格式
深度伪彩色
可视化展示
⚠️ 采集流程说明
当前采集流程为：机械臂移动 → 停止 → 采集数据，不支持边移动边采集。相机用途为数据采集。
踩坑经验（4项）
| # | 问题 | 解决方案 |
|---|---|---|
| 1 | 深度图格式：16-bit Y16 格式需手动归一化才能可视化，直接保存 PNG 会全黑 | 归一化处理后再可视化 |
| 2 | 运动范围：move_cartesian 目标坐标需验证 r = √(X²+Y²+Z²) < 0.9m，否则报错 21301 | 运动前校验坐标距离 |
| 3 | 启动重试：rs_robot_startup 初次调用可能返回 1002，需等待5秒后重试 | 添加重试逻辑 |
| 4 | DLL 依赖：ctypes 调用 DLL 时需先 os.add_dll_directory() 添加依赖路径 | 加载前设置依赖路径 |
🔒 安全机制
急停、重力补偿、关节限位等安全保护功能由机械臂厂家 SDK 自行实现。
实测演示
Qclaw 直接驱动机械臂演示
自然语言指令控制 Aubo i5 运动
SECTION 06
技术架构详情
详细的技术架构设计，包括数据模型和程序包格式。
元动作数据模型（MetaAction）
{
"id": "string", // 元动作唯一标识
"type": "pick | place | insert | align", // 动作类型
"params": { // 类型特定参数
"position": { "x": 0, "y": 0, "z": 0 },
"orientation": { "roll": 0, "pitch": 0, "yaw": 0 },
"velocity": 0.5,
"force": 10
},
"preconditions": [...], // 前置条件列表
"effects": [...] // 后置效果列表
}程序包格式
程序包（Program Package）是工艺设计层与现场执行层之间的传输单元，包含以下组成部分：
元动作序列
工艺参数
机器人配置
资源引用
版本信息
部署架构
工艺设计层
PostgreSQL
元数据存储
Redis
缓存与会话
MinIO
文件存储
现场执行层
Docker
容器化部署
gRPC/HTTP
通信协议
NVIDIA GPU
边缘推理加速
SECTION 07
L1-L2 工艺设计层详细方案
工艺设计层（Process Design Workstation）详细开发方案，面向笔记本/PAD平板/云端Web的零代码工艺编辑工具。
一、总体设计
1.1 设计目标
| 目标 | 说明 | 验收标准 |
|---|---|---|
| 零代码 | 客户技术人员无需编程即可维护工艺 | 拖拽完成流程变更，无需写代码 |
| 10-30分钟 | 成熟设备参数调整时间 | 从打开工具到导出程序包 ≤ 30分钟 |
| 可视化 | 所见即所得的状态树编辑 | 流程可视化率100% |
| 离线可用 | 导出程序包后可断网运行 | 程序包ZIP格式，现场导入即用 |
| 仿真验证 | 数字孪生验证，避免现场调试风险 | 碰撞检测覆盖率>95% |
1.2 核心功能模块
┌──────────────────────────────────────────────────────────────────────┐
│ 工艺设计层 — Process Design Workstation │
├──────────────┬─────────────────┬─────────────────┬──────────────────┤
│ │ │ │ │
│ Skill │ Editor │ Params │ Package │
│ 模板库 │ 状态树编辑器 │ 参数配置面板 │ 程序包管理 │
│ │ │ │ │
│ • 浏览模板 │ • 拖拽编辑 │ • 位姿参数 │ • 打包导出 │
│ • 导入导出 │ • 节点配置 │ • 速度/加速度 │ • 版本标记 │
│ • 版本管理 │ • 连线逻辑 │ • 温度/时间 │ • 导入现场 │
│ • 分类筛选 │ • 验证检查 │ • IO配置 │ • 反向同步 │
│ │ │ │ │
└──────────────┴─────────────────┴─────────────────┴──────────────────┘
│
▼
┌──────────────────┐
│ 仿真验证引擎 │
│ • 数字孪生 │
│ • 碰撞检测 │
│ • 节拍预估 │
└──────────┬─────────┘
│
▼
┌──────────────────┐
│ 程序包导出 │
│ JSON + ZIP格式 │
└──────────────────┘二、技术栈方案
技术选型总览
| 层级 | 技术选型 | 用途 |
|---|---|---|
| 前端框架 | React 18 + TypeScript | UI组件、状态管理 |
| 流程编辑器 | ReactFlow 12.x | 状态树可视化编辑 |
| 状态管理 | Zustand 4.x | 全局状态 |
| 样式方案 | Tailwind CSS + shadcn/ui | UI组件 |
| 后端框架 | NestJS 10.x | API服务 |
| 数据库 | PostgreSQL 15.x | 数据持久化 |
| 缓存 | Redis 7.x | 会话、缓存 |
| 容器化 | Docker | 部署隔离 |
三、UI/UE 设计方案
设计原则
| 原则 | 说明 | 具体体现 |
|---|---|---|
| 工业感 | 深色背景+高对比度，适合工厂环境 | 深色主题、高对比度文字 |
| 直觉化 | 操作符合工程师思维习惯 | 拖拽编辑、右键菜单 |
| 容错性 | 防误触、可撤销 | 操作确认、撤销栈、自动保存 |
| 响应式 | 笔记本/PAD/云端自适应 | 断点适配、触控优化 |
界面布局
┌──────────────────────────────────────────────────────────────────────┐
│ [Logo] 工艺设计工作站 [用户] [设置] [导出] │
├────────────┬───────────────────────────────────────────────────────────┤
│ │ │
│ Skill │ 状态树编辑器 (主区域) │
│ 模板库 │ │
│ │ ┌─────┐ ┌─────┐ ┌─────┐ │
│ ○ 光模块 │ │开始 │ ──→ │ 吸取 │ ──→ │ 检测 │ │
│ ○ 路由器 │ └──┬──┘ └──┬──┘ └──┬──┘ │
│ ○ CNC │ └────────────┴────────────┘ │
│ │ │ │
│ ┌────────┐│ ┌────┴────┐ │
│ │ 工具箱 ││ │ OK/NG │ │
│ │ ● 开始 ││ └────┬────┘ │
│ │ ● 吸取 ││ │ │
│ │ ● 放置 ││ ┌─────────────────────────────────────────────────────┐│
│ │ ● 检测 ││ │ 参数配置面板 ││
│ └────────┘│ │ 节点: 吸取 │ 位姿: X:350 Y:120 Z:180 ││
│ │ │ 速度: 50% │ IO: Q0.0 (夹爪) ││
│ │ └─────────────────────────────────────────────────────┘│
├────────────┴───────────────────────────────────────────────────────────┤
│ [状态栏] 当前项目: xxx │ [仿真] [导出程序包] │
└──────────────────────────────────────────────────────────────────────┘四、仿真方案
💡 技术选型倾向：后端仿真
采用后端仿真方案，任务执行结果回传前端展示。避免前端WebGL实现的复杂性和兼容性问题。
仿真方案对比
| 维度 | 后端仿真（推荐） | 前端仿真（不推荐） |
|---|---|---|
| 技术方案 | ROS/rviz 或类似仿真环境 | WebGL / Three.js |
| 兼容性 | ✅ 好 | ❌ 多浏览器兼容挑战 |
| 实现复杂度 | ✅ 中等 | ❌ 高（机械臂+车体联动） |
| 前端负载 | ✅ 轻量 | ❌ 重 |
| 扩展性 | ✅ 易扩展 | ❌ 受限 |
仿真架构
┌─────────────────┐ ┌─────────────────┐
│ 前端（轻量） │ │ 后端仿真环境 │
│ │ │ │
│ • 状态树编辑 │ 触发 │ • ROS/rviz │
│ • 结果回放 │ ────→ │ • 物理仿真 │
│ • 可视化展示 │ ←──── │ • 碰撞检测 │
│ │ 结果 │ • 轨迹渲染 │
└─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐
│ 仿真结果回传 │
│ • 图片/视频 │
│ • 时间戳状态帧 │
└─────────────────┘仿真类型
| 类型 | 功能 | 技术方案 |
|---|---|---|
| 逻辑仿真 | 验证状态流转正确性 | 基于状态机的虚拟执行 |
| 运动仿真 | 验证机械臂运动轨迹 | ROS/rviz 正运动学 |
| 碰撞检测 | 检测干涉和碰撞 | 仿真环境内置碰撞体计算 |
五、数据模型设计
核心实体关系
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ User │ │ Project │ │ Skill │
│ (用户) │────▶│ (项目) │◀────│ (模板) │
└─────────────┘ └──────┬──────┘ └─────────────┘
│
▼
┌─────────────┐
│ StateTree │
│ (状态树) │
└──────┬──────┘
│
▼
┌─────────────┐ ┌─────────────┐
│ Package │────▶│ SyncPackage│
│ (程序包) │ │ (同步包) │
└─────────────┘ └─────────────┘六、API 接口设计
API 概览
| 模块 | 主要功能 |
|---|---|
| Skill 模板 | 模板CRUD、分类筛选 |
| 状态树 | 状态树CRUD、验证、导出程序包 |
| 程序包 | 版本管理、MD5校验 |
| 用户认证 | JWT认证、权限管理 |
七、开发实施计划
里程碑规划
| 阶段 | 周期 | 交付物 |
|---|---|---|
| Sprint 1-2 | Week 1-4 | 项目脚手架 + 状态树编辑器基础 |
| Sprint 3-4 | Week 5-8 | 参数配置面板 + Skill模板库 |
| Sprint 5-6 | Week 9-12 | 仿真系统 + 程序包管理 |
| Sprint 7-8 | Week 13-16 | 后端API + 数据库 + 集成测试 |
SECTION 08
开发计划
基于 A+B 混合融合架构，分阶段推进。
Phase 1
已完成
三步验证完成
- 步骤一：离线代码生成与执行
- 步骤二：驱动单一实体外设
- 步骤三：多设备协同任务（物料搬运）
✅ 已验证
Phase 2
进行中
A+B 融合架构落地
- 云端协同方案（MD5校验+审核）
- 流程图编辑器技术选型
- 后端仿真方案确定
⏳ 进行中
Phase 3
筹备中
现场验证
- 真实场景验证
- 云端部署
- 性能调优
📋 筹备中
SECTION 09
风险与对策
识别项目潜在风险，制定应对策略，确保项目顺利推进。
风险汇总
| 风险项 | 类别 | 概率 | 影响 | 应对策略 |
|---|---|---|---|---|
| A+B融合架构接口设计 | 融合 | 中 | 高 | 明确定义层间接口协议，先试点后推广 |
| 后端仿真技术选型 | 技术 | 中 | 中 | ROS/rviz方案可行性评估 |
| GraspNet 推理性能不足 | 技术 | 中 | 高 | 边缘 GPU 加速、模型量化优化 |
| 异构设备兼容性问题 | 技术 | 中 | 中 | 抽象层隔离、充分测试覆盖 |
| 离线运行数据同步 | 进度 | 低 | 中 | 程序包版本管理、MD5校验机制 |
| 机械臂与相机协同控制 | 集成 | 中 | 中 | 标准化接口、充分联调测试 |
| 客户需求变更 | 进度 | 低 | 高 | 模块化设计、灵活配置 |
SECTION 10
结论与下一步行动
总结当前进展，明确后续发展方向。
✅ 已完成验证
✓
双层架构技术方案设计（v4.0）
✓
Aubo i5 机械臂 SDK 集成
✓
Orbbec 深度相机集成
✓
两种控制方案实现（UI/自然语言）
✓
100% 命令执行成功率验证
✓
Qclaw 间接控制远程部署（WebSocket + JSON-RPC 2.0）
✓
任务 V2 格式规范化
✓
jzt-arm-task Skill 封装
✓
Modbus 全协议外设扩展支持
✓
三步验证：离线代码→单一外设→多设备协同
✓
A+B 混合融合架构方案确定
🔄 持续推进
→
GraspNet 抓取姿态预测集成
→
WAM 力控装配方案完善
→
现场离线运行测试
→
反向同步机制优化
→
Qclaw Skill 与机械臂运动集成
→
方案B的 Skill 化封装
📋 下一步行动
| 优先级 | 行动项 | 负责人 | 截止日期 |
|---|---|---|---|
| P0 | Phase 2 模型集成启动 | 算法团队 | 待定 |
| P1 | 方案A生产环境部署准备 | 开发团队 | 待定 |
| P2 | 方案B Skill 化开发 | AI 团队 | 待定 |
| P2 | 客户演示场景准备 | 产品团队 | 待定 |
🔥 融合战略
战略方向：A+B 混合融合架构
采用混合架构：上层任务调度与分解使用B方案（利用其优秀的任务理解与规划能力），下层具体动作执行采用A方案（利用其稳定、高效的框架化代码生成）。
B方案层
🔮 任务理解与规划
大模型原生能力
- 自然语言理解
- 任务分解与调度
- 结果分发
⬇ 调用 ⬇
A方案层
🏗️ 框架化代码执行
标准化、可控执行
- API规范约束
- 逻辑与参数分离
- 审核机制保障
📌 融合价值
- 类比 Kimi 等智能体：负责发现任务、调度、分发结果，但不直接处理底层控制
- 具体执行由标准化框架完成：提供API规范约束，确保执行稳定性
- 开发更简单：兼顾灵活性与可靠性，为智能调度预留入口
A方案优势
- 边界清晰，生成效率高
- 逻辑与参数分离，易于审核
- 便于对接不同外设
B方案优势
- 自然语言理解能力强
- 任务分解与规划出色
- 灵活应对变化场景
方案B踩坑经验（精简）
| 问题类型 | 描述 | 应对策略 |
|---|---|---|
| 上下文处理 | 每次需重新读取大量历史信息，响应慢 | 分层架构减少上下文依赖 |
| 推倒重来 | 细微改动可能导致整个任务链重新生成 | 框架化约束减少变化范围 |
| Skill封装臃肿 | 每个动作都需封装为Skill，新增外设需封装更多Skill | A方案统一API规范简化对接 |
| 泛化能力有限 | 对未见过或稍有变化的指令，可能无法有效组合现有Skill | 融合架构保留B方案理解能力 |
❓ 待明确问题
| 问题 | 优先级 |
|---|---|
| 流程图编辑器的具体技术选型（不推荐Mermaid，需考察阿里类似产品） | P0 |
| 后端仿真方案的技术路径确定（倾向ROS/rviz） | P1 |
| 云端协同中，数据同步与校验机制的具体实现细节 | P1 |
| A+B层间接口协议设计 | P2 |