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

06-决策记录

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

ADR-A120-001：ABB120 基准使用仓库内 fixture，而不是新增未验证 URDF

状态：Accepted 日期：2026-06-27 关联任务：A120-001

背景

用户要求根据 ABB120 的 URDF 编写全面测试文档。当前仓库没有独立 .urdf 文件，但已有 kdl-wasm/web/tests/fixtures/abbIrb120.ts，其中包含 ABB_IRB120_3_58_URDF、load options、来源记录和标准关节位。

决策

working1 以当前 fixture 内嵌 URDF 作为 ABB120 基准。后续如需要独立文件，可从 fixture 导出到稳定测试资产目录，但不得引入未验证 URDF 替换基准。

后果

1. 文档和测试能立即对齐当前代码。
2. 后续 fixture 抽取不会改变机器人基准。
3. 如果未来引入完整 mesh/inertial URDF，需要作为独立任务评审。

ADR-A120-002：全面测试以 GRL/IR 为中心，品牌程序是输入输出格式

状态：Accepted 日期：2026-06-27 关联任务：A120-010、A120-050、A120-051

背景

需求要求编写通用机器人程序、运行程序、转换为其他品牌程序，并做离线编程全面测试。如果直接围绕 ABB RAPID 或其他品牌语法构建运行链路，会导致虚拟控制器和报告被品牌细节绑定。

决策

标准链路为：

GRL -> AST -> Semantic IR -> KDL / Virtual Controller / Reports -> ABB/FANUC/KUKA post

品牌导入链路为：

ABB/FANUC/KUKA text -> importer -> OLP patch + GRL + Semantic IR -> reports

后果

1. 同一测试程序可跨品牌输出。
2. 虚拟控制器只执行统一 IR。
3. 品牌差异通过 post/import report 解释。

ADR-A120-003：pose target 优先由 ABB120 FK 生成

状态：Accepted 日期：2026-06-27 关联任务：A120-010、A120-031

背景

ABB120 是 6 轴机械臂。手写笛卡尔 pose 可能因为姿态、工具、base 或 IK 初值导致不可达，从而让 happy path 测试不稳定。

决策

happy path 的 pose target 优先由标准关节位 FK 生成。不可达点、限位点和奇异点只放入 error diagnostic suite。

后果

1. MOVEL/MOVEC happy path 更稳定。
2. 诊断测试不会污染主流程。
3. FK 结果变化会通过 snapshot 明确暴露。

ADR-A120-004：跨品牌输出必须配套转换报告和回读差异

状态：Accepted 日期：2026-06-27 关联任务：A120-050、A120-051

背景

ABB RAPID、FANUC LS 和 KUKA KRL 的速度、zone、工具、frame、等待和工艺语义不完全一致。

决策

每次后处理必须输出品牌程序和转换报告；每次品牌导入或回读必须输出 roundtrip diff。

后果

1. 近似语义不会静默丢失。
2. 用户能判断程序是否适合现场控制器复核。
3. 后续新增品牌时必须遵守同样报告格式。

ADR-A120-005：HTML 虚拟控制器对标 RobotStudio 工作流，不复制 ABB 视觉资产

状态：Accepted 日期：2026-06-27 关联任务：A120-090 到 A120-094

背景

用户要求对标 ABB 既有仿真器界面，并使用 HTML 编写本项目虚拟控制器。ABB RobotStudio 是 ABB 的离线编程与仿真平台，公开资料包括 RobotStudio Suite 官方页面、RobotStudio Operating Manual 2026.2 和 ABB Robotics downloads。需求参考 Virtual Controller、RAPID 编辑、Station 图形窗口、Simulation 和 Virtual FlexPendant 等工作流。

决策

本项目 HTML 界面对标信息架构和操作流程：

1. Station 对象树。
2. 机器人/路径 viewport。
3. 程序编辑器和 source map。
4. 控制器状态和运行控制。
5. Virtual FlexPendant 风格的状态、Jog、IO 和报警面板。
6. 报告和后处理出口。

不复制 ABB 商标、图标、配色、截图或专有资源。

后果

1. UI 满足用户熟悉的离线编程工作流。
2. 降低品牌侵权和误导风险。
3. 视觉语言可按本项目设计系统独立演进。

ADR-A120-006：HTML UI 必须消费 runtime/facade snapshot，不重写运行时

状态：Accepted 日期：2026-06-27 关联任务：A120-090 到 A120-093

背景

当前仓库已有 VirtualController、MotionQueue、IoImageRuntime、WorkbenchFacade 和 DebugFacade。如果 UI 中重复实现程序运行、IO、Wait 或 source map，会造成行为分叉。

决策

HTML UI 只负责展示和触发命令，业务状态来自 runtime/facade snapshot。

后果

1. UI 与测试共用同一运行时行为。
2. 自动化测试可以先验证 facade，再验证页面绑定。
3. 后续替换 UI 框架时不影响核心运行逻辑。

ADR-A120-007：证据优先使用 job_id 和 report_id 串联

状态：Accepted 日期：2026-06-27 关联任务：A120-033、A120-071、A120-900

背景

全面测试会产生多种证据：轨迹、trace、诊断、品牌程序、报告、截图、PDF 和交付包。如果只靠文件名追踪，后续很难定位一次完整运行。

决策

每次 ABB120 suite 运行生成 job_id；每份报告生成 report_id。所有产物 manifest 必须包含这两个字段或其中一个字段。

后果

1. 验收证据可追溯。
2. CI、人工页面验收和交付包能关联到同一次运行。
3. 历史证据可以长期归档和比对。

ADR-GRL-EXPR-001：运算功能采用跨品牌公共数学子集

状态：Accepted 日期：2026-06-27 关联任务：GRL-EXPR-001 到 GRL-EXPR-006

背景

用户要求“运算功能，对标 ABB、FANUC、库卡”。ABB RAPID、FANUC LS/KAREL、KUKA KRL 都具备数值计算、比较、逻辑和常用数学函数，但语法细节、系统变量和控制器运行时能力不完全一致。如果首版照搬某一家品牌语法，会破坏 GRL 作为统一语言和统一 IR 的定位。

决策

GRL 首版运算功能采用公共数学子集：

1. 算术：+ - * / mod。
2. 比较：== != < <= > >=。
3. 逻辑：and or not，兼容 && || ! 输入别名。
4. 括号和函数调用。
5. 函数：sin/cos/tan/asin/acos/atan/atan2/sqrt/abs/pow/min/max/clamp/floor/ceil/round。
6. 常量：pi/e。

品牌专用函数、控制器系统变量和复杂运行时表达式不作为首版公共能力。

后果

1. GRL 语义保持跨品牌一致。
2. ABB/FANUC/KUKA 后处理器可以优先消费折叠后的 IR 数值。
3. 品牌专用能力后续通过 post_hint、import report 或品牌扩展包增量支持。

ADR-GRL-EXPR-002：运动参数中的表达式必须编译期求值

状态：Accepted 日期：2026-06-27 关联任务：GRL-EXPR-003、GRL-EXPR-004、GRL-EXPR-005

背景

运算功能如果只停在 parser 层，真实机器人程序参数仍无法工作。例如 speed linear(100 + 50 mm/s)、pose(400 + 50 mm, ...)、joint_target { joints: [(10 + 5) deg] } 都必须进入 KDL planner 和品牌后处理。KDL request 和后处理器需要的是确定的数值，而不是未求值的表达式文本。

决策

以下位置必须在编译期求值并写入 Semantic IR / KDL request：

1. 数据声明。
2. speed、zone。
3. pose、poseq、robot_config。
4. joint_target、pose_target。
5. tool、frame。
6. path defaults/source。
7. path point 内联 motion 参数。
8. path event distance。
9. wait timeout、pulse duration。
10. operation process 中的数值常量。

需要常量的位置如果出现运行时变量或无法确定的表达式，输出 GRL_EXPR_NON_CONSTANT。

后果

1. 真实 motion/path 参数可以编译并进入规划。
2. 后处理输出为具体 ABB/FANUC/KUKA 数值，便于现场复核。
3. runtime 条件表达式需要单独建模，不能混入常量求值器。

ADR-GRL-EXPR-003：单位采用上下文默认值加 SI 归一化

状态：Accepted 日期：2026-06-27 关联任务：GRL-EXPR-003

背景

GRL 已经支持带单位的 number token，例如 300 mm/s、10 mm、90 deg。用户要求支持 linear(100 + 50 mm/s) 这类表达式，其中 100 的单位依赖 linear 速度上下文。如果完全禁止无单位数，会让 GRL 编写繁琐；如果完全允许无单位数，会造成歧义。

决策

采用上下文默认单位加 SI 归一化：

1. linear(...) 默认 mm/s。
2. z(...) 默认 mm。
3. joint(...) 的 % 默认比例上下文。
4. pose(...) 前三项默认 mm，后三项默认 deg。
5. joint_target.joints 默认 deg。
6. timeout/duration 默认 s。
7. 明确单位的数值优先使用自身单位。
8. 同维度才能相加、相减、比较；不兼容维度报 GRL_EXPR_UNIT_MISMATCH。

所有进入 IR/KDL 的数值归一化为 SI：长度 m、速度 m/s、加速度 m/s2、角度 rad、时间 s、质量 kg、百分比 0 到 1。

后果

1. linear(100 + 50 mm/s) 可按用户预期编译为 0.15 m/s。
2. 生成器和文档示例仍推荐输出显式单位，减少人工阅读歧义。
3. 实现时必须把期望单位上下文传入常量求值器，不能只在 lexer 层处理。

ADR-GRL-EXPR-004：复杂运行时表达式先进入报告，不强行后处理映射

状态：Accepted 日期：2026-06-27 关联任务：GRL-EXPR-006、A120-050、A120-051

背景

ABB、FANUC、KUKA 对运行时表达式、IO 条件、函数调用和控制器变量的支持差异较大。强行把所有 GRL 表达式映射到三品牌文本，容易产生看似可运行但语义不一致的程序。

决策

首版后处理策略：

1. 需要常量的位置全部在 GRL 编译阶段折叠为 IR 数值。
2. 后处理器只输出折叠后的具体数值。
3. wait/if/while 等运行时条件表达式如果可以保真映射，则输出品牌表达式。
4. 如果不能保真映射，输出转换报告项 GRL_EXPR_UNSUPPORTED_RUNTIME，必要时在品牌程序中输出注释或 unsupported 占位。

后果

1. 避免静默改变机器人程序行为。
2. 用户能通过 post report 判断是否需要人工调整或品牌专用扩展。
3. 后续每新增一个品牌表达式映射，都必须补 roundtrip diff 证据。