Add ABB120 demo suite and docs

2026-06-28 20:58:18 +08:00
parent 84a5b54195
commit 65187499d6
820 changed files with 215410 additions and 211 deletions
--- a/working2/01-项目功能内容.md
+++ b/working2/01-项目功能内容.md
@@ -0,0 +1,216 @@
+# 01-项目功能内容
+
+版本：0.1
+日期：2026-06-28
+
+## 1. 总体需求
+
+目标是对标 `通用机器人编程语法规范.md`，以 ABB IRB120 3/58 URDF fixture 为基础，创建一套覆盖 GRL 语法规范的机器人程序集，并全面完成虚拟控制器执行验收。
+
+核心结果：
+
+1. 语法规范覆盖矩阵：每个 GRL 章节都有对应程序、静态测试或后处理测试。
+2. ABB120 机器人程序集：覆盖数据声明、表达式、工具/坐标、目标点、速度、zone、运动、path、operation、IO/wait、流程控制、proc/func、异常、品牌扩展和后处理。
+3. 虚拟控制器执行报告：每个可执行程序都能生成 controller state、program counter、motion queue、trace、IO image、wait/alarm、source map 和 trajectory 证据。
+4. 错误诊断套件：限位、不可达、表达式错误、单位错误、wait timeout、重复符号、非法控制流等故障必须稳定输出 diagnostic。
+5. 三品牌输出与回读：同一 IR 输出 ABB RAPID、FANUC LS 风格、KUKA KRL 风格，并生成 post/roundtrip 差异报告。
+6. 服务器演示包：把虚拟控制器网站、19 个 GRL 规范测试程序、最新 W2 job 证据包、截图和使用说明打包发布到 HTTPS 服务器，用户可通过浏览器演示虚拟控制器全部功能。
+
+## 2. 覆盖分层
+
+不是所有语法都应强行作为虚拟控制器 happy path 执行。覆盖分为三层：
+
+| 层级 | 范围 | 验收方式 |
+| --- | --- | --- |
+| Runtime | `module/proc/main`、数据、表达式、target、speed、zone、movej/movel/movec、path、operation、IO、wait、pulse、if/while/for/switch、call/return、alarm/raise/try | 虚拟控制器加载并执行，输出 trace 和状态快照。 |
+| Static | `func` 副作用限制、参数方向、scope、label/jump 合法性、switch case 常量、表达式诊断、trap/interrupt/task 语义边界 | parser/semantic diagnostic 和 source map。 |
+| Post | `post_hint`、`@brand.*`、ABB/FANUC/KUKA 映射、导入回读、runtime 表达式保真边界 | post report、roundtrip report、差异报告。 |
+
+## 3. ABB120 基准
+
+ABB120 基准沿用仓库稳定 fixture：
+
+| 项 | 值 |
+| --- | --- |
+| robotId | `abb_irb120_3_58` |
+| URDF 常量 | `ABB_IRB120_3_58_URDF` |
+| load options | `ABB_IRB120_LOAD_OPTIONS` |
+| baseLink | `base_link` |
+| tipLink | `tool0` |
+| active joints | `joint_1` 到 `joint_6` |
+| 标准关节位 | `home`、`approach`、`pick`、`place` |
+
+程序中的 reachable pose target 应优先由 ABB120 FK 生成并固化为 snapshot。不可达 pose、限位和奇异姿态只进入 error suite。
+
+## 4. 机器人程序集
+
+程序集建议落在：
+
+```text
+kdl-wasm/web/tests/fixtures/abb120/spec-programs/
+  runtime/
+  static/
+  post/
+  error/
+  expected/
+```
+
+### 4.1 Runtime happy path
+
+| 程序 | 覆盖目标 |
+| --- | --- |
+| `W2_00_MinimalModule.grl` | language、module、proc main、const speed/zone、movej。 |
+| `W2_10_DataTargetToolFrame.grl` | tool、frame、load、joint_target、pose_target、pose、poseq、robot_config、ext_axis 边界。 |
+| `W2_20_ExpressionMath.grl` | 算术、比较、逻辑、单位后缀、pi/e、三角函数、数值函数、编译期求值。 |
+| `W2_30_MotionAllTypes.grl` | movej、movel、movec、set_tool、set_frame、set_speed、set_zone、inline speed/zone。 |
+| `W2_40_PathEvents.grl` | path defaults/source、point、event before/after/at distance、run_path。 |
+| `W2_50_OperationProcess.grl` | operation kind/process/start_action/end_action/run_operation。 |
+| `W2_60_IOWaitPulse.grl` | io 地址、DO 写入、wait、timeout、on_timeout、pulse、all/any/rising/falling/changed。 |
+| `W2_70_ControlFlow.grl` | if/elseif/else、while、for、switch、break、continue。 |
+| `W2_80_ProcFuncCall.grl` | proc 参数、in/out/inout、call、return、func 返回值和函数调用表达式。 |
+| `W2_90_ExceptionAlarm.grl` | alarm、raise、try/catch/finally 可执行边界。 |
+| `W2_99_FullSpecExample.grl` | 完整示例的 tool/frame、path、operation、IO event、run_operation 和回 home。 |
+
+### 4.2 Static/error suite
+
+| 程序 | 覆盖目标 |
+| --- | --- |
+| `W2_E10_ExpressionDiagnostics.grl` | `GRL_EXPR_PARSE/DOMAIN/DIV_ZERO/UNIT_MISMATCH/NON_CONSTANT/UNKNOWN_*`。 |
+| `W2_E20_SemanticDiagnostics.grl` | 重复符号、缺失引用、类型不匹配、非法 out/inout 实参。 |
+| `W2_E30_MotionDiagnostics.grl` | 关节限位、不可达 pose、movec 共线、缺少 tool/frame/speed/zone。 |
+| `W2_E40_ControlFlowDiagnostics.grl` | 非法 break/continue、jump 进入块、重复 case、非常量 case。 |
+| `W2_E50_RuntimeTimeout.grl` | wait timeout、on_timeout alarm/call、trace 和报警 source map。 |
+
+### 4.3 Post/import suite
+
+| 程序 | 覆盖目标 |
+| --- | --- |
+| `W2_P10_BrandHints.grl` | `post_hint`、`@brand.abb/fanuc/kuka` 元数据和转换报告。 |
+| `W2_P20_CrossBrandMotion.grl` | ABB/FANUC/KUKA 的 move、speed、zone、IO、wait 映射。 |
+| `W2_P30_Roundtrip.grl` | post 后重新导入，比较 target/path/motion/operation 等价性。 |
+
+## 5. 虚拟控制器执行要求
+
+每个 runtime 程序必须执行以下控制器命令序列：
+
+1. `loadProgram`
+2. `start`
+3. `stepInto`
+4. `hold`
+5. `resume`
+6. `stepMotion`
+7. `stop`
+8. `resetFault`
+
+每次运行必须输出：
+
+| 证据 | 内容 |
+| --- | --- |
+| `job.json` | job_id、suite_id、program_id、robot_id、git revision、输入文件 hash。 |
+| `compile.json` | AST/IR 摘要、diagnostics、source map 统计。 |
+| `controller.json` | 状态机转换、mode、program pointer、scope、变量快照。 |
+| `motion-queue.json` | 队列项、activeIndex、duration、blend、planner diagnostic。 |
+| `trace.json` | motion、IO、wait、pulse、alarm、call/return、source map。 |
+| `io.json` | DI/DO/AI/AO/GI/GO/RI/RO 初值、脚本变化和最终状态。 |
+| `trajectory.json` | 采样点数、起止关节、TCP 路径、限位和奇异诊断。 |
+| `report.html/json` | 汇总报告、失败摘要、可追溯链接。 |
+
+## 6. 全面验收
+
+验收不只看测试通过，还必须证明“覆盖了语法规范”：
+
+1. `programs/manifest.md` 中每个规范章节至少有一项程序或测试覆盖。
+2. 每个 Runtime 程序有虚拟控制器执行证据。
+3. 每个 Static/error 程序有稳定 diagnostic。
+4. 每个 Post/import 程序有 post report 或 roundtrip report。
+5. HTML 虚拟控制器可以打开 ABB120 suite 最新 job，显示程序、队列、trace、IO、wait、报警和报告。
+
+## 7. 服务器演示包功能要求
+
+服务器演示包用于对外展示虚拟控制器能力，不能只发布静态 HTML。包内必须包含可被页面读取和人工检查的测试程序、运行证据和说明文档。
+
+### 7.1 发布目标
+
+| 项 | 值 |
+| --- | --- |
+| HTTPS 访问地址 | `https://82.156.24.101:8095/` |
+| 服务端口 | `8095` |
+| 推荐服务器目录 | `/opt/kdl-olp-demo/8095/current` |
+| 发布包归档目录 | `/opt/kdl-olp-demo/8095/releases/<release_id>` |
+| 回滚链接 | `/opt/kdl-olp-demo/8095/previous` 或保留上一个 release 目录 |
+
+### 7.2 演示包内容
+
+```text
+demo-package/
+  app/
+    virtual-controller.html
+    virtual-controller.css
+    virtual-controller.js
+  spec-programs/
+    manifest.json
+    runtime/*.grl
+    static/*.grl
+    error/*.grl
+    post/*.grl
+  test-results/
+    abb120-spec/<latest-job>/
+      job.json
+      report.json
+      report.html
+      programs/<program_id>/*.json
+    virtual-controller/
+      evidence.json
+      virtual-controller-desktop.png
+      virtual-controller-mobile.png
+  docs/
+    GRL功能语法逻辑与程序创建使用手册.docx
+    通用机器人离线编程系统测试文档.docx
+  index.html
+  demo-manifest.json
+  README.md
+```
+
+### 7.3 演示能力清单
+
+| 能力 | 演示程序或证据 |
+| --- | --- |
+| 最小加载和 MoveJ | `W2_00_MinimalModule.grl` |
+| 数据、目标点、工具和坐标系 | `W2_10_DataTargetToolFrame.grl` |
+| 表达式、单位和数学函数 | `W2_20_ExpressionMath.grl` |
+| MoveJ/MoveL/MoveC | `W2_30_MotionAllTypes.grl` |
+| Path 和事件 | `W2_40_PathEvents.grl` |
+| Operation 工艺封装 | `W2_50_OperationProcess.grl` |
+| IO、wait、pulse、边沿 | `W2_60_IOWaitPulse.grl` |
+| 流程控制 | `W2_70_ControlFlow.grl` |
+| proc/func/call/return | `W2_80_ProcFuncCall.grl` |
+| 异常和报警 | `W2_90_ExceptionAlarm.grl` |
+| 完整示例 | `W2_99_FullSpecExample.grl` |
+| 表达式错误诊断 | `W2_E10_ExpressionDiagnostics.grl` |
+| 语义错误诊断 | `W2_E20_SemanticDiagnostics.grl` |
+| 运动错误诊断 | `W2_E30_MotionDiagnostics.grl` |
+| 控制流错误诊断 | `W2_E40_ControlFlowDiagnostics.grl` |
+| wait timeout | `W2_E50_RuntimeTimeout.grl` |
+| 品牌 hint/post report | `W2_P10_BrandHints.grl` |
+| 跨品牌 motion/IO/wait 输出 | `W2_P20_CrossBrandMotion.grl` |
+| post 后导入回读 | `W2_P30_Roundtrip.grl` |
+
+### 7.4 页面演示要求
+
+1. 首页必须能进入虚拟控制器页面。
+2. 页面必须能看到当前 suite、job_id、程序数量、通过/诊断/失败统计。
+3. 页面必须列出 19 个程序，并支持查看源码或证据摘要。
+4. 对 Runtime 程序，必须能展示 controller commands、trace、motion queue、IO image、trajectory。
+5. 对 Static/error 程序，必须能展示 expected diagnostics 和实际 diagnostics。
+6. 对 Post 程序，必须能展示 ABB/FANUC/KUKA 文件名、post report 和 roundtrip 状态。
+7. 页面必须保留桌面和移动端截图证据，便于远程验收。
+
+### 7.5 验收结论口径
+
+只有同时满足以下条件，服务器演示包才可以标记为通过：
+
+1. 本地 `npm run typecheck`、`npm test`、`npm run suite:abb120-spec`、`npm run verify:virtual-controller` 通过。
+2. 演示包包含 19 个 `.grl` 程序和最新 `W2-JOB-*` 证据。
+3. 远程 `https://82.156.24.101:8095/` 可打开，无证书阻断以外的页面错误。
+4. 远程页面能访问 `demo-manifest.json`、`report.json`、`virtual-controller.html` 和截图文件。
+5. 远程 smoke test 记录到 `working2/05-验收证据.md`。