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

06-决策记录

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

ADR-001：working 对标 /work 全部文档资产

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

背景

用户要求 /home/meswork/kdl_work/working 内实施文档完全覆盖 /home/meswork/kdl_work/work 下文档的全部功能。该目录当前包含 5 份 Markdown 源文档、5 份 Mermaid .mmd 流程图源码和 5 份 PNG 流程图渲染资产：

1. /home/meswork/kdl_work/work/doc/KDL_WASM计算接口设计.md
2. /home/meswork/kdl_work/work/doc/通用机器人编程语法规范.md
3. /home/meswork/kdl_work/work/doc/通用机器人离线编程虚拟控制器技术方案.md
4. /home/meswork/kdl_work/work/doc/通用机器人项目主要实施步骤.md
5. /home/meswork/kdl_work/work/doc/通用机器人项目功能与数据流程图.md
6. /home/meswork/kdl_work/work/doc/通用机器人项目功能与数据流程图-png/flow-01.mmd 到 flow-05.mmd
7. /home/meswork/kdl_work/work/doc/通用机器人项目功能与数据流程图-png/flow-01.png 到 flow-05.png

决策

working 的范围从上述全部文档资产抽取。KDL/GRL 已完成任务继续保留为 KW-001 到 KW-013、KW-100 到 KW-112；虚拟控制器、OPFS-like 工作区、工作台 facade、报告、品牌导入、交付包、商业扩展、多机器人/外部轴、真实控制器校验流程边界和流程图资产按 KW-200 到 KW-211 实施并验收。

后果

1. 任务分为 KDL WASM、GRL、虚拟控制器/IO、工作区/UI、报告/品牌导入/交付、商业扩展/流程图资产六条主线。
2. KDL/GRL P0 已完成的实现证据不被重新标记为未完成。
3. 全目录对标任务均有任务编号、实现模块和验收证据。
4. P0/MVP 与 P1/商业级扩展以各源文档中的实施优先级、MVP 范围和验收标准共同约束。
5. Mermaid 源图和 PNG 渲染图作为文档资产纳入覆盖证据，不只依赖 Markdown 正文。

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。

ADR-013：虚拟控制器执行统一 IR，不直接解释品牌文本

状态：Accepted 日期：2026-06-27 关联任务：KW-202、KW-203、KW-207

背景

虚拟控制器技术方案要求虚拟控制器支持 GRL 程序和品牌程序，但真正执行统一 IR。数据流程图也以 Executable IR 作为虚拟控制器、KDL、后处理和报告之间的中枢。

决策

虚拟控制器运行时只执行 Executable IR。GRL 先经 Lexer/Parser/Semantic Analyzer 转 IR；ABB/FANUC/KUKA 文本先经 Brand Importer 转 Brand AST，再转统一 IR。

后果

1. 品牌源程序行号通过 source map 和 Brand Context 保留。
2. 品牌特有语义必须转换为等价 IR、近似 IR 或不支持诊断。
3. 调试、报告、后处理和跨品牌转换不直接依赖品牌语法树。

ADR-014：OPFS 是内部工作区，必须提供显式导入导出和快照

状态：Accepted 日期：2026-06-27 关联任务：KW-201、KW-205、KW-206

背景

技术方案要求使用 OPFS 保存项目，但 OPFS 是浏览器 Origin 私有文件系统，用户通常不能像普通目录一样直接看到文件。

决策

项目内部保存在 OPFS 的 /projects/{projectId} 布局中，并必须提供 exportZip/importZip/snapshot。客户交付包不直接等同于 OPFS 内部目录，而是由导出流程生成。

后果

1. 所有项目关键资源必须进入 manifest 或索引。
2. 导出 zip 后再导入必须恢复等价项目。
3. trace 大文件可选导出，避免项目包过大。
4. 存储占用、迁移、损坏检测和备份属于工作区验收项。

ADR-015：首版 UI 是离线编程工作台，不做营销首屏

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

背景

虚拟控制器界面设计明确界面目标是离线编程和虚拟调试，第一屏应直接进入工作台。

决策

首版 UI 按工作台实现，包含项目对象树、程序/路径/Operation 编辑、虚拟示教器、控制器面板、IO 面板、运动监控、日志报警、Wait 调试、报告和后处理导出入口。

后果

1. 不建设单独营销 landing page 作为首屏。
2. UI 验收以工程工作流可用、状态可见、诊断可定位、数据可导出为准。
3. Wait 卡住时必须显示表达式、关联 IO、时间、最近变化和可用调试动作。

ADR-016：品牌导入首版以可读文本为边界

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

背景

技术方案要求支持 ABB RAPID、KUKA KRL、FANUC LS 或可读导出文本导入，同时明确 FANUC 二进制 TP 不能作为首版目标。

决策

首版 Brand Importer 支持 ABB .mod/.sys 文本、KUKA .src/.dat 文本、FANUC LS 风格文本或可读 TP 导出。导入目标是尽量恢复 target/path/program 和统一 IR，而不是完全还原真实控制器所有系统变量、工艺包和 advance run 细节。

后果

1. FANUC TP 二进制不进入首版验收。
2. KUKA $ADVANCE、ABB 复杂错误处理、多任务和品牌工艺包以近似或不支持诊断记录。
3. 导入报告是必需产物，不能静默丢失语义。

ADR-017：报告和客户交付包是独立交付链路

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

背景

技术方案要求商业级 OLP 输出可达性、碰撞、节拍、IO、后处理、校准、导入报告，并能生成客户交付包。

决策

报告引擎消费 IR、轨迹、诊断、trace、对象模型和 post/import report，输出稳定 JSON 和 HTML。客户交付包由专门流程生成，包含源程序、品牌程序、目标点、路径、IO map、报告、校准数据和可选 trace。

后果

1. 报告 JSON schema 必须稳定并可测试。
2. 后处理导出不等于项目交付，交付包必须包含验证和诊断材料。
3. 基础碰撞和校准可按 MVP 后续阶段逐步接入，但报告接口需预留。

ADR-018：流程图资产必须和功能文档同步

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

背景

work/doc/通用机器人项目功能与数据流程图-png 下的 .mmd 文件是流程图源码，.png 文件是对应渲染资产。它们分别描述总体功能流程、GRL 编译执行流程、KDL 计算流程、数据传递流程和诊断传递流程。

决策

流程图资产作为一等文档输入。working 中必须能把 flow-01 到 flow-05 映射到功能章节、任务编号和验收证据。

后果

1. 流程图源或 PNG 变更时，任务矩阵和验收证据必须同步检查。
2. 任一流程图没有对应任务编号时，视为覆盖缺口。
3. UI facade、报告和端到端链路验收可直接引用流程图语义。

ADR-019：商业级扩展不属于首版完成项，但必须有任务归属

状态：Accepted 日期：2026-06-27 关联任务：KW-208、KW-209、KW-210

背景

技术方案包含商业级 OLP、虚拟调试增强、碰撞、校准、Sim-to-Real、多机器人、外部轴和真实控制器校验流程。这些能力不都属于首版 MVP，但属于 /work 文档功能范围。

决策

这些能力不得从 working 中省略。已完成对象模型、报告/交付链路、基础碰撞、校准、调试 facade、多机器人/外部轴 schema 和真实控制器校验流程边界；真实控制器通信、完整 CAD kernel、高精度轨迹复现仍作为非 MVP 边界明确记录。

后果

1. MVP 验收不会误承诺完整碰撞检测、完整 CAD kernel、真实控制器通信或高精度轨迹复现。
2. 商业级功能已有任务编号、文档依据和 MVP 验收口径。
3. 后续若扩展真实设备接入，可在 KW-210 边界上新增独立任务，不改变当前 MVP 完成状态。