同步KDL工程源码到云仓库

work/doc/通用机器人项目主要实施步骤.md

@@ -0,0 +1,530 @@
+# 通用机器人项目主要实施步骤
+
+版本：0.1  
+日期：2026-06-27  
+来源：`/home/meswork/kdl_work/work/working1`  
+用途：作为阅读参考，概览项目从 KDL WASM 计算接口到 GRL 编译与后处理的主要实施步骤。
+
+## 1. 实施主线
+
+项目实施分两条主线推进：
+
+1. KDL WASM 计算接口线
+   - 任务编号：`KW-001` 到 `KW-013`
+   - 对标：`KDL_WASM计算接口设计.md`
+   - 目标：提供稳定的 Worker API、机器人模型、运动学、轨迹规划、Path 验证、诊断和性能能力。
+
+2. GRL 编程语法线
+   - 任务编号：`KW-100` 到 `KW-112`
+   - 对标：`通用机器人编程语法规范.md`
+   - 目标：实现 GRL lexer/parser、AST、语义检查、IR、Path/Operation、IO/wait、后处理和自动生成。
+
+两条线的集成点是：GRL 的 `movej/movel/movec/path/operation` 编译为 KDL WASM 的 `MoveJRequest/MoveLRequest/MoveCRequest/PathPlanRequest`，由 KDL WASM 返回轨迹和诊断。
+
+## 2. 推荐工程结构
+
+```text
+/home/meswork/kdl_work/
+  orocos_kinematics_dynamics/
+    orocos_kdl/
+  kdl-wasm/
+    CMakeLists.txt
+    bindings/
+      kdl_c_api.cpp
+      kdl_embind.cpp
+    web/
+      src/
+        kdl/
+          kdlClient.ts
+          kdl.worker.ts
+          rpc.ts
+          types.ts
+        robot/
+          urdfParser.ts
+          normalizedRobotModel.ts
+        grl/
+          lexer/
+          parser/
+          ast/
+          semantic/
+          ir/
+          generator/
+        post/
+          abb/
+          fanuc/
+          kuka/
+      tests/
+        kdl/
+        grl/
+        integration/
+        post/
+```
+
+## 3. 阶段 1：基础工程、Worker RPC 和 GRL 词法骨架
+
+关联任务：`KW-001`、`KW-100`、`KW-101`
+
+目标：
+
+1. 建立 `kdl-wasm` wrapper 工程。
+2. 使用 Emscripten 编译 Orocos KDL，生成 `kdl.js`、`kdl.wasm`、`kdl.d.ts`。
+3. 建立 `KdlRpcRequest/KdlRpcResponse` 和 `KdlWorkerClient`。
+4. KDL WASM 只在 Worker 中运行。
+5. 建立 GRL lexer，支持注释、标识符、字符串、数字、单位和保留关键字。
+6. 建立 GRL parser 和 AST 骨架，支持 `language grl 0.1`、`module`、`import`、顶层声明。
+
+输入：
+
+1. Orocos KDL 源码。
+2. GRL 源文件。
+
+输出：
+
+1. KDL WASM 构建产物。
+2. Worker RPC 基础 API。
+3. GRL Tokens 和 AST。
+
+验收重点：
+
+1. `init()` 返回 `KdlRuntimeInfo`。
+2. Worker 请求有唯一 id。
+3. 错误返回 `{ code, message, diagnostics }`。
+4. GRL 最小文件可解析。
+5. AST 保留 source range、注释位置、单位原文和规范化值。
+
+## 4. 阶段 2：机器人模型、GRL 数据声明和共享类型
+
+关联任务：`KW-002`、`KW-102`
+
+目标：
+
+1. TypeScript 解析 URDF XML。
+2. 检查 link/joint 连通性和单位。
+3. 生成 `NormalizedRobotModel`。
+4. WASM 根据标准模型构造 KDL `Tree/Chain`。
+5. 创建 `RobotHandle` 并缓存求解器。
+6. GRL 支持 `const/var/persistent`、基础类型、机器人类型。
+7. GRL 支持 `tool/frame/load/joint_target/pose_target/pose/poseq/robot_config/ext_axis/speed/zone/offset/offset_in`。
+
+输入：
+
+1. `robot.urdf`
+2. GRL 中的 tool/frame/target/speed/zone 声明。
+
+输出：
+
+1. `NormalizedRobotModel`
+2. `RobotHandle`
+3. `JointTarget`
+4. `PoseTarget`
+5. `SpeedSpec`
+6. `ZoneSpec`
+7. `OffsetSpec`
+
+验收重点：
+
+1. URDF joint 顺序稳定。
+2. base/tip 不连通返回 `KDL_INVALID_MODEL`。
+3. `getRobotInfo/getJointLimits` 正确。
+4. GRL target 能编译为 KDL 共享数据结构。
+5. speed/zone 能编译为 `SpeedSpec/ZoneSpec`。
+
+## 5. 阶段 3：KDL 基础运动学和 GRL 运动指令
+
+关联任务：`KW-003` 到 `KW-006`、`KW-103`
+
+目标：
+
+1. 实现 KDL `fk`、`fkAllLinks`。
+2. 实现 KDL `ik`、`ikBatch`。
+3. 实现 KDL `jacobian`、`checkSingularity`、`checkJointLimits`、`checkReachability`、`checkReachabilityBatch`、`checkVelocityLimits`。
+4. 实现 KDL `normalizePose`、`composePose`、`inversePose`、`applyToolAndFrame`、`applyOffset`。
+5. GRL 支持 `movej/movel/movec` 和 `set_tool/set_frame/set_speed/set_zone`。
+6. GRL 运动指令编译为 `MotionInstruction`，再映射为 KDL request。
+
+输入：
+
+1. `RobotHandle`
+2. `JointTarget`
+3. `PoseTarget`
+4. `tool/frame/speed/zone`
+5. GRL 运动语句。
+
+输出：
+
+1. FK/TCP 位姿。
+2. IK 关节解。
+3. Jacobian 和奇异性诊断。
+4. `MotionInstruction`
+5. `MoveJRequest/MoveLRequest/MoveCRequest`
+
+验收重点：
+
+1. FK 与 golden 数据或原生 KDL 对比在容差内。
+2. IK 后 FK 回代误差小于容差。
+3. `ikBatch` 返回顺序与输入顺序一致。
+4. 奇异点返回 `KDL_SINGULARITY` warning。
+5. `offset`、`offset_in tool`、`offset_in frame` 结果正确。
+6. GRL 编译到 IR 前能解析确定的 tool、frame、speed、zone。
+
+## 6. 阶段 4：梯形速度和三类基础运动轨迹
+
+关联任务：`KW-007` 到 `KW-010`
+
+目标：
+
+1. 实现 `makeTrapProfile` 和 `sampleTrapProfile`。
+2. 实现 `planMoveJ`。
+3. 实现 `planMoveL`。
+4. 实现 `planMoveC`。
+
+MOVEJ 重点：
+
+1. `joint_target` 直接作为 `qEnd`。
+2. `pose_target` 先 IK 得到 `qEnd`。
+3. 各关节同起同停。
+4. 每个采样点 FK 输出 TCP。
+
+MOVEL 重点：
+
+1. 起点由 `startJoints` FK 得到。
+2. 目标点应用 tool/frame/offset。
+3. 生成 TCP 直线采样。
+4. 逐点 IK，seed 使用上一采样点关节。
+
+MOVEC 重点：
+
+1. 起点由当前关节 FK 得到。
+2. via 和 target 应用 tool/frame/offset。
+3. 检查三点重合或近似共线。
+4. 计算圆心、半径、法向、角度、弧长。
+5. `TrajectoryResult.meta.circle` 包含 `CirclePlanMeta`。
+
+输入：
+
+1. `MoveJRequest`
+2. `MoveLRequest`
+3. `MoveCRequest`
+4. `TrapProfileOptions`
+
+输出：
+
+1. `TrapProfileResult`
+2. `TrajectoryResult`
+3. `MotionDiagnostic`
+
+验收重点：
+
+1. 梯形速度曲线长距离为 trapezoid，短距离为 triangle。
+2. 采样首点 `s=0`，末点 `s=1`，`s` 单调递增。
+3. MOVEJ 关节同起同停。
+4. MOVEL TCP 直线误差小于容差。
+5. MOVEC 圆弧元数据正确。
+6. 三点共线返回 `KDL_ARC_DEGENERATE`。
+7. P0 中非 fine zone 返回 `KDL_ZONE_APPROXIMATED`。
+
+## 7. 阶段 5：Path、Operation 和批量路径验证
+
+关联任务：`KW-011`、`KW-104`、`KW-105`
+
+目标：
+
+1. GRL 支持 `path/defaults/source/point/event/run_path`。
+2. GRL 支持 `operation/kind/path/process/start_action/end_action/run_operation`。
+3. Path 编译为 `PathPlanRequest`。
+4. Operation 展开为 start action + path + end action。
+5. KDL 实现 `planPath` 和 `validatePath`。
+
+输入：
+
+1. GRL Path。
+2. GRL Operation。
+3. `MotionSegmentRequest[]`
+4. `PathPlanRequest`
+
+输出：
+
+1. `PathPlanResult`
+2. `PathValidationResult`
+3. Path source map。
+4. Operation 展开结果。
+
+验收重点：
+
+1. 空 Path 报错。
+2. 重复 point 名称报错。
+3. `run_path` 可生成 `PathPlanRequest`。
+4. `planPath` 按 segment 顺序规划。
+5. 上一段终点关节作为下一段起点。
+6. 轨迹点合并后重新编号和更新时间。
+7. 保留 `segmentId/targetId/sourceMap`。
+8. `run_operation` 展开后 KDL 只处理 motion segment。
+
+## 8. 阶段 6：IO、wait、pulse 和流程控制
+
+关联任务：`KW-106`、`KW-107`
+
+目标：
+
+1. 支持 `io.di/do/ai/ao/gi/go/ri/ro`。
+2. 支持 `io.alias.*`。
+3. 支持 IO 赋值。
+4. 支持 `wait` 条件、`timeout`、`on_timeout alarm/call`。
+5. 支持 `all/any/rising/falling/changed`。
+6. 支持 `pulse`。
+7. 支持 `if/elseif/else`、`while`、`for`、`switch/case/default`。
+8. 支持 `break/continue/label/jump`。
+
+输入：
+
+1. IO map。
+2. GRL IO/wait/pulse 语句。
+3. GRL 流程控制语句。
+
+输出：
+
+1. `IoInstruction`
+2. `WaitInstruction`
+3. `BranchInstruction`
+4. pulse IR。
+
+验收重点：
+
+1. IO 地址按 io_map 或允许范围校验。
+2. wait 条件可编译。
+3. pulse trace 必须包含置位和复位事件。
+4. 条件表达式必须为 bool。
+5. `break/continue` 位置合法。
+6. `switch case` 为常量表达式且不重复。
+7. `jump` 不能跳入非法块结构。
+8. IO、wait、pulse 和流程控制不直接进入 KDL。
+
+## 9. 阶段 7：proc、func、异常、报警、中断和多任务语法
+
+关联任务：`KW-108`、`KW-109`
+
+目标：
+
+1. 支持 `proc`、`func`、`call`、`return`。
+2. 支持参数方向 `in/out/inout`。
+3. 实现作用域和名称解析。
+4. 对递归给出 warning 或 error。
+5. 支持 `alarm`、`raise`、`try/catch/finally`。
+6. P1 语法保留 `trap/interrupt/enable/disable/task cycle`。
+
+输入：
+
+1. GRL 子程序和函数。
+2. GRL 异常和中断语法。
+
+输出：
+
+1. `CallInstruction`
+2. `ReturnInstruction`
+3. `AlarmInstruction`
+4. 异常处理 IR。
+5. P1 语法 AST。
+
+验收重点：
+
+1. `out` 参数所有正常返回路径赋值。
+2. `inout/out` 实参必须为左值。
+3. `func` 所有正常返回路径返回兼容类型。
+4. `func` 默认不允许执行运动、wait、pulse、run_path、run_operation。
+5. P0 支持 alarm/raise/try/catch 基础语义。
+6. P1 未实现语义必须在后处理或运行时报明确诊断。
+
+## 10. 阶段 8：语义检查、IR、source map 和 KDL 集成
+
+关联任务：`KW-110`、`KW-012`
+
+目标：
+
+1. 实现 Symbol Table。
+2. 实现 Semantic Analyzer。
+3. 生成 Executable IR。
+4. 保留 source map。
+5. 完成 GRL 到 KDL request 的编译桥接。
+6. KDL 实现 `estimateCycleTime` 和 `resampleTrajectory`。
+7. 建立统一诊断分级：error、warning、info。
+
+必须检查：
+
+1. 标识符重复或未声明。
+2. 类型是否匹配。
+3. 目标点类型是否适合运动指令。
+4. `movec` 是否缺少 via 点。
+5. 圆弧三点是否重合或共线。
+6. 工具、坐标系、速度、过渡是否可解析。
+7. 单位是否正确。
+8. IO 地址是否存在。
+9. 子程序参数数量和类型是否匹配。
+10. `out` 参数是否赋值。
+11. `func` 返回路径是否正确。
+12. `break/continue/jump` 是否合法。
+13. Path 是否为空或点名重复。
+14. Operation 是否引用不存在的 Path。
+15. 目标点是否可达。
+16. 关节是否超限。
+17. 后处理目标品牌是否支持所用语义。
+
+输入：
+
+1. AST。
+2. Symbol Table。
+3. `RobotHandle`。
+4. KDL 检查结果。
+
+输出：
+
+1. Executable IR。
+2. KDL request。
+3. `CycleTimeResult`。
+4. `MotionDiagnostic`。
+
+验收重点：
+
+1. 完整 GRL 示例可编译为 IR。
+2. IR 运动指令可映射到 KDL request。
+3. source map 能定位 GRL 行列、path point、operation。
+4. `estimateCycleTime` 只计算运动时间。
+5. `resampleTrajectory` 时间和点序稳定。
+6. 所有错误返回结构化诊断。
+
+## 11. 阶段 9：三品牌后处理原型
+
+关联任务：`KW-111`
+
+目标：
+
+1. ABB RAPID 后处理。
+2. FANUC LS/TP 风格后处理。
+3. KUKA KRL 后处理。
+4. 支持 `post_hint` 和 `@brand.*`。
+5. 生成后处理转换报告。
+
+输入：
+
+1. Executable IR。
+2. target/tool/frame/speed/zone 数据。
+3. post profile。
+4. brand metadata。
+
+输出：
+
+1. ABB RAPID 程序。
+2. FANUC LS/TP 风格文本。
+3. KUKA KRL 程序。
+4. 转换报告。
+
+验收重点：
+
+1. `movej/movel/movec` 三品牌 golden file 通过。
+2. target/tool/frame/speed/zone 映射正确。
+3. IO/wait 基础映射正确。
+4. `post_hint` 和 `@brand.*` 只影响指定品牌。
+5. 不支持语义进入转换报告，不能静默丢失。
+
+## 12. 阶段 10：自动生成、往返和性能优化
+
+关联任务：`KW-112`、`KW-013`
+
+目标：
+
+1. 自动生成 GRL 时优先生成 target/path/operation。
+2. 点名稳定。
+3. path defaults 和单点 override 稳定。
+4. source metadata 稳定。
+5. 支持 compact/expanded 输出风格。
+6. 生成 GRL 可再解析回等价对象。
+7. KDL 底层导出稳定 C ABI。
+8. 高频 FK/IK 增加 TypedArray 版本。
+9. RobotHandle 缓存 FK、IK、Jacobian solver。
+10. 长路径分块计算或提供进度。
+
+输入：
+
+1. 自动编程对象。
+2. Path/Operation 数据。
+3. KDL 批量计算输入。
+
+输出：
+
+1. 稳定 GRL 文本。
+2. 可回读 AST/IR。
+3. C ABI / Embind API。
+4. TypedArray 批量接口。
+5. 性能报告。
+
+验收重点：
+
+1. 同一输入重复生成结果一致。
+2. 生成文本可 diff。
+3. 生成文本可解析、语义检查并后处理。
+4. 单机器人 6 轴初始化小于 1 秒。
+5. 单次 FK 小于 1 ms。
+6. 单次 IK 平均小于 10 ms。
+7. 1000 个目标点批量可达性检查在可接受交互时间内完成。
+8. 10 秒轨迹按 4 ms 采样约 2500 点可稳定生成和回放。
+
+## 13. 推荐集成顺序
+
+```text
+1. KW-001 + KW-100 + KW-101
+   基础工程、Worker RPC、Lexer/Parser 骨架。
+
+2. KW-002 + KW-102
+   URDF/标准模型和 GRL target/tool/frame/speed/zone。
+
+3. KW-003 到 KW-006 + KW-103
+   运动指令编译到 KDL FK/IK/变换。
+
+4. KW-007 到 KW-010
+   梯形速度、MOVEJ、MOVEL、MOVEC。
+
+5. KW-104 + KW-011
+   Path 编译为 PathPlanRequest，KDL 生成整条路径。
+
+6. KW-105 + KW-011
+   Operation 展开后复用 Path 规划。
+
+7. KW-106 到 KW-110
+   完成 P0 语义检查和 IR。
+
+8. KW-111
+   三品牌后处理原型。
+
+9. KW-112 + KW-013
+   自动生成、往返、性能和批量优化。
+```
+
+## 14. 常用验证命令
+
+实际命令以工程 `package.json` 和 CMake 配置为准。每个阶段至少应提供等效命令：
+
+```bash
+npm run typecheck
+npm run test -- grl
+npm run test -- kdl
+npm run test -- integration
+npm run test -- post
+npm run build
+```
+
+KDL WASM 构建：
+
+```bash
+cd /home/meswork/kdl_work
+emcmake cmake -S kdl-wasm -B kdl-wasm/build-wasm \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DKDL_SOURCE_DIR=/home/meswork/kdl_work/orocos_kinematics_dynamics/orocos_kdl
+cmake --build kdl-wasm/build-wasm -j16
+```
+
+## 15. 阅读建议
+
+1. 先读本文，理解项目主要阶段和集成顺序。
+2. 再读 `通用机器人项目功能与数据流程图.md`，理解功能流和数据流。
+3. 需要接口细节时读 `KDL_WASM计算接口设计.md`。
+4. 需要语言语法和后处理细节时读 `通用机器人编程语法规范.md`。
+5. 需要执行级任务和证据时读 `/home/meswork/kdl_work/work/working1` 下的实施文档。

work/doc/通用机器人项目功能与数据流程图-png/flow-01.mmd

@@ -0,0 +1,58 @@
+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[转换报告]

work/doc/通用机器人项目功能与数据流程图-png/flow-02.mmd

@@ -0,0 +1,42 @@
+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[转换报告]

work/doc/通用机器人项目功能与数据流程图-png/flow-03.mmd

@@ -0,0 +1,48 @@
+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]

work/doc/通用机器人项目功能与数据流程图-png/flow-04.mmd

@@ -0,0 +1,92 @@
+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

work/doc/通用机器人项目功能与数据流程图-png/flow-05.mmd

@@ -0,0 +1,16 @@
+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]

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

@@ -0,0 +1,357 @@
+# 通用机器人项目功能与数据流程图
+
+版本：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 或品牌源。