整理项目文档目录

working/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 初始化、崩溃恢复和取消请求测试通过。