Upload project files
This commit is contained in:
wangdequan
@@ -1,35 +1,42 @@
|
||||
# 06-决策记录
|
||||
|
||||
版本：0.3
|
||||
版本：0.5
|
||||
日期：2026-06-27
|
||||
|
||||
## ADR-001：`working1` 只对标两份源文档
|
||||
## ADR-001：`working` 对标 `/work` 全部文档资产
|
||||
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
关联任务：`KW-000`
|
||||
|
||||
### 背景
|
||||
|
||||
用户要求 `/home/meswork/kdl_work/work/working1` 内实施文档完全对标：
|
||||
用户要求 `/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`
|
||||
|
||||
### 决策
|
||||
|
||||
`working1` 的范围只从这两份文档抽取。其他技术方案不作为本目录任务、验收和 ADR 的来源。
|
||||
`working` 的范围从上述全部文档资产抽取。KDL/GRL 已完成任务继续保留为 `KW-001` 到 `KW-013`、`KW-100` 到 `KW-112`；虚拟控制器、OPFS-like 工作区、工作台 facade、报告、品牌导入、交付包、商业扩展、多机器人/外部轴、真实控制器校验流程边界和流程图资产按 `KW-200` 到 `KW-211` 实施并验收。
|
||||
|
||||
### 后果
|
||||
|
||||
1. 任务分为 KDL WASM 计算接口线和 GRL 编程语法线。
|
||||
2. OPFS、UI、虚拟控制器和碰撞检测等内容不单独展开，除非两份源文档明确作为工程结构、调用关系、后处理或测试项出现。
|
||||
3. 所有 P0/P1 以两份源文档的实施优先级为准。
|
||||
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
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
关联任务：`KW-001` 到 `KW-013`、`KW-103` 到 `KW-110`
|
||||
|
||||
### 背景
|
||||
@@ -48,8 +55,8 @@ KDL WASM 只接收已经由 TypeScript 编译层解析完成的模型、目标
|
||||
|
||||
## ADR-003：GRL AST、语义检查、IR 和 KDL request 分层实现
|
||||
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
关联任务：`KW-100` 到 `KW-110`
|
||||
|
||||
### 背景
|
||||
@@ -79,8 +86,8 @@ KDL 接口设计要求 GRL 编译器把 `movej/movel/movec` 解析为 IR 后，
|
||||
|
||||
## ADR-004：机器人结构以 URDF 为源数据，TypeScript 生成标准模型
|
||||
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
关联任务：`KW-002`
|
||||
|
||||
### 背景
|
||||
@@ -109,8 +116,8 @@ WASM 负责：
|
||||
|
||||
## ADR-005：内部统一使用 SI 单位和位置 + 四元数位姿
|
||||
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
关联任务：`KW-006`、`KW-100`、`KW-102`
|
||||
|
||||
### 背景
|
||||
@@ -133,8 +140,8 @@ GRL 支持 `mm`、`deg`、`mm/s` 等带单位字面量。KDL 接口设计要求
|
||||
|
||||
## ADR-006：P0 zone 只保留语义并近似为 fine
|
||||
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
关联任务：`KW-008` 到 `KW-011`、`KW-111`
|
||||
|
||||
### 背景
|
||||
@@ -153,8 +160,8 @@ P0 中 `ZoneSpec` 必须保留在 IR、KDL request、TrajectoryResult 和后处
|
||||
|
||||
## ADR-007：所有 KDL API 返回结构化诊断
|
||||
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
关联任务：`KW-001` 到 `KW-013`
|
||||
|
||||
### 背景
|
||||
@@ -194,8 +201,8 @@ KDL 诊断固定包含：
|
||||
|
||||
## ADR-008：Worker RPC 是 KDL TypeScript API 的唯一调用入口
|
||||
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
关联任务：`KW-001`、`KW-013`
|
||||
|
||||
### 背景
|
||||
@@ -214,8 +221,8 @@ KDL 接口设计要求 KDL WASM 运行在 Worker 中，避免阻塞 UI 主线程
|
||||
|
||||
## ADR-009：KDL 底层导出稳定 C ABI / Embind 包装
|
||||
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
关联任务：`KW-013`
|
||||
|
||||
### 背景
|
||||
@@ -251,8 +258,8 @@ TypeScript API 在 Worker 内包装这些函数，向上暴露 `KdlWasmApi`。
|
||||
|
||||
## ADR-010：GRL P0 严格按语法规范第 24 章实现
|
||||
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
关联任务：`KW-100` 到 `KW-112`
|
||||
|
||||
### 背景
|
||||
@@ -285,8 +292,8 @@ GRL P0 必须覆盖：
|
||||
|
||||
## ADR-011：后处理以 GRL IR 为输入，必须保留品牌差异报告
|
||||
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
关联任务：`KW-111`
|
||||
|
||||
### 背景
|
||||
@@ -305,8 +312,8 @@ GRL 语法规范要求 GRL 可转换为 ABB RAPID、FANUC LS/TP 风格文本和
|
||||
|
||||
## ADR-012：自动生成 GRL 优先生成 target/path/operation
|
||||
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
状态：Accepted
|
||||
日期：2026-06-27
|
||||
关联任务：`KW-112`
|
||||
|
||||
### 背景
|
||||
@@ -329,3 +336,144 @@ GRL Generator 的默认输出为结构化对象风格：
|
||||
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 完成状态。
|
||||
|
||||
Reference in New Issue
Block a user