a0810b8598
结论：新增独立 wasm-port 工作区，修复 native probes include 路径，最小解释器 harness 已可验证 G0 直线快速、G1 进给和 SET_FEED_RATE canonical event。检查：git diff --check 通过；wasm-port/tests/native/verify_native_probes.sh 通过。
117 lines
3.2 KiB
Markdown
117 lines
3.2 KiB
Markdown
# AGENTS.md
|
|
|
|
## Scope
|
|
|
|
This file defines agent operating rules for the standalone LinuxCNC WASM
|
|
simulation port located under `wasm-port/`.
|
|
|
|
This workspace is separate from the upstream LinuxCNC tree in
|
|
`../linuxcnc/`.
|
|
|
|
## Primary Objective
|
|
|
|
Build a standalone CNC simulation system that:
|
|
|
|
- reuses LinuxCNC source as the semantic source of truth;
|
|
- compiles core CNC logic to WASM;
|
|
- uses HTML + JavaScript for the frontend;
|
|
- uses OPFS for browser persistence;
|
|
- does not drive real hardware;
|
|
- preserves LinuxCNC software behavior as closely as practical.
|
|
|
|
## Repository Boundaries
|
|
|
|
1. `../linuxcnc/` is upstream and must be treated as read-only input for the
|
|
port effort.
|
|
2. Port-specific code must live under `wasm-port/`.
|
|
3. Vendored LinuxCNC source copies must live under
|
|
`wasm-port/vendor/linuxcnc/`.
|
|
4. Any source-level adaptation must be applied to vendored copies only.
|
|
5. Never treat experimental files under `../linuxcnc/web/` as the official
|
|
port target. The official port program is managed here.
|
|
|
|
## Engineering Rules
|
|
|
|
1. Reuse LinuxCNC source before reimplementing any CNC logic.
|
|
2. Prefer wrappers, shims, and extraction scripts over invasive source edits.
|
|
3. Preserve LinuxCNC semantics for:
|
|
- G-code execution;
|
|
- modal state;
|
|
- parameter and variable behavior;
|
|
- kinematics;
|
|
- planner behavior;
|
|
- machine and controller state visible to software.
|
|
4. Replace only the native runtime edges:
|
|
- file IO;
|
|
- process model;
|
|
- HAL runtime;
|
|
- IPC;
|
|
- GUI.
|
|
5. Frontend code must be implemented with web technology, not migrated from
|
|
native GUI code.
|
|
|
|
## Required Layout
|
|
|
|
The standalone port should use these major areas:
|
|
|
|
- `docs/`
|
|
- `vendor/`
|
|
- `patches/`
|
|
- `tools/`
|
|
- `runtime/core/`
|
|
- `runtime/sdk/`
|
|
- `runtime/ui/`
|
|
- `runtime/opfs/`
|
|
- `tests/`
|
|
|
|
Do not collapse these concerns back into the upstream tree.
|
|
|
|
## File Ownership
|
|
|
|
- `docs/`: planning, architecture, drift tracking, validation
|
|
- `vendor/`: copied upstream source
|
|
- `patches/`: patches against vendored copies
|
|
- `tools/`: extraction and sync scripts
|
|
- `runtime/core/`: standalone native/WASM simulation runtime
|
|
- `runtime/sdk/`: JS or TS SDK
|
|
- `runtime/ui/`: HTML + JavaScript simulation frontend
|
|
- `runtime/opfs/`: browser persistence layer
|
|
- `tests/`: standalone native and browser regression coverage
|
|
|
|
## Validation Requirements
|
|
|
|
Every migrated feature should be validated against LinuxCNC-native behavior
|
|
using one or more of:
|
|
|
|
- existing LinuxCNC tests;
|
|
- extracted native harness tests;
|
|
- WASM regression tests;
|
|
- browser smoke tests.
|
|
|
|
Validation should cover:
|
|
|
|
- path output;
|
|
- machine/controller state;
|
|
- parameter and variable behavior;
|
|
- kinematic transforms;
|
|
- file/config loading.
|
|
|
|
## Non-Goals
|
|
|
|
This project must not:
|
|
|
|
- attempt realtime hardware control;
|
|
- port LinuxCNC drivers to the browser;
|
|
- recreate LinuxCNC's native process topology;
|
|
- rewrite major CNC semantics in JavaScript if LinuxCNC source can be reused;
|
|
- depend on LinuxCNC native GUI code as implementation code.
|
|
|
|
## Working Style
|
|
|
|
When extending this workspace:
|
|
|
|
1. Update docs before or alongside structural changes.
|
|
2. Keep extraction and patching reproducible.
|
|
3. Keep adapters narrow and explicit.
|
|
4. Keep LinuxCNC-derived logic traceable to its upstream file origin.
|