KDL_WORK/02-项目程序开发详细步骤.md

02-项目程序开发详细步骤

版本：0.3
日期：2026-06-27
对标文档：

1. /home/meswork/kdl_work/work/doc/KDL_WASM计算接口设计.md
2. /home/meswork/kdl_work/work/doc/通用机器人编程语法规范.md

1. 推荐目录

目录按两条主线组织：grl 负责语言、AST、语义、IR、后处理；kdl-wasm 负责 KDL Worker API 和运动计算。

/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/

2. KDL 实施线

KDL 实施顺序严格对标 KDL_WASM计算接口设计.md 第 24 章。

2.1 KW-001：WASM 工程骨架和 Worker RPC

目标：

1. 新建 kdl-wasm wrapper 工程。
2. 使用 Emscripten 编译 Orocos KDL。
3. 生成 kdl.js、kdl.wasm、kdl.d.ts。
4. 建立 KdlRpcRequest/KdlRpcResponse。
5. 建立 KdlWorkerClient，所有 KDL API 异步调用。

核心要求：

1. KDL 运行在 Worker 中。
2. Worker 请求必须有唯一 id。
3. Worker 初始化失败可恢复并重新初始化。
4. 错误返回结构化 { code, message, diagnostics }。

验收：

1. init() 返回 KdlRuntimeInfo。
2. dispose() 可释放 Worker。
3. Worker RPC 单元测试通过。

2.2 KW-002：NormalizedRobotModel 到 KDL Chain

目标：

1. TypeScript 解析 URDF XML。
2. 检查 link/joint 连通性和单位。
3. 生成 NormalizedRobotModel。
4. WASM 根据标准模型构造 KDL Tree/Chain。
5. 创建 RobotHandle 并缓存求解器。

必须实现：

1. loadRobotFromUrdf
2. createRobotFromModel
3. destroyRobot
4. getRobotInfo
5. getJointLimits

验收：

1. URDF joint 顺序稳定。
2. base/tip 不连通返回 KDL_INVALID_MODEL。
3. 不支持 joint 类型返回诊断。
4. 机器人信息中的 dof/jointNames/limits 正确。

2.3 KW-003：FK 和 fkAllLinks

目标：

1. 实现 fk。
2. 实现 fkAllLinks。
3. 支持 tool/frame 选项。
4. 输出法兰位姿、TCP 位姿和 link 位姿。

验收：

1. FK 与 golden 数据或原生 KDL 对比在容差内。
2. fkAllLinks link 数量和顺序正确。
3. 关节维度错误有结构化诊断。

2.4 KW-004：IK 和 ikBatch

目标：

1. 实现 ik。
2. 实现 ikBatch。
3. 支持 seed、qMin/qMax、多 seed、容差、最大迭代次数。
4. 失败原因覆盖 unreachable/joint_limit/singularity/max_iteration/invalid_model。

验收：

1. IK 后 FK 回代误差小于容差。
2. ikBatch 返回顺序与输入顺序一致。
3. 不可达目标返回 KDL_TARGET_UNREACHABLE 或 KDL_IK_FAILED。
4. 连续点 seed 使用上一点结果。

2.5 KW-005：Jacobian、奇异性和基础检查

目标：

1. 实现 jacobian。
2. 实现 checkSingularity。
3. 实现 checkJointLimits。
4. 实现 checkReachability 和 checkReachabilityBatch。
5. 实现 checkVelocityLimits。

验收：

1. Jacobian 行列数正确。
2. 奇异点附近产生 KDL_SINGULARITY warning。
3. 关节超限产生 KDL_JOINT_LIMIT。
4. 批量可达性保持输入顺序。

2.6 KW-006：位姿变换和 offset

目标：

1. 实现 normalizePose。
2. 实现 composePose。
3. 实现 inversePose。
4. 实现 applyToolAndFrame。
5. 实现 applyOffset。

验收：

1. pose() 欧拉角可规范化为四元数。
2. poseq() 四元数可归一化。
3. offset 默认在 frame 下解释。
4. offset_in tool 和 offset_in frame fixture 结果正确。

2.7 KW-007：梯形速度曲线

目标：

1. 实现 makeTrapProfile。
2. 实现 sampleTrapProfile。
3. 长距离输出 trapezoid。
4. 短距离自动退化为 triangle。

验收：

1. 首点 s=0。
2. 末点 s=1。
3. s 单调递增。
4. 所有 TrajectoryResult 保留实际速度曲线采样。

2.8 KW-008：planMoveJ

目标：

1. 对应 GRL movej。
2. target 为 joint_target 时直接得到 qEnd。
3. target 为 pose_target 时先 IK。
4. 按关节速度、加速度约束计算同步运动时长。
5. 每个采样点 FK 输出 TCP。

必须诊断：

1. 目标 IK 失败。
2. 起点或终点关节超限。
3. 采样点速度或加速度超限。
4. 接近奇异点。
5. P0 zone 被近似为 fine。

2.9 KW-009：planMoveL

目标：

1. 对应 GRL movel。
2. 起点由 startJoints FK 得到。
3. 目标点应用 tool/frame/offset。
4. 生成 TCP 直线采样。
5. 姿态使用 fixed 或 slerp。
6. 每个采样点 IK，seed 使用上一采样点关节。

必须诊断：

1. 目标不可达。
2. 采样点 IK 失败。
3. TCP 直线误差超过容差。
4. 姿态误差超过容差。
5. 关节配置突变。
6. 速度或加速度超限。

2.10 KW-010：planMoveC

目标：

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

必须诊断：

1. via 或 target 不可达。
2. 三点重合、近似重合或近似共线。
3. 半径过小或弧长过短。
4. 采样点 IK 失败。
5. 圆弧误差超过容差。
6. 速度或加速度超限。

2.11 KW-011：planPath 和 validatePath

目标：

1. planPath 用于 run_path 展开后的整条路径轨迹生成。
2. validatePath 用于离线编程路径验证。
3. run_operation 在 TypeScript 层展开，KDL 只处理 motion segment。

验收：

1. 段顺序正确。
2. 上一段终点关节作为下一段起点。
3. 合并后轨迹点重新编号和更新时间。
4. 保留 segmentId/targetId/sourceMap。
5. 空路径返回 KDL_PATH_EMPTY。

2.12 KW-012：节拍估算、重采样和诊断报告

目标：

1. 实现 estimateCycleTime。
2. 实现 resampleTrajectory。
3. KDL 只估算运动时间。
4. waitTime、ioTime 由调用方补充。

验收：

1. CycleTimeResult.motionTime/totalTime/segmentTimes 正确。
2. 重采样后轨迹时间、点序、source map 稳定。
3. error/warning/info 分级正确。

2.13 KW-013：C ABI / Embind 和性能优化

目标：

1. 底层导出稳定 C ABI。
2. TypeScript API 包装 C ABI 或 Embind。
3. 高频 FK/IK 增加 TypedArray 版本。
4. RobotHandle 缓存 FK、IK、Jacobian solver。
5. 长路径分块计算或提供进度。

性能目标：

1. 单机器人 6 轴初始化小于 1 秒。
2. 单次 FK 小于 1 ms。
3. 单次 IK 平均小于 10 ms。
4. 1000 个目标点批量可达性检查在可接受交互时间内完成。
5. 10 秒轨迹按 4 ms 采样约 2500 点可稳定生成和回放。

3. GRL 实施线

GRL 实施顺序严格对标 通用机器人编程语法规范.md 第 24 章。

3.1 KW-100：Lexer、单位和关键字

目标：

1. UTF-8 输入。
2. 识别单行、多行注释。
3. 识别标识符、字符串、数字、单位。
4. 识别保留关键字。
5. 单位规范化到 SI。

验收：

1. 100 mm -> 0.1 m。
2. 180 deg -> pi rad。
3. 300 mm/s -> 0.3 m/s。
4. 注释位置可保留。

3.2 KW-101：Parser 和 AST 骨架

目标：

1. 实现 EBNF 第 22 章主体。
2. 支持 language grl 0.1。
3. 支持 module/import/end。
4. 支持 top-level declarations。
5. AST 保留 source range、原始单位文本、规范化值和 metadata。

验收：

1. 最小文件可解析。
2. 错误行列号准确。
3. AST snapshot 稳定。

3.3 KW-102：数据声明、类型系统和目标点

目标：

1. const/var/persistent。
2. 基础类型和机器人类型。
3. tool/frame/load。
4. joint_target/pose_target。
5. pose/poseq/robot_config/ext_axis。
6. speed/zone。
7. offset/offset_in。

验收：

1. 类型 AST 正确。
2. target 能编译为 JointTarget/PoseTarget。
3. speed/zone 能编译为 SpeedSpec/ZoneSpec。
4. offset 能编译为 OffsetSpec。

3.4 KW-103：运动指令和当前上下文

目标：

1. movej
2. movel
3. movec
4. set_tool
5. set_frame
6. set_speed
7. set_zone

编译规则：

1. 显式运动参数优先。
2. path defaults 次之。
3. target 自带 tool/frame 次之。
4. 当前控制器状态最低。
5. 编译到 IR 前必须解析出确定 tool/frame/speed/zone。

验收：

1. movej 可生成 MotionInstruction(joint)。
2. movel 可生成 MotionInstruction(linear)。
3. movec 可生成 MotionInstruction(circular)。
4. movej/movel/movec 可生成 KDL request。

3.5 KW-104：Path、event 和 run_path

目标：

1. path
2. defaults
3. source
4. point
5. event before/after
6. event at ... distance
7. run_path

编译语义：

1. 展开 defaults、points、events。
2. 每个 point 变为 Motion IR。
3. event 变为 IO/Wait/Process IR。
4. 保留 pathId、pointId、source metadata。

验收：

1. 空 path 报错。
2. 重复 point 名称报错。
3. run_path 可生成 PathPlanRequest。

3.6 KW-105：Operation 和 run_operation

目标：

1. operation
2. kind
3. path
4. process
5. start_action
6. end_action
7. run_operation

编译语义：

1. 执行 start action。
2. 执行引用 path。
3. 执行 end action。
4. 保留工艺参数，供仿真、报告和后处理使用。

验收：

1. Operation 引用不存在 Path 报错。
2. run_operation 可展开为 action + path + action。
3. KDL 只接收展开后的 motion segment。

3.7 KW-106：IO、wait 和 pulse

目标：

1. io.di/do/ai/ao/gi/go/ri/ro。
2. io.alias.*。
3. IO 赋值。
4. wait 条件。
5. timeout。
6. on_timeout alarm/call。
7. all/any/rising/falling/changed。
8. pulse。

验收：

1. IO 地址可按 io_map 或允许范围校验。
2. wait 条件可编译为 WaitInstruction。
3. pulse trace 必须包含置位和复位事件。
4. IO/wait 不进入 KDL。

3.8 KW-107：流程控制

目标：

1. if/elseif/else
2. while
3. for
4. switch/case/default
5. break
6. continue
7. label
8. jump

验收：

1. 条件表达式必须为 bool。
2. break/continue 位置合法。
3. switch case 为常量表达式且不重复。
4. jump 不能跳入非法块结构。

3.9 KW-108：proc、func、参数方向和作用域

目标：

1. proc。
2. func。
3. call。
4. return。
5. in/out/inout。
6. 作用域和名称解析。
7. 递归 warning 或 error。

验收：

1. out 参数所有正常返回路径赋值。
2. inout/out 实参必须为左值。
3. func 所有正常返回路径返回兼容类型。
4. func 默认不允许执行运动、wait、pulse、run_path、run_operation。

3.10 KW-109：异常、报警、中断和多任务语法

目标：

1. alarm
2. raise
3. try/catch/finally
4. trap
5. interrupt
6. enable/disable interrupt
7. task ... cycle ...

范围：

1. P0 至少实现 alarm、raise 和简单 catch。
2. trap/interrupt/task 按 P1 语法保留，可先不做完整调度。

验收：

1. AST 能表达全部语法。
2. P0 支持 alarm/raise/try/catch 基础语义。
3. P1 未实现语义在后处理或运行时报明确诊断。

3.11 KW-110：语义检查、IR 和 source map

目标：

1. Symbol Table。
2. Semantic Analyzer。
3. Executable IR。
4. Source map。
5. GRL 到 KDL request 的编译桥接。

必须检查：

1. 语法规范第 21 章全部 22 项。
2. KDL 可达性、关节限位和圆弧退化。
3. 后处理目标品牌是否支持所用语义。

验收：

1. 完整示例可编译为 IR。
2. IR 运动指令可映射到 KDL request。
3. source map 能定位 GRL 行列、path point、operation。

3.12 KW-111：ABB、FANUC、KUKA 后处理原型

目标：

1. ABB RAPID 映射。
2. FANUC LS/TP 风格映射。
3. KUKA KRL 映射。
4. 后处理报告。
5. post_hint 和 @brand.*。

验收：

1. movej/movel/movec 三品牌 golden file 通过。
2. target/tool/frame/speed/zone 映射正确。
3. IO/wait 基础映射正确。
4. 不支持语义进入转换报告。

3.13 KW-112：自动生成规则和往返

目标：

1. 自动生成程序优先生成 target/path/operation。
2. 点名稳定。
3. path defaults 和单点 override 稳定。
4. source metadata 稳定。
5. compact/expanded 输出风格。
6. 生成 GRL 可再解析回等价对象。

验收：

1. 同一输入重复生成结果一致。
2. 生成文本可 diff。
3. 生成文本可解析、语义检查并后处理。

4. 集成顺序

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：自动生成、性能和批量优化。

5. 通用命令约定

实际命令以工程 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