KDL_WORK/06-决策记录.md

06-决策记录

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

ADR-001：working1 只对标两份源文档

状态：Accepted
日期：2026-06-27
关联任务：KW-000

背景

用户要求 /home/meswork/kdl_work/work/working1 内实施文档完全对标：

1. /home/meswork/kdl_work/work/doc/KDL_WASM计算接口设计.md
2. /home/meswork/kdl_work/work/doc/通用机器人编程语法规范.md

决策

working1 的范围只从这两份文档抽取。其他技术方案不作为本目录任务、验收和 ADR 的来源。

后果

1. 任务分为 KDL WASM 计算接口线和 GRL 编程语法线。
2. OPFS、UI、虚拟控制器和碰撞检测等内容不单独展开，除非两份源文档明确作为工程结构、调用关系、后处理或测试项出现。
3. 所有 P0/P1 以两份源文档的实施优先级为准。

ADR-002：KDL WASM 是 GRL 的运动计算内核，不解释 GRL

状态：Accepted
日期：2026-06-27
关联任务：KW-001 到 KW-013、KW-103 到 KW-110

背景

KDL WASM 接口设计明确规定 KDL 不负责 GRL 词法语法解析、流程控制、变量、IO、wait、子程序调用、碰撞检测和 OPFS 项目文件管理。

决策

KDL WASM 只接收已经由 TypeScript 编译层解析完成的模型、目标点、速度、zone、tool、frame 和 motion request。

后果

1. movej/movel/movec/run_path 编译后调用 KDL。
2. if/for/switch/call/wait/io/alarm 不直接调用 KDL。
3. operation.process 不进入 KDL，TypeScript 只把 operation 展开的 motion segment 交给 KDL。

ADR-003：GRL AST、语义检查、IR 和 KDL request 分层实现

状态：Accepted
日期：2026-06-27
关联任务：KW-100 到 KW-110

背景

GRL 语法规范定义的编译管线为：

GRL Source -> Lexer -> Parser -> AST -> Symbol Table -> Semantic Analyzer -> Executable IR -> Virtual Controller -> Post Processor

KDL 接口设计要求 GRL 编译器把 movej/movel/movec 解析为 IR 后，由虚拟控制器调用 KDL 函数。

决策

实现中明确区分：

1. AST：保留语法结构、source range、单位原文和品牌 metadata。
2. Semantic Analyzer：完成类型、单位、名称、路径、operation、IO 和运动语义检查。
3. IR：作为虚拟控制器和后处理的统一输入。
4. KDL request：只由运动 IR、Path IR 派生。

后果

1. KDL API 不依赖 GRL AST。
2. 后处理不直接消费 KDL 轨迹点，而是优先消费 IR、目标点和品牌 profile。
3. source map 必须贯穿 AST、IR、KDL request 和诊断。

ADR-004：机器人结构以 URDF 为源数据，TypeScript 生成标准模型

状态：Accepted
日期：2026-06-27
关联任务：KW-002

背景

KDL 接口设计规定机器人结构源数据为 URDF，TypeScript 解析 XML 并生成 NormalizedRobotModel，WASM 根据标准模型构造 KDL Tree/Chain。

决策

实现 loadRobotFromUrdf 时，TypeScript 负责：

1. 解析 URDF XML。
2. 检查 link/joint 连通性和单位。
3. 生成 NormalizedRobotModel。

WASM 负责：

1. 从 NormalizedRobotModel 构造 KDL Chain。
2. 创建 FK、IK、Jacobian solver。
3. 返回 RobotHandle。

后果

1. NormalizedRobotModel schema 是 TypeScript 与 WASM 的稳定边界。
2. GRL 编译器在编译 joint_target 时按 RobotInfo.dof 检查长度。
3. WASM 仍需对模型做防御性校验并返回 KDL_INVALID_MODEL。

ADR-005：内部统一使用 SI 单位和位置 + 四元数位姿

状态：Accepted
日期：2026-06-27
关联任务：KW-006、KW-100、KW-102

背景

GRL 支持 mm、deg、mm/s 等带单位字面量。KDL 接口设计要求内部位姿统一为位置 + 四元数。

决策

1. GRL lexer/parser 保留单位原文。
2. 语义层将单位规范化为 SI。
3. pose() 在编译层转换为四元数。
4. poseq() 四元数必须归一化。
5. KDL API 只接收规范化后的 Pose。

后果

1. 所有后处理时再按品牌格式转换。
2. 单位错误在 GRL 语义检查阶段报告。
3. 位姿数值约定由 KDL normalizePose/composePose/inversePose 测试固定。

ADR-006：P0 zone 只保留语义并近似为 fine

状态：Accepted
日期：2026-06-27
关联任务：KW-008 到 KW-011、KW-111

背景

KDL 接口设计写明首版 zone 可只用于诊断和后处理，运动规划先按 fine 到点执行，P1 再实现连续 blend。

决策

P0 中 ZoneSpec 必须保留在 IR、KDL request、TrajectoryResult 和后处理中。KDL 轨迹规划按 fine 到点执行，并返回 KDL_ZONE_APPROXIMATED warning。

后果

1. P0 轨迹不声称复现品牌控制器连续过渡。
2. 后处理仍可输出 ABB zonedata、FANUC CNT、KUKA C_DIS 等语义。
3. P1 再实现 planBlendPath 或等价连续过渡。

ADR-007：所有 KDL API 返回结构化诊断

状态：Accepted
日期：2026-06-27
关联任务：KW-001 到 KW-013

背景

KDL 接口设计要求所有 API 不抛裸字符串错误，必须返回结构化错误和诊断。

决策

KDL Worker RPC 错误统一为：

interface KdlError {
  code: string;
  message: string;
  diagnostics: MotionDiagnostic[];
}

KDL 诊断固定包含：

1. KDL_INVALID_MODEL
2. KDL_TARGET_UNREACHABLE
3. KDL_IK_FAILED
4. KDL_JOINT_LIMIT
5. KDL_VELOCITY_LIMIT
6. KDL_ACCEL_LIMIT
7. KDL_SINGULARITY
8. KDL_ARC_DEGENERATE
9. KDL_PATH_EMPTY
10. KDL_ZONE_APPROXIMATED

后果

1. 自动测试断言诊断 code，不依赖 message 文本。
2. sourceMap 必须随诊断传递。
3. 后处理和报告可区分 error、warning、info。

ADR-008：Worker RPC 是 KDL TypeScript API 的唯一调用入口

状态：Accepted
日期：2026-06-27
关联任务：KW-001、KW-013

背景

KDL 接口设计要求 KDL WASM 运行在 Worker 中，避免阻塞 UI 主线程，并要求大数组使用 Transferable 或共享内存策略。

决策

主线程或 GRL 编译/运行层只调用 KdlWorkerClient。C ABI / Embind 仅在 Worker 内封装。

后果

1. 所有 KDL API 为 Promise 风格。
2. Worker 崩溃和初始化失败必须可恢复。
3. 高频轨迹和批量 IK/FK 优先在 Worker 内整段计算，减少跨线程往返。

ADR-009：KDL 底层导出稳定 C ABI / Embind 包装

状态：Accepted
日期：2026-06-27
关联任务：KW-013

背景

KDL 接口设计不建议把 KDL C++ 类完整暴露给 TypeScript，而是通过稳定函数导出。

决策

P0 底层导出以 C ABI 为基准：

1. kdl_init
2. kdl_create_robot
3. kdl_destroy_robot
4. kdl_get_robot_info
5. kdl_fk
6. kdl_fk_all_links
7. kdl_jacobian
8. kdl_ik
9. kdl_plan_movej
10. kdl_plan_movel
11. kdl_plan_movec
12. kdl_plan_path
13. kdl_sample_trap
14. kdl_last_error

TypeScript API 在 Worker 内包装这些函数，向上暴露 KdlWasmApi。

后果

1. C++ 对象生命周期不泄漏到 TypeScript 业务层。
2. 高频接口可增加 TypedArray 版本。
3. C ABI 返回码和 kdl_last_error 必须有测试。

ADR-010：GRL P0 严格按语法规范第 24 章实现

状态：Accepted
日期：2026-06-27
关联任务：KW-100 到 KW-112

背景

GRL 语法规范第 24 章明确列出 P0 和 P1。

决策

GRL P0 必须覆盖：

1. language/module/proc。
2. const/var/persistent。
3. tool/frame/speed/zone。
4. joint_target/pose_target。
5. movej/movel/movec。
6. path/point/event/run_path。
7. operation/run_operation。
8. if/elseif/else/while/for/switch。
9. call/return/break/continue。
10. proc 参数方向。
11. func 和返回值检查。
12. io.do/di、wait、pulse。
13. AST、语义检查、IR、source map。
14. ABB、FANUC、KUKA 后处理原型。

后果

1. label/jump、trap/interrupt、多任务、完整品牌导入等 P1 内容不得阻塞 P0。
2. 但 P1 语法若已解析，未实现语义必须有明确诊断。

ADR-011：后处理以 GRL IR 为输入，必须保留品牌差异报告

状态：Accepted
日期：2026-06-27
关联任务：KW-111

背景

GRL 语法规范要求 GRL 可转换为 ABB RAPID、FANUC LS/TP 风格文本和 KUKA KRL，并要求无法支持的品牌扩展进入转换报告。

决策

后处理器以 GRL IR、目标点、tool/frame、speed/zone 和 post profile 为输入。post_hint 和 @brand.* 只影响指定品牌。

后果

1. 不支持语义不能静默丢失。
2. 后处理 golden file 必须覆盖运动、目标点、工具、坐标系、速度、zone、IO 和 wait。
3. 转换报告是后处理验收的一部分。

ADR-012：自动生成 GRL 优先生成 target/path/operation

状态：Accepted
日期：2026-06-27
关联任务：KW-112

背景

GRL 语法规范第 18 章要求自动生成程序优先生成 target、path、operation，不要直接把大量运动语句塞进 proc main()。

决策

GRL Generator 的默认输出为结构化对象风格：

1. 目标点命名稳定。
2. 路径点命名稳定。
3. 路径整体参数放入 defaults。
4. 单点差异写在 point 上。
5. CAD 或工艺来源写入 source。
6. 支持 compact 和 expanded 两种输出。

后果

1. 同一输入重复生成结果必须一致。
2. 生成文本必须可 diff。
3. 生成后必须能解析回等价对象和 IR。