KDL_WORK/working2/06-决策记录.md

06-决策记录

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

ADR-W2-001：working2 以当前语法规范作为覆盖源

状态：Accepted 日期：2026-06-28 关联任务：W2-SPEC-001

背景

用户要求对标 通用机器人编程语法规范.md 创建机器人程序集，并全面完成虚拟控制器执行情况。working1 已经覆盖 ABB120 基础测试和虚拟控制器，但不是逐章按最新语法规范做覆盖矩阵。

决策

working2 以 work/doc/通用机器人编程语法规范.md 为唯一覆盖源。任何程序或测试是否“覆盖”，必须能追溯到规范章节、语法项和验收证据。

后果

1. 覆盖结论可审计。
2. 语法规范更新后可以重新生成缺口清单。
3. 不再用“已有测试通过”替代规范覆盖证明。

ADR-W2-002：ABB120 基准继续使用仓库内稳定 fixture

状态：Accepted 日期：2026-06-28 关联任务：W2-PROG-010、W2-RUN-020

背景

仓库已有 kdl-wasm/web/src/fixtures/abb120.ts 和测试导出 abbIrb120.ts，其中包含 ABB IRB120 3/58 URDF、load options 和标准关节位。重新引入外部 URDF 会增加模型差异和验证成本。

决策

working2 继续使用仓库内 ABB120 fixture。若未来需要独立 .urdf 文件，只能从当前 fixture 导出，不能静默替换机器人模型。

后果

1. working2 结果与 existing KDL/virtual controller 测试一致。
2. FK/IK/limit snapshot 可复用。
3. 外部 mesh/inertial 完整模型另列任务。

ADR-W2-003：语法覆盖分为 Runtime、Static、Post 三层

状态：Accepted 日期：2026-06-28 关联任务：W2-SPEC-002

背景

语法规范包含流程控制、运动、IO，也包含 trap、interrupt、task、brand metadata、post_hint 等不适合全部作为虚拟控制器 happy path 执行的语义。如果强行要求所有语法都运行，会混淆实现边界。

决策

覆盖分三层：

1. Runtime：虚拟控制器必须执行并输出 trace。
2. Static：parser/semantic 必须诊断或验证。
3. Post：后处理、导入回读和报告必须覆盖。

后果

1. happy path 稳定。
2. P1/P2 语义不会被误报为已完整执行。
3. 覆盖矩阵能清楚说明每项语法的验证方式。

ADR-W2-004：虚拟控制器验收以证据包为准

状态：Accepted 日期：2026-06-28 关联任务：W2-RUN-001 到 W2-RUN-060

背景

“执行情况”不能只看单元测试通过。虚拟控制器需要证明状态机、程序指针、motion queue、IO/wait、报警、source map 和轨迹结果都正确。

决策

每次 suite 运行生成 W2-JOB-* 证据包，至少包含：

1. job.json
2. compile.json
3. controller.json
4. motion-queue.json
5. trace.json
6. io.json
7. trajectory.json
8. report.json/html

后果

1. 运行结果可回放和审计。
2. HTML 虚拟控制器可以消费同一证据。
3. CI 失败时能定位到具体程序、source range 和 controller 状态。

ADR-W2-005：working2 不改写 working1 完成记录

状态：Accepted 日期：2026-06-28 关联任务：W2-SPEC-000

背景

working1 已记录已完成的 ABB120 基础测试、表达式功能和虚拟控制器验收。用户要求任务整合到 working2 并参考 working1，不是要求重写历史记录。

决策

working2 新建独立任务包，状态从 Todo 开始。working1 仅作为参考和可复用资产来源。

后果

1. 避免把旧验收直接当作新目标完成。
2. working2 可以独立追踪新增覆盖缺口。
3. 后续实现可以逐项把 Todo 推进到 Done。

ADR-W2-006：W2 runner 使用同步 fixture planner 生成审计轨迹

状态：Accepted 日期：2026-06-28 关联任务：W2-RUN-020、W2-RUN-040

背景

working2 的核心目标是逐章覆盖 GRL 语法规范，并为每个程序输出稳定、可审计的 controller、motion queue、trace、IO 和 trajectory 证据。仓库已有 ABB120 KDL 集成测试负责真实 URDF FK/IK/planPath 验证。

决策

runAbb120SpecSuite 在 W2 job 中使用同步 fixture planner 生成稳定 trajectory 和 planner diagnostic；真实 ABB120 URDF/KDL 检查继续由既有 abb120Programs.test.ts 和 KDL 测试承担。

后果

1. W2 证据包生成快速、稳定、可在普通 Node/Vitest 环境执行。
2. Motion queue、source map、IO/wait/alarm 和 post/roundtrip 证据可稳定归档。
3. 若后续要求 job 内嵌真实 KDL 轨迹，可在 runner 中增加 async KDL planner 模式。

ADR-W2-007：异常和 P1 语义采用 runtime/static 边界组合

状态：Accepted 日期：2026-06-28 关联任务：W2-RUN-060、W2-PROG-010.10

背景

当前语法规范定义 try/catch/finally、trap、interrupt、task。现有 parser/semantic 已有异常分析器，但控制流分析器不应把 try 当普通控制流执行；trap/task 仍是 P1 runtime 边界。

决策

控制流分析器将 try 块保留为 raw boundary，由 exception semantic 负责 alarm/raise/try/catch/finally 分析。trap/task/interrupt 输出 GRL_P1_UNIMPLEMENTED warning 或 unsupported runtime trace，不作为 happy path 完整执行。

后果

1. W2_90_ExceptionAlarm.grl 可以稳定 parse、compile、load 并输出异常语义证据。
2. P1 语义不会被误报为完整 runtime 支持。
3. 后续实现 trap/interrupt/task 时可替换 raw boundary，不影响 W2 manifest 结构。

ADR-W2-008：服务器演示采用静态发布包加证据包模式

状态：Accepted 日期：2026-06-28 关联任务：W2-DEPLOY-001 到 W2-DEPLOY-060

背景

用户要求把虚拟测试程序打包到服务器，并能通过这些程序演示虚拟控制器全部功能。当前虚拟控制器页面、GRL 程序、suite job、截图和 Word 文档都可以作为静态文件发布；远程演示的重点是可访问、可审计、可重复，而不是在服务器上重新执行 Node/Vitest。

决策

服务器发布采用静态演示包模式：

1. 本地先执行 typecheck、test、suite 和截图验证。
2. 将虚拟控制器页面、19 个 GRL 程序、最新 W2-JOB-*、截图、Word 文档和 demo-manifest.json 打成 zip。
3. 服务器仅负责 HTTPS 静态托管。
4. 远程验收通过 demo-manifest.json、report.json、程序源码、截图和页面入口验证。
5. 服务器保留 release 目录和 current 链接，支持回滚。

后果

1. 发布包可离线审计，不依赖服务器 Node 环境。
2. 演示内容与本地测试证据一致，避免远程环境差异导致结论不稳定。
3. 后续如需在线编辑和动态运行，可在当前静态包基础上增加 API 服务，不影响现有验收链路。
4. 凭据不进入仓库文档，降低泄露风险。