# 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`。