cnc/AGENTS.md

继续按 align-linuxcnc 约束，先确认干净基线，尽量完成多部分功能。 如果提交满足，及时提交。禁止顺手扩功能 smoke 每次完善提交结束后，立即上传到云仓库，使用中文；git上传的标题使用提示词，说明使用结论。 双向同步

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

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

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

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

3. Record the source file/function in the test, fixture, manifest, comment, or nearby documentation when the mapping is not obvious.

4. Add or update an automated test, generated fixture, or manifest entry.

5. Implement only the minimal port/wrapper/shim/bridge needed.

6. Run the required checks.

7. 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.

Faster Iteration Policy

When the prompt is "尽快推进", optimize for measurable completion progress instead of low-yield source-map churn.

• Prefer changes that add runnable source-backed coverage or remove a real blocker: LinuxCNC source-linked RS274 paths, WASM-safe dependency wrappers, generated LinuxCNC config/remap fixtures, OPFS browser persistence checks, or thin bridge/API paths.
• Avoid repeated documentation/source-map-only commits. Source-map tightening is useful only when it protects a newly added source path, unblocks a build/test, or documents a real bridge/shim change. After two source-map-only commits, the next iteration should attempt code, generator, manifest, fixture, or executable test progress.
• Batch one coherent mini-slice per commit: source lookup, manifest or fixture, minimal shim/bridge/generator change, and required check should travel together when they are part of the same workstream.
• Time-box LinuxCNC source discovery. If the source basis cannot be located quickly, switch to another target and report the blocked symbol/path rather than inventing CNC behavior.
• Do not expand temporary smoke parser semantics. Prefer deleting, shrinking, or routing smoke-only paths toward LinuxCNC source-linked execution.

Impact priority:

1. Replace smoke/fallback behavior with LinuxCNC source-linked execution.
2. Wrap browser-hostile LinuxCNC dependencies without changing CNC semantics: Python/remap, Boost.Python, dlopen, HAL/filesystem, and tooldata.
3. Add real browser OPFS persistence verification for WASM reads/writes.
4. Expand generated source-backed LinuxCNC INI/HAL/remap/kinematics coverage.
5. Strengthen source maps only when guarding one of the above.

After a successful commit, push once. If the cloud repository still lacks HTTP credentials, report the failure and continue local progress instead of retrying the same push repeatedly.

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.