# 通用机器人项目功能与数据流程图

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

1. `通用机器人编程语法规范.md`
2. `KDL_WASM计算接口设计.md`

## 1. 范围说明

本文描述 GRL 通用机器人程序语言和 KDL WASM 计算接口之间的总体功能流程和数据传递流程。

核心边界：

1. GRL 层负责程序文本、语法、语义、IR、Path、Operation、IO、wait、后处理。
2. KDL WASM 层负责机器人模型、位姿变换、FK、IK、Jacobian、梯形速度、MOVEJ、MOVEL、MOVEC、Path 轨迹和诊断。
3. KDL WASM 不解析 GRL，不执行流程控制、变量、IO、wait、子程序和异常逻辑。
4. TypeScript 编译器和虚拟控制器把 GRL/IR 转换为 KDL 可执行的运动请求。

## 2. 总体功能流程图

```mermaid
flowchart TD
  A[项目资源] --> A1[robots/robot.urdf]
  A --> A2[targets/*.json]
  A --> A3[paths/*.json]
  A --> A4[operations/*.json]
  A --> A5[programs/*.grl]
  A --> A6[io/io_map.json]
  A --> A7[post/*.profile.json]

  A5 --> B[GRL Lexer]
  B --> C[GRL Parser]
  C --> D[GRL AST]
  D --> E[Symbol Table]
  E --> F[Semantic Analyzer]

  A1 --> G[URDF Parser]
  G --> H[NormalizedRobotModel]
  H --> I[KDL createRobotFromModel]
  I --> J[RobotHandle]

  F --> K[Executable IR]
  K --> L{IR 指令类型}

  L -->|MotionInstruction| M[生成 MotionSegmentRequest]
  L -->|run_path| N[展开 Path points/events]
  L -->|run_operation| O[展开 start_action + path + end_action]
  L -->|IO / wait / pulse| P[虚拟控制器 IO Service]
  L -->|if/for/switch/call/return| Q[虚拟控制器流程执行]
  L -->|alarm / raise / try/catch| R[虚拟控制器报警与异常处理]

  N --> M
  O --> N

  M --> S[KdlWorkerClient]
  S --> T[kdl.worker.ts]
  T --> U[KDL WASM API]

  U --> U1[planMoveJ]
  U --> U2[planMoveL]
  U --> U3[planMoveC]
  U --> U4[planPath]
  U --> U5[validatePath]

  U1 --> V[TrajectoryResult]
  U2 --> V
  U3 --> V
  U4 --> W[PathPlanResult]
  U5 --> X[PathValidationResult]

  V --> Y[Motion Queue / 轨迹回放]
  W --> Y
  X --> Z[可达性与诊断报告]

  K --> AA[Post Processor]
  AA --> AA1[ABB RAPID]
  AA --> AA2[FANUC LS/TP 风格文本]
  AA --> AA3[KUKA KRL]
  AA --> AA4[转换报告]
```

## 3. GRL 编译与执行流程图

```mermaid
flowchart TD
  A[GRL Source .grl] --> B[Lexer]
  B --> C[Tokens]
  C --> D[Parser]
  D --> E[AST]
  E --> F[Symbol Table]
  F --> G[Semantic Analyzer]

  G --> G1[名称解析]
  G --> G2[类型检查]
  G --> G3[单位规范化]
  G --> G4[tool/frame/speed/zone 解析]
  G --> G5[Path/Operation 引用检查]
  G --> G6[IO 地址检查]
  G --> G7[运动目标可达性检查]
  G --> G8[后处理能力检查]

  G1 --> H[Executable IR]
  G2 --> H
  G3 --> H
  G4 --> H
  G5 --> H
  G6 --> H
  G7 --> H
  G8 --> H

  H --> I{IR}
  I -->|MotionInstruction| J[Motion Request Builder]
  I -->|WaitInstruction| K[Wait Registry]
  I -->|IoInstruction| L[IO Image]
  I -->|BranchInstruction| M[Program Counter]
  I -->|CallInstruction| N[Call Stack]
  I -->|AlarmInstruction| O[Alarm Queue]
  I -->|ReturnInstruction| P[Scope/Call Stack]

  J --> Q[KDL WASM]
  Q --> R[TrajectoryResult / Diagnostics]
  R --> S[Motion Queue]

  H --> T[Post Processor]
  T --> U[品牌程序]
  T --> V[转换报告]
```

## 4. KDL WASM 计算流程图

```mermaid
flowchart TD
  A[NormalizedRobotModel] --> B[createRobotFromModel]
  B --> C[RobotHandle]
  C --> D[KDL Chain / Solvers Cache]

  E[Motion Request] --> F{motion}
  F -->|MOVEJ| G[planMoveJ]
  F -->|MOVEL| H[planMoveL]
  F -->|MOVEC| I[planMoveC]
  F -->|PATH| J[planPath / validatePath]

  G --> G1[校验 startJoints 和限位]
  G1 --> G2{target 类型}
  G2 -->|joint_target| G3[qEnd = target.joints]
  G2 -->|pose_target| G4[IK 求 qEnd]
  G3 --> G5[关节差分]
  G4 --> G5
  G5 --> G6[梯形速度曲线]
  G6 --> G7[采样关节位置/速度/加速度]
  G7 --> G8[FK 输出 TCP]
  G8 --> R[TrajectoryResult]

  H --> H1[FK 得到起点 TCP]
  H1 --> H2[applyToolAndFrame / applyOffset]
  H2 --> H3[直线位置和姿态插补]
  H3 --> H4[梯形速度曲线]
  H4 --> H5[逐点 IK]
  H5 --> H6[限位/速度/奇异性检查]
  H6 --> R

  I --> I1[FK 得到起点 TCP]
  I1 --> I2[via/target 位姿变换]
  I2 --> I3[三点退化检查]
  I3 --> I4[圆心/半径/法向/弧长]
  I4 --> I5[圆弧采样]
  I5 --> I6[逐点 IK]
  I6 --> I7[圆弧误差和限位检查]
  I7 --> R

  J --> J1[按 segment 顺序规划]
  J1 --> J2[上一段终点关节作为下一段起点]
  J2 --> J3[合并轨迹点和诊断]
  J3 --> J4[保留 sourceMap]
  J4 --> P[PathPlanResult / PathValidationResult]

  R --> D1[MotionDiagnostic]
  P --> D1
  D1 --> D2[error / warning / info]
```

## 5. 数据传递流程图

```mermaid
flowchart LR
  subgraph Project[项目输入数据]
    A1[robot.urdf]
    A2[main.grl]
    A3[targets / paths / operations]
    A4[io_map.json]
    A5[post profile]
  end

  subgraph Compile[TypeScript 编译层]
    B1[URDF Parser]
    B2[GRL Lexer/Parser]
    B3[AST]
    B4[Symbol Table]
    B5[Semantic Analyzer]
    B6[Executable IR]
    B7[Motion Request Builder]
  end

  subgraph KDL[KDL Worker / WASM]
    C1[KdlRpcRequest]
    C2[RobotHandle]
    C3[KDL Solvers]
    C4[FK / IK / Jacobian]
    C5[Trap Profile]
    C6[Motion Planner]
    C7[KdlRpcResponse]
  end

  subgraph Runtime[虚拟控制器运行层]
    D1[Program Counter]
    D2[Call Stack]
    D3[Scope Stack]
    D4[Motion Queue]
    D5[IO Image]
    D6[Wait Registry]
    D7[Alarm Queue]
    D8[Trace Buffer]
  end

  subgraph Output[输出数据]
    E1[TrajectoryResult]
    E2[PathPlanResult]
    E3[PathValidationResult]
    E4[MotionDiagnostic]
    E5[CycleTimeResult]
    E6[ABB/FANUC/KUKA 程序]
    E7[转换报告]
  end

  A1 --> B1
  B1 -->|NormalizedRobotModel| C1
  C1 --> C2
  C2 --> C3

  A2 --> B2
  A3 --> B5
  A4 --> B5
  B2 --> B3
  B3 --> B4
  B4 --> B5
  B5 --> B6

  B6 -->|MotionInstruction| B7
  B7 -->|MoveJRequest / MoveLRequest / MoveCRequest / PathPlanRequest| C1
  C1 --> C4
  C1 --> C5
  C4 --> C6
  C5 --> C6
  C6 --> C7

  C7 --> E1
  C7 --> E2
  C7 --> E3
  C7 --> E4
  C7 --> E5

  B6 --> D1
  B6 --> D2
  B6 --> D3
  E1 --> D4
  E2 --> D4
  B6 -->|IO / wait / pulse| D5
  B6 -->|wait| D6
  E4 --> D7
  D4 --> D8
  D5 --> D8
  D6 --> D8

  B6 -->|IR + post profile| A5
  A5 --> E6
  A5 --> E7
```

## 6. 关键对象数据流

| 输入对象 | 产生阶段 | 传递到 | 输出对象 |
| --- | --- | --- | --- |
| `robot.urdf` | 项目资源 | TypeScript URDF Parser | `NormalizedRobotModel` |
| `NormalizedRobotModel` | TypeScript 编译层 | `createRobotFromModel` | `RobotHandle` |
| `tool/frame/target/speed/zone` | GRL Parser + Semantic Analyzer | IR、KDL request builder | `ToolRef`、`FrameRef`、`JointTarget`、`PoseTarget`、`SpeedSpec`、`ZoneSpec` |
| `movej` | GRL Parser | Semantic Analyzer | `MotionInstruction(joint)` |
| `movel` | GRL Parser | Semantic Analyzer | `MotionInstruction(linear)` |
| `movec` | GRL Parser | Semantic Analyzer | `MotionInstruction(circular)` |
| `path` | GRL Parser | Path compiler | `MotionSegmentRequest[]` |
| `operation` | GRL Parser | Operation compiler | start action + path + end action |
| `MotionInstruction` | IR | KDL request builder | `MoveJRequest`、`MoveLRequest`、`MoveCRequest` |
| `PathPlanRequest` | Path compiler | KDL WASM | `PathPlanResult` |
| `TrajectoryResult` | KDL WASM | Motion Queue、trace、报告 | 轨迹点、诊断、节拍输入 |
| `MotionDiagnostic` | GRL 语义检查或 KDL WASM | 编辑器、报警、报告、后处理 | error/warning/info |
| `Executable IR` | Semantic Analyzer | 虚拟控制器、后处理器 | 执行流、品牌程序 |

## 7. KDL API 与 GRL 语法映射

| GRL 语法 | TypeScript 编译结果 | 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` |

## 8. 不进入 KDL WASM 的数据流

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

| GRL 语义 | 执行位置 | 输出 |
| --- | --- | --- |
| `if/elseif/else` | Program Counter / BranchInstruction | 分支后的 IR 执行位置 |
| `while/for/switch` | Program Counter / BranchInstruction | 循环或选择后的 IR 执行位置 |
| `proc/func/call/return` | Call Stack / Scope Stack | 调用栈和变量作用域 |
| `io.do/di/ai/ao` | IO Image / IO Service | IO 事件和 trace |
| `wait/pulse/timer` | Wait Registry / IO Service | wait 状态、timeout、pulse trace |
| `alarm/raise/try/catch` | Alarm Queue / Exception Handler | 报警和异常处理结果 |
| `operation.process` | Operation compiler / 后处理器 | 工艺参数、转换报告 |

## 9. 诊断传递流程

```mermaid
flowchart TD
  A[GRL Parser] -->|语法错误| D[Diagnostic]
  B[Semantic Analyzer] -->|类型/单位/引用/IO/后处理错误| D
  C[KDL WASM] -->|IK/限位/奇异/轨迹错误| D
  E[Post Processor] -->|不支持或近似转换| D

  D --> F{severity}
  F -->|error| G[阻止编译或进入 alarm/hold]
  F -->|warning| H[允许继续但写入报告]
  F -->|info| I[写入 trace 或调试信息]

  D --> J[sourceMap]
  J --> J1[GRL file/line/column]
  J --> J2[pathId/pathPointId]
  J --> J3[operationId]
  J --> J4[brandSource]
```

## 10. 总结

项目的数据流以 GRL IR 为中枢：

1. GRL 文本、Path、Operation、IO 和品牌扩展先进入 TypeScript 编译层。
2. 编译层完成语法、语义、单位、source map 和后处理能力检查。
3. 只有运动相关 IR 被转换为 KDL WASM request。
4. KDL WASM 返回轨迹、节拍和结构化诊断。
5. 虚拟控制器消费 IR 和轨迹，后处理器消费 IR 和品牌 profile。
6. 诊断贯穿 Parser、Semantic Analyzer、KDL WASM 和 Post Processor，并通过 source map 回到 GRL、Path、Operation 或品牌源。
