同步KDL工程源码到云仓库

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

@@ -0,0 +1,530 @@
+# 通用机器人项目主要实施步骤
+
+版本：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` 下的实施文档。