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