cnc/AGENTS.md

# CNC Project Agent Guide

继续按 `align-linuxcnc` 约束推进。先确认基线，优先完成能降低剩余风险的可验证功能切片；禁止顺手扩展 smoke parser。提交满足后及时提交并推送云仓库，提交标题和说明使用中文，说明源依据、结论和检查结果。

## 现状判断

项目已经迭代很久但仍有大量工作，主要原因不是单个测试失败，而是后段工作集中在 LinuxCNC 浏览器化最难的边界：

- Python/remap、Boost.Python、tooldata mmap、HAL/native filesystem 等 LinuxCNC 依赖不能靠自写兼容逻辑绕过，必须按 LinuxCNC 源码移植、裁剪、封装或替换。
- 早期 smoke/fallback 体量仍大，后续只能缩减或路由到 LinuxCNC source-linked 路径，不能继续扩语义。
- 很多提交用于 source-map、guardrail 和边界证明，能防退化但不直接减少功能缺口。
- 完整验证成本高：native、source-link、Node WASM、真实浏览器 OPFS smoke 都要保持闭环。
- 如果本地提交未及时推送，云端会严重落后，后续上下文会误判进度。

因此后续默认按“高收益切片”推进，不再把文档/source-map-only 作为主要进度。

## 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 simulator change with:

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

For root-level instruction edits, also check:

```bash
cd /home/cnc/桌面/cnc
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.
- Never expand temporary smoke parser semantics. Prefer deletion, shrinkage, or LinuxCNC source-linked routing.

## High-Impact Lanes

When the user asks to continue, default to one of these three lanes unless the user explicitly asks otherwise:

1. Python/remap inert shim 收敛
   - Compile or link more LinuxCNC Python/remap/Boost.Python source surfaces against inert wasm-safe shims.
   - Preserve disabled-Python boundaries until a source-backed browser-safe execution plan exists.
   - Useful outputs: symbol probe, object/link probe, negative-status probe, blocker reduction, manifest/test update.

2. tooldata mmap 后端替换
   - Move LinuxCNC `tooldata_mmap.cc` behavior toward wasm-safe storage without changing tool semantics.
   - Useful outputs: backend behavior parity probe, source-backed table load/save coverage, mmap/native-fs blocker shrinkage.

3. smoke parser 缩减到 LinuxCNC source-linked 路径
   - Replace smoke/fallback coverage with LinuxCNC RS274 source-linked tests and bridge paths.
   - Useful outputs: deleted smoke branches, tests moved to `linuxcnc-rs274`, source-linked fixture coverage.

## Fast Loop

1. Pick one small missing source-backed bridge point or blocker-reducing gap.
2. Locate the LinuxCNC source/config/remap first:

   ```bash
   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 executable test, generated fixture, probe, or manifest entry.
5. Implement only the minimal port/wrapper/shim/bridge needed.
6. Run required checks.
7. Commit and push once if checks pass.
8. Report changed files, LinuxCNC source basis, tests, push status, and completion estimate.

## Required Checks

For code, generated fixture, source-manifest, shim, build, or probe changes:

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

For generated switchkins/remap table changes, also run:

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

Documentation-only instruction edits do not require native/source-link; run `git diff --check` and report that full simulator tests were not run.

## Anti-Stall Rules

- Avoid repeated documentation/source-map-only commits. They are allowed only when protecting a new source path, unblocking a build/test, or updating requested process rules.
- After one source-map-only or docs-only commit, the next simulator iteration should attempt code, generator, fixture, executable probe, or smoke shrinkage.
- Time-box source discovery. If a source basis cannot be located quickly, report the blocked symbol/path and switch to another high-impact lane.
- Do not make broad cleanups, UI work, or unrelated refactors while the three high-impact lanes still have blockers.
- Batch one coherent mini-slice per commit. Do not mix unrelated workstreams.
- Keep browser persistence OPFS-only.

## Commit And Push

- Commit each coherent slice once required checks pass.
- Use Chinese commit titles and include a conclusion in the commit body.
- Push after each successful commit.
- If HTTP credentials are unavailable, report the failure and continue local progress instead of retrying the same failing push repeatedly.
- If credentials are already available outside the repository, use a temporary non-interactive credential helper or askpass flow; do not commit credentials.
- Before finishing, confirm `git status --short` and remote divergence when a push was expected.

## 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.
- Native and source-linked RS274 test paths.
- Canon event bridge and event sink for many interpreter callbacks.
- Broad regression corpus under `tests/gcode/`.
- Generated M428/M429/M430 switchkins/remap config coverage.
- Node and real browser WASM smoke coverage including OPFS paths.

Main remaining risks:

- Temporary smoke parser still exists and must shrink.
- Python/remap and Boost.Python paths are compile/shim covered but not browser-executed.
- `tooldata_mmap.cc` native backend remains a core wasm replacement risk.
- HAL/filesystem assumptions still need source-backed browser-safe boundaries.
- Five-axis and RTCP coverage must remain tied to LinuxCNC kinematics/remap/config source.

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