From fe13b081e3b481c59e268dcfdcd6130a5db4230d Mon Sep 17 00:00:00 2001 From: wangdequan Date: Sat, 27 Jun 2026 07:26:48 -0400 Subject: [PATCH] Initial working1 implementation docs --- 01-项目功能内容.md | 490 +++++++++++++++ 02-项目程序开发详细步骤.md | 596 ++++++++++++++++++ 03-推进台账.md | 1097 +++++++++++++++++++++++++++++++++ 04-任务矩阵.md | 150 +++++ 05-验收证据.md | 1169 ++++++++++++++++++++++++++++++++++++ 06-决策记录.md | 331 ++++++++++ README.md | 69 +++ 7 files changed, 3902 insertions(+) create mode 100644 01-项目功能内容.md create mode 100644 02-项目程序开发详细步骤.md create mode 100644 03-推进台账.md create mode 100644 04-任务矩阵.md create mode 100644 05-验收证据.md create mode 100644 06-决策记录.md create mode 100644 README.md diff --git a/01-项目功能内容.md b/01-项目功能内容.md new file mode 100644 index 0000000..1a4f8e7 --- /dev/null +++ b/01-项目功能内容.md @@ -0,0 +1,490 @@ +# 01-项目功能内容 + +版本：0.3 +日期：2026-06-27 +对标文档： + +1. `/home/meswork/kdl_work/work/doc/通用机器人编程语法规范.md` +2. `/home/meswork/kdl_work/work/doc/KDL_WASM计算接口设计.md` + +## 1. 项目定位 + +本目录用于把 GRL 编程语法规范和 KDL WASM 计算接口设计落成实施计划。实施目标是形成一套互相闭合的语言层和运动计算层： + +```text +GRL Source + -> Lexer / Parser + -> AST + -> Symbol Table + -> Semantic Analyzer + -> Executable IR / MotionSegmentRequest + -> KdlWorkerClient + -> KDL WASM + -> TrajectoryResult / PathValidationResult / Diagnostics +``` + +Web UI、OPFS、碰撞检测和真实控制器通信不作为独立实施主线；相关内容只在两份对标文档明确要求的 GRL 工程结构、轨迹 trace、虚拟控制器调用关系、后处理或测试场景中进入范围。 + +## 2. GRL 语言功能范围 + +### 2.1 设计目标 + +GRL 是用于离线编程和虚拟调试的通用机器人程序语言，必须满足： + +1. 支持目标点、路径、工艺、IO、等待、流程控制、报警、仿真执行、报告和后处理。 +2. 可由规划点、CAD 曲线、工艺模板或 AI 规划器自动生成程序。 +3. 可转换为 ABB RAPID、FANUC LS/TP 风格文本、KUKA KRL。 +4. 可反向导入品牌程序，恢复为统一 IR、GRL 和 OLP 对象模型。 +5. 程序文本稳定、可读、可 diff。 +6. 编译后生成统一可执行 IR，虚拟控制器不依赖品牌控制器细节。 + +### 2.2 语法必须覆盖 + +1. 文件工程结构： + - `project.json` + - `robots/*.urdf` + - `programs/*.grl` + - `targets/*.json` + - `paths/*.json` + - `operations/*.json` + - `io/io_map.json` + - `post/{abb,fanuc,kuka}.profile.json` + - `generated/{abb,fanuc,kuka}/` + - `reports/*.json` + +2. 词法： + - UTF-8。 + - 小写关键字。 + - 大小写敏感标识符。 + - `snake_case` 推荐。 + - 单行和多行注释。 + - 带单位数值。 + - 保留关键字表。 + +3. 顶层结构： + - `language grl 0.1` + - `module` + - `import` + - `persistent/const/var` + - `target` + - `path` + - `operation` + - `proc` + - `func` + - `trap` + - `task` + - `post_hint` + +4. 类型系统： + - `bool/int/real/string/time/length/angle/percent` + - `pose/joint_array/pose_target/joint_target/tool/frame/speed/zone/load/robot_config/ext_axis/path/operation` + +5. 数据声明： + - `tool` + - `frame` + - `joint_target` + - `pose_target` + - `pose` + - `poseq` + - `robot_config` + - 偏移表达式 `offset`、`offset_in` + +6. 速度和过渡： + - `joint(percent)` + - `joint(angle/s)` + - `linear(length/s)` + - `angular(angle/s)` + - 可选 `acc` + - `fine` + - `z(distance)` + - `cnt(percent)` + - `continuous` + +7. 运动指令： + - `movej TargetExpr [speed Speed] [zone Zone] [tool Tool] [frame Frame]` + - `movel TargetExpr [speed Speed] [zone Zone] [tool Tool] [frame Frame]` + - `movec via ViaTargetExpr target EndTargetExpr [speed Speed] [zone Zone] [tool Tool] [frame Frame]` + - `set_tool` + - `set_frame` + - `set_speed` + - `set_zone` + +8. Path： + - `path` + - `defaults` + - `source` + - `point` + - `event before/after/at` + - `run_path` + +9. Operation： + - `operation` + - `kind` + - `path` + - `process` + - `start_action` + - `end_action` + - `run_operation` + +10. IO 与等待： + - `io.di/do/ai/ao/gi/go/ri/ro` + - `io.alias.*` + - IO 赋值。 + - `wait` + - `timeout` + - `on_timeout alarm` + - `on_timeout call` + - `all/any/rising/falling/changed` + - `pulse` + +11. 流程控制： + - `if/elseif/else` + - `while` + - `for` + - `switch/case/default` + - `break` + - `continue` + - `label` + - `jump` + +12. 子程序和函数： + - `proc` + - `func` + - `call` + - `return` + - 参数方向 `in/out/inout` + - 作用域和名称解析。 + +13. 异常、报警和中断： + - `alarm` + - `raise` + - `try/catch/finally` + - `trap` + - `interrupt` + - `enable/disable interrupt` + +14. 多任务语法： + - `task ... cycle ...` + - 首版只定义语法，不要求完整实时调度。 + +15. 品牌扩展： + - `post_hint abb/fanuc/kuka` + - `@brand.abb` + - `@brand.fanuc` + - `@brand.kuka` + - 无法支持的品牌扩展必须进入转换报告。 + +### 2.3 GRL P0 + +按语法规范第 24 章，P0 必须实现： + +1. `language`、`module`、`proc`。 +2. `const`、`var`、`persistent`。 +3. `tool`、`frame`、`speed`、`zone`。 +4. `joint_target`、`pose_target`。 +5. `movej`、`movel`、`movec`。 +6. `path`、`point`、`event`、`run_path`。 +7. `operation`、`run_operation`。 +8. `if`、`elseif`、`else`、`while`、`for`、`switch`。 +9. `call`、`return`、`break`、`continue`。 +10. `proc` 参数方向 `in/out/inout`。 +11. `func`、函数调用表达式和返回值检查。 +12. `io.do/di`、`wait`、`pulse`。 +13. AST、语义检查、IR、source map。 +14. ABB、FANUC、KUKA 后处理原型。 + +### 2.4 GRL P1 + +按语法规范第 24 章，P1 扩展： + +1. `label/jump` 和品牌标签程序导入。 +2. `trap`、`interrupt`。 +3. 多任务 `task`。 +4. 更完整的 IO 类型。 +5. 工艺模板库。 +6. 品牌程序导入。 +7. 复杂品牌扩展和转换报告。 + +## 3. KDL WASM 功能范围 + +### 3.1 目标 + +KDL WASM 是 GRL、虚拟控制器、离线编程、路径验证和轨迹回放共用的运动学与轨迹计算内核。接口设计从 GRL 语义反推，不直接暴露 KDL C++ 类。 + +KDL WASM 负责： + +1. `joint_target`、`pose_target` 的目标点解析和可达性验证。 +2. `tool`、`frame`、`offset`、`offset_in` 的位姿变换。 +3. `movej` 关节角度差分运行。 +4. `movel` TCP 直线运行。 +5. `movec` TCP 圆弧运行。 +6. `path`、`run_path`、`operation` 的批量轨迹生成和批量诊断。 +7. 速度、加速度、zone、采样周期、节拍估算。 +8. 当前 TCP、当前关节、轨迹采样点、报警诊断。 + +KDL WASM 不负责： + +1. GRL 词法和语法解析。 +2. 程序流程控制、变量、IO、wait、子程序调用。 +3. 碰撞检测和几何布尔运算。 +4. 真实品牌控制器完整 look-ahead 和伺服细节。 +5. OPFS 项目文件管理。 + +### 3.2 顶层 TypeScript API + +必须实现 `KdlWasmApi` 中的异步接口： + +1. 生命周期： + - `init` + - `dispose` + +2. 机器人模型： + - `loadRobotFromUrdf` + - `createRobotFromModel` + - `destroyRobot` + - `getRobotInfo` + - `getJointLimits` + +3. 位姿变换： + - `normalizePose` + - `composePose` + - `inversePose` + - `applyToolAndFrame` + - `applyOffset` + +4. 运动学： + - `fk` + - `fkAllLinks` + - `jacobian` + - `ik` + - `ikBatch` + +5. 检查： + - `checkJointLimits` + - `checkVelocityLimits` + - `checkSingularity` + - `checkReachability` + - `checkReachabilityBatch` + +6. 梯形速度： + - `makeTrapProfile` + - `sampleTrapProfile` + +7. 轨迹规划： + - `planMoveJ` + - `planMoveL` + - `planMoveC` + - `planPath` + - `validatePath` + - `estimateCycleTime` + - `resampleTrajectory` + +### 3.3 KDL P0 + +按 KDL WASM 接口设计第 22 章，P0 必须暴露： + +1. `init` +2. `loadRobotFromUrdf` +3. `createRobotFromModel` +4. `destroyRobot` +5. `getRobotInfo` +6. `getJointLimits` +7. `normalizePose` +8. `composePose` +9. `inversePose` +10. `applyOffset` +11. `applyToolAndFrame` +12. `fk` +13. `fkAllLinks` +14. `jacobian` +15. `ik` +16. `ikBatch` +17. `checkJointLimits` +18. `checkSingularity` +19. `checkReachability` +20. `checkReachabilityBatch` +21. `makeTrapProfile` +22. `sampleTrapProfile` +23. `planMoveJ` +24. `planMoveL` +25. `planMoveC` +26. `planPath` +27. `validatePath` +28. `estimateCycleTime` +29. `resampleTrajectory` + +### 3.4 KDL P1 + +按 KDL WASM 接口设计第 22 章，P1 扩展： + +1. `planBlendPath` +2. `planMoveSpline` +3. `checkCollisionInputPoses`，只提供 link poses，不做碰撞本身。 +4. `optimizeSeedSequence` +5. `compareTrajectory` +6. 外部轴协调相关函数。 + +## 4. 共享数据和单位 + +### 4.1 单位 + +GRL 编译器内部必须统一： + +| 物理量 | 内部单位 | +| --- | --- | +| 长度 | meter | +| 角度 | radian | +| 时间 | second | +| 质量 | kilogram | +| 线速度 | meter/second | +| 角速度 | radian/second | +| 加速度 | meter/second^2 或 radian/second^2 | + +### 4.2 位姿 + +内部统一为： + +```ts +interface Pose { + position: [number, number, number]; + quaternion: [number, number, number, number]; // x, y, z, w +} +``` + +GRL `pose(x, y, z, rx, ry, rz)` 必须在 TypeScript 编译层规范化为 KDL `Pose`。 + +### 4.3 目标点 + +必须统一到： + +```ts +interface PoseTarget { + id?: string; + pose: Pose; + config?: RobotConfiguration; + tool?: Pose; + frame?: Pose; + extAxis?: number[]; + sourceMap?: MotionSourceMap; +} + +interface JointTarget { + id?: string; + joints: number[]; + extAxis?: number[]; + sourceMap?: MotionSourceMap; +} +``` + +### 4.4 速度和 zone + +GRL 速度和过渡必须编译为： + +```ts +type SpeedSpec = + | { kind: "joint_percent"; value: number } + | { kind: "joint_abs"; velocity: number; acceleration?: number } + | { kind: "linear"; velocity: number; acceleration?: number; angularVelocity?: number }; + +type ZoneSpec = + | { kind: "fine" } + | { kind: "distance"; value: number } + | { kind: "cnt"; value: number } + | { kind: "continuous" }; +``` + +首版 `zone` 只用于诊断和后处理，运动规划按 `fine` 到点执行，并产生 `KDL_ZONE_APPROXIMATED`。 + +### 4.5 诊断 + +所有语言、语义、KDL 和后处理错误必须结构化。KDL 固定 code 至少包含： + +| code | 含义 | +| --- | --- | +| `KDL_INVALID_MODEL` | 机器人模型非法 | +| `KDL_TARGET_UNREACHABLE` | 目标不可达 | +| `KDL_IK_FAILED` | IK 求解失败 | +| `KDL_JOINT_LIMIT` | 关节超限 | +| `KDL_VELOCITY_LIMIT` | 速度超限 | +| `KDL_ACCEL_LIMIT` | 加速度超限 | +| `KDL_SINGULARITY` | 接近奇异 | +| `KDL_ARC_DEGENERATE` | 圆弧退化 | +| `KDL_PATH_EMPTY` | 空路径 | +| `KDL_ZONE_APPROXIMATED` | zone 被近似处理 | + +GRL 语义诊断至少覆盖： + +1. 未定义符号。 +2. 重复声明。 +3. 类型不匹配。 +4. 单位错误。 +5. 目标点类型不适合运动指令。 +6. `movec` 缺 via 或三点退化。 +7. 工具、坐标系、速度、zone 不可解析。 +8. IO 地址非法。 +9. 参数数量、类型、方向错误。 +10. `func` 返回路径错误或包含非法副作用。 +11. `break/continue/jump` 位置非法。 +12. Path 为空或点名重复。 +13. Operation 引用不存在的 Path。 +14. 后处理品牌不支持所用语义。 + +## 5. GRL 与 KDL 的调用关系 + +| GRL 语法 | 编译结果 | KDL WASM 函数 | +| --- | --- | --- | +| `target home = joint_target` | `JointTarget` | `checkJointLimits` | +| `target pick = pose_target` | `PoseTarget` | `checkReachability` | +| `pick offset z 100 mm` | `OffsetSpec` | `applyOffset` | +| `movej home` | `MoveJRequest` | `planMoveJ` | +| `movel pick` | `MoveLRequest` | `planMoveL` | +| `movec via mid target end` | `MoveCRequest` | `planMoveC` | +| `run_path pick_path` | `PathPlanRequest` | `planPath` | +| Path 可达性检查 | `PathPlanRequest` | `validatePath` | +| 节拍报告 | `TrajectoryResult/PathPlanResult` | `estimateCycleTime` | + +以下 GRL 语义不进入 KDL WASM： + +1. `if/elseif/else` +2. `while/for/switch` +3. `proc/func/call/return` +4. `io.do/di/ai/ao` +5. `wait/pulse/timer` +6. `alarm/raise/try/catch` +7. `operation.process` + +## 6. 验收口径 + +### 6.1 GRL P0 验收 + +1. EBNF 覆盖语法规范第 22 章。 +2. 语法规范第 23 章完整示例可解析。 +3. AST 保留 source range、单位原文、规范化值和品牌 metadata。 +4. 语义检查覆盖语法规范第 21 章全部检查项。 +5. `path` 可编译为 `PathPlanRequest`。 +6. `operation` 可展开为 start action、path、end action。 +7. `movej/movel/movec` 可编译为对应 KDL request。 +8. ABB、FANUC、KUKA 后处理原型有 golden file。 + +### 6.2 KDL P0 验收 + +1. P0 29 个函数全部在 TypeScript API 和 Worker RPC 中可调用。 +2. URDF 到 KDL Chain joint 顺序稳定。 +3. FK 与 golden 或原生 KDL 结果对比在容差内。 +4. IK 后 FK 回代误差小于容差。 +5. Jacobian 尺寸和奇异性指标正确。 +6. 梯形速度曲线长距离/短距离测试通过。 +7. `planMoveJ` 关节同起同停。 +8. `planMoveL` TCP 直线误差小于容差。 +9. `planMoveC` 圆心、半径、弧长、圆弧误差正确，共线返回 `KDL_ARC_DEGENERATE`。 +10. `planPath/validatePath` 保留 segment、target 和 source map。 +11. 错误处理不抛裸字符串，返回结构化 `KdlError` 或 `MotionDiagnostic`。 + +### 6.3 集成验收 + +1. GRL `movej/movel/movec` 编译为 KDL request 并生成轨迹。 +2. GRL `path` 编译为 `PathPlanRequest` 并生成整条路径。 +3. `run_operation` 展开后 KDL 只处理 motion segment。 +4. `if/for/switch/call/wait/io` 不直接调用 KDL，但能影响虚拟控制器何时调用运动函数。 +5. 长路径批量验证有性能记录。 +6. Worker 初始化、崩溃恢复和取消请求测试通过。 diff --git a/02-项目程序开发详细步骤.md b/02-项目程序开发详细步骤.md new file mode 100644 index 0000000..6c8d15e --- /dev/null +++ b/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 +``` diff --git a/03-推进台账.md b/03-推进台账.md new file mode 100644 index 0000000..cebdbef --- /dev/null +++ b/03-推进台账.md @@ -0,0 +1,1097 @@ +# 03-推进台账 + +版本：0.3 +日期：2026-06-27 + +## 1. 记录规则 + +每轮推进后追加记录，格式固定： + +```text +轮次： +日期： +关联任务： +本轮目标： +做了什么： +改了哪些文件： +验证了什么： +问题和风险： +下一步： +``` + +## 2. 台账 + +### 轮次 001 + +日期：2026-06-27 +关联任务：`KW-000` +本轮目标：根据用户要求，将 `working1` 实施文档调整为完全对标两份源文档： + +1. `/home/meswork/kdl_work/work/doc/KDL_WASM计算接口设计.md` +2. `/home/meswork/kdl_work/work/doc/通用机器人编程语法规范.md` + +做了什么： + +1. 抽取 KDL WASM 文档中的目标、架构、API、数据类型、轨迹函数、诊断、P0/P1、测试要求和实施顺序。 +2. 抽取 GRL 语法规范中的词法、顶层结构、类型系统、目标点、运动、Path、Operation、IO、流程控制、proc/func、异常、中断、多任务、品牌扩展、后处理、IR、语义检查、EBNF、P0/P1。 +3. 将任务编号重排为： + - `KW-001` 到 `KW-013`：KDL WASM 计算接口实施。 + - `KW-100` 到 `KW-112`：GRL 编程语法实施。 +4. 删除当前实施范围中对其他源文档的依赖表述。 +5. 按两份源文档重写功能范围、开发步骤、任务矩阵、验收证据和 ADR。 + +改了哪些文件： + +1. `work/working1/README.md` +2. `work/working1/01-项目功能内容.md` +3. `work/working1/02-项目程序开发详细步骤.md` +4. `work/working1/03-推进台账.md` +5. `work/working1/04-任务矩阵.md` +6. `work/working1/05-验收证据.md` +7. `work/working1/06-决策记录.md` + +验证了什么： + +1. `work/doc/KDL_WASM计算接口设计.md` 存在。 +2. `work/doc/通用机器人编程语法规范.md` 存在。 +3. `working1` 当前文档只以这两份文档作为对标来源。 +4. KDL P0 29 个函数已进入任务和验收证据。 +5. GRL P0 14 类能力已进入任务和验收证据。 + +问题和风险： + +1. 当前仍是实施文档，不包含实际代码实现。 +2. KDL 性能指标需要真实 WASM 构建和浏览器环境验证。 +3. GRL 后处理 golden file 需要补充 ABB、FANUC、KUKA 示例。 +4. `trap/interrupt/task` 属于 GRL P1，若提前解析但不执行，必须返回明确诊断。 + +下一步： + +1. 执行 `KW-001`：建立 KDL WASM wrapper 工程和 Worker RPC。 +2. 并行执行 `KW-100`：建立 GRL lexer、单位规范化和关键字表。 +3. 第一集成点为 `KW-103`：GRL `movej/movel/movec` 编译为 KDL request。 + +### 轮次 002 + +日期：2026-06-27 +关联任务：`KW-001`、`KW-100` +本轮目标：按 `working1` 下一步连续推进，建立 KDL WASM wrapper/Worker RPC 工程骨架，并实现 GRL lexer、单位规范化和关键字表。 + +做了什么： + +1. 新建 `/home/meswork/kdl_work/kdl-wasm` 工程骨架。 +2. 增加 CMake/Emscripten WASM wrapper，导出 `kdl.js`、`kdl.wasm`、`kdl.d.ts`。 +3. 增加 C ABI 占位边界：`kdl_init`、`kdl_create_robot`、`kdl_destroy_robot`、`kdl_get_robot_info`、`kdl_fk`、`kdl_ik`、`kdl_plan_movej`、`kdl_last_error` 等。 +4. 增加 TypeScript KDL 类型、`KdlRpcRequest/KdlRpcResponse`、结构化错误、Worker dispatch、`kdl.worker.ts` 和 `KdlWorkerClient`。 +5. Worker runtime 支持注入 native module loader；默认通过 ES module 动态加载 WASM wrapper，`init` 调用底层 `kdl_init`。 +6. 增加 GRL lexer：注释、关键字、标识符、字符串、数字、source range、EOF token。 +7. 增加 GRL 单位规范化：长度、角度、时间、质量、线速度、角速度、线加速度、角加速度、百分比。 +8. 增加 Vitest 单元测试和 TypeScript 严格类型检查入口。 + +改了哪些文件： + +1. `/home/meswork/kdl_work/package.json` +2. `/home/meswork/kdl_work/package-lock.json` +3. `/home/meswork/kdl_work/.gitignore` +4. `/home/meswork/kdl_work/kdl-wasm/CMakeLists.txt` +5. `/home/meswork/kdl_work/kdl-wasm/bindings/kdl_c_api.cpp` +6. `/home/meswork/kdl_work/kdl-wasm/bindings/kdl.d.ts` +7. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/*` +8. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/lexer/*` +9. `/home/meswork/kdl_work/kdl-wasm/web/tests/kdl/rpc.test.ts` +10. `/home/meswork/kdl_work/kdl-wasm/web/tests/grl/lexer.test.ts` +11. `/home/meswork/kdl_work/work/working1/03-推进台账.md` +12. `/home/meswork/kdl_work/work/working1/04-任务矩阵.md` +13. `/home/meswork/kdl_work/work/working1/05-验收证据.md` + +验证了什么： + +1. `npm run typecheck` 通过。 +2. `npm test` 通过，2 个测试文件共 11 个测试通过。 +3. `npm run test -- kdl rpc` 通过。 +4. `npm run test -- grl lexer` 通过。 +5. `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` 通过。 +6. `cmake --build kdl-wasm/build-wasm -j16` 通过。 +7. `kdl-wasm/build-wasm/kdl.js`、`kdl-wasm/build-wasm/kdl.wasm`、`kdl-wasm/build-wasm/kdl.d.ts` 存在。 +8. Node 动态加载 `kdl.js` 并调用 `kdl_init` 返回 `0`。 + +问题和风险： + +1. `KW-001` 已完成工程骨架和 Worker RPC，但 C ABI 中机器人建模、FK/IK、轨迹规划仍是后续任务占位。 +2. `KW-100` 已完成 lexer 和单位表，但 parser、AST、语义检查尚未开始。 +3. 当前未启动浏览器 Worker 真实环境测试，Worker 加载通过注入 loader 和 Node 动态 import 验证；浏览器/Playwright 可在 UI 或集成环境出现后补充。 + +下一步： + +1. 执行 `KW-002`：URDF XML 解析、`NormalizedRobotModel`、RobotHandle 生命周期和基础模型诊断。 +2. 执行 `KW-101`：GRL parser 和 AST 骨架，覆盖最小文件、source range 和错误行列号。 + +### 轮次 003 + +日期：2026-06-27 +关联任务：`KW-002`、`KW-101` +本轮目标：继续按台账推进，完成 URDF 到标准模型和 GRL parser/AST 骨架。 + +做了什么： + +1. 增加 URDF XML 解析，读取 robot/link/joint/parent/child/origin/axis/limit。 +2. 增加 `NormalizedRobotModel` 生成，包含 `robotId/name/baseLink/tipLink/links/joints/activeJointNames/limits/source.urdfHash`。 +3. 增加 base/tip 连通性检查、unsupported joint type、jointOrder 和 limit override 处理。 +4. 增加 TypeScript `RobotModelRegistry`，支持 RobotHandle create/getInfo/getJointLimits/destroy 生命周期。 +5. 扩展 Worker runtime 和 `KdlWorkerClient`，支持 `loadRobotFromUrdf/createRobotFromModel/destroyRobot/getRobotInfo/getJointLimits`。 +6. 增加 GRL AST 类型和 parser 骨架，覆盖 `language grl 0.1`、`module`、`import`、`proc`，并保留顶层 raw declaration。 +7. 增加 parser 错误行列号和 source range 测试。 + +改了哪些文件： + +1. `/home/meswork/kdl_work/package.json` +2. `/home/meswork/kdl_work/package-lock.json` +3. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/types.ts` +4. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/runtime.ts` +5. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/kdlClient.ts` +6. `/home/meswork/kdl_work/kdl-wasm/web/src/robot/*` +7. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/ast/*` +8. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/parser/*` +9. `/home/meswork/kdl_work/kdl-wasm/web/tests/kdl/urdf.test.ts` +10. `/home/meswork/kdl_work/kdl-wasm/web/tests/grl/parser.test.ts` +11. `/home/meswork/kdl_work/work/working1/03-推进台账.md` +12. `/home/meswork/kdl_work/work/working1/04-任务矩阵.md` +13. `/home/meswork/kdl_work/work/working1/05-验收证据.md` + +验证了什么： + +1. `npm run typecheck` 通过。 +2. `npm test` 通过，4 个测试文件共 19 个测试通过。 +3. `npm run test -- kdl urdf normalized-model` 通过。 +4. `npm run test -- grl parser ast` 通过。 + +问题和风险： + +1. RobotHandle 目前绑定 TypeScript 标准模型 registry，尚未创建真实 Orocos KDL `Tree/Chain` 求解器。 +2. Parser 对数据声明、target、path、operation、语句体仍保留 raw token，细化工作进入 `KW-102` 到 `KW-109`。 + +下一步： + +1. 执行 `KW-003`：基于标准模型实现 FK 和 fkAllLinks 的初版数值计算、维度诊断和 link 顺序测试。 +2. 执行 `KW-102`：细化数据声明、类型系统、target/tool/frame/speed/zone 和 offset AST。 + +### 轮次 004 + +日期：2026-06-27 +关联任务：`KW-003`、`KW-102` +本轮目标：继续推进 FK/fkAllLinks 计算接口，并把 GRL 数据声明、target、speed、zone、offset 编译为共享类型。 + +做了什么： + +1. 增加基础位姿数学工具：矩阵相乘、RPY、轴角、四元数、pose compose。 +2. 基于 `NormalizedRobotModel` 实现 TypeScript FK 基线，支持 revolute、continuous、prismatic、fixed joint。 +3. 实现 `fk`，返回 flange、tcp、joints、diagnostics，并支持 tool/frame 选项。 +4. 实现 `fkAllLinks`，返回 base-to-tip link pose 列表。 +5. 增加 FK 维度和非法关节值结构化诊断。 +6. 扩展 Worker runtime 和 `KdlWorkerClient`，暴露 `fk/fkAllLinks`。 +7. 扩展 GRL AST 和 parser，结构化输出 `DataDeclaration`、`TargetDeclaration`、表达式 AST、object/call/array/offset。 +8. 增加 GRL 数据编译函数，支持 `tool/frame/joint_target/pose_target/speed/zone/offset` 到共享数据结构。 +9. 增加负数单位值解析，覆盖 `offset y -10 mm` 等场景。 + +改了哪些文件： + +1. `/home/meswork/kdl_work/kdl-wasm/web/src/math/poseMath.ts` +2. `/home/meswork/kdl_work/kdl-wasm/web/src/robot/normalizedRobotModel.ts` +3. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/types.ts` +4. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/runtime.ts` +5. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/kdlClient.ts` +6. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/ast/*` +7. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/parser/*` +8. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/semantic/*` +9. `/home/meswork/kdl_work/kdl-wasm/web/tests/kdl/fk.test.ts` +10. `/home/meswork/kdl_work/kdl-wasm/web/tests/grl/dataDeclarations.test.ts` +11. `/home/meswork/kdl_work/work/working1/03-推进台账.md` +12. `/home/meswork/kdl_work/work/working1/04-任务矩阵.md` +13. `/home/meswork/kdl_work/work/working1/05-验收证据.md` + +验证了什么： + +1. `npm run typecheck` 通过。 +2. `npm test` 通过，6 个测试文件共 28 个测试通过。 +3. `npm run test -- kdl fk` 通过。 +4. `npm run test -- grl types declarations targets` 通过。 +5. `cmake --build kdl-wasm/build-wasm -j16` 通过。 + +问题和风险： + +1. 当前 FK 是 TypeScript 标准模型基线，尚未与真实 Orocos KDL WASM solver 做数值 golden 对比。 +2. GRL 数据编译已覆盖 P0 数据结构，但尚未做全局符号表、类型引用检查和重复定义诊断；这些进入 `KW-110`。 + +下一步： + +1. 执行 `KW-004`：IK 和 ikBatch 的基础接口、失败原因和回代测试。 +2. 执行 `KW-103`：解析 `movej/movel/movec`、当前 tool/frame/speed/zone，并编译为 KDL request。 + +### 轮次 005 + +日期：2026-06-27 +关联任务：`KW-004`、`KW-103` +本轮目标：继续推进 IK/ikBatch 基础接口，并完成 GRL 运动语句到 KDL request 的第一个集成点。 + +做了什么： + +1. 正式化 `IkOptions/IkResult`、`MoveJRequest/MoveLRequest/MoveCRequest` 类型。 +2. 在 TypeScript 标准模型 registry 中实现 `ik` 和 `ikBatch`。 +3. IK 当前支持 single-prismatic 和 Rz+Px 链，返回可达、关节限位、unsupported model 等结构化结果。 +4. `ikBatch` 保持输入顺序，并在前一点成功时复用上一点结果作为后续 seed。 +5. Worker runtime 和 `KdlWorkerClient` 暴露 `ik/ikBatch`。 +6. 增加 GRL Motion IR：`MotionInstruction`、`MotionKind` 和 request 编译类型。 +7. 增加 `buildMotionContext`，从 data/target 声明建立 targets、speeds、zones、tools、frames。 +8. 增加 `parseProcedureMotionInstructions`，从 `proc` body token 解析 `set_tool/set_frame/set_speed/set_zone/movej/movel/movec`。 +9. 增加 `compileMotionToKdlRequest`，生成 `MoveJRequest/MoveLRequest/MoveCRequest`。 + +改了哪些文件： + +1. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/types.ts` +2. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/runtime.ts` +3. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/kdlClient.ts` +4. `/home/meswork/kdl_work/kdl-wasm/web/src/robot/normalizedRobotModel.ts` +5. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/ir/*` +6. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/semantic/compileMotion.ts` +7. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/semantic/index.ts` +8. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/parser/parser.ts` +9. `/home/meswork/kdl_work/kdl-wasm/web/tests/kdl/ik.test.ts` +10. `/home/meswork/kdl_work/kdl-wasm/web/tests/grl/motionCompile.test.ts` +11. `/home/meswork/kdl_work/work/working1/03-推进台账.md` +12. `/home/meswork/kdl_work/work/working1/04-任务矩阵.md` +13. `/home/meswork/kdl_work/work/working1/05-验收证据.md` + +验证了什么： + +1. `npm run typecheck` 通过。 +2. `npm test` 通过，8 个测试文件共 34 个测试通过。 +3. `npm run test -- kdl ik` 通过。 +4. `npm run test -- grl motion` 通过。 +5. `cmake --build kdl-wasm/build-wasm -j16` 通过。 + +问题和风险： + +1. IK 当前是受限 TypeScript 几何基线，不是完整 Orocos KDL 迭代 IK。 +2. `KW-103` 已完成直写 `proc` 内 motion 指令编译，但 path/operation 内 point/event 展开仍属于后续 `KW-104/KW-105`。 +3. 独立 `integration grl-kdl-motion` 测试文件尚未建立，当前由 `grl motion` 和全量测试覆盖同一集成链路。 + +下一步： + +1. 执行 `KW-005`：Jacobian、奇异性和基础检查 API。 +2. 执行 `KW-104`：Path、event 和 `run_path` 编译为 PathPlanRequest。 + +### 轮次 006 + +日期：2026-06-27 +关联任务：`KW-005` +本轮目标：实现 Jacobian、奇异性、关节限位、速度限位和可达性批量检查 API。 + +做了什么： + +1. 正式化 `JacobianResult`、`LimitCheckResult`、`SingularityResult`、`ReachabilityResult` 类型。 +2. 基于 FK 数值差分实现 `jacobian`，返回 6 x dof 矩阵。 +3. 实现 `checkSingularity`，输出 manipulability、conditionNumber 和 `KDL_SINGULARITY` warning。 +4. 实现 `checkJointLimits`，对超限关节输出 `KDL_JOINT_LIMIT`。 +5. 实现 `checkVelocityLimits`，对轨迹点速度/加速度输出 `KDL_VELOCITY_LIMIT`、`KDL_ACCEL_LIMIT` 和最大比例。 +6. 实现 `checkReachability/checkReachabilityBatch`，复用 IK 基线并保持批量顺序。 +7. Worker runtime 和 `KdlWorkerClient` 暴露 KW-005 API。 + +改了哪些文件： + +1. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/types.ts` +2. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/runtime.ts` +3. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/kdlClient.ts` +4. `/home/meswork/kdl_work/kdl-wasm/web/src/robot/normalizedRobotModel.ts` +5. `/home/meswork/kdl_work/kdl-wasm/web/tests/kdl/checks.test.ts` +6. `/home/meswork/kdl_work/work/working1/03-推进台账.md` +7. `/home/meswork/kdl_work/work/working1/04-任务矩阵.md` +8. `/home/meswork/kdl_work/work/working1/05-验收证据.md` + +验证了什么： + +1. `npm run typecheck` 通过。 +2. `npm run test -- kdl jacobian checks` 通过。 +3. `npm test` 通过，9 个测试文件共 38 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 + +问题和风险： + +1. Jacobian 当前为 TypeScript 数值差分基线，后续真实 Orocos KDL solver 接入后应增加 golden 对比。 +2. 奇异性指标当前使用线速度 Jacobian 的 Gram 行列式和列范数估算，适合作为 P0 诊断基线，不等价于完整工业控制器判据。 +3. `KW-104` 依赖 `KW-011 planPath/validatePath`，本轮未推进，避免把 Path 集成误标完成。 + +下一步： + +1. 执行 `KW-006`：位姿变换和 offset API。 +2. 执行 `KW-007`：梯形速度曲线，为后续 `planMoveJ/planMoveL/planMoveC` 做准备。 + +### 轮次 007 + +日期：2026-06-27 +关联任务：`KW-006` +本轮目标：实现位姿规范化、组合、逆变换、tool/frame 应用和 offset API。 + +做了什么： + +1. 在数学模块补充 `inversePose` 刚体逆变换。 +2. 增加 `kdl/poseApi.ts`，集中实现 `normalizePose/composePose/inversePose/applyToolAndFrame/applyOffset`。 +3. `normalizePose` 支持 `position/quaternion`、`xyz/rpy`、`xyz/quat` 三种输入，并统一规范化四元数。 +4. `applyToolAndFrame` 保持与当前 FK 一致的 `frame * target.pose * tool` 约定。 +5. `applyOffset` 支持 `frame/world` 左乘偏移和 `tool` 右乘偏移，并保留 `PoseTarget` 元数据。 +6. Worker runtime 和 `KdlWorkerClient` 暴露 KW-006 API。 +7. 非法位姿输入返回 `KDL_INVALID_POSE` 结构化诊断。 + +改了哪些文件： + +1. `/home/meswork/kdl_work/kdl-wasm/web/src/math/poseMath.ts` +2. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/poseApi.ts` +3. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/runtime.ts` +4. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/kdlClient.ts` +5. `/home/meswork/kdl_work/kdl-wasm/web/tests/kdl/poseApi.test.ts` +6. `/home/meswork/kdl_work/work/working1/03-推进台账.md` +7. `/home/meswork/kdl_work/work/working1/04-任务矩阵.md` +8. `/home/meswork/kdl_work/work/working1/05-验收证据.md` + +验证了什么： + +1. `npm run typecheck` 通过。 +2. `npm run test -- kdl pose offset` 通过，10 个测试文件共 43 个测试通过。 +3. `npm test` 通过，10 个测试文件共 43 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 + +问题和风险： + +1. `frameId` 当前作为 `OffsetSpec` 元数据保留，尚未接入全局 frame registry；命名 frame 解析会在 `KW-110` 语义检查和后续路径集成中继续完善。 +2. 位姿变换当前为 TypeScript 基线实现，后续 C ABI / WASM 真实封装可复用这些测试作为行为约束。 + +下一步： + +1. 执行 `KW-007`：梯形速度曲线。 +2. 之后按依赖推进 `KW-008 planMoveJ`。 + +### 轮次 008 + +日期：2026-06-27 +关联任务：`KW-007` +本轮目标：实现梯形速度曲线 profile 和采样 API，为后续运动规划提供路径参数。 + +做了什么： + +1. 将 `TrapProfileOptions/TrapSample/TrapProfileResult` 从 `JsonObject` 占位改为明确类型。 +2. 增加 `kdl/trapProfile.ts`，实现 `makeTrapProfile` 和 `sampleTrapProfile`。 +3. 长距离场景生成 trapezoid，短距离场景自动退化为 triangle。 +4. 采样点输出 `index/time/s/sd/sdd`，其中 `s` 为 `[0,1]` 归一化路径参数。 +5. 首末采样点严格固定为 `s=0` 和 `s=1`，中间采样按 `sampleTime` 单调生成。 +6. 非法输入返回 `KDL_INVALID_TRAP_PROFILE` 结构化诊断。 +7. Worker runtime 和 `KdlWorkerClient` 暴露 `makeTrapProfile/sampleTrapProfile`。 + +改了哪些文件： + +1. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/types.ts` +2. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/trapProfile.ts` +3. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/runtime.ts` +4. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/kdlClient.ts` +5. `/home/meswork/kdl_work/kdl-wasm/web/tests/kdl/trapProfile.test.ts` +6. `/home/meswork/kdl_work/work/working1/03-推进台账.md` +7. `/home/meswork/kdl_work/work/working1/04-任务矩阵.md` +8. `/home/meswork/kdl_work/work/working1/05-验收证据.md` + +验证了什么： + +1. `npm run typecheck` 通过。 +2. `npm run test -- kdl trap-profile` 通过，11 个测试文件共 47 个测试通过。 +3. `npm test` 通过，11 个测试文件共 47 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 + +问题和风险： + +1. 当前速度曲线是 TypeScript 基线实现，后续真实 KDL `VelocityProfile_Trap` 接入后应使用这些测试做行为对齐。 +2. `startVelocity/endVelocity` 已做输入校验，但后续连续 path blend 对非零边界速度的策略还需要在 `KW-011` 中统一。 + +下一步： + +1. 执行 `KW-008`：`planMoveJ`。 +2. 继续把梯形速度曲线接入 MOVEJ 轨迹采样、限位和诊断。 + +### 轮次 009 + +日期：2026-06-27 +关联任务：`KW-008` +本轮目标：实现 `planMoveJ`，把目标关节、梯形速度曲线、FK 和诊断串成可回放轨迹。 + +做了什么： + +1. 将 `TrajectoryPoint/TrajectoryEvent/TrajectoryResult` 从 `JsonObject` 占位改为明确类型。 +2. 在 `RobotModelRegistry` 中实现 `planMoveJ`。 +3. `joint_target` 直接生成终点关节，`pose_target` 复用当前 IK 基线求终点关节。 +4. 使用 `KW-007` 梯形速度曲线生成归一化 `s/sd/sdd`，并映射到每个关节的位置、速度、加速度。 +5. 每个轨迹点执行 FK，输出 `flange/tcp`，用于仿真回放。 +6. 覆盖起终点关节限位、采样点速度/加速度、奇异性和 P0 zone 近似诊断。 +7. Worker runtime 和 `KdlWorkerClient` 暴露 `planMoveJ`。 + +改了哪些文件： + +1. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/types.ts` +2. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/runtime.ts` +3. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/kdlClient.ts` +4. `/home/meswork/kdl_work/kdl-wasm/web/src/robot/normalizedRobotModel.ts` +5. `/home/meswork/kdl_work/kdl-wasm/web/tests/kdl/planMoveJ.test.ts` +6. `/home/meswork/kdl_work/work/working1/03-推进台账.md` +7. `/home/meswork/kdl_work/work/working1/04-任务矩阵.md` +8. `/home/meswork/kdl_work/work/working1/05-验收证据.md` + +验证了什么： + +1. `npm run typecheck` 通过。 +2. `npm run test -- kdl movej planMoveJ` 通过，12 个测试文件共 51 个测试通过。 +3. `npm test` 通过，12 个测试文件共 51 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 + +问题和风险： + +1. `pose_target` 的 IK 仍使用当前 TypeScript 几何基线，真实 6 轴工业机器人求解要等 Orocos KDL solver 深度接入。 +2. `zone` 在 P0 仍近似为 fine，连续 blend 会在 `KW-011` 统一处理。 +3. 当前 MOVEJ 使用归一化同步参数实现，同起同停可用；品牌控制器级 look-ahead 和更复杂速度策略属于后续阶段。 + +下一步： + +1. 执行 `KW-009`：`planMoveL`。 +2. 复用 `TrajectoryResult`、梯形速度曲线和 IK seed 连续策略生成 TCP 直线轨迹。 + +### 轮次 010 + +日期：2026-06-27 +关联任务：`KW-009` +本轮目标：实现 `planMoveL`，按 TCP 直线采样、逐点 IK，并输出可回放轨迹。 + +做了什么： + +1. 在 `RobotModelRegistry` 中实现 `planMoveL`。 +2. 使用起点 FK 得到 TCP 起点，按目标 pose 生成 TCP 直线采样 pose。 +3. 使用 `KW-007` 梯形速度曲线按直线长度生成 `s/sd/sdd`。 +4. 对每个采样点逐点 IK，seed 使用上一采样点关节解。 +5. 每个轨迹点输出 `joints/jointVelocity/jointAcceleration/flange/tcp`。 +6. 覆盖 TCP 直线误差、采样点 IK 失败、速度/加速度、奇异性和 P0 zone 近似诊断。 +7. Worker runtime 和 `KdlWorkerClient` 暴露 `planMoveL`。 + +改了哪些文件： + +1. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/runtime.ts` +2. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/kdlClient.ts` +3. `/home/meswork/kdl_work/kdl-wasm/web/src/robot/normalizedRobotModel.ts` +4. `/home/meswork/kdl_work/kdl-wasm/web/tests/kdl/planMoveL.test.ts` +5. `/home/meswork/kdl_work/work/working1/03-推进台账.md` +6. `/home/meswork/kdl_work/work/working1/04-任务矩阵.md` +7. `/home/meswork/kdl_work/work/working1/05-验收证据.md` + +验证了什么： + +1. `npm run typecheck` 通过。 +2. `npm run test -- kdl movel planMoveL` 通过，13 个测试文件共 54 个测试通过。 +3. `npm test` 通过，13 个测试文件共 54 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 + +问题和风险： + +1. 姿态插值当前为 P0 固定目标四元数近似，完整 slerp 和 `tool_z_lock` 会在后续真实 KDL/轨迹阶段继续完善。 +2. 当前 IK 基线仍只覆盖 single-prismatic 与 Rz+Px 链，通用 6 轴 MOVEL 依赖后续 Orocos KDL solver 深度接入。 +3. `zone` 仍近似为 fine，连续 blend 进入 `KW-011`。 + +下一步： + +1. 执行 `KW-010`：`planMoveC`。 +2. 复用轨迹点结构、梯形速度曲线和逐点 IK seed 策略，补圆弧几何和退化诊断。 + +### 轮次 011 + +日期：2026-06-27 +关联任务：`KW-010` +本轮目标：实现 `planMoveC`，完成三点圆弧几何、圆弧采样、逐点 IK 和退化诊断。 + +做了什么： + +1. 在 `RobotModelRegistry` 中实现 `planMoveC`。 +2. 基于起点 TCP、via、target 三点计算圆心、半径、法向、角度、弧长和方向。 +3. 使用 `KW-007` 梯形速度曲线按圆弧长度生成 `s/sd/sdd`。 +4. 对每个圆弧采样点逐点 IK，seed 使用上一采样点关节解。 +5. 每个轨迹点输出 `joints/jointVelocity/jointAcceleration/flange/tcp`。 +6. `TrajectoryResult.meta.circle` 输出 `center/radius/normal/angle/length/direction/maxArcError`。 +7. 三点重合或共线返回 `KDL_ARC_DEGENERATE`。 +8. Worker runtime 和 `KdlWorkerClient` 暴露 `planMoveC`。 + +改了哪些文件： + +1. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/runtime.ts` +2. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/kdlClient.ts` +3. `/home/meswork/kdl_work/kdl-wasm/web/src/robot/normalizedRobotModel.ts` +4. `/home/meswork/kdl_work/kdl-wasm/web/tests/kdl/planMoveC.test.ts` +5. `/home/meswork/kdl_work/work/working1/03-推进台账.md` +6. `/home/meswork/kdl_work/work/working1/04-任务矩阵.md` +7. `/home/meswork/kdl_work/work/working1/05-验收证据.md` + +验证了什么： + +1. `npm run typecheck` 通过。 +2. `npm run test -- kdl movec planMoveC` 通过，14 个测试文件共 57 个测试通过。 +3. `npm test` 通过，14 个测试文件共 57 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 + +问题和风险： + +1. MOVEC 当前为 P0 三点圆弧基线，尚未覆盖 `arcMode=center/radius` 和 `circleDirection=long/cw/ccw` 的完整品牌语义。 +2. 姿态插值当前为 P0 固定目标四元数近似，完整 slerp 会在后续阶段继续完善。 +3. 当前 IK 基线仍限制通用 6 轴 MOVEC 覆盖范围，真实 Orocos KDL solver 接入后需补更多 golden 测试。 + +下一步： + +1. 执行 `KW-011`：`planPath` 和 `validatePath`。 +2. 将 MOVEJ/MOVEL/MOVEC 段轨迹合并，并保留 segmentId、targetId、sourceMap 与诊断报告。 + +### 轮次 012 + +日期：2026-06-27 +关联任务：`KW-011` +本轮目标：实现 `planPath` 和 `validatePath`，把 MOVEJ/MOVEL/MOVEC 段轨迹合并成整条路径，并输出段级验证报告。 + +做了什么： + +1. 将 `MotionSegmentRequest/PathPlanRequest/PathPlanResult/SegmentValidationReport/PathValidationResult` 从占位类型改为明确结构。 +2. 在 `RobotModelRegistry` 中实现 `planPath`。 +3. `planPath` 按段调用 `planMoveJ/planMoveL/planMoveC`，并用上一段终点关节作为下一段起点。 +4. 合并轨迹点时重新编号、累加时间，并保留 `segmentId/targetId/sourceMap`。 +5. 空路径返回 `KDL_PATH_EMPTY` 结构化诊断。 +6. 实现 `validatePath`，输出 `segmentReports`、`cycleTime`、速度/加速度比例、笛卡尔误差和诊断。 +7. Worker runtime 和 `KdlWorkerClient` 暴露 `planPath/validatePath`。 + +改了哪些文件： + +1. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/types.ts` +2. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/runtime.ts` +3. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/kdlClient.ts` +4. `/home/meswork/kdl_work/kdl-wasm/web/src/robot/normalizedRobotModel.ts` +5. `/home/meswork/kdl_work/kdl-wasm/web/tests/kdl/path.test.ts` +6. `/home/meswork/kdl_work/work/working1/03-推进台账.md` +7. `/home/meswork/kdl_work/work/working1/04-任务矩阵.md` +8. `/home/meswork/kdl_work/work/working1/05-验收证据.md` + +验证了什么： + +1. `npm run typecheck` 通过。 +2. `npm run test -- kdl path validation` 通过，15 个测试文件共 60 个测试通过。 +3. `npm test` 通过，15 个测试文件共 60 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 + +问题和风险： + +1. `planPath` 当前按 P0 语义串行拼接各段，尚未实现连续 blend/look-ahead。 +2. `validatePath` 的笛卡尔误差从已有段诊断和 `meta.circle.maxArcError` 汇总，后续可扩展更细的路径误差统计。 +3. Path 中 event 和 `run_path` 的 GRL 语法编译仍属于 `KW-104`。 + +下一步： + +1. 执行 `KW-012`：节拍估算、重采样和诊断报告。 +2. 继续补 `estimateCycleTime/resampleTrajectory`，为路径报告和回放采样做准备。 + +### 轮次 013 + +日期：2026-06-27 +关联任务：`KW-012` +本轮目标：实现节拍估算、轨迹重采样和诊断分级，为路径报告和回放采样提供基础 API。 + +做了什么： + +1. 新增 `CycleTimeResult/CycleTimeSegment` 明确类型。 +2. 实现 `estimateCycleTime`，支持单段 `TrajectoryResult` 和多段 `PathPlanResult`。 +3. 实现 `resampleTrajectory`，按固定 `sampleTime` 重采样轨迹点并保持首末点稳定。 +4. 重采样对关节、关节速度、关节加速度、flange 和 tcp 位置做线性插值。 +5. 空轨迹返回 `KDL_RESAMPLE_EMPTY_TRAJECTORY` warning。 +6. 非法采样时间抛出 `KDL_INVALID_SAMPLE_TIME` 结构化错误。 +7. 成功重采样追加 `KDL_TRAJECTORY_RESAMPLED` info 诊断。 +8. Worker runtime 和 `KdlWorkerClient` 暴露 `estimateCycleTime/resampleTrajectory`。 +9. 将 path 段内 points 的 `segmentId/sourceMap` 与合并 points 保持一致，便于节拍和诊断定位。 + +改了哪些文件： + +1. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/types.ts` +2. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/trajectoryUtils.ts` +3. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/runtime.ts` +4. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/kdlClient.ts` +5. `/home/meswork/kdl_work/kdl-wasm/web/src/robot/normalizedRobotModel.ts` +6. `/home/meswork/kdl_work/kdl-wasm/web/tests/kdl/trajectoryUtils.test.ts` +7. `/home/meswork/kdl_work/work/working1/03-推进台账.md` +8. `/home/meswork/kdl_work/work/working1/04-任务矩阵.md` +9. `/home/meswork/kdl_work/work/working1/05-验收证据.md` + +验证了什么： + +1. `npm run typecheck` 通过。 +2. `npm run test -- kdl cycle-time resample diagnostics` 通过，16 个测试文件共 63 个测试通过。 +3. `npm test` 通过，16 个测试文件共 63 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 + +问题和风险： + +1. 节拍估算当前只统计 KDL 运动时间，`waitTime/ioTime` 保留为 0，完整 IO/等待节拍需等 GRL `KW-106` 接入。 +2. 姿态重采样当前采用端点四元数选择的 P0 近似，完整 slerp 可在轨迹精度增强阶段补充。 +3. 重采样暂未输出 TCP 速度/加速度，后续若 UI 或后处理需要可从采样点差分扩展。 + +下一步： + +1. 执行 `KW-013`：C ABI / Embind 和性能优化。 +2. 梳理当前 C ABI 导出、JS 包装接口和 TypedArray/批量性能基线，补最小可验收测试。 + +### 轮次 014 + +日期：2026-06-27 +关联任务：`KW-013` +本轮目标：稳定 C ABI 导出和错误边界，补 TypedArray 高频 FK 接口，并记录性能基线。 + +做了什么： + +1. C++ C ABI 增加 RobotHandle 生命周期缓存：`kdl_create_robot/kdl_destroy_robot/kdl_get_robot_info`。 +2. `kdl_get_robot_info` 返回 JSON handle 信息，输出缓冲区不足时返回 `KDL_BUFFER_TOO_SMALL`。 +3. 保持计算类 C ABI 函数为显式 `KDL_NOT_IMPLEMENTED`，避免伪造尚未接入的 C++ solver 能力。 +4. 新增 `KdlNativeAbi`，封装 C ABI 导出检查、JSON 缓冲区读取、返回码检查和 `kdl_last_error` 结构化错误。 +5. 扩展 Emscripten native module 类型，覆盖 `cwrap/UTF8ToString/_malloc/_free`。 +6. 新增 `fkPose7`，通过 `Float64Array` 输入和可复用输出缓冲返回 TCP pose7。 +7. Worker runtime 和 `KdlWorkerClient` 暴露 `fkPose7`。 +8. 新增性能基线工具，记录 6 轴初始化、TypedArray FK、平面 IK、1000 点批量可达性、10 秒 4 ms 轨迹采样。 +9. 新增 C ABI、性能和 `fkPose7` 测试。 + +改了哪些文件： + +1. `/home/meswork/kdl_work/kdl-wasm/bindings/kdl_c_api.cpp` +2. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/nativeModule.ts` +3. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/nativeAbi.ts` +4. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/performanceBaseline.ts` +5. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/types.ts` +6. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/runtime.ts` +7. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/kdlClient.ts` +8. `/home/meswork/kdl_work/kdl-wasm/web/src/robot/normalizedRobotModel.ts` +9. `/home/meswork/kdl_work/kdl-wasm/web/tests/kdl/cAbi.test.ts` +10. `/home/meswork/kdl_work/kdl-wasm/web/tests/kdl/performance.test.ts` +11. `/home/meswork/kdl_work/kdl-wasm/web/tests/kdl/fk.test.ts` +12. `/home/meswork/kdl_work/work/working1/03-推进台账.md` +13. `/home/meswork/kdl_work/work/working1/04-任务矩阵.md` +14. `/home/meswork/kdl_work/work/working1/05-验收证据.md` + +验证了什么： + +1. `npm run typecheck` 通过。 +2. `cmake --build kdl-wasm/build-wasm -j16` 通过。 +3. `npm run test -- kdl c-abi performance` 通过，18 个测试文件共 68 个测试通过。 +4. `npm test` 通过，18 个测试文件共 70 个测试通过。 +5. 性能基线：6 轴初始化 3.536 ms；TypedArray FK 平均 0.019288 ms；平面 IK 平均 0.010930 ms；1000 点可达性 7.166 ms；10 秒 4 ms 轨迹 2526 点、48.864 ms。 + +问题和风险： + +1. C++ C ABI 当前稳定到导出、handle 生命周期和结构化错误边界，真实 FK/IK/Jacobian/轨迹求解仍由 TypeScript runtime 基线承载。 +2. 性能基线中的 IK 是当前支持的平面 Rz+Px 模型，不代表通用 6 轴 IK 性能。 +3. `fkPose7` 为 P0 高频 FK 输出，后续可继续补 `jacobian`/批量 FK 的 TypedArray 接口。 + +下一步： + +1. 进入 `KW-104`：GRL Path、event 和 `run_path`。 +2. 将 GRL path 语法编译到 `PathPlanRequest`，并保留 path point/source map/event 信息。 + +### 轮次 015 + +日期：2026-06-27 +关联任务：`KW-104` +本轮目标：实现 GRL Path、event 和 `run_path`，将 path 编译为 KDL `PathPlanRequest`。 + +做了什么： + +1. 将 `path` 从 raw top-level declaration 提升为结构化 `PathDeclaration` AST。 +2. 新增 `PathDefaultsBlock/PathSourceBlock/PathPoint/PathEvent` AST 类型。 +3. Parser 支持 `defaults/source/point/event before/after/at distance`。 +4. `PathPlanRequest` 扩展 `pathId/events/source`，`MotionSegmentRequest` 扩展 `targetId/source`。 +5. 新增 `compilePathToPlanRequest`，把 path point 编译为 `MotionSegmentRequest`。 +6. Path defaults 支持 `tool/frame/speed/zone`，优先级高于当前上下文。 +7. Source metadata 编译为 `PathPlanRequest.source`，并保留到每个 segment。 +8. Event 编译为 `PathEventRequest` metadata，保留 timing、pointId、distance、kind、statement、sourceMap。 +9. 新增 `parseProcedureRunPathStatements`，从 proc body token 提取 `run_path` 引用并保留 sourceMap。 +10. Motion target 支持 `OffsetExpression`，`movel pick offset z 100 mm` 可编译为 offset 后的 PoseTarget。 +11. 空 path、重复 point、event 引用缺失 point 均返回结构化错误。 + +改了哪些文件： + +1. `/home/meswork/kdl_work/kdl-wasm/web/src/kdl/types.ts` +2. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/ast/ast.ts` +3. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/ast/index.ts` +4. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/parser/parser.ts` +5. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/ir/motion.ts` +6. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/ir/index.ts` +7. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/semantic/compileData.ts` +8. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/semantic/compileMotion.ts` +9. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/semantic/index.ts` +10. `/home/meswork/kdl_work/kdl-wasm/web/tests/grl/pathCompile.test.ts` +11. `/home/meswork/kdl_work/work/working1/03-推进台账.md` +12. `/home/meswork/kdl_work/work/working1/04-任务矩阵.md` +13. `/home/meswork/kdl_work/work/working1/05-验收证据.md` + +验证了什么： + +1. `npm run typecheck` 通过。 +2. `npm run test -- grl path run_path event` 通过，6 个测试文件共 22 个测试通过。 +3. `npm test` 通过，19 个测试文件共 75 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 + +问题和风险： + +1. Event 当前保留为 metadata，具体 IO/Wait/Pulse IR 展开属于 `KW-106`。 +2. `run_path` 目前提取 path 引用和 sourceMap，完整执行流组合将在 `KW-105/KW-110` 继续增强。 +3. Path 的连续 blend/look-ahead 仍由 KDL 路径规划后续阶段处理，当前 GRL 编译只负责结构展开。 + +下一步： + +1. 执行 `KW-105`：Operation 和 `run_operation`。 +2. 解析 operation/process/actions，并将 `run_operation` 展开为 action + path + action 的 IR 骨架。 + +### 轮次 016 + +日期：2026-06-27 +关联任务：`KW-105` +本轮目标：实现 GRL Operation 和 `run_operation`，将 operation 展开为 start action、path、end action 的 IR 骨架。 + +做了什么： + +1. 将 `operation` 从 raw top-level declaration 提升为结构化 `OperationDeclaration` AST。 +2. 新增 `OperationProcessBlock/OperationActionBlock` AST 类型。 +3. Parser 支持 `kind/path/process/start_action/end_action`。 +4. 新增 Operation IR 类型：`CompiledOperation/OperationActionInstruction/RunOperationInstruction/OperationExecutionStep`。 +5. 新增 `compileOperation`，验证 operation 引用的 path 存在。 +6. Process 参数编译为 metadata，保留字符串、数值、identifier 和复合字面量。 +7. start/end action 编译为 metadata，保留 actionKind、operationId、statement 和 sourceMap。 +8. 新增 `parseProcedureRunOperationStatements`，从 proc body token 提取 `run_operation`。 +9. 新增 `expandRunOperation`，展开为 start action、`RUN_PATH`、end action。 +10. 缺失 path 返回 `GRL_OPERATION_PATH_NOT_FOUND`，缺失 operation 返回 `GRL_OPERATION_NOT_FOUND`。 + +改了哪些文件： + +1. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/ast/ast.ts` +2. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/ast/index.ts` +3. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/parser/parser.ts` +4. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/ir/motion.ts` +5. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/ir/index.ts` +6. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/semantic/compileMotion.ts` +7. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/semantic/index.ts` +8. `/home/meswork/kdl_work/kdl-wasm/web/tests/grl/operationCompile.test.ts` +9. `/home/meswork/kdl_work/work/working1/03-推进台账.md` +10. `/home/meswork/kdl_work/work/working1/04-任务矩阵.md` +11. `/home/meswork/kdl_work/work/working1/05-验收证据.md` + +验证了什么： + +1. `npm run typecheck` 通过。 +2. `npm run test -- grl operation run_operation` 通过，6 个测试文件共 23 个测试通过。 +3. `npm test` 通过，20 个测试文件共 79 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 + +问题和风险： + +1. Operation action 当前保留为 metadata，具体 IO/Wait/Pulse 语义将在 `KW-106` 展开。 +2. `expandRunOperation` 输出 IR 骨架，完整可执行 IR 调度仍属于 `KW-110`。 +3. KDL 边界仍只接收 Path 展开的 motion segment，operation action 不直接进入 KDL 运动规划。 + +下一步： + +1. 执行 `KW-106`：IO、wait 和 pulse。 +2. 解析 IO 地址、wait、pulse，并把 path/operation action metadata 展开为对应 IR。 + +### 轮次 017 + +日期：2026-06-27 +关联任务：`KW-106` +本轮目标：实现 GRL IO、wait 和 pulse 语义，将 procedure body、Path event 和 Operation action 中的 IO 语句展开为独立 IR，并保持 KDL 边界清晰。 + +做了什么： + +1. 新增 IO IR 类型：`IoReference/IoWriteInstruction/WaitInstruction/PulseInstruction/IoFlowInstruction`。 +2. 新增 `parseIoFlowStatements`，从 GRL token 编译 IO 写入、wait 和 pulse。 +3. 支持 `io.di/do/ai/ao/gi/go/ri/ro` 和 `io.alias.*`，并按 `IoMap.allowedRanges` 校验地址范围。 +4. 地址越界返回结构化错误 `GRL_IO_ADDRESS_NOT_FOUND`。 +5. `wait` 支持条件字符串、`timeout`、`on_timeout alarm` 和 `on_timeout call`。 +6. wait 条件覆盖 `all/any/rising/falling/changed` 表达式，并修正连续语句边界，避免 wait 吞掉后续 `pulse/io`。 +7. `pulse` 生成 set/reset trace，并将 `ms/s` 等单位归一化为秒。 +8. Operation action IR 保留原始 token，Path event metadata 保留原始 token，避免 statement 字符串丢失单位类型。 +9. 新增 `compilePathEventIo` 和 `compileOperationActionIo`，可将 Path event / Operation action metadata 展开为 IO/wait/pulse IR。 +10. statement fallback 使用 GRL lexer 重新解析，保持 `true/false` 和单位字面量类型正确。 +11. 新增 `ioCompile.test.ts` 覆盖 procedure IO 流、alias、地址校验、wait timeout/on_timeout、pulse trace、Path event 和 Operation action 展开。 + +改了哪些文件： + +1. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/ir/motion.ts` +2. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/ir/index.ts` +3. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/semantic/compileIo.ts` +4. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/semantic/compileMotion.ts` +5. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/semantic/index.ts` +6. `/home/meswork/kdl_work/kdl-wasm/web/tests/grl/ioCompile.test.ts` +7. `/home/meswork/kdl_work/work/working1/03-推进台账.md` +8. `/home/meswork/kdl_work/work/working1/04-任务矩阵.md` +9. `/home/meswork/kdl_work/work/working1/05-验收证据.md` + +验证了什么： + +1. `npm run typecheck` 通过。 +2. `npm run test -- grl io wait pulse` 通过，7 个测试文件共 28 个测试通过。 +3. `npm test` 通过，21 个测试文件共 84 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 + +问题和风险： + +1. `WaitInstruction.condition` 当前保留为字符串 IR，尚未建立布尔表达式 AST；更完整的静态类型检查归入 `KW-110`。 +2. IO/wait/pulse 当前作为独立 GRL IR，不直接进入 KDL；完整执行调度和与 path/operation 的顺序组合仍属于 `KW-110`。 +3. IO alias 只在可解析为 `IoReference` 的位置解析；wait 条件内部的 alias 仍以条件字符串保留。 + +下一步： + +1. 执行 `KW-107`：流程控制。 +2. 解析 `if/elseif/else`、`while`、`for`、`switch`、`break/continue`、`label/jump`，并补充结构化流程 IR 和非法跳转诊断。 + +### 轮次 018 + +日期：2026-06-27 +关联任务：`KW-107` +本轮目标：实现 GRL 流程控制语义层，将 procedure body token 编译为结构化流程 IR，并覆盖关键合法性诊断。 + +做了什么： + +1. 新增流程控制 IR 类型：`ControlExpression/RawProcedureStatement/IfInstruction/WhileInstruction/ForInstruction/SwitchInstruction/BreakInstruction/ContinueInstruction/LabelInstruction/JumpInstruction`。 +2. 新增 `parseProcedureControlFlow` 和 `parseControlFlowStatements`。 +3. 支持 `if/elseif/else`，每个分支保留条件文本、原始 token、sourceMap 和嵌套 body。 +4. 支持 `while` 和 `for i = from to to step step`，并维护 loop depth。 +5. 支持 `switch/case/default`，case 值编译为常量，重复 case/default 返回结构化错误。 +6. `break` 限定在 loop 或 switch 内，`continue` 限定在 loop 内。 +7. `label/jump` 支持重复 label、缺失 label 和跳入内层块诊断。 +8. 控制条件做 P0 bool 检查，明显数值/字符串条件报 `GRL_CONTROL_CONDITION_NOT_BOOL`。 +9. 未识别普通语句保留为 `RAW_STATEMENT`，便于后续 KW-110 将 motion/io/run 等 IR 统一组合。 +10. 新增 `controlFlow.test.ts` 覆盖正常流程树、非法条件、break/continue、switch case、label/jump。 + +改了哪些文件： + +1. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/ir/motion.ts` +2. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/ir/index.ts` +3. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/semantic/compileControlFlow.ts` +4. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/semantic/index.ts` +5. `/home/meswork/kdl_work/kdl-wasm/web/tests/grl/controlFlow.test.ts` +6. `/home/meswork/kdl_work/work/working1/03-推进台账.md` +7. `/home/meswork/kdl_work/work/working1/04-任务矩阵.md` +8. `/home/meswork/kdl_work/work/working1/05-验收证据.md` + +验证了什么： + +1. `npm run typecheck` 通过。 +2. `npm run test -- grl control-flow` 通过，8 个测试文件共 33 个测试通过。 +3. `npm test` 通过，22 个测试文件共 89 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 + +问题和风险： + +1. 条件 bool 检查目前是 P0 语法/字面量级别；基于 symbol table 的完整类型判断属于 `KW-110`。 +2. 普通语句暂存为 `RAW_STATEMENT`，完整可执行 IR 顺序组合属于 `KW-110`。 +3. label/jump 当前按块作用域防止跳入内层或兄弟块，未做更复杂的异常/多任务边界检查。 + +下一步： + +1. 执行 `KW-108`：proc、func、参数方向和作用域。 +2. 建立过程/函数签名、call/return 语义、参数方向检查和函数副作用限制。 + +### 轮次 019 + +日期：2026-06-27 +关联任务：`KW-108` +本轮目标：实现 GRL proc/func/call/return 语义检查，覆盖参数方向、返回路径、作用域和函数副作用限制。 + +做了什么： + +1. 将 `func` 从 `RawTopLevelDeclaration` 提升为结构化 `FunctionDeclaration` AST。 +2. Parser 支持 `func return_type name(params) ... end`，保留参数 token 和 body token。 +3. 新增 routine IR 类型：`ProcedureSignature/FunctionSignature/RoutineParameter/CallInstruction/ReturnInstruction/ProcFunctionAnalysis`。 +4. 新增 `analyzeProcFunctionSemantics`，统一建立 proc/func 签名表。 +5. 支持 `in/out/inout` 参数方向解析，默认参数方向为 `in`。 +6. `call` 检查目标存在、参数数量、基础类型兼容和 out/inout 左值。 +7. `out` 参数做所有正常返回路径赋值检查，并支持通过调用带 out/inout 参数的子过程完成赋值。 +8. `return` 检查 proc 不能带返回值，func 必须返回且返回类型兼容。 +9. func 默认禁止运动、`wait`、`pulse`、`run_path`、`run_operation` 和调用 procedure。 +10. 自递归和名称遮蔽以 warning diagnostic 返回。 +11. 新增 `procFunction.test.ts` 覆盖签名、call/return、out 赋值路径、左值检查、返回类型、函数副作用、递归 warning 和遮蔽 warning。 + +改了哪些文件： + +1. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/ast/ast.ts` +2. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/ast/index.ts` +3. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/parser/parser.ts` +4. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/ir/motion.ts` +5. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/ir/index.ts` +6. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/semantic/compileProcFunction.ts` +7. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/semantic/index.ts` +8. `/home/meswork/kdl_work/kdl-wasm/web/tests/grl/procFunction.test.ts` +9. `/home/meswork/kdl_work/work/working1/03-推进台账.md` +10. `/home/meswork/kdl_work/work/working1/04-任务矩阵.md` +11. `/home/meswork/kdl_work/work/working1/05-验收证据.md` + +验证了什么： + +1. `npm run typecheck` 通过。 +2. `npm run test -- grl proc func scope` 通过，9 个测试文件共 39 个测试通过。 +3. `npm test` 通过，23 个测试文件共 95 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 + +问题和风险： + +1. 参数和返回类型检查目前覆盖基础字面量、变量和简单函数调用，完整表达式类型推断仍归入 `KW-110`。 +2. out 赋值路径采用保守控制流合并模型，异常路径和复杂 early-exit 仍待 `KW-109/KW-110` 联合完善。 +3. 名称解析当前覆盖全局名、参数和本地声明，完整 symbol table 仍属于 `KW-110`。 + +下一步： + +1. 执行 `KW-109`：异常、报警、中断和多任务语法。 +2. P0 实现 alarm/raise/try/catch/finally 基础语义，P1 trap/interrupt/task 保留可解析结构和明确诊断。 + +### 轮次 020 + +日期：2026-06-27 +关联任务：`KW-109` +本轮目标：实现 GRL alarm/raise/try/catch/finally 基础语义，并为 P1 trap/interrupt/task 提供可解析结构和明确未实现诊断。 + +做了什么： + +1. 新增异常/报警 IR 类型：`AlarmInstruction/RaiseInstruction/TryInstruction/CatchInstruction/FinallyInstruction/UnsupportedRuntimeInstruction`。 +2. 新增 `parseProcedureExceptionFlow` 和 `parseExceptionFlowStatements`。 +3. 支持 procedure body 中的 `alarm`，保留 alarm id、message、severity 和 sourceMap。 +4. 支持 `raise alarm_id`。 +5. 支持 `try/catch/finally/end`，catch 可带 alarm id。 +6. `try` 没有 catch/finally 时返回 `GRL_TRY_HANDLER_MISSING`。 +7. `alarm` 或 `raise` 缺少 id 时返回结构化错误。 +8. 修正 top-level raw parser，使 `task ... cycle ... end` 按 end-style block 收集，不再要求 `{}`。 +9. `trap` 和 `task` 保留为完整 `RawTopLevelDeclaration` token block。 +10. 新增 `analyzeExceptionSemantics`，对 P1 trap/task 输出 `UNSUPPORTED_RUNTIME` 和 `GRL_P1_UNIMPLEMENTED` warning。 +11. procedure body 内 `enable/disable interrupt` 输出 `UNSUPPORTED_RUNTIME`，明确 P0 不执行。 +12. 新增 `exceptionCompile.test.ts` 覆盖 alarm/raise、try/catch/finally、trap/task raw 语法和 P1 未实现诊断。 + +改了哪些文件： + +1. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/parser/parser.ts` +2. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/ir/motion.ts` +3. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/ir/index.ts` +4. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/semantic/compileException.ts` +5. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/semantic/index.ts` +6. `/home/meswork/kdl_work/kdl-wasm/web/tests/grl/exceptionCompile.test.ts` +7. `/home/meswork/kdl_work/work/working1/03-推进台账.md` +8. `/home/meswork/kdl_work/work/working1/04-任务矩阵.md` +9. `/home/meswork/kdl_work/work/working1/05-验收证据.md` + +验证了什么： + +1. `npm run typecheck` 通过。 +2. `npm run test -- grl alarm interrupt task` 通过，10 个测试文件共 43 个测试通过。 +3. `npm test` 通过，24 个测试文件共 99 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 + +问题和风险： + +1. P1 trap/interrupt/task 当前只解析和诊断，不执行调度。 +2. 异常传播、finally 在复杂控制流中的执行顺序仍留给 `KW-110` 的统一 executable IR。 +3. alarm/raise 目前只编译为 IR，不接入运行时报警系统。 + +下一步： + +1. 执行 `KW-110`：语义检查、IR 和 source map。 +2. 统一 Motion/IO/Wait/Call/Branch/Alarm/Return 等 IR，补齐第 21 章语义检查和 source map 快照。 + +### 轮次 021 + +日期：2026-06-27 +关联任务：`KW-110` +本轮目标：实现统一 Semantic Analyzer、Executable IR、source map 聚合和 GRL 到 KDL request 的编译桥接。 + +做了什么： + +1. 新增统一语义 IR：`SemanticProgramIr/SemanticSymbol/SemanticSourceMapEntry/ExecutableProcedure/ExecutableInstruction`。 +2. 新增 executable control IR：`EXEC_IF/EXEC_WHILE/EXEC_FOR/EXEC_SWITCH`。 +3. 新增 `compileSemanticProgram`，组合前序数据、target、path、operation、IO、流程控制、proc/func、异常/报警分析结果。 +4. 输出 `symbols` 符号表，覆盖 data、target、path、operation、procedure、function、raw P1 declaration。 +5. 输出 22 项 `semanticChecks` 清单，对齐 GRL 第 21 章 P0 检查面。 +6. 统一 procedure executable IR，覆盖 Motion、IO、Wait、Pulse、RunPath、RunOperation、Call、Return、Branch、Alarm、UnsupportedRuntime。 +7. 通过 `kdlBridge.motionRequests` 将 executable motion 映射为 KDL request。 +8. 通过 `kdlBridge.pathRequests` 保留 PathPlanRequest。 +9. 聚合 source map，覆盖 procedure 行列、path point/event、operation action。 +10. 重复符号输出 `GRL_SYMBOL_DUPLICATE` diagnostic。 +11. 修正 motion 参数解析跨行边界，避免 motion 表达式吞掉下一行 IO/wait/control token。 +12. 新增 `semanticIr.test.ts` 覆盖完整程序、统一 IR、KDL bridge、source map 和重复符号诊断。 + +改了哪些文件： + +1. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/ir/motion.ts` +2. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/ir/index.ts` +3. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/semantic/compileMotion.ts` +4. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/semantic/compileSemantic.ts` +5. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/semantic/index.ts` +6. `/home/meswork/kdl_work/kdl-wasm/web/tests/grl/semanticIr.test.ts` +7. `/home/meswork/kdl_work/work/working1/03-推进台账.md` +8. `/home/meswork/kdl_work/work/working1/04-任务矩阵.md` +9. `/home/meswork/kdl_work/work/working1/05-验收证据.md` + +验证了什么： + +1. `npm run typecheck` 通过。 +2. `npm run test -- grl semantic ir sourcemap` 通过，11 个测试文件共 46 个测试通过。 +3. `npm test` 通过，25 个测试文件共 102 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 + +问题和风险： + +1. `semanticChecks` 当前是 P0 检查面清单，完整逐项 spec 编号映射可在规范文本稳定后继续细化。 +2. Executable IR 已统一主要 P0 指令，但虚拟控制器实际调度仍在后续任务中接入。 +3. KDL bridge 当前覆盖 motion/path request，IO、Alarm、Call、Branch 不直接调用 KDL，符合边界设计。 + +下一步： + +1. 执行 `KW-111`：ABB、FANUC、KUKA 后处理原型。 +2. 基于 `SemanticProgramIr` 输出三品牌后处理 golden file 和转换报告。 + +### 轮次 022 + +日期：2026-06-27 +关联任务：`KW-111` +本轮目标：实现 ABB RAPID、FANUC LS/TP 风格、KUKA KRL 三品牌后处理原型，并输出转换报告。 + +做了什么： + +1. 新增 `kdl-wasm/web/src/grl/post` 后处理模块。 +2. 新增 `postProcessBrand` 和 `postProcessAllBrands`，以 `SemanticProgramIr` 为输入。 +3. ABB RAPID 原型输出 `MODULE/PROC`、`MoveJ/MoveL/MoveC`、`SetDO`、`WaitUntil`、`PulseDO`。 +4. FANUC LS/TP 风格原型输出 `/PROG`、`/MN`、`J/L/C`、`DO`、`WAIT`、`PULSE`。 +5. KUKA KRL 原型输出 `DEF`、`PTP/LIN/CIRC`、`$OUT`、`WAIT FOR`、`PULSE`。 +6. speed/zone 映射覆盖 joint percent、linear speed、fine、distance zone。 +7. `post_hint abb` 对 ABB 生效，对 FANUC/KUKA 产生 `GRL_POST_HINT_IGNORED` report。 +8. 不支持的 executable IR 产生 `GRL_POST_UNSUPPORTED` report。 +9. 新增 `postProcessor.test.ts`，用 golden 字符串覆盖三品牌文本和转换报告。 + +改了哪些文件： + +1. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/post/postProcessor.ts` +2. `/home/meswork/kdl_work/kdl-wasm/web/src/grl/post/index.ts` +3. `/home/meswork/kdl_work/kdl-wasm/web/tests/post/postProcessor.test.ts` +4. `/home/meswork/kdl_work/work/working1/03-推进台账.md` +5. `/home/meswork/kdl_work/work/working1/04-任务矩阵.md` +6. `/home/meswork/kdl_work/work/working1/05-验收证据.md` + +验证了什么： + +1. `npm run typecheck` 通过。 +2. `npm run test -- post abb fanuc kuka` 通过，1 个测试文件共 2 个测试通过。 +3. `npm test` 通过，26 个测试文件共 104 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 + +问题和风险： + +1. FANUC 输出为 LS/TP 风格文本原型，并非完整 TP 二进制。 +2. 品牌扩展目前以 `post_hint` raw symbol 为主，`@brand.*` 装饰语法仍留作后续扩展。 +3. 后处理当前覆盖 P0 运动、IO、wait、pulse；更复杂流程控制展开策略可在后续虚拟控制器阶段细化。 + +下一步： + +1. 执行 `KW-112`：自动生成规则和往返。 +2. 生成稳定 GRL 文本，确保可 diff、可解析、可语义检查并可后处理。 diff --git a/04-任务矩阵.md b/04-任务矩阵.md new file mode 100644 index 0000000..f04c6ab --- /dev/null +++ b/04-任务矩阵.md @@ -0,0 +1,150 @@ +# 04-任务矩阵 + +版本：0.3 +日期：2026-06-27 + +## 1. 状态定义 + +| 状态 | 含义 | +| --- | --- | +| Todo | 尚未开始。 | +| Doing | 正在执行。 | +| Blocked | 被依赖、环境、设计问题阻塞。 | +| Review | 已实现，等待验证或复核。 | +| Done | 已实现且验收证据完整。 | + +## 2. 任务编号规则 + +| 编号范围 | 对标文档 | 说明 | +| --- | --- | --- | +| `KW-000` | 管理任务 | 文档维护和推进记录。 | +| `KW-001` 到 `KW-099` | `KDL_WASM计算接口设计.md` | KDL WASM API、轨迹、诊断、Worker、性能。 | +| `KW-100` 到 `KW-199` | `通用机器人编程语法规范.md` | GRL 语法、AST、语义、IR、后处理。 | + +## 3. 任务总表 + +| 编号 | 任务 | 状态 | 依赖 | 对标章节 | 验收标准 | +| --- | --- | --- | --- | --- | --- | +| KW-000 | 对标实施文档维护 | Done | 无 | 两份文档全文 | README、功能范围、开发步骤、任务矩阵、证据、ADR 已对齐两份源文档。 | +| KW-001 | WASM 工程骨架和 Worker RPC | Done | KW-000 | KDL 2、17、18、24 | `init/dispose`、RPC、结构化错误、Worker 加载通过测试。 | +| KW-002 | `NormalizedRobotModel` 到 KDL Chain | Done | KW-001 | KDL 6、22、24 | URDF 解析、标准模型、RobotHandle、机器人信息和限位测试通过。 | +| KW-003 | FK 和 fkAllLinks | Done | KW-002 | KDL 8.1、8.2、22、23 | FK golden 对比、link 位姿顺序和维度诊断通过。 | +| KW-004 | IK 和 ikBatch | Done | KW-003 | KDL 8.3、15、22、23 | IK 回代、批量顺序、失败原因和限位测试通过。 | +| KW-005 | Jacobian、奇异性和基础检查 | Done | KW-004 | KDL 8.4、15、22、23 | Jacobian、奇异性、关节限位、可达性、速度检查通过。 | +| KW-006 | 位姿变换和 offset | Done | KW-005 | KDL 7、21、22、23 | normalize/compose/inverse/applyToolAndFrame/applyOffset 测试通过。 | +| KW-007 | 梯形速度曲线 | Done | KW-006 | KDL 9、22、23 | trapezoid/triangle、采样单调、首末点规则通过。 | +| KW-008 | `planMoveJ` | Done | KW-007 | KDL 11、21、22、23 | 关节同起同停、限位、速度、zone 近似诊断通过。 | +| KW-009 | `planMoveL` | Done | KW-008 | KDL 12、21、22、23 | TCP 直线误差、逐点 IK、速度和加速度诊断通过。 | +| KW-010 | `planMoveC` | Done | KW-009 | KDL 13、21、22、23 | 圆弧元数据、退化诊断、逐点 IK 和误差测试通过。 | +| KW-011 | `planPath` 和 `validatePath` | Done | KW-010 | KDL 14、15、21、22、23 | Path 轨迹合并、段报告、source map、空路径诊断通过。 | +| KW-012 | 节拍估算、重采样和诊断报告 | Done | KW-011 | KDL 16、19、20、22、23 | CycleTime、resample、error/warning/info 分级通过。 | +| KW-013 | C ABI / Embind 和性能优化 | Done | KW-012 | KDL 18、19、24 | C ABI 稳定、TypedArray 批量接口和性能基线达标。 | +| KW-100 | Lexer、单位和关键字 | Done | KW-000 | GRL 4、24 | 注释、标识符、单位、保留关键字测试通过。 | +| KW-101 | Parser 和 AST 骨架 | Done | KW-100 | GRL 5、22、23、24 | 最小文件、完整示例、AST source range 和快照通过。 | +| KW-102 | 数据声明、类型系统和目标点 | Done | KW-101 | GRL 6、7、8、24 | tool/frame/speed/zone/target/offset 编译为共享类型。 | +| KW-103 | 运动指令和当前上下文 | Done | KW-102, KW-006 | GRL 9、20、21、24 | movej/movel/movec 编译为 MotionInstruction 和 KDL request。 | +| KW-104 | Path、event 和 `run_path` | Done | KW-103, KW-011 | GRL 10、18、20、21、24 | path 编译为 PathPlanRequest，event 和 source map 正确。 | +| KW-105 | Operation 和 `run_operation` | Done | KW-104 | GRL 11、20、21、24 | operation 展开为 action + path + action，引用检查正确。 | +| KW-106 | IO、wait 和 pulse | Done | KW-101 | GRL 12、20、21、24 | IO 地址、WaitInstruction、pulse 语义和 KDL 边界正确。 | +| KW-107 | 流程控制 | Done | KW-101 | GRL 13、20、21、24 | if/while/for/switch/break/continue/label/jump 语义检查通过。 | +| KW-108 | proc、func、参数方向和作用域 | Done | KW-101 | GRL 14、20、21、24 | 参数方向、返回路径、作用域、func 副作用检查通过。 | +| KW-109 | 异常、报警、中断和多任务语法 | Done | KW-101 | GRL 15、16、24 | alarm/raise/try/catch P0 可用，trap/interrupt/task 语法可表达。 | +| KW-110 | 语义检查、IR 和 source map | Done | KW-103, KW-104, KW-105, KW-106, KW-107, KW-108 | GRL 20、21、24；KDL 21 | 语法规范第 21 章检查项全部覆盖，IR 可调用 KDL。 | +| KW-111 | ABB、FANUC、KUKA 后处理原型 | Done | KW-110 | GRL 17、19、24 | 三品牌 golden file、post_hint、brand metadata 和转换报告通过。 | +| KW-112 | 自动生成规则和往返 | Todo | KW-111 | GRL 18、24 | 自动生成 GRL 稳定、可 diff、可解析回等价对象。 | + +## 4. KDL 子任务 + +### KW-001：WASM 工程骨架和 Worker RPC + +| 编号 | 内容 | 状态 | 验收 | +| --- | --- | --- | --- | +| KW-001.1 | 创建 `kdl-wasm` wrapper 工程 | Done | CMake 可配置。 | +| KW-001.2 | 编译 KDL WASM 产物 | Done | `kdl.js/kdl.wasm/kdl.d.ts` 存在。 | +| KW-001.3 | 定义 `KdlRpcRequest/KdlRpcResponse` | Done | 请求 id、method、payload、结构化错误完整。 | +| KW-001.4 | 实现 `kdl.worker.ts` | Done | Worker 加载 WASM 并响应 `init/dispose`。 | +| KW-001.5 | 实现 `KdlWorkerClient` | Done | Promise API 可用。 | + +### KW-002：`NormalizedRobotModel` 到 KDL Chain + +| 编号 | 内容 | 状态 | 验收 | +| --- | --- | --- | --- | +| KW-002.1 | URDF XML 解析 | Done | link/joint/origin/axis/limit 可读取。 | +| KW-002.2 | 连通性和单位检查 | Done | base/tip 不连通有诊断。 | +| KW-002.3 | 生成 `NormalizedRobotModel` | Done | activeJointNames 和 limits 稳定。 | +| KW-002.4 | WASM 创建 KDL Chain | Review | `createRobotFromModel` 返回 RobotHandle；当前为 TypeScript registry，真实 KDL Chain 绑定在 KW-003 起逐步接入。 | +| KW-002.5 | RobotHandle 生命周期 | Done | create/getInfo/getLimits/destroy 通过。 | + +### KW-003 到 KW-013：KDL P0 计算接口 + +| 编号 | 内容 | 状态 | 验收 | +| --- | --- | --- | --- | +| KW-003.1 | `fk` | Done | 返回 flange、tcp、diagnostics。 | +| KW-003.2 | `fkAllLinks` | Done | 返回 link pose 列表。 | +| KW-004.1 | `ik` | Done | 返回 joints、iterations、residual、reason。 | +| KW-004.2 | `ikBatch` | Done | 顺序保持。 | +| KW-005.1 | `jacobian` | Done | Float64Array 矩阵正确。 | +| KW-005.2 | `checkSingularity` | Done | manipulability 或 conditionNumber 可用。 | +| KW-005.3 | `checkJointLimits/checkVelocityLimits` | Done | 限位诊断正确。 | +| KW-005.4 | `checkReachability/checkReachabilityBatch` | Done | 可达性和失败原因正确。 | +| KW-006.1 | `normalizePose/composePose/inversePose` | Done | 位姿数值测试通过。 | +| KW-006.2 | `applyToolAndFrame/applyOffset` | Done | 与 GRL offset 语义一致。 | +| KW-007.1 | `makeTrapProfile/sampleTrapProfile` | Done | 采样规则正确。 | +| KW-008.1 | `planMoveJ` | Done | MOVEJ 运动测试通过。 | +| KW-009.1 | `planMoveL` | Done | MOVEL 运动测试通过。 | +| KW-010.1 | `planMoveC` | Done | MOVEC 运动测试通过。 | +| KW-011.1 | `planPath` | Done | 多段轨迹合并正确。 | +| KW-011.2 | `validatePath` | Done | 段报告和诊断正确。 | +| KW-012.1 | `estimateCycleTime/resampleTrajectory` | Done | 节拍和重采样正确。 | +| KW-013.1 | C ABI / Embind 稳定导出 | Done | TypeScript 可包装全部 P0 API。 | +| KW-013.2 | TypedArray 和批量性能 | Done | 性能指标有记录。 | + +## 5. GRL 子任务 + +### KW-100 到 KW-103：语法基础和运动 + +| 编号 | 内容 | 状态 | 验收 | +| --- | --- | --- | --- | +| KW-100.1 | Lexer token 和关键字 | Done | 保留关键字表覆盖规范。 | +| KW-100.2 | 单位规范化 | Done | 长度、角度、时间、速度、质量转换正确。 | +| KW-101.1 | EBNF parser | Done | 已覆盖 language/module/import/proc 和顶层 raw 声明骨架。 | +| KW-101.2 | AST source range | Done | 行列、注释过滤、单位原文保留在 token 中。 | +| KW-102.1 | 类型系统和变量声明 | Done | const/var/persistent 类型检查。 | +| KW-102.2 | tool/frame/target/speed/zone | Done | 编译为共享数据结构。 | +| KW-102.3 | offset/offset_in | Done | 编译为 `OffsetSpec`。 | +| KW-103.1 | movej/movel/movec parser | Done | 运动语句 AST 正确。 | +| KW-103.2 | 当前 tool/frame/speed/zone 解析 | Done | 参数优先级正确。 | +| KW-103.3 | MotionInstruction 到 KDL request | Done | KDL 调用关系正确。 | + +### KW-104 到 KW-110：Path、Operation、IO、流程和 IR + +| 编号 | 内容 | 状态 | 验收 | +| --- | --- | --- | --- | +| KW-104.1 | path defaults/source/point/event | Done | Path AST 正确。 | +| KW-104.2 | `run_path` 编译 | Done | 生成 `PathPlanRequest`。 | +| KW-105.1 | operation/process/actions | Done | Operation AST 正确。 | +| KW-105.2 | `run_operation` 展开 | Done | start action + path + end action。 | +| KW-106.1 | IO 地址和别名 | Done | IO map 校验正确。 | +| KW-106.2 | wait/pulse | Done | WaitInstruction 和 pulse IR 正确。 | +| KW-107.1 | 结构化流程控制 | Done | if/while/for/switch 语义正确。 | +| KW-107.2 | label/jump | Done | P1 语法和非法跳转诊断。 | +| KW-108.1 | proc/func/call/return | Done | 调用和返回检查正确。 | +| KW-108.2 | in/out/inout 和作用域 | Done | 左值、赋值路径、遮蔽 warning。 | +| KW-109.1 | alarm/raise/try/catch | Done | P0 异常基础语义。 | +| KW-109.2 | trap/interrupt/task | Done | P1 语法可解析。 | +| KW-110.1 | Semantic Analyzer | Done | 规范第 21 章 22 项检查覆盖。 | +| KW-110.2 | Executable IR | Done | Motion/Wait/Call/Branch/IO/Alarm/Return。 | +| KW-110.3 | Source map | Done | GRL 行列、path point、operation 可定位。 | + +### KW-111 到 KW-112：后处理和自动生成 + +| 编号 | 内容 | 状态 | 验收 | +| --- | --- | --- | --- | +| KW-111.1 | ABB RAPID 后处理 | Done | golden file 通过。 | +| KW-111.2 | FANUC LS/TP 风格后处理 | Done | golden file 通过。 | +| KW-111.3 | KUKA KRL 后处理 | Done | golden file 通过。 | +| KW-111.4 | post_hint 和 brand metadata | Done | 只影响指定品牌。 | +| KW-111.5 | 转换报告 | Done | 不支持和近似语义明确列出。 | +| KW-112.1 | target/path/operation 自动生成 | Todo | 命名稳定、defaults 和 override 正确。 | +| KW-112.2 | compact/expanded 输出 | Todo | 同一输入输出稳定。 | +| KW-112.3 | 生成后再解析 | Todo | 可恢复等价对象和 IR。 | diff --git a/05-验收证据.md b/05-验收证据.md new file mode 100644 index 0000000..47a288e --- /dev/null +++ b/05-验收证据.md @@ -0,0 +1,1169 @@ +# 05-验收证据 + +版本：0.3 +日期：2026-06-27 + +## 1. 记录规则 + +每条证据必须包含： + +1. 证据编号。 +2. 关联任务。 +3. 对标章节。 +4. 命令、页面、报告、截图、日志或产物路径。 +5. 执行环境。 +6. 结果摘要。 +7. 是否通过。 + +状态取值： + +| 状态 | 含义 | +| --- | --- | +| 待验证 | 任务未执行或证据未产生。 | +| 通过 | 结果满足验收标准。 | +| 不通过 | 已执行但不满足验收标准。 | +| 阻塞 | 因环境、依赖或设计问题无法验证。 | + +## 2. 环境基线 + +| 项 | 当前值 | +| --- | --- | +| 工作区 | `/home/meswork/kdl_work` | +| KDL 源码 | `/home/meswork/kdl_work/orocos_kinematics_dynamics/orocos_kdl` | +| KDL 对标文档 | `/home/meswork/kdl_work/work/doc/KDL_WASM计算接口设计.md` | +| GRL 对标文档 | `/home/meswork/kdl_work/work/doc/通用机器人编程语法规范.md` | +| 实施文档目录 | `/home/meswork/kdl_work/work/working1` | +| Emscripten | `emcc 6.0.0` | +| Node.js | `v22.23.0` | +| 浏览器 | 待 Playwright 安装后记录 | + +## 3. 管理证据 + +### EV-000：对标实施文档 + +关联任务：`KW-000` +对标章节：两份源文档全文 +类型：文件清单 +命令： + +```bash +find /home/meswork/kdl_work/work/working1 -maxdepth 1 -type f -print | sort +``` + +预期结果： + +```text +README.md +01-项目功能内容.md +02-项目程序开发详细步骤.md +03-推进台账.md +04-任务矩阵.md +05-验收证据.md +06-决策记录.md +``` + +结果摘要：待复核。 +是否通过：待验证。 + +## 4. KDL WASM 证据 + +### EV-001：WASM 工程和 Worker RPC + +关联任务：`KW-001` +对标章节：KDL 2、17、18、24 +类型：构建和单元测试 +命令： + +```bash +cd /home/meswork/kdl_work +npm run typecheck +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 +npm run test -- kdl rpc +node --input-type=module -e "import createKdlModule from './kdl-wasm/build-wasm/kdl.js'; const m=await createKdlModule({ locateFile: (p) => new URL('./kdl-wasm/build-wasm/' + p, import.meta.url).pathname }); const rc=m.ccall('kdl_init','number',['string'],['{}']); console.log(JSON.stringify({ rc, hasCwrap: typeof m.cwrap === 'function' }));" +``` + +预期产物： + +```text +kdl-wasm/build-wasm/kdl.js +kdl-wasm/build-wasm/kdl.wasm +kdl-wasm/build-wasm/kdl.d.ts +``` + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +cmake 3.22.1 +emcmake/emcc: /home/meswork/emsdk/upstream/emscripten +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. CMake 配置和 `cmake --build kdl-wasm/build-wasm -j16` 通过。 +3. 产物存在：`kdl-wasm/build-wasm/kdl.js`、`kdl-wasm/build-wasm/kdl.wasm`、`kdl-wasm/build-wasm/kdl.d.ts`。 +4. `npm run test -- kdl rpc` 通过，2 个测试文件共 11 个测试通过。 +5. Node 动态加载 `kdl.js` 并调用 `kdl_init`，输出 `{"rc":0,"hasCwrap":true}`。 +6. 当前 C ABI 在 `KW-013` 已补稳定导出、RobotHandle 生命周期和结构化错误边界；真实 FK/IK 和轨迹计算仍由 TypeScript runtime 基线承载。 + +是否通过：通过。 + +### EV-002：URDF 和 `NormalizedRobotModel` + +关联任务：`KW-002` +对标章节：KDL 6、22、23、24 +类型：单元测试 +命令： + +```bash +npm run typecheck +npm run test -- kdl urdf normalized-model +``` + +验证点： + +1. URDF link/joint/origin/axis/limit 解析。 +2. base/tip 连通性诊断。 +3. activeJointNames 顺序稳定。 +4. `createRobotFromModel/getRobotInfo/getJointLimits/destroyRobot`。 + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `npm run test -- kdl urdf normalized-model` 通过，4 个测试文件共 19 个测试通过。 +3. URDF 解析覆盖 link、joint、origin、axis、limit。 +4. `NormalizedRobotModel` 生成 `activeJointNames`、`limits`、`source.urdfHash`。 +5. base/tip 不连通、unsupported joint type 返回 `KDL_INVALID_MODEL` 结构化诊断。 +6. Worker runtime 支持 `loadRobotFromUrdf/createRobotFromModel/getRobotInfo/getJointLimits/destroyRobot` 的 RobotHandle 生命周期。 +7. 当前 RobotHandle 由 TypeScript registry 管理；真实 KDL `Tree/Chain` 和求解器绑定在后续 FK/IK 任务中接入。 + +是否通过：通过。 + +### EV-003：FK 和 fkAllLinks + +关联任务：`KW-003` +对标章节：KDL 8.1、8.2、22、23 +类型：单元测试 +命令： + +```bash +npm run typecheck +npm run test -- kdl fk +``` + +验证点： + +1. `fk` 返回 flange、tcp、joints、diagnostics。 +2. `fkAllLinks` 返回 link pose 列表。 +3. FK golden 数据误差在容差内。 +4. 关节维度错误返回结构化诊断。 + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `npm run test -- kdl fk` 通过，6 个测试文件共 28 个测试通过。 +3. `cmake --build kdl-wasm/build-wasm -j16` 回归通过。 +4. `fk` 返回 `ok/flange/tcp/joints/diagnostics`。 +5. `fkAllLinks` 返回 base-to-tip link pose 顺序。 +6. 覆盖零位 FK、revolute + prismatic 关节、tool TCP 偏移、link 顺序和关节维度结构化诊断。 +7. 当前 FK 为 TypeScript 标准模型数值基线，真实 Orocos KDL solver 对比可在后续 WASM 求解器接入时补充 golden 对比。 + +是否通过：通过。 + +### EV-004：IK 和 ikBatch + +关联任务：`KW-004` +对标章节：KDL 8.3、15、22、23 +类型：单元测试 +命令： + +```bash +npm run typecheck +npm run test -- kdl ik +``` + +验证点： + +1. IK 后 FK 回代误差小于容差。 +2. `ikBatch` 顺序保持。 +3. seed、多 seed、qMin/qMax、maxIterations 生效。 +4. 不可达、限位、奇异、迭代失败原因稳定。 + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `npm run test -- kdl ik` 通过，8 个测试文件共 34 个测试通过。 +3. `ik` 返回 `ok/joints/iterations/residualPosition/residualOrientation/reason/diagnostics`。 +4. 覆盖可达目标 IK、FK 回代误差、`ikBatch` 顺序保持、关节限位失败、unsupported model 的 `invalid_model` reason。 +5. 当前 IK 为 TypeScript 基线几何求解器，支持 single-prismatic 和 Rz+Px 链；通用 6 轴迭代 IK 与真实 Orocos KDL solver 接入后继续扩展。 + +是否通过：通过。 + +### EV-005：Jacobian、奇异性和检查 API + +关联任务：`KW-005` +对标章节：KDL 8.4、15、22、23 +类型：单元测试 +命令： + +```bash +npm run typecheck +npm run test -- kdl jacobian checks +``` + +验证点： + +1. Jacobian rows/cols/data 正确。 +2. 奇异点 warning。 +3. 关节限位、速度限位、可达性诊断。 +4. 批量可达性结果与输入一一对应。 + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `npm run test -- kdl jacobian checks` 通过，9 个测试文件共 38 个测试通过。 +3. `npm test` 通过，9 个测试文件共 38 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 +5. `jacobian` 返回 `ok/rows/cols/data/diagnostics`，覆盖 6 x dof 矩阵和关键线速度分量。 +6. `checkSingularity` 返回 `nearSingularity/manipulability/conditionNumber`，奇异场景返回 `KDL_SINGULARITY` warning。 +7. `checkJointLimits/checkVelocityLimits` 返回 `KDL_JOINT_LIMIT/KDL_VELOCITY_LIMIT/KDL_ACCEL_LIMIT` 结构化诊断。 +8. `checkReachability/checkReachabilityBatch` 基于 IK 返回可达性、关节解、残差和批量顺序。 + +是否通过：通过。 + +### EV-006：位姿变换和 offset + +关联任务：`KW-006` +对标章节：KDL 7、21、22、23 +类型：单元测试 +命令： + +```bash +npm run typecheck +npm run test -- kdl pose offset +npm test +cmake --build kdl-wasm/build-wasm -j16 +``` + +验证点： + +1. `normalizePose` 处理 `pose/poseq`。 +2. `composePose/inversePose` 数值正确。 +3. `applyToolAndFrame` 与 GRL tool/frame 语义一致。 +4. `applyOffset` 支持 frame/tool/world。 + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `npm run test -- kdl pose offset` 通过，10 个测试文件共 43 个测试通过。 +3. `npm test` 通过，10 个测试文件共 43 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 +5. `normalizePose` 支持 `position/quaternion`、`xyz/rpy`、`xyz/quat`，并规范化四元数。 +6. `composePose/inversePose` 覆盖平移组合和逆变换回到 identity。 +7. `applyToolAndFrame` 按当前 FK 约定执行 `frame * target.pose * tool`。 +8. `applyOffset` 覆盖 `frame/world` 左乘偏移、`tool` 右乘偏移，并保留目标点元数据。 +9. 非法位姿输入返回 `KDL_INVALID_POSE` 结构化诊断。 + +是否通过：通过。 + +### EV-007：梯形速度曲线 + +关联任务：`KW-007` +对标章节：KDL 9、22、23 +类型：单元测试 +命令： + +```bash +npm run typecheck +npm run test -- kdl trap-profile +npm test +cmake --build kdl-wasm/build-wasm -j16 +``` + +验证点： + +1. 长距离为 trapezoid。 +2. 短距离为 triangle。 +3. 首末采样点严格对应 `s=0` 和 `s=1`。 +4. `s` 单调递增。 + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `npm run test -- kdl trap-profile` 通过，11 个测试文件共 47 个测试通过。 +3. `npm test` 通过，11 个测试文件共 47 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 +5. 长距离场景生成 trapezoid，覆盖 `tAccel/tConst/tDecel/duration/vPeak`。 +6. 短距离场景自动退化为 triangle，并输出 `KDL_TRAP_TRIANGLE_PROFILE` info 诊断。 +7. `makeTrapProfile` 返回完整 profile 和 samples，`sampleTrapProfile` 返回同一采样规则下的 samples。 +8. 首末采样点严格对应 `s=0` 和 `s=1`，采样时间和 `s` 单调递增。 +9. 非法输入返回 `KDL_INVALID_TRAP_PROFILE` 结构化诊断。 + +是否通过：通过。 + +### EV-008：MOVEJ 轨迹 + +关联任务：`KW-008` +对标章节：KDL 11、21、22、23 +类型：运动测试 +命令： + +```bash +npm run typecheck +npm run test -- kdl movej planMoveJ +npm test +cmake --build kdl-wasm/build-wasm -j16 +``` + +验证点： + +1. 关节同起同停。 +2. `joint_target` 和 `pose_target` 两类目标。 +3. FK 输出 TCP。 +4. 限位、速度、加速度、奇异性诊断。 +5. 非 fine zone 返回 `KDL_ZONE_APPROX_FINE`。 + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `npm run test -- kdl movej planMoveJ` 通过，12 个测试文件共 51 个测试通过。 +3. `npm test` 通过，12 个测试文件共 51 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 +5. `planMoveJ` 支持 `joint_target` 直接规划和 `pose_target` IK 求终点关节。 +6. 轨迹点输出 `time/dt/s/sd/sdd/joints/jointVelocity/jointAcceleration/flange/tcp`。 +7. 使用梯形速度曲线生成关节同步轨迹，首末点速度归零。 +8. 终点关节限位失败返回 `TrajectoryResult.ok=false` 和 `KDL_JOINT_LIMIT`。 +9. 速度、加速度保持在 joint limits 内；非 fine zone 返回 `KDL_ZONE_APPROX_FINE` warning；采样点奇异性返回 `KDL_SINGULARITY` warning。 + +是否通过：通过。 + +### EV-009：MOVEL 轨迹 + +关联任务：`KW-009` +对标章节：KDL 12、21、22、23 +类型：运动测试 +命令： + +```bash +npm run typecheck +npm run test -- kdl movel planMoveL +npm test +cmake --build kdl-wasm/build-wasm -j16 +``` + +验证点： + +1. 起点 FK。 +2. 目标 tool/frame/offset。 +3. TCP 直线误差。 +4. 逐点 IK 连续。 +5. 速度、加速度、姿态误差和配置突变诊断。 + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `npm run test -- kdl movel planMoveL` 通过，13 个测试文件共 54 个测试通过。 +3. `npm test` 通过，13 个测试文件共 54 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 +5. `planMoveL` 使用起点 FK 得到 TCP 起点，按 TCP 直线生成采样 pose。 +6. 每个采样点逐点 IK，seed 使用上一采样点关节解。 +7. 轨迹点输出 `MOVEL` 的 `joints/jointVelocity/jointAcceleration/flange/tcp`。 +8. 可达直线测试覆盖 TCP 直线误差和终点 TCP；不可达采样点返回 `TrajectoryResult.ok=false` 和 `KDL_JOINT_LIMIT`。 +9. 非 linear speed 返回 `KDL_MOVEL_JOINT_SPEED_APPROX` warning；非 fine zone 返回 `KDL_ZONE_APPROX_FINE` warning。 + +是否通过：通过。 + +### EV-010：MOVEC 轨迹 + +关联任务：`KW-010` +对标章节：KDL 13、21、22、23 +类型：运动测试 +命令： + +```bash +npm run typecheck +npm run test -- kdl movec planMoveC +npm test +cmake --build kdl-wasm/build-wasm -j16 +``` + +验证点： + +1. 圆心、半径、法向、角度、弧长正确。 +2. `TrajectoryResult.meta.circle` 包含 `CirclePlanMeta`。 +3. 三点共线返回 `KDL_ARC_DEGENERATE`。 +4. 逐点 IK 和圆弧误差诊断。 + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `npm run test -- kdl movec planMoveC` 通过，14 个测试文件共 57 个测试通过。 +3. `npm test` 通过，14 个测试文件共 57 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 +5. `planMoveC` 基于起点 TCP、via、target 三点计算圆心、半径、法向、角度和弧长。 +6. `TrajectoryResult.meta.circle` 包含 `center/radius/normal/angle/length/direction/maxArcError`。 +7. 圆弧采样逐点 IK，seed 使用上一采样点关节解。 +8. 三点重合或共线返回 `TrajectoryResult.ok=false` 和 `KDL_ARC_DEGENERATE`。 +9. 非 linear speed 返回 `KDL_MOVEC_JOINT_SPEED_APPROX` warning；非 fine zone 返回 `KDL_ZONE_APPROX_FINE` warning。 + +是否通过：通过。 + +### EV-011：Path 规划和验证 + +关联任务：`KW-011` +对标章节：KDL 14、15、21、22、23 +类型：集成测试 +命令： + +```bash +npm run typecheck +npm run test -- kdl path validation +npm test +cmake --build kdl-wasm/build-wasm -j16 +``` + +验证点： + +1. `planPath` 多段轨迹合并。 +2. `validatePath` 返回 `PathValidationResult`。 +3. 空路径返回 `KDL_PATH_EMPTY`。 +4. segmentId、targetId、sourceMap 保留。 + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `npm run test -- kdl path validation` 通过，15 个测试文件共 60 个测试通过。 +3. `npm test` 通过，15 个测试文件共 60 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 +5. `PathPlanRequest/MotionSegmentRequest/PathPlanResult/PathValidationResult` 已从占位类型改为明确结构。 +6. `planPath` 按段调用 `planMoveJ/planMoveL/planMoveC`，并用上一段终点关节作为下一段起点。 +7. 合并轨迹点重新编号并更新时间，保留 `segmentId/targetId/sourceMap`。 +8. `validatePath` 返回 `segmentReports`、`cycleTime`、速度/加速度比例和诊断。 +9. 空路径返回 `TrajectoryResult.ok=false` 风格的 `KDL_PATH_EMPTY` 诊断。 + +是否通过：通过。 + +### EV-012：节拍估算、重采样和诊断 + +关联任务：`KW-012` +对标章节：KDL 16、19、20、22、23 +类型：单元测试 +命令： + +```bash +npm run typecheck +npm run test -- kdl cycle-time resample diagnostics +npm test +cmake --build kdl-wasm/build-wasm -j16 +``` + +验证点： + +1. `estimateCycleTime` 只计算运动时间。 +2. `resampleTrajectory` 时间和点序稳定。 +3. error/warning/info 分级正确。 +4. KDL API 不抛裸字符串错误。 + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `npm run test -- kdl cycle-time resample diagnostics` 通过，16 个测试文件共 63 个测试通过。 +3. `npm test` 通过，16 个测试文件共 63 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 +5. `estimateCycleTime` 支持单段 `TrajectoryResult` 和多段 `PathPlanResult`，当前只统计 KDL 运动时间，`waitTime/ioTime` 保留为 0。 +6. `resampleTrajectory` 按固定 `sampleTime` 重采样，首末点保持稳定，时间单调并重新编号。 +7. 重采样对关节、速度、加速度、flange 和 tcp 位置做线性插值，并输出 `KDL_TRAJECTORY_RESAMPLED` info。 +8. 空轨迹重采样返回 `KDL_RESAMPLE_EMPTY_TRAJECTORY` warning；非法采样时间抛出 `KDL_INVALID_SAMPLE_TIME` 结构化错误。 +9. Path 段级 points 也保留 `segmentId/sourceMap`，便于节拍估算和诊断报告定位。 + +是否通过：通过。 + +### EV-013：C ABI、Embind 和性能 + +关联任务：`KW-013` +对标章节：KDL 18、19、24 +类型：构建、性能报告 +命令： + +```bash +npm run typecheck +cmake --build kdl-wasm/build-wasm -j16 +npm run test -- kdl c-abi performance +npm test +``` + +指标： + +| 指标 | 结果 | +| --- | --- | +| 单机器人 6 轴初始化 | 3.536 ms，目标 < 1000 ms | +| 单次 FK | `fkPose7` TypedArray 平均 0.019288 ms，目标 < 1 ms | +| 单次 IK | 平面 Rz+Px IK 平均 0.010930 ms，目标 < 10 ms | +| 1000 个目标点批量可达性 | 7.166 ms，目标 < 500 ms | +| 10 秒轨迹 4 ms 采样 | 2526 点，48.864 ms，目标 < 500 ms | + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +Emscripten emcc 6.0.0 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `cmake --build kdl-wasm/build-wasm -j16` 通过。 +3. `npm run test -- kdl c-abi performance` 通过，18 个测试文件共 68 个测试通过。 +4. `npm test` 通过，18 个测试文件共 70 个测试通过。 +5. C ABI 稳定导出 `kdl_init/create_robot/destroy_robot/get_robot_info/fk/fk_all_links/jacobian/ik/plan_movej/plan_movel/plan_movec/plan_path/sample_trap/last_error`。 +6. C++ ABI 现支持 `kdl_create_robot/kdl_destroy_robot/kdl_get_robot_info` 的 handle 生命周期和 JSON 输出。 +7. C ABI 失败统一通过 `kdl_last_error` 返回结构化 `code/message/diagnostics`，覆盖 `KDL_NOT_IMPLEMENTED` 和 `KDL_BUFFER_TOO_SMALL`。 +8. 新增 `KdlNativeAbi` 封装 C ABI 导出检查、缓冲区读取、返回码检查和错误归一化。 +9. 新增 `fkPose7` TypedArray 高频 FK 接口，支持复用输出缓冲区并覆盖输出维度错误。 +10. 性能基线已记录 6 轴初始化、TypedArray FK、平面 IK、1000 点批量可达性和 10 秒 4 ms 轨迹采样。 +11. 真实通用 6 轴 IK/轨迹求解仍按当前 TypeScript baseline 能力覆盖；后续接入 Orocos KDL solver 时复用本轮 ABI 和性能测试作为回归基线。 + +是否通过：通过。 + +## 5. GRL 证据 + +### EV-100：Lexer、单位和关键字 + +关联任务：`KW-100` +对标章节：GRL 4、24 +类型：单元测试 +命令： + +```bash +npm run typecheck +npm run test -- grl lexer units +``` + +验证点： + +1. 注释、标识符、字符串、数字。 +2. 保留关键字表。 +3. 长度、角度、时间、质量、速度、加速度单位规范化。 + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `npm run test -- grl lexer` 通过，1 个测试文件 5 个测试通过。 +3. Lexer 覆盖单行/多行注释、关键字、标识符、字符串、数字、source range 和 EOF token。 +4. 关键字表覆盖 GRL 规范第 4.5 节 85 个保留关键字。 +5. 单位规范化覆盖 `mm/m/deg/rad/mm/s/%/ms/kg/mm/s2`，`100 mm -> 0.1 m`、`180 deg -> pi rad`、`300 mm/s -> 0.3 m/s` 通过。 + +是否通过：通过。 + +### EV-101：Parser 和 AST + +关联任务：`KW-101` +对标章节：GRL 5、22、23、24 +类型：parser 测试和 snapshot +命令： + +```bash +npm run typecheck +npm run test -- grl parser ast +``` + +验证点： + +1. 最小文件解析。 +2. 第 23 章完整示例解析。 +3. AST source range、注释、单位原文、metadata。 +4. 非法语法行列号。 + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `npm run test -- grl parser ast` 通过，2 个测试文件共 8 个测试通过。 +3. 最小文件 `language grl 0.1 / module / proc / end` 可解析。 +4. AST 保留 `LanguageDeclaration`、`ModuleDeclaration`、`ImportDeclaration`、`ProcedureDeclaration` 和 source range。 +5. 顶层 `const/target/path/operation/func/trap/task/post_hint` 当前保留为 RawTopLevelDeclaration，后续 KW-102 到 KW-109 逐步细化。 +6. 非法语法错误行列号稳定。 + +是否通过：通过。 + +### EV-102：类型、数据声明和目标点 + +关联任务：`KW-102` +对标章节：GRL 6、7、8、24 +类型：单元测试 +命令： + +```bash +npm run typecheck +npm run test -- grl types declarations targets +``` + +验证点： + +1. `const/var/persistent`。 +2. `tool/frame/load`。 +3. `joint_target/pose_target`。 +4. `pose/poseq/robot_config/ext_axis`。 +5. `speed/zone/offset/offset_in` 编译为共享结构。 + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `npm run test -- grl types declarations targets` 通过，3 个测试文件共 12 个测试通过。 +3. Parser 结构化输出 `DataDeclaration`、`TargetDeclaration`、表达式 AST、对象表达式、数组、调用和 offset 表达式。 +4. `tool/frame` 可编译为包含 TCP/origin 的共享结构。 +5. `joint_target/pose_target` 可编译为 `JointTarget/PoseTarget`，单位规范化为 SI。 +6. `speed/zone` 可编译为 `SpeedSpec/ZoneSpec`。 +7. `offset/offset_in tool` 可编译为 `OffsetSpec`。 + +是否通过：通过。 + +### EV-103：运动指令 + +关联任务：`KW-103` +对标章节：GRL 9、20、21、24；KDL 21 +类型：单元测试、集成测试 +命令： + +```bash +npm run typecheck +npm run test -- grl motion +npm test +``` + +验证点： + +1. `movej/movel/movec` AST。 +2. tool/frame/speed/zone 参数优先级。 +3. MotionInstruction。 +4. KDL `MoveJRequest/MoveLRequest/MoveCRequest`。 + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `npm run test -- grl motion` 通过，4 个测试文件共 14 个测试通过。 +3. `npm test` 通过，8 个测试文件共 34 个测试通过。 +4. `movej/movel/movec` 可从 `proc` body token 编译为 `MotionInstruction`。 +5. 当前 `set_tool/set_frame/set_speed/set_zone` 可作为运行上下文默认值。 +6. 显式 motion 参数优先于当前上下文。 +7. `MotionInstruction` 可编译为 `MoveJRequest/MoveLRequest/MoveCRequest`，包含 startJoints、target/via、speed、zone、tool、frame、sampleTime、sourceMap。 +8. 预留命令 `npm run test -- integration grl-kdl-motion` 当前无独立测试文件，集成点由 `grl motion` 和全量测试覆盖。 + +是否通过：通过。 + +### EV-104：Path 和 `run_path` + +关联任务：`KW-104` +对标章节：GRL 10、18、20、21、24；KDL 14、21 +类型：单元测试、集成测试 +命令： + +```bash +npm run typecheck +npm run test -- grl path run_path event +npm test +cmake --build kdl-wasm/build-wasm -j16 +``` + +验证点： + +1. `defaults/source/point/event`。 +2. 空 Path、重复点名诊断。 +3. `run_path` 编译为 `PathPlanRequest`。 +4. source map 到 path point。 + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `npm run test -- grl path run_path event` 通过，6 个测试文件共 22 个测试通过。 +3. `npm test` 通过，19 个测试文件共 75 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 +5. Parser 将 `path` 从 raw declaration 提升为 `PathDeclaration`，覆盖 `defaults/source/point/event before/after/at distance`。 +6. Path defaults 支持 tool、frame、speed、zone，并按高于当前控制器上下文的优先级应用到 point motion。 +7. Source metadata 编译为 `PathPlanRequest.source`，数值单位规范化，例如 `5 mm -> 0.005`。 +8. Path point 编译为 `MotionSegmentRequest`，保留 point id、targetId、sourceMap 和 source metadata。 +9. `run_path` 从 procedure body token 编译为 `RunPathInstruction`，保留 sourceMap。 +10. Event 当前编译为 `PathEventRequest` metadata，保留 timing、pointId、distance、kind、statement 和 sourceMap；具体 IO/Wait/Pulse IR 在 `KW-106` 展开。 +11. 空 Path 返回 `GRL_PATH_EMPTY`，重复 point 返回 `GRL_PATH_POINT_DUPLICATE`，event 引用缺失 point 返回 `GRL_PATH_EVENT_POINT_NOT_FOUND`。 + +是否通过：通过。 + +### EV-105：Operation 和 `run_operation` + +关联任务：`KW-105` +对标章节：GRL 11、20、21、24；KDL 14 +类型：单元测试 +命令： + +```bash +npm run typecheck +npm run test -- grl operation run_operation +npm test +cmake --build kdl-wasm/build-wasm -j16 +``` + +验证点： + +1. `operation kind/path/process/start_action/end_action`。 +2. Operation 引用不存在 Path 报错。 +3. `run_operation` 展开后 KDL 只处理 motion segment。 + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `npm run test -- grl operation run_operation` 通过，6 个测试文件共 23 个测试通过。 +3. `npm test` 通过，20 个测试文件共 79 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 +5. Parser 将 `operation` 从 raw declaration 提升为 `OperationDeclaration`，覆盖 `kind/path/process/start_action/end_action`。 +6. `compileOperation` 验证 operation 引用的 path 存在，缺失时报 `GRL_OPERATION_PATH_NOT_FOUND`。 +7. Process 参数编译为 metadata，保留数值、字符串和 identifier。 +8. start/end action 编译为 `OperationActionInstruction` metadata，保留 actionKind、operationId、statement、sourceMap。 +9. `parseProcedureRunOperationStatements` 从 procedure body token 提取 `run_operation` 并保留 sourceMap。 +10. `expandRunOperation` 展开为 start action、`RUN_PATH`、end action；缺失 operation 报 `GRL_OPERATION_NOT_FOUND`。 +11. KDL 仍只接收 Path 展开后的 motion segment；operation action 的 IO/Wait/Pulse 语义在 `KW-106` 继续展开。 + +是否通过：通过。 + +### EV-106：IO、wait 和 pulse + +关联任务：`KW-106` +对标章节：GRL 12、20、21、24；KDL 21.1 +类型：单元测试 +命令： + +```bash +npm run typecheck +npm run test -- grl io wait pulse +npm test +cmake --build kdl-wasm/build-wasm -j16 +``` + +验证点： + +1. IO 地址和别名。 +2. wait 条件、timeout、on_timeout。 +3. all/any/rising/falling/changed。 +4. pulse IR。 +5. IO/wait/pulse 不直接调用 KDL。 + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `npm run test -- grl io wait pulse` 通过，7 个测试文件共 28 个测试通过。 +3. `npm test` 通过，21 个测试文件共 84 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 +5. 新增 `IoWriteInstruction/WaitInstruction/PulseInstruction/IoFlowInstruction`，覆盖 IO 写入、等待和脉冲 IR。 +6. `parseIoFlowStatements` 支持 `io.di/do/ai/ao/gi/go/ri/ro`、`io.alias.*`、IO map 范围校验和 `GRL_IO_ADDRESS_NOT_FOUND`。 +7. `wait` 支持条件字符串、`timeout`、`on_timeout alarm/call`，并覆盖 `all/any/rising/falling/changed` 条件表达。 +8. `pulse` 生成 set/reset trace，单位归一化保留到秒。 +9. `compilePathEventIo` 和 `compileOperationActionIo` 可将 Path event / Operation action metadata 展开为 IO/wait/pulse IR。 +10. Path/Operation action token 原样保留，statement fallback 使用 GRL lexer，确保 `true/false` 和 `ms/s` 单位类型正确。 +11. KDL 边界保持不变：IO/wait/pulse 不进入 KDL motion segment 或 wasm 运动规划。 + +是否通过：通过。 + +### EV-107：流程控制 + +关联任务：`KW-107` +对标章节：GRL 13、20、21、24 +类型：单元测试 +命令： + +```bash +npm run typecheck +npm run test -- grl control-flow +npm test +cmake --build kdl-wasm/build-wasm -j16 +``` + +验证点： + +1. if/elseif/else。 +2. while/for/switch。 +3. break/continue 合法性。 +4. label/jump 规则。 +5. jump 进入非法块结构诊断。 + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `npm run test -- grl control-flow` 通过，8 个测试文件共 33 个测试通过。 +3. `npm test` 通过，22 个测试文件共 89 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 +5. 新增流程控制 IR：`IfInstruction/WhileInstruction/ForInstruction/SwitchInstruction/BreakInstruction/ContinueInstruction/LabelInstruction/JumpInstruction`。 +6. `parseProcedureControlFlow` 从 procedure body token 编译结构化流程控制树。 +7. `if/elseif/else`、`while`、`for`、`switch/case/default` 均保留 sourceMap、条件/表达式文本和原始 token。 +8. 条件表达式做 P0 bool 检查，明显数值/字符串条件报 `GRL_CONTROL_CONDITION_NOT_BOOL`。 +9. `break/continue` 做位置合法性检查，非法位置分别报 `GRL_BREAK_OUTSIDE_FLOW` 和 `GRL_CONTINUE_OUTSIDE_LOOP`。 +10. switch case 要求常量表达式，重复 case/default 会报结构化错误。 +11. label/jump 做重复、缺失和跳入内层块检查，覆盖 `GRL_LABEL_DUPLICATE`、`GRL_LABEL_NOT_FOUND`、`GRL_JUMP_INTO_BLOCK`。 + +是否通过：通过。 + +### EV-108：proc、func、参数方向和作用域 + +关联任务：`KW-108` +对标章节：GRL 14、20、21、24 +类型：单元测试 +命令： + +```bash +npm run typecheck +npm run test -- grl proc func scope +npm test +cmake --build kdl-wasm/build-wasm -j16 +``` + +验证点： + +1. proc/call/return。 +2. func 返回路径。 +3. in/out/inout。 +4. out 所有正常返回路径赋值。 +5. func 非法副作用诊断。 +6. 名称解析和遮蔽 warning。 + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `npm run test -- grl proc func scope` 通过，9 个测试文件共 39 个测试通过。 +3. `npm test` 通过，23 个测试文件共 95 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 +5. `func` 从 raw top-level declaration 提升为结构化 `FunctionDeclaration`。 +6. 新增 procedure/function signature IR，支持 `in/out/inout` 参数方向。 +7. `analyzeProcFunctionSemantics` 建立 proc/func 签名表，解析 `call` 和 `return`。 +8. `out/inout` 实参必须为左值，参数数量和基础类型不匹配会返回结构化错误。 +9. `out` 参数做正常返回路径赋值检查，支持通过 `call` 写入 out/inout 实参。 +10. `func` 检查缺失返回、返回类型不兼容、proc return value 非法。 +11. `func` 默认禁止运动、wait、pulse、run_path、run_operation 和调用 proc。 +12. 名称遮蔽和自递归以 warning diagnostic 返回。 + +是否通过：通过。 + +### EV-109：异常、报警、中断和多任务语法 + +关联任务：`KW-109` +对标章节：GRL 15、16、24 +类型：单元测试 +命令： + +```bash +npm run typecheck +npm run test -- grl alarm interrupt task +npm test +cmake --build kdl-wasm/build-wasm -j16 +``` + +验证点： + +1. alarm/raise。 +2. try/catch/finally。 +3. trap/interrupt 语法。 +4. task cycle 语法。 +5. P1 未实现语义有明确诊断。 + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `npm run test -- grl alarm interrupt task` 通过，10 个测试文件共 43 个测试通过。 +3. `npm test` 通过，24 个测试文件共 99 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 +5. 新增异常/报警 IR：`AlarmInstruction/RaiseInstruction/TryInstruction/CatchInstruction/FinallyInstruction/UnsupportedRuntimeInstruction`。 +6. `parseProcedureExceptionFlow` 支持 `alarm`、`raise`、`try/catch/finally`。 +7. `alarm` 保留 alarm id、message、severity 和 sourceMap。 +8. `try` 要求至少一个 `catch` 或 `finally`，否则报 `GRL_TRY_HANDLER_MISSING`。 +9. `trap` 和 `task ... cycle ... end` 保持为 raw top-level declaration，AST 可表达完整 token block。 +10. `analyzeExceptionSemantics` 对 P1 的 trap/task 返回 `UNSUPPORTED_RUNTIME` 并输出 `GRL_P1_UNIMPLEMENTED` warning diagnostic。 +11. procedure body 内 `enable/disable interrupt` 编译为 `UNSUPPORTED_RUNTIME`，明确标识 P0 不执行。 + +是否通过：通过。 + +### EV-110：语义检查、IR 和 source map + +关联任务：`KW-110` +对标章节：GRL 20、21、24；KDL 21 +类型：语义测试、IR snapshot +命令： + +```bash +npm run typecheck +npm run test -- grl semantic ir sourcemap +npm test +cmake --build kdl-wasm/build-wasm -j16 +``` + +验证点： + +1. 语法规范第 21 章 22 项检查覆盖。 +2. Executable IR。 +3. Motion IR 到 KDL request。 +4. source map 定位 GRL、Path、Operation。 + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `npm run test -- grl semantic ir sourcemap` 通过，11 个测试文件共 46 个测试通过。 +3. `npm test` 通过，25 个测试文件共 102 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 +5. 新增 `compileSemanticProgram` 统一语义入口，组合数据、target、path、operation、proc/func、IO、流程控制、异常/报警语义。 +6. 新增 `SemanticProgramIr`，包含 `symbols/semanticChecks/procedures/paths/operations/diagnostics/sourceMap/kdlBridge`。 +7. `semanticChecks` 覆盖 22 项检查清单，用于对齐 GRL 第 21 章 P0 语义检查面。 +8. Executable IR 支持 Motion、IO、Wait、Pulse、RunPath、RunOperation、Call、Return、Branch、Alarm、UnsupportedRuntime。 +9. `kdlBridge.motionRequests` 可从 executable motion 映射到 KDL request，`kdlBridge.pathRequests` 保留 PathPlanRequest。 +10. source map 聚合 GRL procedure 行列、path point/event、operation action。 +11. 修正 motion 语句参数解析的跨行边界，避免 `movej ... zone fine` 吞掉下一行 IO/wait/control token。 +12. 重复符号通过 semantic diagnostic 返回 `GRL_SYMBOL_DUPLICATE`。 + +是否通过：通过。 + +### EV-111：三品牌后处理原型 + +关联任务：`KW-111` +对标章节：GRL 17、19、24 +类型：golden file 测试 +命令： + +```bash +npm run typecheck +npm run test -- post abb fanuc kuka +npm test +cmake --build kdl-wasm/build-wasm -j16 +``` + +验证点： + +1. ABB RAPID。 +2. FANUC LS/TP 风格。 +3. KUKA KRL。 +4. post_hint。 +5. brand metadata。 +6. 不支持语义转换报告。 + +执行环境： + +```text +Node.js v22.23.0 +npm 10.9.8 +Vitest 3.2.6 +``` + +结果摘要： + +1. `npm run typecheck` 通过。 +2. `npm run test -- post abb fanuc kuka` 通过，1 个测试文件共 2 个测试通过。 +3. `npm test` 通过，26 个测试文件共 104 个测试通过。 +4. `cmake --build kdl-wasm/build-wasm -j16` 通过。 +5. 新增 `postProcessBrand/postProcessAllBrands`，以 `SemanticProgramIr` 为后处理输入。 +6. ABB RAPID 原型输出 `MoveJ/MoveL/MoveC/SetDO/WaitUntil/PulseDO`。 +7. FANUC LS/TP 风格原型输出 `/PROG`、`J/L/C`、`DO/WAIT/PULSE`。 +8. KUKA KRL 原型输出 `DEF`、`PTP/LIN/CIRC`、`$OUT/WAIT FOR/PULSE`。 +9. speed/zone 映射覆盖 joint percent、linear mm/s、fine、distance zone。 +10. `post_hint abb` 对 ABB 生效，对 FANUC/KUKA 输出 `GRL_POST_HINT_IGNORED` report。 +11. 不支持语义进入转换报告，测试覆盖 `ALARM` 的 `GRL_POST_UNSUPPORTED`。 + +是否通过：通过。 + +### EV-112：自动生成规则和往返 + +关联任务：`KW-112` +对标章节：GRL 18、24 +类型：生成器测试、往返测试 +命令： + +```bash +npm run test -- grl generator roundtrip +``` + +验证点： + +1. 优先生成 target/path/operation。 +2. 点名稳定。 +3. defaults 和单点 override 稳定。 +4. source metadata 保留。 +5. compact/expanded 输出。 +6. 生成后可再解析为等价对象和 IR。 + +结果摘要：待执行。 +是否通过：待验证。 diff --git a/06-决策记录.md b/06-决策记录.md new file mode 100644 index 0000000..d9d43d4 --- /dev/null +++ b/06-决策记录.md @@ -0,0 +1,331 @@ +# 06-决策记录 + +版本：0.3 +日期：2026-06-27 + +## ADR-001：`working1` 只对标两份源文档 + +状态：Accepted +日期：2026-06-27 +关联任务：`KW-000` + +### 背景 + +用户要求 `/home/meswork/kdl_work/work/working1` 内实施文档完全对标： + +1. `/home/meswork/kdl_work/work/doc/KDL_WASM计算接口设计.md` +2. `/home/meswork/kdl_work/work/doc/通用机器人编程语法规范.md` + +### 决策 + +`working1` 的范围只从这两份文档抽取。其他技术方案不作为本目录任务、验收和 ADR 的来源。 + +### 后果 + +1. 任务分为 KDL WASM 计算接口线和 GRL 编程语法线。 +2. OPFS、UI、虚拟控制器和碰撞检测等内容不单独展开，除非两份源文档明确作为工程结构、调用关系、后处理或测试项出现。 +3. 所有 P0/P1 以两份源文档的实施优先级为准。 + +## ADR-002：KDL WASM 是 GRL 的运动计算内核，不解释 GRL + +状态：Accepted +日期：2026-06-27 +关联任务：`KW-001` 到 `KW-013`、`KW-103` 到 `KW-110` + +### 背景 + +KDL WASM 接口设计明确规定 KDL 不负责 GRL 词法语法解析、流程控制、变量、IO、wait、子程序调用、碰撞检测和 OPFS 项目文件管理。 + +### 决策 + +KDL WASM 只接收已经由 TypeScript 编译层解析完成的模型、目标点、速度、zone、tool、frame 和 motion request。 + +### 后果 + +1. `movej/movel/movec/run_path` 编译后调用 KDL。 +2. `if/for/switch/call/wait/io/alarm` 不直接调用 KDL。 +3. `operation.process` 不进入 KDL，TypeScript 只把 operation 展开的 motion segment 交给 KDL。 + +## ADR-003：GRL AST、语义检查、IR 和 KDL request 分层实现 + +状态：Accepted +日期：2026-06-27 +关联任务：`KW-100` 到 `KW-110` + +### 背景 + +GRL 语法规范定义的编译管线为： + +```text +GRL Source -> Lexer -> Parser -> AST -> Symbol Table -> Semantic Analyzer -> Executable IR -> Virtual Controller -> Post Processor +``` + +KDL 接口设计要求 GRL 编译器把 `movej/movel/movec` 解析为 IR 后，由虚拟控制器调用 KDL 函数。 + +### 决策 + +实现中明确区分： + +1. AST：保留语法结构、source range、单位原文和品牌 metadata。 +2. Semantic Analyzer：完成类型、单位、名称、路径、operation、IO 和运动语义检查。 +3. IR：作为虚拟控制器和后处理的统一输入。 +4. KDL request：只由运动 IR、Path IR 派生。 + +### 后果 + +1. KDL API 不依赖 GRL AST。 +2. 后处理不直接消费 KDL 轨迹点，而是优先消费 IR、目标点和品牌 profile。 +3. source map 必须贯穿 AST、IR、KDL request 和诊断。 + +## ADR-004：机器人结构以 URDF 为源数据，TypeScript 生成标准模型 + +状态：Accepted +日期：2026-06-27 +关联任务：`KW-002` + +### 背景 + +KDL 接口设计规定机器人结构源数据为 URDF，TypeScript 解析 XML 并生成 `NormalizedRobotModel`，WASM 根据标准模型构造 KDL `Tree/Chain`。 + +### 决策 + +实现 `loadRobotFromUrdf` 时，TypeScript 负责： + +1. 解析 URDF XML。 +2. 检查 link/joint 连通性和单位。 +3. 生成 `NormalizedRobotModel`。 + +WASM 负责： + +1. 从 `NormalizedRobotModel` 构造 KDL Chain。 +2. 创建 FK、IK、Jacobian solver。 +3. 返回 `RobotHandle`。 + +### 后果 + +1. `NormalizedRobotModel` schema 是 TypeScript 与 WASM 的稳定边界。 +2. GRL 编译器在编译 `joint_target` 时按 `RobotInfo.dof` 检查长度。 +3. WASM 仍需对模型做防御性校验并返回 `KDL_INVALID_MODEL`。 + +## ADR-005：内部统一使用 SI 单位和位置 + 四元数位姿 + +状态：Accepted +日期：2026-06-27 +关联任务：`KW-006`、`KW-100`、`KW-102` + +### 背景 + +GRL 支持 `mm`、`deg`、`mm/s` 等带单位字面量。KDL 接口设计要求内部位姿统一为位置 + 四元数。 + +### 决策 + +1. GRL lexer/parser 保留单位原文。 +2. 语义层将单位规范化为 SI。 +3. `pose()` 在编译层转换为四元数。 +4. `poseq()` 四元数必须归一化。 +5. KDL API 只接收规范化后的 `Pose`。 + +### 后果 + +1. 所有后处理时再按品牌格式转换。 +2. 单位错误在 GRL 语义检查阶段报告。 +3. 位姿数值约定由 KDL `normalizePose/composePose/inversePose` 测试固定。 + +## ADR-006：P0 zone 只保留语义并近似为 fine + +状态：Accepted +日期：2026-06-27 +关联任务：`KW-008` 到 `KW-011`、`KW-111` + +### 背景 + +KDL 接口设计写明首版 `zone` 可只用于诊断和后处理，运动规划先按 `fine` 到点执行，P1 再实现连续 blend。 + +### 决策 + +P0 中 `ZoneSpec` 必须保留在 IR、KDL request、TrajectoryResult 和后处理中。KDL 轨迹规划按 `fine` 到点执行，并返回 `KDL_ZONE_APPROXIMATED` warning。 + +### 后果 + +1. P0 轨迹不声称复现品牌控制器连续过渡。 +2. 后处理仍可输出 ABB `zonedata`、FANUC `CNT`、KUKA `C_DIS` 等语义。 +3. P1 再实现 `planBlendPath` 或等价连续过渡。 + +## ADR-007：所有 KDL API 返回结构化诊断 + +状态：Accepted +日期：2026-06-27 +关联任务：`KW-001` 到 `KW-013` + +### 背景 + +KDL 接口设计要求所有 API 不抛裸字符串错误，必须返回结构化错误和诊断。 + +### 决策 + +KDL Worker RPC 错误统一为： + +```ts +interface KdlError { + code: string; + message: string; + diagnostics: MotionDiagnostic[]; +} +``` + +KDL 诊断固定包含： + +1. `KDL_INVALID_MODEL` +2. `KDL_TARGET_UNREACHABLE` +3. `KDL_IK_FAILED` +4. `KDL_JOINT_LIMIT` +5. `KDL_VELOCITY_LIMIT` +6. `KDL_ACCEL_LIMIT` +7. `KDL_SINGULARITY` +8. `KDL_ARC_DEGENERATE` +9. `KDL_PATH_EMPTY` +10. `KDL_ZONE_APPROXIMATED` + +### 后果 + +1. 自动测试断言诊断 code，不依赖 message 文本。 +2. sourceMap 必须随诊断传递。 +3. 后处理和报告可区分 error、warning、info。 + +## ADR-008：Worker RPC 是 KDL TypeScript API 的唯一调用入口 + +状态：Accepted +日期：2026-06-27 +关联任务：`KW-001`、`KW-013` + +### 背景 + +KDL 接口设计要求 KDL WASM 运行在 Worker 中，避免阻塞 UI 主线程，并要求大数组使用 Transferable 或共享内存策略。 + +### 决策 + +主线程或 GRL 编译/运行层只调用 `KdlWorkerClient`。C ABI / Embind 仅在 Worker 内封装。 + +### 后果 + +1. 所有 KDL API 为 Promise 风格。 +2. Worker 崩溃和初始化失败必须可恢复。 +3. 高频轨迹和批量 IK/FK 优先在 Worker 内整段计算，减少跨线程往返。 + +## ADR-009：KDL 底层导出稳定 C ABI / Embind 包装 + +状态：Accepted +日期：2026-06-27 +关联任务：`KW-013` + +### 背景 + +KDL 接口设计不建议把 KDL C++ 类完整暴露给 TypeScript，而是通过稳定函数导出。 + +### 决策 + +P0 底层导出以 C ABI 为基准： + +1. `kdl_init` +2. `kdl_create_robot` +3. `kdl_destroy_robot` +4. `kdl_get_robot_info` +5. `kdl_fk` +6. `kdl_fk_all_links` +7. `kdl_jacobian` +8. `kdl_ik` +9. `kdl_plan_movej` +10. `kdl_plan_movel` +11. `kdl_plan_movec` +12. `kdl_plan_path` +13. `kdl_sample_trap` +14. `kdl_last_error` + +TypeScript API 在 Worker 内包装这些函数，向上暴露 `KdlWasmApi`。 + +### 后果 + +1. C++ 对象生命周期不泄漏到 TypeScript 业务层。 +2. 高频接口可增加 TypedArray 版本。 +3. C ABI 返回码和 `kdl_last_error` 必须有测试。 + +## ADR-010：GRL P0 严格按语法规范第 24 章实现 + +状态：Accepted +日期：2026-06-27 +关联任务：`KW-100` 到 `KW-112` + +### 背景 + +GRL 语法规范第 24 章明确列出 P0 和 P1。 + +### 决策 + +GRL P0 必须覆盖： + +1. language/module/proc。 +2. const/var/persistent。 +3. tool/frame/speed/zone。 +4. joint_target/pose_target。 +5. movej/movel/movec。 +6. path/point/event/run_path。 +7. operation/run_operation。 +8. if/elseif/else/while/for/switch。 +9. call/return/break/continue。 +10. proc 参数方向。 +11. func 和返回值检查。 +12. io.do/di、wait、pulse。 +13. AST、语义检查、IR、source map。 +14. ABB、FANUC、KUKA 后处理原型。 + +### 后果 + +1. label/jump、trap/interrupt、多任务、完整品牌导入等 P1 内容不得阻塞 P0。 +2. 但 P1 语法若已解析，未实现语义必须有明确诊断。 + +## ADR-011：后处理以 GRL IR 为输入，必须保留品牌差异报告 + +状态：Accepted +日期：2026-06-27 +关联任务：`KW-111` + +### 背景 + +GRL 语法规范要求 GRL 可转换为 ABB RAPID、FANUC LS/TP 风格文本和 KUKA KRL，并要求无法支持的品牌扩展进入转换报告。 + +### 决策 + +后处理器以 GRL IR、目标点、tool/frame、speed/zone 和 post profile 为输入。`post_hint` 和 `@brand.*` 只影响指定品牌。 + +### 后果 + +1. 不支持语义不能静默丢失。 +2. 后处理 golden file 必须覆盖运动、目标点、工具、坐标系、速度、zone、IO 和 wait。 +3. 转换报告是后处理验收的一部分。 + +## ADR-012：自动生成 GRL 优先生成 target/path/operation + +状态：Accepted +日期：2026-06-27 +关联任务：`KW-112` + +### 背景 + +GRL 语法规范第 18 章要求自动生成程序优先生成 `target`、`path`、`operation`，不要直接把大量运动语句塞进 `proc main()`。 + +### 决策 + +GRL Generator 的默认输出为结构化对象风格： + +1. 目标点命名稳定。 +2. 路径点命名稳定。 +3. 路径整体参数放入 `defaults`。 +4. 单点差异写在 point 上。 +5. CAD 或工艺来源写入 `source`。 +6. 支持 compact 和 expanded 两种输出。 + +### 后果 + +1. 同一输入重复生成结果必须一致。 +2. 生成文本必须可 diff。 +3. 生成后必须能解析回等价对象和 IR。 diff --git a/README.md b/README.md new file mode 100644 index 0000000..8922d6c --- /dev/null +++ b/README.md @@ -0,0 +1,69 @@ +# working1 实施文档索引 + +版本：0.3 +日期：2026-06-27 +主题：GRL 编程语法规范与 KDL WASM 计算接口设计的对标实施方案。 + +## 1. 文档依据 + +本目录只对标以下两份文档： + +1. `/home/meswork/kdl_work/work/doc/通用机器人编程语法规范.md` +2. `/home/meswork/kdl_work/work/doc/KDL_WASM计算接口设计.md` + +OPFS、虚拟控制器、UI、报告等内容只在上述两份文档明确要求的接口边界、编译调用关系或测试场景中出现。 + +## 2. 对标主线 + +`working1` 的实施主线分为两条： + +1. GRL 语言实施 + - 词法、单位、保留关键字。 + - 顶层结构、类型系统、变量声明。 + - tool、frame、target、speed、zone。 + - `movej/movel/movec`。 + - `path/event/run_path`。 + - `operation/run_operation`。 + - IO、wait、pulse。 + - if/while/for/switch、label/jump。 + - proc/func、参数方向、作用域。 + - alarm/raise/try/catch、trap/interrupt、多任务语法。 + - post_hint、brand metadata、后处理映射。 + - AST、语义检查、IR、source map。 + +2. KDL WASM 计算接口实施 + - Worker RPC 和稳定 TypeScript API。 + - URDF 到 `NormalizedRobotModel`，再到 KDL Chain。 + - RobotHandle 生命周期。 + - 位姿规范化、组合、逆、offset、tool/frame 变换。 + - FK、fkAllLinks、Jacobian、IK、ikBatch。 + - 关节限位、奇异性、可达性批量检查。 + - 梯形速度曲线。 + - `planMoveJ/planMoveL/planMoveC`。 + - `planPath/validatePath`。 + - 节拍估算、重采样、结构化诊断。 + - C ABI / Embind 暴露和性能优化。 + +## 3. 文档入口 + +| 文件 | 用途 | +| --- | --- | +| `01-项目功能内容.md` | 两份规范的功能范围、P0/P1 边界、模块职责和验收口径。 | +| `02-项目程序开发详细步骤.md` | 按 GRL 和 KDL WASM 对标项拆解可执行开发步骤。 | +| `03-推进台账.md` | 记录每轮修改、验证、风险和下一步。 | +| `04-任务矩阵.md` | 管理任务编号、状态、依赖和验收标准。 | +| `05-验收证据.md` | 保存测试命令、报告路径、产物和结果摘要。 | +| `06-决策记录.md` | 固化两份规范中影响实施的关键设计决策。 | + +## 4. 推进规则 + +1. 所有任务编号统一使用 `KW-###`。 +2. `KW-001` 到 `KW-099` 对标 KDL WASM 计算接口设计。 +3. `KW-100` 到 `KW-199` 对标 GRL 编程语法规范。 +4. 每个 P0 项必须能映射回源文档对应章节。 +5. 任务完成必须补充 `05-验收证据.md`。 +6. 任何 P1 内容不得阻塞 P0 验收，除非源文档明确将其列为 P0。 + +## 5. 当前首要任务 + +从 KDL WASM 工程骨架与 Worker RPC 开始，同时建立 GRL lexer/parser 骨架。两条线的第一个集成点是：把 GRL `movej/movel/movec/path` 编译为 KDL `MotionSegmentRequest` 并生成轨迹。