131 lines
4.9 KiB
Markdown
131 lines
4.9 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```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 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:
|
|
|
|
```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 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.
|