KDL_WORK/work/doc/通用机器人项目主要实施步骤.md

通用机器人项目主要实施步骤

版本：0.1
日期：2026-06-27
来源：/home/meswork/kdl_work/work/working1
用途：作为阅读参考，概览项目从 KDL WASM 计算接口到 GRL 编译与后处理的主要实施步骤。

1. 实施主线

项目实施分两条主线推进：

1. KDL WASM 计算接口线

   • 任务编号：KW-001 到 KW-013
   • 对标：KDL_WASM计算接口设计.md
   • 目标：提供稳定的 Worker API、机器人模型、运动学、轨迹规划、Path 验证、诊断和性能能力。

2. GRL 编程语法线

   • 任务编号：KW-100 到 KW-112
   • 对标：通用机器人编程语法规范.md
   • 目标：实现 GRL lexer/parser、AST、语义检查、IR、Path/Operation、IO/wait、后处理和自动生成。

两条线的集成点是：GRL 的 movej/movel/movec/path/operation 编译为 KDL WASM 的 MoveJRequest/MoveLRequest/MoveCRequest/PathPlanRequest，由 KDL WASM 返回轨迹和诊断。

2. 推荐工程结构

/home/meswork/kdl_work/
  orocos_kinematics_dynamics/
    orocos_kdl/
  kdl-wasm/
    CMakeLists.txt
    bindings/
      kdl_c_api.cpp
      kdl_embind.cpp
    web/
      src/
        kdl/
          kdlClient.ts
          kdl.worker.ts
          rpc.ts
          types.ts
        robot/
          urdfParser.ts
          normalizedRobotModel.ts
        grl/
          lexer/
          parser/
          ast/
          semantic/
          ir/
          generator/
        post/
          abb/
          fanuc/
          kuka/
      tests/
        kdl/
        grl/
        integration/
        post/

3. 阶段 1：基础工程、Worker RPC 和 GRL 词法骨架

关联任务：KW-001、KW-100、KW-101

目标：

1. 建立 kdl-wasm wrapper 工程。
2. 使用 Emscripten 编译 Orocos KDL，生成 kdl.js、kdl.wasm、kdl.d.ts。
3. 建立 KdlRpcRequest/KdlRpcResponse 和 KdlWorkerClient。
4. KDL WASM 只在 Worker 中运行。
5. 建立 GRL lexer，支持注释、标识符、字符串、数字、单位和保留关键字。
6. 建立 GRL parser 和 AST 骨架，支持 language grl 0.1、module、import、顶层声明。

输入：

1. Orocos KDL 源码。
2. GRL 源文件。

输出：

1. KDL WASM 构建产物。
2. Worker RPC 基础 API。
3. GRL Tokens 和 AST。

验收重点：

1. init() 返回 KdlRuntimeInfo。
2. Worker 请求有唯一 id。
3. 错误返回 { code, message, diagnostics }。
4. GRL 最小文件可解析。
5. AST 保留 source range、注释位置、单位原文和规范化值。

4. 阶段 2：机器人模型、GRL 数据声明和共享类型

关联任务：KW-002、KW-102

目标：

1. TypeScript 解析 URDF XML。
2. 检查 link/joint 连通性和单位。
3. 生成 NormalizedRobotModel。
4. WASM 根据标准模型构造 KDL Tree/Chain。
5. 创建 RobotHandle 并缓存求解器。
6. GRL 支持 const/var/persistent、基础类型、机器人类型。
7. GRL 支持 tool/frame/load/joint_target/pose_target/pose/poseq/robot_config/ext_axis/speed/zone/offset/offset_in。

输入：

1. robot.urdf
2. GRL 中的 tool/frame/target/speed/zone 声明。

输出：

1. NormalizedRobotModel
2. RobotHandle
3. JointTarget
4. PoseTarget
5. SpeedSpec
6. ZoneSpec
7. OffsetSpec

验收重点：

1. URDF joint 顺序稳定。
2. base/tip 不连通返回 KDL_INVALID_MODEL。
3. getRobotInfo/getJointLimits 正确。
4. GRL target 能编译为 KDL 共享数据结构。
5. speed/zone 能编译为 SpeedSpec/ZoneSpec。

5. 阶段 3：KDL 基础运动学和 GRL 运动指令

关联任务：KW-003 到 KW-006、KW-103

目标：

1. 实现 KDL fk、fkAllLinks。
2. 实现 KDL ik、ikBatch。
3. 实现 KDL jacobian、checkSingularity、checkJointLimits、checkReachability、checkReachabilityBatch、checkVelocityLimits。
4. 实现 KDL normalizePose、composePose、inversePose、applyToolAndFrame、applyOffset。
5. GRL 支持 movej/movel/movec 和 set_tool/set_frame/set_speed/set_zone。
6. GRL 运动指令编译为 MotionInstruction，再映射为 KDL request。

输入：

1. RobotHandle
2. JointTarget
3. PoseTarget
4. tool/frame/speed/zone
5. GRL 运动语句。

输出：

1. FK/TCP 位姿。
2. IK 关节解。
3. Jacobian 和奇异性诊断。
4. MotionInstruction
5. MoveJRequest/MoveLRequest/MoveCRequest

验收重点：

1. FK 与 golden 数据或原生 KDL 对比在容差内。
2. IK 后 FK 回代误差小于容差。
3. ikBatch 返回顺序与输入顺序一致。
4. 奇异点返回 KDL_SINGULARITY warning。
5. offset、offset_in tool、offset_in frame 结果正确。
6. GRL 编译到 IR 前能解析确定的 tool、frame、speed、zone。

6. 阶段 4：梯形速度和三类基础运动轨迹

关联任务：KW-007 到 KW-010

目标：

1. 实现 makeTrapProfile 和 sampleTrapProfile。
2. 实现 planMoveJ。
3. 实现 planMoveL。
4. 实现 planMoveC。

MOVEJ 重点：

1. joint_target 直接作为 qEnd。
2. pose_target 先 IK 得到 qEnd。
3. 各关节同起同停。
4. 每个采样点 FK 输出 TCP。

MOVEL 重点：

1. 起点由 startJoints FK 得到。
2. 目标点应用 tool/frame/offset。
3. 生成 TCP 直线采样。
4. 逐点 IK，seed 使用上一采样点关节。

MOVEC 重点：

1. 起点由当前关节 FK 得到。
2. via 和 target 应用 tool/frame/offset。
3. 检查三点重合或近似共线。
4. 计算圆心、半径、法向、角度、弧长。
5. TrajectoryResult.meta.circle 包含 CirclePlanMeta。

输入：

1. MoveJRequest
2. MoveLRequest
3. MoveCRequest
4. TrapProfileOptions

输出：

1. TrapProfileResult
2. TrajectoryResult
3. MotionDiagnostic

验收重点：

1. 梯形速度曲线长距离为 trapezoid，短距离为 triangle。
2. 采样首点 s=0，末点 s=1，s 单调递增。
3. MOVEJ 关节同起同停。
4. MOVEL TCP 直线误差小于容差。
5. MOVEC 圆弧元数据正确。
6. 三点共线返回 KDL_ARC_DEGENERATE。
7. P0 中非 fine zone 返回 KDL_ZONE_APPROXIMATED。

7. 阶段 5：Path、Operation 和批量路径验证

关联任务：KW-011、KW-104、KW-105

目标：

1. GRL 支持 path/defaults/source/point/event/run_path。
2. GRL 支持 operation/kind/path/process/start_action/end_action/run_operation。
3. Path 编译为 PathPlanRequest。
4. Operation 展开为 start action + path + end action。
5. KDL 实现 planPath 和 validatePath。

输入：

1. GRL Path。
2. GRL Operation。
3. MotionSegmentRequest[]
4. PathPlanRequest

输出：

1. PathPlanResult
2. PathValidationResult
3. Path source map。
4. Operation 展开结果。

验收重点：

1. 空 Path 报错。
2. 重复 point 名称报错。
3. run_path 可生成 PathPlanRequest。
4. planPath 按 segment 顺序规划。
5. 上一段终点关节作为下一段起点。
6. 轨迹点合并后重新编号和更新时间。
7. 保留 segmentId/targetId/sourceMap。
8. run_operation 展开后 KDL 只处理 motion segment。

8. 阶段 6：IO、wait、pulse 和流程控制

关联任务：KW-106、KW-107

目标：

1. 支持 io.di/do/ai/ao/gi/go/ri/ro。
2. 支持 io.alias.*。
3. 支持 IO 赋值。
4. 支持 wait 条件、timeout、on_timeout alarm/call。
5. 支持 all/any/rising/falling/changed。
6. 支持 pulse。
7. 支持 if/elseif/else、while、for、switch/case/default。
8. 支持 break/continue/label/jump。

输入：

1. IO map。
2. GRL IO/wait/pulse 语句。
3. GRL 流程控制语句。

输出：

1. IoInstruction
2. WaitInstruction
3. BranchInstruction
4. pulse IR。

验收重点：

1. IO 地址按 io_map 或允许范围校验。
2. wait 条件可编译。
3. pulse trace 必须包含置位和复位事件。
4. 条件表达式必须为 bool。
5. break/continue 位置合法。
6. switch case 为常量表达式且不重复。
7. jump 不能跳入非法块结构。
8. IO、wait、pulse 和流程控制不直接进入 KDL。

9. 阶段 7：proc、func、异常、报警、中断和多任务语法

关联任务：KW-108、KW-109

目标：

1. 支持 proc、func、call、return。
2. 支持参数方向 in/out/inout。
3. 实现作用域和名称解析。
4. 对递归给出 warning 或 error。
5. 支持 alarm、raise、try/catch/finally。
6. P1 语法保留 trap/interrupt/enable/disable/task cycle。

输入：

1. GRL 子程序和函数。
2. GRL 异常和中断语法。

输出：

1. CallInstruction
2. ReturnInstruction
3. AlarmInstruction
4. 异常处理 IR。
5. P1 语法 AST。

验收重点：

1. out 参数所有正常返回路径赋值。
2. inout/out 实参必须为左值。
3. func 所有正常返回路径返回兼容类型。
4. func 默认不允许执行运动、wait、pulse、run_path、run_operation。
5. P0 支持 alarm/raise/try/catch 基础语义。
6. P1 未实现语义必须在后处理或运行时报明确诊断。

10. 阶段 8：语义检查、IR、source map 和 KDL 集成

关联任务：KW-110、KW-012

目标：

1. 实现 Symbol Table。
2. 实现 Semantic Analyzer。
3. 生成 Executable IR。
4. 保留 source map。
5. 完成 GRL 到 KDL request 的编译桥接。
6. KDL 实现 estimateCycleTime 和 resampleTrajectory。
7. 建立统一诊断分级：error、warning、info。

必须检查：

1. 标识符重复或未声明。
2. 类型是否匹配。
3. 目标点类型是否适合运动指令。
4. movec 是否缺少 via 点。
5. 圆弧三点是否重合或共线。
6. 工具、坐标系、速度、过渡是否可解析。
7. 单位是否正确。
8. IO 地址是否存在。
9. 子程序参数数量和类型是否匹配。
10. out 参数是否赋值。
11. func 返回路径是否正确。
12. break/continue/jump 是否合法。
13. Path 是否为空或点名重复。
14. Operation 是否引用不存在的 Path。
15. 目标点是否可达。
16. 关节是否超限。
17. 后处理目标品牌是否支持所用语义。

输入：

1. AST。
2. Symbol Table。
3. RobotHandle。
4. KDL 检查结果。

输出：

1. Executable IR。
2. KDL request。
3. CycleTimeResult。
4. MotionDiagnostic。

验收重点：

1. 完整 GRL 示例可编译为 IR。
2. IR 运动指令可映射到 KDL request。
3. source map 能定位 GRL 行列、path point、operation。
4. estimateCycleTime 只计算运动时间。
5. resampleTrajectory 时间和点序稳定。
6. 所有错误返回结构化诊断。

11. 阶段 9：三品牌后处理原型

关联任务：KW-111

目标：

1. ABB RAPID 后处理。
2. FANUC LS/TP 风格后处理。
3. KUKA KRL 后处理。
4. 支持 post_hint 和 @brand.*。
5. 生成后处理转换报告。

输入：

1. Executable IR。
2. target/tool/frame/speed/zone 数据。
3. post profile。
4. brand metadata。

输出：

1. ABB RAPID 程序。
2. FANUC LS/TP 风格文本。
3. KUKA KRL 程序。
4. 转换报告。

验收重点：

1. movej/movel/movec 三品牌 golden file 通过。
2. target/tool/frame/speed/zone 映射正确。
3. IO/wait 基础映射正确。
4. post_hint 和 @brand.* 只影响指定品牌。
5. 不支持语义进入转换报告，不能静默丢失。

12. 阶段 10：自动生成、往返和性能优化

关联任务：KW-112、KW-013

目标：

1. 自动生成 GRL 时优先生成 target/path/operation。
2. 点名稳定。
3. path defaults 和单点 override 稳定。
4. source metadata 稳定。
5. 支持 compact/expanded 输出风格。
6. 生成 GRL 可再解析回等价对象。
7. KDL 底层导出稳定 C ABI。
8. 高频 FK/IK 增加 TypedArray 版本。
9. RobotHandle 缓存 FK、IK、Jacobian solver。
10. 长路径分块计算或提供进度。

输入：

1. 自动编程对象。
2. Path/Operation 数据。
3. KDL 批量计算输入。

输出：

1. 稳定 GRL 文本。
2. 可回读 AST/IR。
3. C ABI / Embind API。
4. TypedArray 批量接口。
5. 性能报告。

验收重点：

1. 同一输入重复生成结果一致。
2. 生成文本可 diff。
3. 生成文本可解析、语义检查并后处理。
4. 单机器人 6 轴初始化小于 1 秒。
5. 单次 FK 小于 1 ms。
6. 单次 IK 平均小于 10 ms。
7. 1000 个目标点批量可达性检查在可接受交互时间内完成。
8. 10 秒轨迹按 4 ms 采样约 2500 点可稳定生成和回放。

13. 推荐集成顺序

1. KW-001 + KW-100 + KW-101
   基础工程、Worker RPC、Lexer/Parser 骨架。

2. KW-002 + KW-102
   URDF/标准模型和 GRL target/tool/frame/speed/zone。

3. KW-003 到 KW-006 + KW-103
   运动指令编译到 KDL FK/IK/变换。

4. KW-007 到 KW-010
   梯形速度、MOVEJ、MOVEL、MOVEC。

5. KW-104 + KW-011
   Path 编译为 PathPlanRequest，KDL 生成整条路径。

6. KW-105 + KW-011
   Operation 展开后复用 Path 规划。

7. KW-106 到 KW-110
   完成 P0 语义检查和 IR。

8. KW-111
   三品牌后处理原型。

9. KW-112 + KW-013
   自动生成、往返、性能和批量优化。

14. 常用验证命令

实际命令以工程 package.json 和 CMake 配置为准。每个阶段至少应提供等效命令：

npm run typecheck
npm run test -- grl
npm run test -- kdl
npm run test -- integration
npm run test -- post
npm run build

KDL WASM 构建：

cd /home/meswork/kdl_work
emcmake cmake -S kdl-wasm -B kdl-wasm/build-wasm \
  -DCMAKE_BUILD_TYPE=Release \
  -DKDL_SOURCE_DIR=/home/meswork/kdl_work/orocos_kinematics_dynamics/orocos_kdl
cmake --build kdl-wasm/build-wasm -j16

15. 阅读建议

1. 先读本文，理解项目主要阶段和集成顺序。
2. 再读 通用机器人项目功能与数据流程图.md，理解功能流和数据流。
3. 需要接口细节时读 KDL_WASM计算接口设计.md。
4. 需要语言语法和后处理细节时读 通用机器人编程语法规范.md。
5. 需要执行级任务和证据时读 /home/meswork/kdl_work/work/working1 下的实施文档。