chore: finalize remaining project artifacts

2026-07-05 22:13:40 -04:00
parent 4224f835dc
commit 6b937a038d
30 changed files with 14093 additions and 46 deletions
--- a/web-rtcp-5axis-xyzbc-trt-sim-plan/working/11-LinuxCNC源码与真实执行严格对标任务.md
+++ b/web-rtcp-5axis-xyzbc-trt-sim-plan/working/11-LinuxCNC源码与真实执行严格对标任务.md
@@ -0,0 +1,130 @@
+# 11-LinuxCNC 源码与真实执行严格对标任务
+
+## 目标
+
+本轮新增任务把 native 对标基线明确升级为：
+
+```text
+/home/mes123456/cnc_wams/linuxcnc
+```
+
+该目录中的 LinuxCNC 源码、配置、构建产物和真实运行态是 `xyzbc-trt` Web 仿真的唯一 native 权威源。后续不能只用整理过的 Markdown、历史 evidence 或手写等价模型作为验收依据；任何 Web 行为、JSON 字段、截图和 compare 结论都必须能反查到 LinuxCNC 源树文件、真实运行采样或二者组合。
+
+## 权威源范围
+
+### 启动与运行入口
+
+| 类别 | 权威路径 | 必须采集的事实 |
+| --- | --- | --- |
+| RIP 环境 | `/home/mes123456/cnc_wams/linuxcnc/scripts/rip-environment` | 环境变量、Python 模块路径、bin/rtlib 路径、启动前置 |
+| AXIS 启动 | `/home/mes123456/cnc_wams/linuxcnc/bin/axis` | 实际 GUI 入口、加载的 INI、进程树 |
+| Vismach 启动 | `/home/mes123456/cnc_wams/linuxcnc/bin/xyzbc-trt-gui` | wrapper 与 Python 模型入口 |
+| 桌面入口 | `/home/mes123456/cnc_wams/linuxcnc/linuxcnc-rtcp-5axis-shortcuts/table-rotary-tilting/xyzbc-trt.desktop` | Exec、WorkingDirectory、加载配置 |
+| 原生模块 | `/home/mes123456/cnc_wams/linuxcnc/rtlib/xyzbc-trt-kins.so` | 构建产物存在性、sha256、符号/版本绑定 |
+
+### 配置与运行文件
+
+| 类别 | 权威路径 | 必须对标的内容 |
+| --- | --- | --- |
+| 主 INI | `configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini` | DISPLAY、RS274NGC、KINS、HAL、HALUI、TRAJ、EMCMOT、TASK、EMCIO、AXIS、JOINT 全字段 |
+| PyVCP | `configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.xml` | SWITCHKINS multilabel、type0/type1/type2、vismach-clear |
+| POSTGUI HAL | `configs/sim/axis/vismach/5axis/table-rotary-tilting/switchkins_postgui.hal` | PyVCP pin 到 halui MDI 与 vismach.plotclear 的 net |
+| basic_sim 生成 HAL | `configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt_cmds.hal` | loadrt/loadusr/net/setp/addf/thread、manual toolchange、sim spindle、PID/mux/home switch |
+| tool table | `configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.tbl` | 工具号、长度、直径、tool-offset 闭环 |
+| parameter file | `configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc.var` | G54/G10/持久化参数和运行前后变化 |
+| 示例程序 | `configs/sim/axis/vismach/5axis/table-rotary-tilting/demos/*.ngc` | 默认程序、boat 程序、真实加载/执行 |
+| remap/Ngcgui 子程序 | `configs/sim/axis/vismach/5axis/table-rotary-tilting/remap_subs/*.ngc` | M428/M429/M430、xyzbc_switchkins_sub、centering、helix_bc |
+
+### 源码级行为
+
+| 类别 | 权威路径 | 必须对标的内容 |
+| --- | --- | --- |
+| switchkins wrapper | `src/emc/kinematics/xyzbc-trt-kins.c` | `identityfirst`、switchkins-type 0/1/2、required_coordinates、HAL prefix |
+| TRT 运动学公式 | `src/emc/kinematics/trtfuncs.c` | XYZBC forward/inverse、offset、tool-offset、rot-point、conventional-directions、坐标映射 |
+| Vismach 模型 | `src/hal/user_comps/vismach/xyzbc-trt-gui.py` | HAL pins、几何层级、颜色、方向、Capture 点、视角 |
+| AXIS UI | LinuxCNC AXIS Python 源码 | 菜单、工具栏、模式、按钮联锁、MDI、jog、override、touch-off、状态消息 |
+| interpreter/task/HAL | LinuxCNC 对应 C/C++/Python 源码和运行 API | 实际执行事件、状态转移、错误路径、采样时序 |
+
+## 新增任务组
+
+### A. 源树权威清单
+
+1. 生成 `xyzbc-trt-source-manifest.json`：记录所有权威文件的绝对路径、sha256、mtime、文件大小、角色和被哪个 Web/evidence 字段使用。
+2. Web staging 必须逐文件引用 manifest；缺失、hash 不同、来源不明都要进入 blocker。
+3. 文档和 evidence 中的每个“已对标”结论必须能反查到 manifest 文件。
+
+### B. 原生真实启动采集
+
+1. 用 `rip-environment` 启动 `xyzbc-trt.ini`。
+2. 记录实际命令、环境变量、当前工作目录、进程树、加载的 rtlib、HAL 组件、GUI 组件和 PyVCP/POSTGUI 加载顺序。
+3. 采集失败时输出结构化 blocked JSON，不允许只留下 traceback。
+
+### C. INI/HAL 全量解析
+
+1. INI 解析必须覆盖所有 section/key，不允许只提取 profile 用到的字段。
+2. HAL 解析必须合并 INI `HALCMD`、`LIB:basic_sim.tcl` 运行生成结果、`switchkins_postgui.hal` 和真实 halcmd show 输出。
+3. compare 必须输出字段缺失、值不一致、未连接 pin、未采集 thread/function 的明细。
+
+### D. 运动学公式级验证
+
+1. 从 `xyzbc-trt-kins.c` 和 `trtfuncs.c` 生成公式对标说明。
+2. 用 native 运行态 HAL pin 组合和多组随机/边界姿态验证 forward/inverse。
+3. Web 与 native 对比必须记录 TCP、joint、toolAxis、offset 误差和首个差异点。
+4. `conventional-directions`、`x/y/z-rot-point`、`x/y/z-offset`、`tool-offset` 都必须进入测试矩阵。
+
+### E. remap 与 switchkins 真实语义
+
+1. M428/M429/M430 必须按源码逐行对标：`M68 E3 Q*`、`M66` 同步、`motion.switchkins-type` 检查、debug/STOP 失败路径。
+2. PyVCP type0/type1/type2 到 HALUI MDI 命令的真实路径必须采集。
+3. 运行中切换、未满足 HAL pin、错误 task 模式等失败路径必须有 native/Web 成对证据。
+
+### F. AXIS/PyVCP/Vismach UI 完整对标
+
+1. AXIS 菜单、工具栏、状态栏、DRO、预览、程序、MDI、jog、override、spindle/coolant、touch-off 的按钮/输入/禁用态必须有来源行和真实点击结果。
+2. PyVCP 的 multilabel、按钮、HAL pin、POSTGUI net 必须完整映射到 Web DOM、状态和 evidence。
+3. Vismach 变换树必须按 `xyzbc-trt-gui.py` 逐层对齐，Web 需要输出 transform/pin/capture 点证据。
+
+### G. 真实执行采样
+
+1. native evidence 必须明确区分：
+   - `sourceDerived`：源文件静态解析。
+   - `runtimeObserved`：LinuxCNC 运行态事件/API/HAL/日志观察。
+   - `runtimeSampled`：按时间采样的 joint/TCP/tool/state。
+2. `SERVO_PERIOD=1000000` 和 `TASK CYCLE_TIME=0.010` 必须进入 evidence；50ms 对比样本必须说明从何种原始时间基准抽取。
+3. 真实执行过程必须包含当前文件/行、调用栈、参数赋值、G/M 代码、work offset、switchkins、motion segment、feed/spindle/coolant/tool 状态。
+
+### H. Web 复现与 compare 升级
+
+1. Web evidence 必须证明 staged 文件 hash 与 LinuxCNC manifest 一致。
+2. WASM artifact 必须绑定 LinuxCNC 源码路径、构建命令、编译选项、sha256 和导出符号。
+3. compare JSON 新增以下顶层结果：
+   - `sourceManifestComparison`
+   - `runtimeLaunchComparison`
+   - `iniFullComparison`
+   - `halGraphComparison`
+   - `kinematicsFormulaComparison`
+   - `uiBehaviorComparison`
+   - `visualComparison`
+4. 任何无法从源码或真实运行证明的 Web 行为，都必须标为 fail 或 blocker。
+
+### I. 截图与视觉证据
+
+1. 同一运行时间点采集 native AXIS/Vismach 截图与 Web DOM/canvas 截图。
+2. 截图 manifest 必须包含 sampleIndex、timeMs、当前源行、joint、TCP、toolAxis、kinstype、feed、spindle、tool、coolant。
+3. 视觉差异必须有文字说明和结构化字段，不能只保存图片。
+
+### J. 回归门禁
+
+1. 提供一键复验命令：启动 native、采集 source/runtime evidence、采集 Web evidence、执行 compare、生成截图和摘要。
+2. T-051 到 T-075 全部通过前，`working` 不得再声明“严格完整对标已完成”；2026-07-04 复验后，最新 `compare-xyzbc-trt-evidence.json` 为 `60/60 pass`，`blockers=[]`。
+3. 全部通过后冻结 manifest、evidence、截图和 compare 摘要；后续任何代码或源文件变更必须重新复验。
+
+## 当前状态
+
+本文件最初为新增任务整理结果。2026-07-04 后续实现轮次已完成 T-051 到 T-075，并更新 `04-任务矩阵.md`、native/Web/compare evidence。当前最新状态：
+
+- `native-xyzbc-trt-evidence.json` 新增 `sourceManifest`、`runtimeLaunch`、`iniFull`、`halGraph`、`kinematicsFormula`、`remapSemantics`、`runtimeExecutionObserved`、`runtimeEvidenceClassification`、`reverseSourceIndex`、`performanceBudget`、`strictAcceptance` 等源码/运行双基线字段。
+- `web-xyzbc-trt-evidence.json` 新增 Web staging sha256、完整 INI、HAL/task 模型、WASM artifact sha256/source binding、UI/Vismach/错误路径/性能预算等同名字段。
+- `compare-xyzbc-trt-evidence.json` 新增 `sourceManifestComparison`、`runtimeLaunchComparison`、`halGraphComparison`、`iniFullComparison`、`kinematicsFormulaComparison`、`uiBehaviorComparison`、`visualComparison` 和 `strictComparison`，当前 `checkCount=60`、`passCount=60`、`failCount=0`、`blockers=[]`。
+
+因此，现有 T-001 到 T-075 均为完成状态；后续任何涉及源码、staging、WASM artifact、UI 行为或采样逻辑的修改，都必须重新生成 native/Web/compare evidence 并保持 60/60 pass 或更新验收门槛。