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

版本：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. 推荐工程结构

```text
/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. 推荐集成顺序

```text
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 配置为准。每个阶段至少应提供等效命令：

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

KDL WASM 构建：

```bash
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` 下的实施文档。