整理项目文档目录

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

@@ -0,0 +1,596 @@
+# 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 和运动计算。
+
+```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/
+```
+
+## 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 配置为准。文档验收要求每个阶段至少提供等效命令：
+
+```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
+```