246 lines
9.3 KiB
Markdown
246 lines
9.3 KiB
Markdown
# 02-项目程序开发详细步骤
|
||
|
||
## 步骤
|
||
|
||
1. 读取 `doc/xyzbc-trt-runtime-files.md`，确认 LinuxCNC 进程、INI、PyVCP、POSTGUI HAL、Vismach、remap、tool table、parameter file 的运行关系。
|
||
2. 读取 `wasm-port/AGENTS.md` 和 `wasm-port/SKILL.md`，确认必须复用 LinuxCNC 源码语义，Web 只做 UI/OPFS/运行边界适配。
|
||
3. 检查 `wasm-port` 是否包含 `xyzbc-trt`：确认 SDK、probe、vendored configs、remap harness 已覆盖。
|
||
4. 复制参考 Web app 到目标目录：
|
||
|
||
```text
|
||
web-rtcp-5axis-xyzbc-trt-sim-plan/app
|
||
web-rtcp-5axis-xyzbc-trt-sim-plan/tests
|
||
```
|
||
|
||
5. 将目标 app 默认机型改为 `xyzbc-trt`：
|
||
|
||
```text
|
||
app/src/state/store.js
|
||
app/src/profiles/index.js
|
||
app/src/runtime/linuxcnc-kinematics-runtime.js
|
||
app/src/runtime/linuxcnc-kinematics-worker-client.js
|
||
app/src/main.js
|
||
```
|
||
|
||
6. 将 OPFS/session/tool-db 根路径改为目标项目命名空间：
|
||
|
||
```text
|
||
web-rtcp-5axis-xyzbc-trt-sim-plan/machines
|
||
web-rtcp-5axis-xyzbc-trt-sim-plan/sessions
|
||
web-rtcp-5axis-xyzbc-trt-sim-plan/tool-db
|
||
```
|
||
|
||
7. 为 `xyzbc-trt` profile 增加默认机器文件 staging：
|
||
|
||
```js
|
||
machineFileStaging: {
|
||
defaultProgramFilename: "xyzbc_switchkins.ngc",
|
||
wasmDir: "/work/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt",
|
||
}
|
||
```
|
||
|
||
8. 新增目标项目 Node smoke：
|
||
|
||
```text
|
||
tests/node/verify_xyzbc_trt_web_app.mjs
|
||
```
|
||
|
||
9. 创建工作文档：
|
||
|
||
```text
|
||
working/01-项目功能内容.md
|
||
working/02-项目程序开发详细步骤.md
|
||
working/03-推进台账.md
|
||
working/04-任务矩阵.md
|
||
working/05-验收证据.md
|
||
working/06-决策记录.md
|
||
working/07-全量对标追踪矩阵.md
|
||
working/README.md
|
||
```
|
||
|
||
10. 按 `07-全量对标追踪矩阵.md` 继续补齐 Web 对标功能：
|
||
|
||
```text
|
||
AXIS 等效界面
|
||
PyVCP/POSTGUI HAL 等效连接
|
||
basic_sim task/HAL 等效运行
|
||
Vismach xyzbc-trt-gui.py 等效 3D 模型
|
||
Ngcgui/remap 子程序全集 staging 和执行
|
||
TRAJ/AXIS/JOINT 限制、速度、单位和 override
|
||
tool table/tool offset 对 kinematics 和模型的双向影响
|
||
native/Web JSON 全字段对比
|
||
```
|
||
|
||
11. 切换 native 真实执行基线到 `/home/mes123456/cnc_wams/linuxcnc`：
|
||
|
||
```bash
|
||
test -x /home/mes123456/cnc_wams/linuxcnc/scripts/rip-environment
|
||
test -x /home/mes123456/cnc_wams/linuxcnc/bin/axis
|
||
test -x /home/mes123456/cnc_wams/linuxcnc/bin/xyzbc-trt-gui
|
||
test -f /home/mes123456/cnc_wams/linuxcnc/rtlib/xyzbc-trt-kins.so
|
||
test -f /home/mes123456/cnc_wams/linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini
|
||
```
|
||
|
||
验收要求：
|
||
|
||
- 上述文件存在后，native 采集脚本统一使用 `/home/mes123456/cnc_wams/linuxcnc/scripts/rip-environment`。
|
||
- 真实执行命令的 INI 必须是 `/home/mes123456/cnc_wams/linuxcnc/configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini`。
|
||
- Web 界面布局、状态流、switchkins 逻辑、Vismach 等效模型、刀具路径和 JSON 字段都以该路径实际执行结果为准。
|
||
- `/home/mes123456/linuxcnc-master` 只能作为历史运行参考，不再作为新的 native evidence 基线。
|
||
|
||
## 后续完整验收步骤
|
||
|
||
1. 生成 WASM artifact：
|
||
|
||
```bash
|
||
source /home/mes123456/emsdk/emsdk_env.sh
|
||
wasm-port/tools/build_kinematics_wasm.sh
|
||
wasm-port/tools/build_wasm_core.sh
|
||
wasm-port/tools/build_tp_wasm.sh
|
||
wasm-port/tools/build_task_hal_wasm.sh
|
||
```
|
||
|
||
2. 运行 wasm-port 对应验证：
|
||
|
||
```bash
|
||
wasm-port/tests/wasm/node/verify_kinematics_wasm.sh
|
||
wasm-port/tests/wasm/node/verify_interp_wasm.sh
|
||
wasm-port/tests/wasm/node/verify_task_hal_wasm.sh
|
||
wasm-port/tests/browser/verify_interp_browser.sh
|
||
```
|
||
|
||
3. 运行目标 app 验证：
|
||
|
||
```bash
|
||
npm --prefix web-rtcp-5axis-xyzbc-trt-sim-plan/app run smoke:node
|
||
npm --prefix web-rtcp-5axis-xyzbc-trt-sim-plan/app run build
|
||
```
|
||
|
||
4. 生成 native/Web 对比证据：
|
||
|
||
```bash
|
||
/home/mes123456/cnc_wams/linuxcnc/scripts/rip-environment \
|
||
python3 web-rtcp-5axis-xyzbc-trt-sim-plan/tools/collect-native-xyzbc-trt-evidence.py --run --timeout 90
|
||
npm --prefix web-rtcp-5axis-xyzbc-trt-sim-plan/app run evidence:web
|
||
npm --prefix web-rtcp-5axis-xyzbc-trt-sim-plan/app run evidence:compare
|
||
```
|
||
|
||
输出：
|
||
|
||
```text
|
||
web-rtcp-5axis-xyzbc-trt-sim-plan/working/evidence/native-xyzbc-trt-evidence.json
|
||
web-rtcp-5axis-xyzbc-trt-sim-plan/working/evidence/web-xyzbc-trt-evidence.json
|
||
web-rtcp-5axis-xyzbc-trt-sim-plan/working/evidence/compare-xyzbc-trt-evidence.json
|
||
```
|
||
|
||
5. 补充刀具预览路径和刀具执行路径采集：
|
||
|
||
```text
|
||
tools/collect-native-xyzbc-trt-evidence.py
|
||
tools/collect-web-xyzbc-trt-evidence.mjs
|
||
tools/compare-xyzbc-trt-evidence.mjs
|
||
```
|
||
|
||
实现要求：
|
||
|
||
- 在 native evidence 中增加 `pathSampling`、`previewPath`、`executionPath`。
|
||
- 在 Web evidence 中增加同名字段，字段结构必须与 native 完全一致。
|
||
- 统一对比采样周期暂定为 `samplePeriodMs = 50`。
|
||
- 采集脚本可保留原始高频/低频轨迹，但写入对比 JSON 的曲线必须重采样到 50ms。
|
||
- 预览路径从 LinuxCNC preview/canon 或 Web preview planner 采集；执行路径从 LinuxCNC `stat()`/HAL 反馈或 Web task/HAL runtime 采集。
|
||
- 每个样本必须包含 `sampleIndex`、`timeMs`、`line`、`motionType`、`activeKinematics`、`tool`、`joint`、`tcp`、`toolAxis`、`feed`、`spindle`。
|
||
- 对 B/C 旋转轴和 TCP/toolAxis 的计算必须以 `xyzbc-trt` kinematics/WASM 结果为准，不能用 UI 插值伪造。
|
||
|
||
6. 补充刀路 compare 规则：
|
||
|
||
```json
|
||
{
|
||
"pathComparison": {
|
||
"samplePeriodMs": 50,
|
||
"previewVsPreview": {},
|
||
"executionVsExecution": {},
|
||
"previewVsExecutionNative": {},
|
||
"previewVsExecutionWeb": {}
|
||
}
|
||
}
|
||
```
|
||
|
||
验收要求：
|
||
|
||
- `compare-xyzbc-trt-evidence.json` 中新增 `pathComparison`。
|
||
- `checks` 中新增 `path-preview`、`path-execution`、`path-preview-execution-consistency` 类别。
|
||
- 每类检查至少输出 `maxTcpErrorMm`、`rmsTcpErrorMm`、`maxJointError`、`rmsJointError`、`maxToolAxisAngleDeg`、`sampleCountDelta`、`missingSamples`。
|
||
- 若 native/Web 两侧采样周期不一致，compare 必须直接 fail，并输出实际周期。
|
||
- 若 WASM artifact 缺失导致 Web 执行路径无法采集，compare 必须保持 fail/blocker，不能用预览路径替代执行路径。
|
||
|
||
7. 补充全量对标 JSON 字段：
|
||
|
||
```json
|
||
{
|
||
"startupSequence": [],
|
||
"iniDisplay": {},
|
||
"halNets": [],
|
||
"kinematicsPins": {},
|
||
"axisJointLimits": {},
|
||
"switchkinsTransitions": [],
|
||
"uiEquivalence": {},
|
||
"vismachEquivalent": {},
|
||
"ngcguiSubroutines": [],
|
||
"demoPrograms": []
|
||
}
|
||
```
|
||
|
||
验收要求：
|
||
|
||
- `startupSequence` 对标 `.desktop -> rip-environment -> linuxcncsvr/rtapi_app/milltask/halui -> basic_sim -> kinematics -> Vismach -> AXIS -> PyVCP -> POSTGUI HAL -> OPEN_FILE`。
|
||
- `halNets` 覆盖 `motion.switchkins-type`、`halui.mdi-command-*`、`pyvcp.*`、`joint.N.pos-fb`、`motion.tooloffset.z`、`xyzbc-trt-kins.*`。
|
||
- `kinematicsPins` 覆盖 `x-offset=-20`、`z-offset=-15`、`x/y/z-rot-point=0`、`conventional-directions=0`、`tool-offset`。
|
||
- `axisJointLimits` 覆盖 `XYZBC` 单位、关节数、B/C 角轴限制、TRAJ 速度/加速度。
|
||
- `uiEquivalence` 覆盖 AXIS 主界面的程序区、坐标区、MDI/switchkins、override、工具、状态、预览/执行路径。
|
||
- `vismachEquivalent` 覆盖 `xyzbc-trt-gui.py` 的模型 pin 和清除轨迹行为。
|
||
- `ngcguiSubroutines` 覆盖 `xyzbc_switchkins_sub.ngc`、`centering.ngc`、`helix_bc.ngc`。
|
||
- `demoPrograms` 覆盖 `xyzbc_switchkins.ngc` 和 `boat-xyzbc.ngc`。
|
||
|
||
8. 启动目标 Web：
|
||
|
||
```bash
|
||
cd web-rtcp-5axis-xyzbc-trt-sim-plan/app
|
||
npm run dev
|
||
```
|
||
|
||
默认 URL：
|
||
|
||
```text
|
||
http://127.0.0.1:4174/
|
||
```
|
||
|
||
当前执行状态：
|
||
|
||
- 2026-07-05 18:08 EDT 已按上述验收链重新执行 native/Web/compare/build/smoke。
|
||
- 最新 native evidence：`status=ok`、`coverage=35/35`、`executionMode=auto-run`。
|
||
- 最新 Web evidence：`status=ready-for-wasm-runtime`、`coverage=49/49`、`blockers=[]`。
|
||
- 最新 compare：`status=pass`、`checkCount=60`、`passCount=60`、`failCount=0`、`blockers=[]`、`requiredImprovements=[]`。
|
||
- 后续任何实现、文档规则、staging 文件、WASM artifact、采集脚本或 UI 行为变更后，都必须重新执行本节第 4 步的 native/Web/compare 证据链，并补跑 `npm --prefix web-rtcp-5axis-xyzbc-trt-sim-plan/app run build`、`smoke:node`、`smoke:browser`。
|
||
|
||
## 截图真实执行过程修复步骤
|
||
|
||
9. 针对 `working/screenshots/web-simulation-full-process-20260703T051258Z` 暴露的问题，页面层新增真实执行过程派生链：
|
||
|
||
```text
|
||
app/src/runtime/axis-preview-path.js
|
||
app/src/state/store.js
|
||
app/src/ui/axis-shell.js
|
||
app/src/styles/axis.css
|
||
tests/node/verify_xyzbc_trt_web_app.mjs
|
||
tests/browser/xyzbc_trt_browser_smoke.html
|
||
```
|
||
|
||
实现要求：
|
||
|
||
- `programAxisPreviewPath.samples[]` 写入 `sourceFile`、`statement`、`segmentIndex`，样本来源必须是 `xyzbc_switchkins_sub.ngc`/`helix_bc.ngc` 展开后的真实源程序。
|
||
- store 中新增 `programUiExecution`，由当前 50ms 样本派生 `sourceFile:line`、operation、sample index、statement、joint、tcp、toolAxis、machineState。
|
||
- RUN/STEP/RUN_FRAME/task-HAL 状态应用必须统一调用样本派生逻辑，不能分别维护刀位、刀轴和当前行。
|
||
- `state.toolAxisVector` 必须从当前样本 `toolAxis.i/j/k` 派生，Three.js 刀头、刀轴线和 Vismach 刀杆方向共享该向量。
|
||
- 程序区必须显示实时执行条，监控面板必须显示当前展开源文件和源行。
|
||
- browser smoke 必须断言 DOM dataset、state、canvas `data-three-tool-axis` 三者一致。
|