wangdequan/KDL_WORK

Fork 0

Files

wangdequan 65187499d6 Add ABB120 demo suite and docs

2026-06-28 20:58:18 +08:00

12 KiB

Raw Blame History

02-项目程序开发详细步骤

版本：0.1 日期：2026-06-28

1. 开发原则

以 通用机器人编程语法规范.md 为覆盖源，不以现有测试数量作为完成标准。
ABB120 URDF 使用仓库内稳定 fixture，不引入未验证机器人模型。
happy path 必须可执行；error path 必须可诊断；post path 必须可报告。
虚拟控制器只执行 Semantic IR，不直接解释品牌文本。
所有新增程序都要保留 source map，报告必须能定位到 GRL 文件行列。

2. 阶段 0：规范覆盖矩阵

W2-SPEC-001：解析语法规范章节

步骤：

从 work/doc/通用机器人编程语法规范.md 抽取章节、关键语法、示例和语义规则。
建立 coverage item，字段包含 spec_section、syntax、runtime_level、program_id、test_id、evidence。
把覆盖矩阵写入 working2/programs/manifest.md。

验收：章节 4 到 23 均有覆盖项；章节 25 的 P0 项全部映射到 runtime 或 static 测试。

W2-SPEC-002：定义执行边界

步骤：

标记虚拟控制器必须执行的 Runtime 语义。
标记只做 semantic diagnostic 的 Static 语义。
标记只做后处理/导入报告的 Post 语义。
对 trap、interrupt、task、brand metadata 等非 P0 执行项写清楚边界。

验收：覆盖矩阵中每项都有 Runtime/Static/Post 分类，不允许空白。

3. 阶段 1：ABB120 程序集

W2-PROG-001：建立 spec-programs 目录

建议目录：

kdl-wasm/web/tests/fixtures/abb120/spec-programs/
  runtime/
  static/
  error/
  post/
  expected/

验收：测试 helper 可以枚举所有 .grl 并读取 manifest。

W2-PROG-010：Runtime 程序

步骤：

创建 W2_00 到 W2_90 十个 runtime 程序，并以 W2_99_FullSpecExample 覆盖第 24 章完整示例。
所有运动目标使用 ABB120 标准关节位或 FK 固化 pose。
每个程序顶部注释写明覆盖的 spec section。
每个程序必须可 parse、compile、load 到虚拟控制器。

验收：runtime 程序全部生成 AST/IR/source map snapshot。

W2-PROG-020：Static/error 程序

步骤：

创建表达式、语义、运动、控制流、runtime timeout 五类 error 程序。
每个 error 程序只聚焦一类错误，避免多个错误互相遮蔽。
expected diagnostic 固化 code/severity/message/sourceRange。

验收：diagnostic snapshot 稳定，新增或消失的错误会导致测试失败。

W2-PROG-030：Post/import 程序

步骤：

创建品牌 hint 和跨品牌 motion 程序。
覆盖 ABB/FANUC/KUKA speed、zone、IO、wait、operation 输出。
固化 roundtrip 输入和差异报告。

验收：三品牌输出非空，近似和不支持项进入 report。

4. 阶段 2：编译和 KDL 验证

W2-RUN-001：统一 suite runner

步骤：

扩展或新增 runAbb120SpecSuite。
输入：program root、suite id、ABB120 fixture、output root。
输出：job_id、程序 manifest、每个程序的 compile/run/post 结果。
job id 格式：W2-JOB-YYYYMMDD-HHMMSS-<short-hash>。

验收：单条命令可生成完整 suite 证据目录。

W2-RUN-010：编译链路

步骤：

parseGrl 生成 AST。
compileSemanticProgram 生成 IR。
对 data/target/path/operation 建 source map 索引。
保存 AST/IR 摘要，不保存过大的重复文本。

验收：每个 runtime/post 程序 compile 无 error；每个 error 程序 compile 输出预期 diagnostic。

W2-RUN-020：ABB120 KDL 检查

步骤：

加载 ABB120 URDF。
对所有 joint target 做 limit check。
对所有 pose target 做 IK 或记录当前实现边界 diagnostic。
对每条 motion/path 生成 planner request。

验收：happy path 没有关节限位错误；不可达或不支持 IK 只能出现在 error suite。

5. 阶段 3：虚拟控制器执行

W2-RUN-030：状态机命令覆盖

步骤：

对每个 runtime 程序执行 load/start/step/hold/resume/stepMotion/stop/resetFault。
记录每次命令前后状态。
非法命令转移必须产生明确 diagnostic。

验收：状态机转换符合控制器规则，trace 可回放。

W2-RUN-040：Motion Queue 和轨迹

步骤：

将 movej/movel/movec/run_path/run_operation 展开到 motion queue。
记录 queue item、activeIndex、duration、planner result。
对轨迹采样点做 limit 和 singularity 检查。

验收：motion queue 与程序 source map 对齐；轨迹结果可进入报告。

W2-RUN-050：IO、wait、pulse 和报警

步骤：

为 W2_60_IOWaitPulse 注入 DI 脚本。
覆盖 wait satisfied、waiting、timeout、on_timeout alarm/call。
覆盖 pulse 自动复位。
覆盖 all/any/rising/falling/changed。

验收：trace 中可看到 IO 写入、DI 变化、wait 状态、pulse reset 和 alarm。

W2-RUN-060：流程控制和调用栈

步骤：

执行 if/elseif/else、while、for、switch。
记录局部变量、循环变量、call stack、return。
out/inout 参数回写进入变量快照。

验收：最终变量状态符合预期，source map 可定位当前执行语句。

6. 阶段 4：后处理和导入回读

W2-POST-010：三品牌 post

步骤：

对 runtime/post 程序调用 postProcessAllBrands。
保存 ABB .mod、FANUC .ls、KUKA .src/.dat。
保存 post report，记录近似和 unsupported。

验收：所有品牌输出包含对应 motion、IO、wait 和 proc 结构。

W2-POST-020：roundtrip

步骤：

将三品牌输出重新导入。
对比 motion 顺序、target 数量、path/operation 结构。
对差异生成 roundtrip.json。

验收：happy path 结构等价；不可逆项全部进入 diff。

7. 阶段 5：HTML 虚拟控制器验收

W2-UI-010：加载最新 job

步骤：

HTML 页面支持选择或加载 W2-JOB-* 证据。
显示程序列表、当前程序、controller snapshot、queue、trace、diagnostics。
点击 trace/source map 能定位 GRL 行。

验收：页面能展示 working2 suite 证据，不只展示静态 mock 数据。

W2-UI-020：截图验证

步骤：

使用现有 verify-virtual-controller.mjs 或新增参数打开 working2 job。
截桌面和移动视口。
检查 command bar、object tree、viewport、pendant、editor、bottom panel 可见。
检查无横向溢出和文字重叠。

验收：生成 desktop/mobile 截图和 evidence.json。

8. 阶段 6：全量 CI

建议命令：

cd E:\Work\kdl_work
npm run typecheck
npm test -- grl abb120 virtual controller runtime post import
npm run verify:virtual-controller

如果需要 WASM native 验证：

cmake --build kdl-wasm/build-wasm -j16

验收：所有命令通过，working2/05-验收证据.md 记录实际命令、时间、job_id、report_id 和产物路径。

9. 阶段 7：服务器演示包和 HTTPS 发布

W2-DEPLOY-001：生成演示包 manifest

步骤：

读取 kdl-wasm/web/tests/fixtures/abb120/spec-programs/manifest.json。
读取最新 kdl-wasm/web/test-results/abb120-spec/W2-JOB-*。
读取 kdl-wasm/web/test-results/virtual-controller/evidence.json。
生成 demo-manifest.json，字段至少包含：
- release_id
- generated_at
- suite_id
- job_id
- program_count
- programs
- report_json
- virtual_controller_entry
- screenshots
- docs
manifest 中路径必须是相对发布根目录的 URL 路径，不能写本机绝对路径。

验收：demo-manifest.json 可被浏览器直接打开，能定位 19 个程序、最新报告和截图。

W2-DEPLOY-010：收集演示包文件