# agentclaw-nl-control **Repository Path**: cawyx/agentclaw-nl-control ## Basic Information - **Project Name**: agentclaw-nl-control - **Description**: 用一句中文让机械臂干活——系统自动完成"解译 → 风险判定 → 安全确认 → 执行 → 全程审计",在 Gazebo 仿真环境全链路可用。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-10 - **Last Updated**: 2026-10-22 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # AgentClaw 自然语言控制与安全确认系统 用一句中文(如「把三个物料放到各自的托盘上」)驱动 myCobot 280 机械臂在 Gazebo 仿真中完成三色物料分拣。 大模型负责理解意图,系统负责安全:风险分级(L1~L4)、高风险强制人工确认、全过程审计留痕。 --- ## 1. 项目是什么(3 行以内) 1. 前端输入一句自然语言,大模型(OpenAI 兼容接口)把它解析成结构化动作指令; 2. 指令经风险分级——L1/L2 自动执行、L3 弹窗人工确认、L4 直接拒绝——后由 MoveIt2 驱动 Gazebo 里的机械臂分拣; 3. 每一步(解译、判定、确认、执行)全部落审计库,可在界面回看全中文时间线。 --- ## 2. 环境与版本 | 组件 | 要求 | 实测版本 | |---|---|---| | OS | Windows 10/11 + WSL2 | Windows 11 | | Docker Desktop | 4.x(WSL2 后端) | — | | ROS 2 | **Lyrical**(只存在于容器内,宿主机不装) | Lyrical | | Gazebo / MoveIt2 | gz-sim + MoveIt2 + Pilz 规划器(容器镜像内自带) | — | | Python | **3.10 ~ 3.13**(依赖是按 CPython 小版本分的预编译 wheel,**3.14 装不上**) | 3.12.10 | | Node.js | 18+ | 22.22 | | MySQL | 8.0.16+(本机安装或 Docker,二选一,见启动步骤 3) | 8.0.46 | | 固件/机器人 | myCobot 280(仿真用官方 mycobot_ros2 的 Lyrical 变体;真机本轮未实现) | — | 依赖清单:后端 `backend/requirements.txt`(21 个包)、前端 `frontend/package.json`。 数据库增量结构:`migrations/0001~0011`(**必须执行**,见启动步骤 4)。 --- ## 3. 如何启动(从零开始,逐条命令) > 以下命令除标注「WSL 终端」外都在 **Windows PowerShell** 执行。 > 项目根目录 = 下面的 `agentclaw-nl-control`。 ### 第 1 步 · 拿到代码 ```powershell git clone <仓库地址> agentclaw-nl-control cd agentclaw-nl-control ``` ### 第 2 步 · 装仿真容器(一次性,约 30 分钟) 机械臂仿真跑在 Docker 容器 `manipulation` 里,容器来自官方 mycobot_ros2 镜像构建: ```powershell # 2.1 安装 Docker Desktop(WSL2 后端),确认能用: docker run --rm hello-world ``` ```bash # 2.2 切到 WSL 终端,拉取官方仿真代码并构建镜像(首次 10~30 分钟) git clone https://github.com/elephantrobotics/mycobot_ros2.git ~/mycobot_ros2 cd ~/mycobot_ros2/docker bash build.sh docker compose up -d manipulation ``` > 卡在 `docker pull` → 镜像加速器没生效,见《Docker 仿真环境搭建全流程.md》§1.4。 > 更多构建细节与报错排查都在那份文档,日常使用不需要再翻它。 ### 第 3 步 · 起数据库(二选一) **硬原则:后端和数据库要跑在同一个地方**——后端在 Windows 本机就配本机 MySQL(直连 1~5ms); 后端在容器里才用 Docker 的 MySQL。跨着连每次查询约 1 秒,还会偶发 500。 **方式 A · 本机 MySQL(当前开发方式,推荐)**——先建库和专用账号(一次性): ```sql CREATE DATABASE IF NOT EXISTS agentclaw CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci; CREATE USER IF NOT EXISTS 'agentclaw'@'localhost' IDENTIFIED BY 'agentclaw123'; CREATE USER IF NOT EXISTS 'agentclaw'@'127.0.0.1' IDENTIFIED BY 'agentclaw123'; GRANT ALL PRIVILEGES ON agentclaw.* TO 'agentclaw'@'localhost'; GRANT ALL PRIVILEGES ON agentclaw.* TO 'agentclaw'@'127.0.0.1'; FLUSH PRIVILEGES; ``` **方式 B · Docker MySQL**: ```powershell docker compose up -d # 起项目根的 agentclaw-mysql(端口 13307) docker compose ps # 等 STATUS 变 healthy ``` ### 第 4 步 · 建表 + 迁移 + 配置后端 ```powershell # 4.1 后端依赖 cd backend python -m venv .venv .venv\Scripts\pip install -r requirements.txt cd .. # 4.2 配置文件(仅第一次) copy backend\.env.example backend\.env # 打开 backend\.env,把 DATABASE_URL 改成与第 3 步一致: # 方式 A(本机)→ mysql+pymysql://agentclaw:agentclaw123@127.0.0.1:3306/agentclaw?charset=utf8mb4 # 方式 B(Docker)→ mysql+pymysql://root:agentclaw123@127.0.0.1:13307/agentclaw?charset=utf8mb4 # LLM_API_KEY 留空也能跑(自动降级本地规则解析);要大模型解译就填 Key。 # 4.3 建表 + 执行全部迁移(0001~0011,缺了会报「动作/点位不存在」) powershell -ExecutionPolicy Bypass -File scripts\init-db.ps1 -User root -Password <你的root密码> # 方式 A(本机库、agentclaw 账号):-User agentclaw -Password agentclaw123 ``` > ⚠️ 迁移必须执行:`batch_sort` 动作、三色点位、物料原位点(home_red 等)都在里面。 > 只跑 schema 不跑迁移的现象是「指令解析通过,执行时报动作/点位不存在」。 > 方式 B 注意:compose 自动建的表不含迁移,起库后同样要跑 4.3。 ### 第 5 步 · 前端依赖 ```powershell cd frontend npm install cd .. ``` ### 第 6 步 · 仿真文件同步进容器(一次性) ```powershell # 容器内的 /root/agentclaw 是复制进去的(不是挂载), # 容器重建后必须重新同步,否则仿真里没有物料/脚本 powershell -ExecutionPolicy Bypass -File scripts\sync-sim.ps1 ``` ### 第 7 步 · 启动(分 5 小步,**严格按顺序**) > 顺序的原因:仿真就绪后才能起 move_group;桥接就绪后才能起后端 > (后端先起会在 2 秒内连不上桥接,自动降级成内置仿真,表现为"机械臂不动")。 **7.1 启动容器 + 仿真**(约 75 秒): ```powershell docker start manipulation docker exec -d -e DISPLAY=:0 -e XAUTHORITY=/tmp/.Xauthority manipulation bash -lc "AGENTCLAW_VIEW=rviz AGENTCLAW_CAMERA=1 bash /root/agentclaw/start_sim.sh > /tmp/agentclaw_sim/boot.log 2>&1" ``` 等 75 秒后确认控制器就绪(应看到 3 行都是 `active`): ```powershell docker exec manipulation bash -lc "source /opt/ros/lyrical/setup.bash; timeout 6 ros2 control list_controllers 2>/dev/null" ``` **7.2 启动 move_group(MoveIt2 规划)**,等 25 秒: ```powershell docker exec -d manipulation bash -lc "source /opt/ros/lyrical/setup.bash; source /root/ros2_ws/install/setup.bash; cd /root/agentclaw; nohup python3 tools/run_launch.py agentclaw_move_group.launch.py > /tmp/agentclaw_sim/move_group.log 2>&1 &" ``` 确认(输出应含 `move_action`): ```powershell docker exec manipulation bash -lc "source /opt/ros/lyrical/setup.bash; timeout 5 ros2 action list 2>/dev/null" | findstr move_action ``` **7.3 启动桥接**: ```powershell powershell -ExecutionPolicy Bypass -File scripts\start-bridge.ps1 ``` 预期日志依次出现:`server listening on 127.0.0.1:9002` → `容器侧节点就绪` → `容器侧节点预热完成`。 **7.4 启动前端**(另开一个终端): ```powershell powershell -ExecutionPolicy Bypass -File scripts\start-frontend.ps1 ``` **7.5 启动后端**(**最后启动**,窗口不要关): ```powershell powershell -ExecutionPolicy Bypass -File scripts\start-backend.ps1 ``` 确认:设备状态页的通道应显示 `external_sim`(若显示内置仿真 = 桥接没就绪, 等桥接日志出现"预热完成"后在设备页点一次「外接仿真」)。 ### 第 8 步 · 验证 - 浏览器打开 `http://localhost:5173`,登录 **admin / admin123** - 后端接口文档:`http://127.0.0.1:8000/docs`;健康检查:`http://127.0.0.1:8000/api/health` ### 停止 ```powershell docker stop manipulation # 仿真容器(内含 Gazebo/RViz/MoveIt 全部进程) # 前后端与桥接:结束对应的 python / node 进程,或直接关掉它们的终端窗口 ``` --- ## 4. 核心目录说明(哪个文件管什么) ``` backend/ ├─ app/services/nlu.py 自然语言→结构化指令(LLM 优先,本地规则兜底) ├─ app/services/llm_client.py 大模型调用与 prompt(场景实时位姿注入、动作/点位 enum 约束) ├─ app/services/executor.py 把动作指令展开为执行步骤并驱动设备(batch_sort 编排在这) ├─ app/services/risk.py 风险引擎(L1 自动 / L3 人工确认 / L4 拒绝) ├─ app/services/confirm.py 高风险确认门(令牌、30 秒倒计时、超时作废) ├─ app/services/authorization.py 会话级授权(豁免 L3 确认门) ├─ app/services/audit.py 审计写入(全操作留痕) ├─ app/device/external_sim.py 外接仿真通道(WebSocket → 桥接 → 容器节点) ├─ app/api/routes/ REST 接口(auth/commands/device/users/audit/risk/authorizations) └─ dev_tools/ 开发验证脚本(权限矩阵、LLM 调试、端到端分拣测试) frontend/src/ ├─ views/Console.vue 指令控制台(输入、确认弹窗、时间线入口) ├─ views/Device.vue 设备状态(姿态回读、通道状态) ├─ views/Waypoints.vue 点位管理(关节角/坐标分列显示、别名编辑) ├─ views/Audit.vue / Users.vue / Risks.vue / Authorizations.vue 审计/用户/风险规则/授权管理 ├─ components/CommandTimeline.vue 指令时间线(全中文摘要,点条目看数据详情) └─ utils/auditSummary.js 审计可读性派生(事件/动作/通道全部中文化) sim/agentclaw/ ├─ agentclaw_sim_node.py 仿真执行节点:高层 op → MoveIt2 关节目标;sort_object 门型分拣、 │ 吸附(attach/detach)、位置防呆、托盘占位拒绝都在这层 ├─ ros_sim_bridge.py 宿主侧桥接:后端 WebSocket ↔ 容器内节点(stdin/stdout) ├─ world/ Gazebo 场景:静态托盘 + 运行时创建的三色物料 SDF(含吸附插件) ├─ world_markers.py RViz 场景可视化(物料位姿 20Hz 跟随真值) ├─ tools/solve_waypoints.py IK 标定工具(改点位位置后用它重解关节角) └─ tools/check_objects.py 查看三个物料的实时位置与标定偏差 scripts/ ├─ reset-scene.ps1 场景复位(重启仿真,物料回地面原位;桥接/后端不用动) ├─ init-db.ps1 建表 + 全部迁移(字节级处理,中文数据不损坏) ├─ sync-sim.ps1 仓库文件同步进容器(新机器/容器重建后必做) └─ start-bridge.ps1 / start-backend.ps1 / start-frontend.ps1 单独启动某一件 migrations/0001~0011.sql 数据库增量(三色点位、物料原位点、batch_sort 动作等) schema.sql 初始建表 + 种子数据(admin 账号) ``` --- ## 5. 已知问题(如实列出) 1. **蓝料平移段无法姿态锁定**:并排布局下蓝料(y=+100)的抓取与放料构型分属两支 (肘部 J3 +94° vs +129°),LIN 姿态锁定平移无解,该段退化为 PTP 换姿态, 肉眼可见腕部换向。红、绿全程姿态稳定。 2. **夹爪闭合有轻微视觉穿模**:闭爪是位置控制(固定角度),指板可能轻微陷入物料; 分拣靠 attach 焊接完成,不影响抓取与落点精度(实测 1~6mm)。 3. **绿料原位偏离正前方** `(0.16, 0.05)`:正前方 (0.15, 0) 的 IK 构型贴关节限位, 反向放料落点偏 60mm,故挪至现位置(分拣/归位均实测 ≤1mm)。 4. **内置仿真通道(sim)坐标为模拟值**:仅用于无 Docker 环境走完整业务流程, 不反映真实机械臂行为。 5. **确认令牌 30 秒有效**:超时后指令作废,需重新提交(前端有对应提示)。 6. **视觉识别未实现**:物料位姿来自 Gazebo 真值(场景快照),不是相机识别。 7. **跨色放置未实现**:「把蓝料放到红托盘」会按物料自身托盘处理 (需每色×每托盘共 12 组放料点位标定,见《仿真重构方案》)。 8. **真机通道未实现**:`real` 通道接口与 `MYCOBOT_*` 配置已预留,适配器未经真机验证。 --- ## 6. 演示入口(从哪个脚本 / 哪个按钮开始跑) **启动**(环境已就绪后,每次演示): ```powershell powershell -ExecutionPolicy Bypass -File scripts\reset-scene.ps1 # 物料回地面原位(推荐演示前执行,含重启仿真) ``` 仿真、桥接、后端、前端的启动按「3. 如何启动」**第 7 步**的 5 个小步逐个执行 (7.1 容器+仿真 → 7.2 move_group → 7.3 桥接 → 7.4 前端 → 7.5 后端)。 **演示动作**: 1. 浏览器 `http://localhost:5173`,登录 `admin / admin123` 2. 指令控制台输入:**把三个物料放到各自的托盘上** → 回车 3. L3 确认弹窗(显示当前确认人角色与要求)→ 点「批准并执行」 4. 机械臂连续分拣:红料→红托盘 → 不回零位 → 绿料→绿托盘 → 蓝料→蓝托盘 → **最后回零位**,全程约 2.5 分钟 5. 审计查询页 / 指令时间线回看全程(全中文) **其他可演示的指令**: | 说法 | 效果 | |---|---| | 把红色物料放到红托盘 | 单件分拣 | | 把绿色物料放回原位 | 从托盘抓起放回地面标定位(反向路径)| | 查询设备状态 / 回到初始位 | 基础动作 | | 把蓝色物料放到红托盘 | 当前会按蓝料自身托盘处理(跨色未实现,见已知问题 7)| **内置防呆(触发即给出中文理由,演示时是有价值的看点)**: - 物料已在托盘上重复下指令 → 幂等返回「已完成」 - 物料被挪离标定位 >20mm → 拒绝抓取,提示先复位场景 - 目标托盘已有别的物料 → 拒绝并说明被谁占用 - 越权 / 超限坐标指令 → L4 直接拒绝并留痕