597 lines
14 KiB
Markdown
597 lines
14 KiB
Markdown
# 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
|
||
```
|