KDL_WORK/working2/01-项目功能内容.md

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. 机器人程序集

程序集建议落在：

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 演示包内容

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。