fb8d8b2d9d
结论：明确禁止继续扩展自写 CNC 主体语义，最小 runtime 仅保留为迁移探针；新增 interp_convert.cc 源码直连编译探针，并以最小 emcStatus 状态边界 shim 暴露 native runtime 阻塞点。检查：git diff --check 通过；wasm-port/tests/native/verify_native_probes.sh 通过，linuxcnc_interp_convert_source_probe exitcode=0。
131 lines
3.9 KiB
Markdown
131 lines
3.9 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.
|
|
|
|
## Current Direction
|
|
|
|
The migration target is the LinuxCNC source program itself, adapted to run as
|
|
the standalone WASM simulation program. The project must not evolve a
|
|
project-authored interpreter, planner, or CNC semantics layer now that the
|
|
porting harness is running.
|
|
|
|
Existing minimal runtime wrappers are migration probes only. They are allowed
|
|
to expose, compile, and validate vendored LinuxCNC code, but they must not be
|
|
expanded into a separate implementation of G-code behavior.
|
|
|
|
## 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. Do not add new project-authored CNC semantics when LinuxCNC source exists.
|
|
Replace temporary wrapper behavior with direct calls into vendored LinuxCNC
|
|
source, or with the narrowest shims needed to make those calls compile.
|
|
3. Prefer wrappers, shims, and extraction scripts over invasive source edits.
|
|
4. Preserve LinuxCNC semantics for:
|
|
- G-code execution;
|
|
- modal state;
|
|
- parameter and variable behavior;
|
|
- kinematics;
|
|
- planner behavior;
|
|
- machine and controller state visible to software.
|
|
5. Replace only the native runtime edges:
|
|
- file IO;
|
|
- process model;
|
|
- HAL runtime;
|
|
- IPC;
|
|
- GUI.
|
|
6. 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.
|