# 01-项目功能内容

版本：0.5
日期：2026-06-27  
对标文档：

1. `/home/meswork/kdl_work/work/doc/通用机器人编程语法规范.md`
2. `/home/meswork/kdl_work/work/doc/KDL_WASM计算接口设计.md`
3. `/home/meswork/kdl_work/work/doc/通用机器人离线编程虚拟控制器技术方案.md`
4. `/home/meswork/kdl_work/work/doc/通用机器人项目主要实施步骤.md`
5. `/home/meswork/kdl_work/work/doc/通用机器人项目功能与数据流程图.md`
6. `/home/meswork/kdl_work/work/doc/通用机器人项目功能与数据流程图-png/flow-01.mmd` 到 `flow-05.mmd`
7. `/home/meswork/kdl_work/work/doc/通用机器人项目功能与数据流程图-png/flow-01.png` 到 `flow-05.png`

## 1. 项目定位

本目录用于把 `/home/meswork/kdl_work/work` 下的通用机器人离线编程方案、流程图源码和流程图渲染资产落成实施计划。实施目标是形成一套互相闭合的语言层、运动计算层、虚拟控制器、工作台和工程交付链路：

```text
Project Resources / OPFS Workspace
  -> GRL Source / OLP Object Model / Brand Source
  -> Lexer / Parser / Brand Importer
  -> AST / Brand AST
  -> Symbol Table / Semantic Analyzer
  -> Executable IR / Source Map
  -> Virtual Controller Runtime
  -> Motion Queue / IO Service / Alarm Queue / Trace Buffer
  -> MotionSegmentRequest / PathPlanRequest
  -> KdlWorkerClient / KDL WASM
  -> TrajectoryResult / PathValidationResult / Diagnostics
  -> Post Processor / Reports / Customer Delivery Package
```

首版 MVP 范围包括单机器人 6 轴 URDF、GRL 语言闭环、KDL WASM 运动计算、虚拟控制器运行调试、DI/DO 虚拟 IO、OPFS 项目保存、三品牌后处理原型、至少一种品牌程序导入原型、可达性/节拍报告和客户交付包导出原型。完整碰撞检测、多机器人协调、外部轴同步、完整 CAD kernel、真实控制器通信和品牌控制器 look-ahead 完全复刻为后续扩展，但必须在任务矩阵中有明确归属。

## 1.1 `/work` 全功能覆盖索引

| 来源资产 | 必须覆盖的功能面 | working 对应任务 |
| --- | --- | --- |
| `KDL_WASM计算接口设计.md` | Worker API、URDF、KDL Chain、FK/IK/Jacobian、轨迹、Path、诊断、C ABI、性能 | `KW-001` 到 `KW-013` |
| `通用机器人编程语法规范.md` | GRL 词法、语法、AST、语义、IR、Path、Operation、IO、流程、后处理、生成器 | `KW-100` 到 `KW-112` |
| `通用机器人离线编程虚拟控制器技术方案.md` | 商业 OLP、对象模型、虚拟控制器、IO/Wait、OPFS、UI、报告、品牌导入、虚拟调试、几何、碰撞、校准、Sim-to-Real、多机器人、外部轴、真实控制器校验 | `KW-200` 到 `KW-210` |
| `通用机器人项目主要实施步骤.md` | 阶段 1 到 10 的实施顺序、输入输出、验收重点和常用命令 | `KW-001` 到 `KW-211` |
| `通用机器人项目功能与数据流程图.md` | 总体功能流、GRL 编译执行流、KDL 计算流、数据传递流、诊断传递流 | `KW-110`、`KW-200` 到 `KW-211` |
| `flow-01.mmd/png` | 项目资源到 GRL/KDL/后处理的总体功能流程 | `KW-211` |
| `flow-02.mmd/png` | GRL 编译、IR 执行、KDL 请求和后处理流程 | `KW-110`、`KW-202`、`KW-211` |
| `flow-03.mmd/png` | KDL RobotHandle、MOVEJ/MOVEL/MOVEC/PATH 计算流程 | `KW-003` 到 `KW-011`、`KW-211` |
| `flow-04.mmd/png` | Project、Compile、KDL、Runtime、Output 数据流 | `KW-200` 到 `KW-206`、`KW-211` |
| `flow-05.mmd/png` | Parser、Semantic、KDL、Post Processor 诊断 severity/sourceMap 流程 | `KW-110`、`KW-206`、`KW-211` |

## 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. 虚拟控制器和 IO 运行时范围

### 4.1 控制器职责

虚拟控制器真正执行统一 `Executable IR`，而不是直接解释品牌文本。它必须支撑：

1. 控制器状态机：`PowerOff/Booting/MotorsOff/Ready/Manual/Auto/Running/Hold/Fault/EmergencyStop`。
2. 基础命令：`powerOn/powerOff/motorsOn/motorsOff/loadProgram/start/hold/resume/stop/resetFault/stepInto/stepOver/stepMotion`。
3. 执行模型：Program Counter、Call Stack、Scope Stack、Motion Queue、IO Image、Timer Table、Interrupt Table、Alarm Queue、Trace Buffer、Source Map、Brand Context。
4. 单主任务首版模型，后续扩展后台任务、多机器人任务、独立 IO 任务和监控任务。
5. `run_path` 展开为路径点运动和 before/after event。
6. `run_operation` 展开为 start action、path、end action，并将工艺状态写入 trace。
7. 品牌程序导入后的 IR 执行，并保留品牌源程序行号和转换报告。

### 4.2 IO Service 和 Wait

虚拟 IO 是虚拟调试核心能力。首版必须覆盖：

1. IO Image、IO Alias Table、IO Event Queue、Wait Registry、Edge Detector、IO Script Engine、IO Trace Logger。
2. 地址规范：`DI[1] -> io.di[1]`、`DO[1] -> io.do[1]`、`AI/AO/GI/GO/RI/RO` 同规则。
3. 程序可写 DO、AO、GO、RO；用户和脚本可按配置修改虚拟输入。
4. 所有读写必须经过 IO Service，并生成 `IoEvent`。
5. `wait` 执行时立即求值，未满足则创建 `ActiveWait`，由 controller tick 或 IO 变化触发重评估。
6. `wait timeout`、`pulse duration`、IO script `delay` 均基于虚拟时间；hold 暂停虚拟时间，stop/reset 取消 ActiveWait。
7. `rising/falling/changed` 边沿只在一个 tick 内有效，并保持同 tick 内事件顺序。
8. Wait 卡住诊断必须显示等待表达式、子表达式当前值、已等待时间、剩余超时时间、相关 IO 最近变化和 IO 脚本状态。

### 4.3 运动队列和 Trace

运动运行时必须：

1. 将 `MotionInstruction`、Path point、Operation 展开为 `MotionQueueItem`。
2. 保留 `instructionId/pathId/pathPointId/operationId`。
3. 调用 KDL 生成轨迹采样后按虚拟时间推进关节和 TCP。
4. 支持程序文本、路径表、3D 轨迹和报警诊断之间通过 source map 联动定位。
5. 记录 motion trace、IO trace、wait trace、alarm trace，供报告和回放使用。

### 4.4 虚拟调试增强

虚拟调试增强必须覆盖：

1. 断点。
2. 单步进入和单步越过。
3. 运动断点。
4. 轨迹回放。
5. 变量 watch。
6. IO 脚本调试。
7. GRL、Path、Operation、品牌源程序行号与 IR 的联动调试。
8. IK、IO、逻辑、后处理和品牌导入错误的跨视图定位。

## 5. OLP 工作台、工作区和交付范围

### 5.1 OLP 对象模型

商业 OLP 工作流以对象树组织项目，而不是只管理文本文件。内部对象模型必须覆盖：

1. `RobotModel`
2. `ToolModel`
3. `FrameModel`
4. `TargetModel`
5. `PathModel`
6. `PathPointModel`
7. `OperationModel`
8. `ProgramModel`
9. `PostProfile`
10. Station、Cell、Fixture、Part、Device、Geometry、Calibration、Report。

对象模型用途：

1. UI 对象树和路径编辑器直接操作。
2. 从规划点或曲线生成 Path。
3. 从 Path/Operation 生成 GRL。
4. 品牌程序导入后尽量恢复 target/path/program。
5. 后处理和虚拟控制器最终仍以 IR 为准。

### 5.2 OPFS 工作区

OPFS 项目必须提供稳定布局和显式导入导出能力：

```text
/projects/{projectId}/
  project.json
  station/
  libraries/
  geometry/
  robots/
  programs/
  targets/
  tools/
  frames/
  io/
  generated/
  logs/
  reports/
  calibration/
  snapshots/
  .index.json
  .lock
```

必须实现的工作区能力：

1. `listProjects/openProject/createProject`
2. `readText/writeText`
3. `readJson/writeJson`
4. `delete`
5. `snapshot`
6. `exportZip/importZip`
7. 存储占用显示、迁移、损坏检测和备份。

### 5.3 Web 工作台

第一屏应直接进入离线编程和虚拟调试工作台。必须页面包括：

1. 项目管理。
2. 工作站布局。
3. 资源库。
4. 几何与 CAD。
5. 程序编辑。
6. 虚拟示教器。
7. IO 面板。
8. 运动监控。
9. 路径编辑器。
10. Operation 编辑器。
11. 验证与报告。
12. 校准与现场回读。
13. 后处理导出。
14. 品牌程序导入。
15. 日志和报警。
16. Wait 调试面板。

UI 验收重点是工作流可用、状态可见、诊断可定位、数据可导出，不以营销展示页作为首屏。

### 5.4 品牌导入和后处理闭环

除三品牌后处理外，全目录对标要求建立 Brand Importer：

```text
ABB RAPID / FANUC LS / KUKA KRL
  -> Brand Importer
  -> Brand AST
  -> Normalized IR
  -> Reconstructed GRL
  -> Optional OLP Path/Operation Model
  -> Import Report
```

首版建议：

1. ABB 解析 `.mod/.sys` 文本中的 `MODULE/PROC/MoveJ/MoveL/MoveC/robtarget/tooldata/wobjdata`。
2. KUKA 解析 `.src/.dat` 文本中的 `DEF/PTP/LIN/CIRC/E6POS/E6AXIS/$TOOL/$BASE`。
3. FANUC 解析 LS 风格文本或可读 TP 导出中的 `J/L/C/P[]/PR[]/UTOOL/UFRAME/CALL/LBL/JMP`。
4. 导入目标是提取目标点、运动序列、工具、坐标系、速度、过渡、主要 IO 和流程控制，转换为统一 IR 并生成转换报告。

### 5.5 报告和客户交付

报告必须可导出 JSON 和 HTML，覆盖：

| 报告 | 内容 |
| --- | --- |
| Reachability Report | 不可达点、接近限位点、IK 解 |
| Collision Report | 碰撞对象、时间、路径点、严重程度 |
| Cycle Time Report | 总节拍、路径节拍、wait 时间、瓶颈 |
| IO Report | IO 映射、wait、pulse、脚本触发 |
| Post Report | 品牌映射、近似处理、不支持项 |
| Calibration Report | TCP、Frame、Base 偏差 |
| Import Report | 品牌程序导入结果、丢失语义、恢复对象 |

客户交付包必须包含 GRL 源程序、品牌后处理程序、目标点和路径数据、IO map、后处理报告、可达性报告、节拍报告、校准数据和可选仿真 trace。

### 5.6 商业级 OLP、Sim-to-Real 和真实项目扩展

商业级扩展必须在任务矩阵中保留，不能被 MVP 范围省略：

1. 资源库管理：机器人库、工具库、夹具库、工艺模板库、后处理 profile 库。
2. 几何导入：mesh/CAD 转换文件、点/边/曲线/面法向提取、曲线路径生成。
3. 碰撞和干涉验证：基础碰撞对象、时间、路径点和严重程度定位。
4. 校准和 Sim-to-Real：TCP、Frame、Base 校准数据，离线/现场差异比对。
5. 品牌程序导入后的真实项目回读和交叉品牌再导出风险报告。
6. 多机器人和外部轴：任务模型、运动组、外部轴协调和复杂工作站支持。
7. 真实控制器校验流程：导出程序不等于现场可高速运行，必须保留低速验证和校验报告边界。
8. 完整 CAD kernel、真实控制器通信、高精度轨迹复现作为更后续扩展，但必须有明确非 MVP 边界。

## 6. 数据流和线程模型

### 6.1 总体数据流

全系统数据流以 `Executable IR` 为中枢：

1. Project resources 提供 URDF、GRL、targets、paths、operations、io map、post profile。
2. TypeScript 编译层生成 AST、符号表、语义诊断和 IR。
3. 只有运动相关 IR 会构造成 KDL request。
4. KDL Worker 返回轨迹、路径验证、节拍和结构化诊断。
5. 虚拟控制器消费 IR、轨迹和 IO 事件，生成 trace。
6. 后处理器消费 IR、OLP 对象模型和 post profile，生成品牌程序和转换报告。
7. 报告引擎消费诊断、trace、轨迹和对象模型，生成 JSON/HTML 报告。

### 6.2 不进入 KDL WASM 的数据流

以下语义由编译层或虚拟控制器执行，不传入 KDL：

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`
8. Brand import context
9. UI 和 OPFS 工作区状态
10. 报告生成和客户交付包打包

### 6.3 推荐线程模型

Web 主线程只负责 UI 交互和轻量状态更新。建议 Worker 划分：

1. Parser Worker：tokenize、parse、semantic check、diagnostics。
2. Controller Worker：interpreter、execution clock、variable state、IO simulation、motion queue。
3. KDL Worker：WASM 初始化、FK/IK/Jacobian、trajectory sampling。
4. Storage Worker：OPFS read/write、project snapshot、import/export。
5. Geometry/Validation Worker：几何采样、碰撞、长路径节拍分析和报告生成。

### 6.4 流程图资产同步

`work/doc/通用机器人项目功能与数据流程图-png` 下的 `.mmd` 是流程图源，`.png` 是渲染结果。实施文档和后续代码必须保持以下同步关系：

1. `flow-01` 对应总体功能流程。
2. `flow-02` 对应 GRL 编译与执行流程。
3. `flow-03` 对应 KDL WASM 计算流程。
4. `flow-04` 对应数据传递流程。
5. `flow-05` 对应诊断传递流程。
6. 若流程图源或渲染图更新，`01-项目功能内容.md`、`02-项目程序开发详细步骤.md`、`04-任务矩阵.md` 和 `05-验收证据.md` 必须同步记录影响。

## 7. 共享数据和单位

### 7.1 单位

GRL 编译器内部必须统一：

| 物理量 | 内部单位 |
| --- | --- |
| 长度 | meter |
| 角度 | radian |
| 时间 | second |
| 质量 | kilogram |
| 线速度 | meter/second |
| 角速度 | radian/second |
| 加速度 | meter/second^2 或 radian/second^2 |

### 7.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`。

### 7.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;
}
```

### 7.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`。

### 7.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. 后处理品牌不支持所用语义。

## 8. 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`

## 9. 验收口径

### 9.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。

### 9.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`。

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

### 9.4 虚拟控制器和 IO 验收

1. 控制器状态机支持上电、使能、加载、启动、暂停、继续、停止、报警复位和单步。
2. 程序运行时能显示当前行、变量、调用栈、IO、报警、TCP、关节、当前 Path/Point/Operation。
3. `run_path` 和 `run_operation` 可在 Motion Queue 中保留 source map 并驱动轨迹回放。
4. `wait` 能显示表达式、关联 IO、已等待时间和剩余 timeout。
5. 用户可通过 IO 面板手动满足 wait。
6. IO 脚本可模拟夹具反馈并自动满足 wait。
7. wait timeout 可产生报警或执行 on_timeout。
8. pulse 输出按虚拟时间自动复位。
9. IO trace、motion trace 和 alarm trace 顺序稳定。

### 9.5 工作区、UI、报告和交付验收

1. 用户能在浏览器中新建、保存、打开、导入和导出项目。
2. 用户能导入 URDF，定义工具、工件坐标、目标点、Path 和 Operation。
3. 用户能从 Path/Operation 生成 GRL，并手工编辑 GRL。
4. 系统能实时显示语法和语义错误。
5. 同一个 Path/Program 能导出 ABB、FANUC、KUKA 三种目标文本和后处理报告。
6. 至少一种品牌程序能导入、转换为 IR 并在虚拟控制器中运行。
7. 能生成可达性报告、节拍报告、IO/Wait 报告、后处理报告。
8. 能导出包含源程序、品牌程序、IO map 和报告的客户交付包。
9. 自动测试覆盖解析器、KDL WASM、虚拟控制器、IO/Wait、后处理和品牌导入。

### 9.6 商业级扩展和流程图资产验收

1. 虚拟调试支持断点、运动断点、轨迹回放、变量 watch 和跨源定位。
2. 资源库、工艺模板、几何导入和曲线路径生成有对象模型和测试。
3. 基础碰撞检测可定位对象、时间和路径点。
4. TCP、Frame、Base 校准数据可保存、应用并进入报告。
5. 多机器人、外部轴、真实控制器校验流程有任务拆解、边界说明和扩展验收。
6. `flow-01` 到 `flow-05` 的 Mermaid 源图和 PNG 渲染图纳入覆盖证据。
7. 流程图资产与功能文档、任务矩阵、验收证据之间无断链。
