Upload project files

2026-06-28 08:20:33 +08:00
parent f0e96308d2
commit 84a5b54195
162 changed files with 14070 additions and 31381 deletions
--- a/working/01-项目功能内容.md
+++ b/working/01-项目功能内容.md
@@ -1,29 +1,52 @@
 # 01-项目功能内容

-版本：0.3  
+版本：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. 项目定位

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

 ```text
-GRL Source
-  -> Lexer / Parser
-  -> AST
-  -> Symbol Table
-  -> Semantic Analyzer
-  -> Executable IR / MotionSegmentRequest
-  -> KdlWorkerClient
-  -> KDL WASM
+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
 ```

-Web UI、OPFS、碰撞检测和真实控制器通信不作为独立实施主线；相关内容只在两份对标文档明确要求的 GRL 工程结构、轨迹 trace、虚拟控制器调用关系、后处理或测试场景中进入范围。
+首版 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 语言功能范围

@@ -324,9 +347,242 @@ KDL WASM 不负责：
 5. `compareTrajectory`
 6. 外部轴协调相关函数。

-## 4. 共享数据和单位
+## 4. 虚拟控制器和 IO 运行时范围

-### 4.1 单位
+### 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 编译器内部必须统一：

@@ -340,7 +596,7 @@ GRL 编译器内部必须统一：
 | 角速度 | radian/second |
 | 加速度 | meter/second^2 或 radian/second^2 |

-### 4.2 位姿
+### 7.2 位姿

 内部统一为：

@@ -353,7 +609,7 @@ interface Pose {

 GRL `pose(x, y, z, rx, ry, rz)` 必须在 TypeScript 编译层规范化为 KDL `Pose`。

-### 4.3 目标点
+### 7.3 目标点

 必须统一到：

@@ -376,7 +632,7 @@ interface JointTarget {
 }
 ```

-### 4.4 速度和 zone
+### 7.4 速度和 zone

 GRL 速度和过渡必须编译为：

@@ -395,7 +651,7 @@ type ZoneSpec =

 首版 `zone` 只用于诊断和后处理，运动规划按 `fine` 到点执行，并产生 `KDL_ZONE_APPROXIMATED`。

-### 4.5 诊断
+### 7.5 诊断

 所有语言、语义、KDL 和后处理错误必须结构化。KDL 固定 code 至少包含：

@@ -429,7 +685,7 @@ GRL 语义诊断至少覆盖：
 13. Operation 引用不存在的 Path。
 14. 后处理品牌不支持所用语义。

-## 5. GRL 与 KDL 的调用关系
+## 8. GRL 与 KDL 的调用关系

 | GRL 语法 | 编译结果 | KDL WASM 函数 |
 | --- | --- | --- |
@@ -453,9 +709,9 @@ GRL 语义诊断至少覆盖：
 6. `alarm/raise/try/catch`
 7. `operation.process`

-## 6. 验收口径
+## 9. 验收口径

-### 6.1 GRL P0 验收
+### 9.1 GRL P0 验收

 1. EBNF 覆盖语法规范第 22 章。
 2. 语法规范第 23 章完整示例可解析。
@@ -466,7 +722,7 @@ GRL 语义诊断至少覆盖：
 7. `movej/movel/movec` 可编译为对应 KDL request。
 8. ABB、FANUC、KUKA 后处理原型有 golden file。

-### 6.2 KDL P0 验收
+### 9.2 KDL P0 验收

 1. P0 29 个函数全部在 TypeScript API 和 Worker RPC 中可调用。
 2. URDF 到 KDL Chain joint 顺序稳定。
@@ -480,7 +736,7 @@ GRL 语义诊断至少覆盖：
 10. `planPath/validatePath` 保留 segment、target 和 source map。
 11. 错误处理不抛裸字符串，返回结构化 `KdlError` 或 `MotionDiagnostic`。

-### 6.3 集成验收
+### 9.3 集成验收

 1. GRL `movej/movel/movec` 编译为 KDL request 并生成轨迹。
 2. GRL `path` 编译为 `PathPlanRequest` 并生成整条路径。
@@ -488,3 +744,37 @@ GRL 语义诊断至少覆盖：
 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. 流程图资产与功能文档、任务矩阵、验收证据之间无断链。