317 lines
16 KiB
Markdown
317 lines
16 KiB
Markdown
# 06-决策记录
|
||
|
||
本文件记录关键技术决策。后续如需变更，必须新增记录说明原因、影响和替代方案，不直接覆盖旧决策。
|
||
|
||
## 记录模板
|
||
|
||
```text
|
||
## ADR-XXX 标题
|
||
|
||
日期：
|
||
状态：
|
||
背景：
|
||
决策：
|
||
理由：
|
||
影响：
|
||
变更条件：
|
||
```
|
||
|
||
## ADR-011 严格上游清单与生成 Vendor Overlay 分离
|
||
|
||
日期：2026-07-10
|
||
状态：生效
|
||
|
||
背景：
|
||
|
||
`verify_vendor_sync.sh` 原来要求 vendor 树中的所有文件都来自 `source-manifest.txt` 并与锁定上游逐字节一致。前序 native TRT phase0 probe 又按 D-013 在 vendor 树保留了由 LinuxCNC `basic_sim.tcl` 生成、但不在锁定 commit 中的 `xyzac-trt_cmds.hal` fallback，导致严格上游同步 gate 与已登记的运行目录 overlay 需求冲突。
|
||
|
||
决策：
|
||
|
||
`tools/source-manifest.txt` 继续只登记锁定 LinuxCNC commit 中可逐字节比较的上游文件。非上游生成 fallback 必须登记到独立 `tools/vendor-overlay-manifest.tsv`，至少绑定相对路径、固定 SHA-256 和 provenance。`verify_vendor_sync.sh` 必须拒绝未登记额外文件、source/overlay 路径重叠、重复 overlay、无效哈希、缺失 provenance 和哈希漂移。
|
||
|
||
理由：
|
||
|
||
这样既不删除 native phase0 所需的既有生成输入，也不把生成文件伪装成 LinuxCNC commit 内的上游源码。严格上游字节一致与少量显式生成 overlay 可以在同一 gate 中分别验证。
|
||
|
||
影响：
|
||
|
||
- 当前只允许一个 `xyzac-trt_cmds.hal` generated overlay，固定哈希为 `d12f6c737000aba518c0a1502943f3aef17bbd5d54b4b8ae45a11f9f236a4ab3`。
|
||
- `vendor sync validation complete` 表示所有 upstream manifest 文件一致，且所有额外文件均通过 overlay manifest；不表示 overlay 文件存在于上游 commit。
|
||
- 新增 overlay 必须经过单独 provenance 审查，不能为了让 gate 通过而自动收录未知文件。
|
||
|
||
变更条件：
|
||
|
||
当 `xyzac-trt_cmds.hal` 可由锁定工具链在构建期确定性生成并迁出 vendor 树，或上游 commit 正式包含等价文件时，可以新增 ADR 调整或删除该 overlay 行。
|
||
|
||
## ADR-008 Full-process promotion 仅限 Web/WASM simulation runtime
|
||
|
||
日期：2026-07-10
|
||
状态：生效
|
||
|
||
背景：
|
||
|
||
`04基于Web的LinuxCNC兼容数控仿真平台.txt` 将 Task、Motion、HAL servo-thread、五轴联动和 full-process 相关能力写为通过；`web-rtcp-5axis-xyzbc-trt-sim-plan` 也已具备 `full-execution-boundary.js`、task/HAL runtime、native readiness audit 等 Web/WASM 仿真运行时证据。但浏览器环境仍不是 LinuxCNC 原生实时内核，也没有运行真实硬件驱动、完整 native NML/process topology 或任意宿主 User-M/Tool DB 外部进程。
|
||
|
||
决策：
|
||
|
||
`完善wasm/working` 将 full-process promotion 限定为 `linuxcnc_task_motion_hal_wasm_simulation_runtime`。当 kinematics、interpreter、planner、machine-file staging、task/motion/HAL runtime、Tool DB Web simulation 和 controlled User-M Web simulation 全部通过时，可以声明 Web/WASM 仿真运行时晋级；同时必须保留 `hardwareDrive=false`、`hostRealtimeKernel=false`、`hostExternalUserMProcessReady=false`、`hostToolDbProcessReady=false` 和 `promotion_scope=web_simulation_only`。
|
||
|
||
理由：
|
||
|
||
这样可以承认可复验的 Web/WASM task-motion-HAL 运行时进展，同时避免把仿真运行时误写成 LinuxCNC 原生实时系统、硬件控制系统或任意宿主外部进程执行环境。
|
||
|
||
影响：
|
||
|
||
- 新增 `22-04-Full-Process-Realtime-Runtime-Proof实现缺口复核.md`。
|
||
- `ACC-034/INT-021` 可按实现缺口复核完成。
|
||
- `14-04-125项逐项源码证据绑定表.md` 中 full-process/realtime 项改为指向 `22`；Web/WASM simulation proof 与 host/hardware/realtime false 必须同时记录。
|
||
- `verify_native_task_hal_audit.mjs` 生成的 readiness artifact 是 Web simulation boundary 证据，不是宿主实时/硬件 promotion 证据。
|
||
|
||
变更条件：
|
||
|
||
只有新增并通过显式 opt-in 的 host realtime、硬件、完整 native process topology 或宿主外部进程 gate 后，才允许新增 ADR 扩大 promotion 范围。
|
||
|
||
## ADR-009 HAL 基础组件必须由 vendored `.comp` 可复现派生
|
||
|
||
日期：2026-07-10
|
||
状态：生效
|
||
|
||
背景：
|
||
|
||
04 将 `and2`、`or2`、`not`、`mux2`、`scale` 写为 HAL 已通过组件，但当前五个 `.comp` 只存在于上游 `linuxcnc/src/hal/components`，没有进入 `wasm-port/vendor/linuxcnc` 或 source manifest；现有 HAL runtime 的 `loadrt`、`addf` 和 servo step 也只记录事件，不执行组件函数。
|
||
|
||
决策：
|
||
|
||
HAL 基础组件的 Web/WASM 实现必须先逐字节同步 vendored `.comp` 并锁定 SHA-256，再使用 LinuxCNC `halcompile` 或能够证明由该 `.comp` 可复现派生的生成链产生预编译实现。禁止在 JS/TS 或项目自有 C/C++ 中手写等价公式后标记为 LinuxCNC 源码复用。`loadrt` 必须实例化 allowlist 组件，`addf` 必须绑定可调用函数，servo step 必须真实更新输出 pin/signal；未知组件保持 blocked。
|
||
|
||
理由：
|
||
|
||
五个公式虽然简单，但手写副本会建立第二套 HAL 语义来源，并绕过 source manifest、上游漂移和 LinuxCNC 生成命名规则。把 P1 同步、生成器 provenance、WASM symbol 和执行 evidence 串成一条链，才能证明组件行为来自锁定的 LinuxCNC 源码。
|
||
|
||
影响：
|
||
|
||
- 新增 `24-04-HAL-Component-Precompile-Manifest-Truth-Table-Gate落地蓝图.md`。
|
||
- `4.7-4.11` 在五个 `.comp` 进入 vendor/source manifest 前不得晋级。
|
||
- `4.16` 仅允许预编译 allowlist 条件通过，任意运行时动态模块加载继续 Blocked。
|
||
- truth-table/formula 测试必须经过真实 `loadrt -> addf -> servo-step -> pin/signal` 路径，不能只直接调用测试 helper。
|
||
|
||
变更条件：
|
||
|
||
只有验收标准明确允许非 LinuxCNC 派生的独立 HAL 扩展时，才可新增单独的“产品扩展”路径；该路径仍不得计入 LinuxCNC 对标完成率。
|
||
|
||
## ADR-010 Project release readiness 与 host runtime promotion 必须分离
|
||
|
||
日期：2026-07-10
|
||
状态：生效
|
||
|
||
背景：
|
||
|
||
当前 `wasm-port/build/project-release-readiness.json` 可以同时出现 `ready=true`、release gate 通过和非空 `blockedRuntimeFamilies`。Host readiness TSV 也可显示三个 opt-in probe 均可 dispatch，但仍明确 `execution_enabled=0`、`promotion_allowed=0`；Python stop-lookahead 单 fixture 已接受 native evidence，manual promotion lock 仍生效。
|
||
|
||
决策：
|
||
|
||
项目发布 readiness 与宿主能力 promotion 使用两套独立状态。`ready=true`、host ready、dispatch allowed、`ready_disabled_by_default`、native pass、evidence accepted、Node/Browser complete、manual unlock 和 promotion 不得合并或跳级。任何 probe 脚本不得直接写 `promotion_allowed=1`；只有独立人工审查 artifact 可以解除对应 fixture/family 的 promotion lock。User-M/Tool DB/Python process probe 不授权 Linux realtime kernel 或硬件驱动。
|
||
|
||
理由：
|
||
|
||
发布 gate 回答“当前已声明范围是否可发布”，host promotion 回答“某项宿主 LinuxCNC 能力是否有完整运行证据并获准开放”。如果共用一个 `ready` 字段，会把默认禁用、单 fixture pass 或 Web simulation proof 误写成外部进程、实时内核或硬件已经完成。
|
||
|
||
影响：
|
||
|
||
- 新增 `25-04-Host-Runtime-Opt-In-Promotion-Evidence-Gate落地蓝图.md`。
|
||
- 后续增加 `host_runtime_opt_in_evidence`、promotion state machine 和 release/promotion separation gate。
|
||
- Python stop-lookahead 只能按 fixture 记录；不能批量晋级全部 Python remap rows。
|
||
- `hostRealtimeKernel=false`、`hardwareDrive=false` 只能由独立 realtime/hardware 安全任务解除。
|
||
|
||
变更条件：
|
||
|
||
只有总验收标准改为要求宿主原生 LinuxCNC 部署且配套安全/人工审查流程已经实现时，才允许调整两套状态的组织方式；仍不得取消逐 family/fixture 证据。
|
||
|
||
## ADR-006 双项目总控采用“核心移植 + 代表应用”口径
|
||
|
||
日期：2026-07-10
|
||
状态：生效
|
||
|
||
背景：
|
||
|
||
用户要求 `/home/mes123456/cnc_wams/wasm-port` 和 `/home/mes123456/cnc_wams/web-rtcp-5axis-xyzbc-trt-sim-plan` 完全对标 LinuxCNC 源程序，并在 `完善wasm/working` 中创建相关文件。两个目录职责不同：`wasm-port` 是 LinuxCNC 源码到 Native/WASM/Browser/OPFS/SDK 的核心移植层；`web-rtcp-5axis-xyzbc-trt-sim-plan` 是 `xyzbc-trt.ini` 的 Web 代表应用和 UI/evidence 闭环。
|
||
|
||
决策：
|
||
|
||
`完善wasm/working` 采用“核心移植 + 代表应用”的总控口径：`wasm-port` 证明 CNC 核心语义来自 LinuxCNC 源码；`web-rtcp-5axis-xyzbc-trt-sim-plan` 证明这些语义能在真实 Web 应用中通过 OPFS、Worker、UI、3D 和 native/Web JSON 对比呈现。二者共用同一 LinuxCNC commit、同一 source reuse 约束和同一条件边界规则。
|
||
|
||
理由：
|
||
|
||
这能避免把 Web UI 工程误当成 LinuxCNC 核心移植，也能避免只看 `wasm-port` 命令全绿却缺少真实代表应用证据。双项目总控必须同时保留源码级证据和用户可见应用证据。
|
||
|
||
影响：
|
||
|
||
- 新增 `07` 到 `12` 作为跨项目总控文件。
|
||
- `09-联合任务矩阵.md` 管理跨项目任务；原 `04-任务矩阵.md` 继续管理 `wasm-port` 核心验收。
|
||
- `04基于Web的LinuxCNC兼容数控仿真平台.txt` 在 ADR-006 创建时为空；补齐后已由 ADR-007 和 `13-04验收文档任务对标矩阵.md` 重新纳入任务体系。
|
||
- `xyzbc-trt` 的完成结论必须继续由 smoke、evidence JSON 和 compare JSON 复验，不因文档登记自动通过。
|
||
|
||
变更条件：
|
||
|
||
如果后续出现新的 Web 代表应用、`04基于Web...txt` 补齐为正式需求，或 `wasm-port` 与 Web 应用职责边界改变，必须新增 ADR 更新总控口径。
|
||
|
||
## ADR-005 当前验收闭合采用“命令全绿 + 条件边界显式锁定”口径
|
||
|
||
日期：2026-07-09
|
||
状态：生效
|
||
|
||
背景：
|
||
|
||
本轮已让上游基线、vendor 同步、Native/WASM/Browser/OPFS/UI/Host 聚合命令通过，但 Python remap、User M 外部进程、硬件驱动和实时内核天然涉及浏览器沙箱、外部进程或实时环境限制，不能因为 smoke 全绿就宣称无条件 LinuxCNC full-process 支持。
|
||
|
||
决策：
|
||
|
||
`ACC-001` 到 `ACC-023` 的当前闭合采用“可执行命令包全绿 + 条件边界显式锁定”口径：能由 LinuxCNC 源码、Native probe、WASM Node、真实浏览器和 UI/OPFS gate 证明的部分标为完成；Python remap、User M、硬件/实时等仍保留 `manual_promotion_lock`、Blocked 或条件通过说明。
|
||
|
||
理由：
|
||
|
||
这样既满足当前发布前命令包 `unexpected_fail=0` 的可复验证据，又避免把浏览器环境无法直接承载的 LinuxCNC 外部进程/实时能力误报为已经完整实现。
|
||
|
||
影响：
|
||
|
||
- `04-任务矩阵.md` 中相关任务可以闭合，但状态使用“条件通过”而不是无条件“完成”。
|
||
- `05-验收证据.md` 必须保留 inventory `29/29/130/0`、skip/block 分类和 Python remap manual lock 说明。
|
||
- 后续如果要解除条件边界，必须新增 ACC 任务、源码归属、runtime owner、fixture 和验收 gate。
|
||
|
||
变更条件：
|
||
|
||
只有当对应 runtime 或安全边界真正实现，并且 Native/WASM/Browser/UI 证据同时通过后，才能把条件通过项升级为无条件完成。
|
||
|
||
## ADR-007 04 验收文档的“通过/100%”表述必须降解为待核验任务
|
||
|
||
日期：2026-07-10
|
||
状态：生效
|
||
|
||
背景：
|
||
|
||
`完善wasm/04基于Web的LinuxCNC兼容数控仿真平台.txt` 已补齐，文档中声明基于 Web/WASM/OPFS 的 LinuxCNC 兼容仿真平台 10 个模块、125 个功能项总体 97.6%，核心模块 100%，并给出多项“通过”结论。但该文件本身不是命令输出、不是 LinuxCNC 源码、不是 Native/WASM/Browser evidence。
|
||
|
||
决策：
|
||
|
||
04 文档中的模块和功能项必须进入 `13-04验收文档任务对标矩阵.md`，作为待验证任务和目标声明处理。任何“通过/100%/超越”表述都不能自动成为 working 的最终验收结论；必须由 LinuxCNC 源码归属、`wasm-port` gate、目标 Web 应用 gate 和 evidence JSON 共同证明。
|
||
|
||
理由：
|
||
|
||
这与 `03完全对标LinuxCNC的可执行验收标准.txt` 的一票否决规则一致，可以避免把总结性文档当成可复验证据，也能防止 full-process、实时内核、动态加载、多通道、HAL Scope/Meter 等边界被静默标绿。
|
||
|
||
影响：
|
||
|
||
- `INT-010` 改为“04 参考说明纳入任务体系”。
|
||
- 新增 `INT-013` 负责 04 的 125 项逐行 evidence 绑定。
|
||
- 04 的受限项继续保留条件通过或 Blocked 口径。
|
||
|
||
变更条件：
|
||
|
||
只有当 04 每个功能项都绑定到源码、测试、命令输出和 evidence，并且 `unexpected_fail=0`，才能把对应 W04 任务升级为完成。
|
||
|
||
## ADR-001 以 LinuxCNC 源码和测试资产作为唯一数控语义基准
|
||
|
||
日期：2026-07-09
|
||
状态：生效
|
||
|
||
背景：
|
||
|
||
验收标准明确要求“完全对标 LinuxCNC”必须证明核心数控语义来自 LinuxCNC 源码、测试资产和运行规则，而不是界面相似或项目自研近似实现。
|
||
|
||
决策：
|
||
|
||
`wasm-port` 的 G 代码解释、刀补、参数、remap、刀具、轨迹规划、运动学、Task/HAL/Motion 等 CNC 语义只能来自 LinuxCNC 源码复用、vendored 同步或明确的薄封装。JS/TS、浏览器 UI 和项目自有 C/C++ 只能承担文件、调度、展示、持久化、C ABI 和边界桥接职责。
|
||
|
||
理由：
|
||
|
||
这能避免 Web 端逐渐形成第二套状态真相，也能让上游测试迁移、Native/WASM/Browser 对比和 blocked table 具备共同基准。
|
||
|
||
影响：
|
||
|
||
- 新功能必须先找到 LinuxCNC 源码归属。
|
||
- 找不到归属的功能不能宣称为 LinuxCNC 对标功能。
|
||
- 疑似自研 CNC 语义必须通过 `verify_no_standalone_cnc_semantics.sh` 或人工审查解释清楚。
|
||
|
||
变更条件：
|
||
|
||
只有验收标准更新并允许某类非 LinuxCNC 语义作为产品扩展时，才能改变此决策；即使变更，也必须与 LinuxCNC 对标功能分开标识。
|
||
|
||
## ADR-002 采用 L0-L5 加 Blocked 的晋级模型
|
||
|
||
日期：2026-07-09
|
||
状态：生效
|
||
|
||
背景：
|
||
|
||
只写“完成”无法区分源码已同步、Native 通过、WASM 通过、浏览器通过和 UI 发布，也容易把 full-process 或硬件依赖降级为解释器通过。
|
||
|
||
决策：
|
||
|
||
所有任务使用 `L0 已盘点`、`L1 已同步`、`L2 Native 通过`、`L3 WASM 通过`、`L4 Browser 通过`、`L5 UI 发布`、`Blocked` 表达真实进度。
|
||
|
||
理由：
|
||
|
||
该模型与验收标准的分层证据体系一致，可以防止跳级宣称，也方便后续按证据缺口继续推进。
|
||
|
||
影响：
|
||
|
||
- 任务矩阵必须记录晋级目标。
|
||
- 浏览器/UI 功能不能只凭 Native 或 WASM 结果标为 L5。
|
||
- Python remap、动态 loadrt、硬件驱动、实时内核等未闭合项应标 Blocked 或条件通过。
|
||
|
||
变更条件：
|
||
|
||
如果新增运行层级或验收标准调整证据层级，需要补充状态定义。
|
||
|
||
## ADR-003 把 `完善wasm/working` 作为总验收推进入口
|
||
|
||
日期：2026-07-09
|
||
状态：生效
|
||
|
||
背景：
|
||
|
||
`wasm-port/working` 已存在 task/status JSON 等局部推进文档，并显示当前 task-HAL 工作已闭合。新的验收标准覆盖整个 LinuxCNC 功能树，需要一个更高层的总入口。
|
||
|
||
决策：
|
||
|
||
`完善wasm/working` 作为完整 LinuxCNC 对标推进入口，维护总任务矩阵、验收证据和决策记录；`wasm-port/working` 继续作为 `wasm-port` 内部具体阶段文档和历史证据来源。
|
||
|
||
理由：
|
||
|
||
这样可以避免把某个已闭合子方向误认为整体验收完成，同时保留既有工作成果。
|
||
|
||
影响：
|
||
|
||
- 后续总体验收先看 `完善wasm/working/README.md` 和 `04-任务矩阵.md`。
|
||
- 涉及具体实现时，再跳转到 `wasm-port/docs`、`wasm-port/working` 和对应测试。
|
||
|
||
变更条件：
|
||
|
||
如果后续决定把总入口迁入 `wasm-port/working`，必须同步迁移任务编号、证据和决策记录，避免两套矩阵并行。
|
||
|
||
## ADR-004 截图和 UI smoke 只能作为补充证据
|
||
|
||
日期：2026-07-09
|
||
状态：生效
|
||
|
||
背景：
|
||
|
||
验收标准明确浏览器测试不能只验证页面元素存在，UI 的坐标、模态、刀具、主轴、程序状态必须与底层 LinuxCNC 状态快照一致。
|
||
|
||
决策：
|
||
|
||
截图、录屏、DOM smoke 和页面存在性检查只作为 P5 证据。任何核心语义、OPFS、Worker、UI 状态发布都必须有 C ABI、状态 JSON、OPFS 文件或底层快照证据支撑。
|
||
|
||
理由：
|
||
|
||
UI 可以显示正确外观但底层状态错误；P4/P5 分离可以防止验收被外观证据污染。
|
||
|
||
影响：
|
||
|
||
- UI 任务必须绑定底层状态断言。
|
||
- 真实浏览器 smoke 需要检查运行结果、错误、文件或快照，而不是只检查按钮。
|
||
|
||
变更条件：
|
||
|
||
无底层状态可取的纯视觉展示功能可用截图验收，但不得宣称 LinuxCNC 核心语义通过。
|