# 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 语法规范定义的编译管线为：

```text
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 错误统一为：

```ts
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 完成状态。