CNC Project Agent Guide

工作树已经有一批未提交修改，太大了。我把这批改动按 6 个上下文拆更合适 switchkins/remap 生成器和表 linuxcnc-kinematics 源清单 WASM 文件系统和 OPFS 持久化浏览器端应用接入 Node / browser 烟测源码链接、构建和文档约束

Mission

Build a browser/WebAssembly CNC simulator whose G-code behavior is aligned with LinuxCNC source. This is not an independent compatible interpreter; it is a port, trim, wrapper, or platform adaptation of LinuxCNC behavior.

Work Roots

Project root: /home/cnc/桌面/cnc
Simulator root: /home/cnc/桌面/cnc/wasm-simulator
LinuxCNC source: /home/cnc/桌面/cnc/linuxcnc or $LINUXCNC_ROOT
LinuxCNC unit tests: /home/cnc/桌面/cnc/linuxcnc/unit_tests

Start every change with:

cd /home/cnc/桌面/cnc/wasm-simulator
git status --short

Non-Negotiable Rules

Port LinuxCNC source first. Prefer direct source porting, trimming, wrapping, or platform adaptation over project-authored replacements.
Do not write independent functional CNC behavior.
Functional behavior must come from LinuxCNC source code.
Do not use documentation, examples, or intuition as the final source when LinuxCNC source is available.
Any G/M interpretation, motion, kinematics, coordinates, cutter compensation, canned cycles, parameter expressions, modal state, tool data, remap behavior, or RTCP behavior must first be traced to LinuxCNC source.
Allowed project-authored code is limited to LinuxCNC porting/trimming, wrappers, platform shims, thin WASM/API/event bridges, generated fixtures, tests, build scripts, and documentation.
Browser-side WASM filesystem access must use OPFS-backed storage. Do not add browser filesystem behavior that bypasses OPFS.

Source-First Workflow

Pick one small missing source-backed bridge point or behavior gap.

Locate the LinuxCNC source/config/remap first. Prefer:

rg -n "symbol|gcode|mcode|error text" ../linuxcnc/src ../linuxcnc/configs

Record the source file/function in the test, fixture, manifest, comment, or nearby documentation when the mapping is not obvious.
Add or update an automated test, generated fixture, or manifest entry.
Implement only the minimal port/wrapper/shim/bridge needed.
Run the required checks.
Report changed files, LinuxCNC source basis, test result, and completion percentage.

Required Checks

For code, generated fixture, or source-manifest changes:

./test-native.sh
./test-linuxcnc-source-link.sh

For generated switchkins/remap table changes, also run:

./check-linuxcnc-switchkins-remap-table.sh linuxcnc-kinematics-source-files.txt

Documentation-only context edits do not require the native/source-link test suite; report that tests were not run.

Current Completion Baseline

Estimated completion: about 72%.

Materially covered:

Stable C ABI in core/include/cnc_sim_api.h.
LinuxCNC RS274 and kinematics source manifests: linuxcnc-rs274-source-files.txt, linuxcnc-rs274-wasm-source-files.txt, and linuxcnc-kinematics-source-files.txt.
Native and source-linked RS274 test paths.
Canon event bridge and event sink for many interpreter callbacks.
Broad regression corpus under tests/gcode/.
M428/M429/M430 switchkins remap config generation from LinuxCNC INI files and remap_subs/{428,429,430}remap.ngc sources.
Browser and Node WASM smoke coverage for generated switchkins config cases.
Source-backed coverage for many modal motion, coordinate, cutter comp, tool length, probe, canned cycle, O-word, parameter, and M-code paths.

Main remaining risks:

Temporary smoke parser still exists and must continue shrinking.
Browser-hostile LinuxCNC dependencies still need deeper replacement or wrapping: Python/Boost.Python remap paths, dynamic loading, HAL/filesystem assumptions, and native tooldata backends.
Browser parity depends on maintaining source-backed behavior instead of extending fallback logic.
Five-axis and RTCP coverage must remain tied to LinuxCNC kinematics source, remap files, and config files.
OPFS integration must be verified in real browser runs, not only Node smoke paths.

Good Next Targets

Replace smoke-only behavior with direct LinuxCNC RS274/source-linked paths.
Expand wasm-safe replacements for Python/remap/tooldata/dlopen dependencies.
Increase generated config coverage from LinuxCNC INI/HAL/remap sources.
Keep M428/M429/M430 and RTCP behavior tied to LinuxCNC kinematics/remap source files.
Add browser checks that prove WASM file reads/writes persist through OPFS.

Stop Conditions

Stop and report if:

LinuxCNC source behavior cannot be located.
A compile/link error cannot be resolved without inventing behavior.
Tests expose a contradiction between project bridge code and LinuxCNC source.
The user explicitly asks to stop.

4.9 KiB Raw Blame History