KDL_WORK/work/doc/通用机器人项目功能与数据流程图.md

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

版本：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. 总体功能流程图

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 编译与执行流程图

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 计算流程图

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. 数据传递流程图

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. 诊断传递流程

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 或品牌源。