按原因重写高效迭代规则
结论：针对长期迭代仍未完成的问题，明确慢因集中在 Python/remap、tooldata mmap、HAL/native filesystem、smoke fallback 和重验证闭环；后续默认只按三条高收益切片推进，并限制 source-map/docs-only 循环。 检查：git diff --check -- AGENTS.md SKILL.md 通过。instruction-only 文档变更，未运行 simulator native/source-link。
This commit is contained in:
cnc
188
AGENTS.md
188
AGENTS.md
@@ -1,22 +1,22 @@
|
||||
继续按 align-linuxcnc 约束，先确认干净基线，尽量完成多部分功能。
|
||||
如果提交满足，及时提交。禁止顺手扩功能 smoke
|
||||
每次完善提交结束后，立即上传到云仓库，使用中文；git上传的标题使用提示词，说明使用结论。
|
||||
双向同步
|
||||
|
||||
|
||||
# CNC Project Agent Guide
|
||||
工作树已经有一批未提交修改，太大了。我把这批改动按 6 个上下文拆更合适
|
||||
switchkins/remap 生成器和表
|
||||
linuxcnc-kinematics 源清单
|
||||
WASM 文件系统和 OPFS 持久化
|
||||
浏览器端应用接入
|
||||
Node / browser 烟测
|
||||
源码链接、构建和文档约束
|
||||
|
||||
继续按 `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.
|
||||
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
|
||||
|
||||
@@ -25,50 +25,67 @@ a port, trim, wrapper, or platform adaptation of LinuxCNC behavior.
|
||||
- LinuxCNC source: `/home/cnc/桌面/cnc/linuxcnc` or `$LINUXCNC_ROOT`
|
||||
- LinuxCNC unit tests: `/home/cnc/桌面/cnc/linuxcnc/unit_tests`
|
||||
|
||||
Start every change with:
|
||||
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.
|
||||
- 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.
|
||||
- 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.
|
||||
|
||||
## Source-First Workflow
|
||||
## High-Impact Lanes
|
||||
|
||||
1. Pick one small missing source-backed bridge point or behavior gap.
|
||||
2. Locate the LinuxCNC source/config/remap first. Prefer:
|
||||
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 automated test, generated fixture, or manifest entry.
|
||||
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 the required checks.
|
||||
7. Report changed files, LinuxCNC source basis, test result, and completion
|
||||
percentage.
|
||||
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, or source-manifest changes:
|
||||
For code, generated fixture, source-manifest, shim, build, or probe changes:
|
||||
|
||||
```bash
|
||||
./test-native.sh
|
||||
@@ -81,8 +98,25 @@ 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.
|
||||
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
|
||||
|
||||
@@ -91,76 +125,20 @@ 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`.
|
||||
- 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/`.
|
||||
- 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.
|
||||
- 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 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.
|
||||
- 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
|
||||
|
||||
|
||||
121
SKILL.md
Normal file
121
SKILL.md
Normal file
@@ -0,0 +1,121 @@
|
||||
---
|
||||
name: align-linuxcnc
|
||||
description: Use for this CNC Web/WASM simulator when evaluating progress or changing LinuxCNC G-code behavior, RS274 source integration, kinematics, remaps, tool data, modal state, parameters, tests, fixtures, build scripts, bridge code, or project iteration strategy.
|
||||
---
|
||||
|
||||
# Align LinuxCNC
|
||||
|
||||
## Purpose
|
||||
|
||||
Advance the simulator by aligning browser/WASM behavior with LinuxCNC source. The project is not a from-scratch compatible interpreter. It is a source-backed LinuxCNC port, trim, wrapper, or platform adaptation.
|
||||
|
||||
## Why Progress Has Been Slow
|
||||
|
||||
The remaining work is concentrated in hard browser-hostile LinuxCNC dependencies:
|
||||
|
||||
- Python/remap and Boost.Python binding surfaces.
|
||||
- Native `tooldata_mmap.cc` storage and filesystem assumptions.
|
||||
- HAL/native filesystem/runtime services.
|
||||
- Large legacy smoke/fallback parser surface that must shrink instead of grow.
|
||||
- Heavy but necessary native/source-link/Node/browser OPFS validation.
|
||||
|
||||
Treat source-map and guardrail work as support, not primary progress.
|
||||
|
||||
## Hard Rules
|
||||
|
||||
- Locate LinuxCNC source before functional changes.
|
||||
- Do not invent CNC behavior.
|
||||
- Do not extend temporary smoke parser semantics.
|
||||
- Keep browser filesystem persistence OPFS-backed.
|
||||
- Only write source ports, wrappers, platform shims, thin API/event bridges, generated fixtures, tests, build scripts, and documentation.
|
||||
- Preserve user changes in dirty worktrees.
|
||||
|
||||
## Start Every Simulator Turn
|
||||
|
||||
```bash
|
||||
cd /home/cnc/桌面/cnc/wasm-simulator
|
||||
git status --short
|
||||
```
|
||||
|
||||
If editing project instructions:
|
||||
|
||||
```bash
|
||||
cd /home/cnc/桌面/cnc
|
||||
git status --short
|
||||
```
|
||||
|
||||
## Default High-Impact Lanes
|
||||
|
||||
Prefer these lanes in order unless the user asks otherwise:
|
||||
|
||||
1. Python/remap inert shim convergence
|
||||
- Compile or link more blocked LinuxCNC Python/Boost.Python/remap sources against inert wasm-safe shims.
|
||||
- Add probes that make remaining non-Python dependencies visible.
|
||||
- Keep Python execution disabled until source-backed browser execution exists.
|
||||
|
||||
2. tooldata mmap backend replacement
|
||||
- Replace native mmap/filesystem assumptions with wasm-safe source-backed storage boundaries.
|
||||
- Preserve LinuxCNC `tooldata_mmap.cc`, `tooldata_common.cc`, `tooldata_nml.cc`, and `tooldata_db.cc` semantics through probes.
|
||||
|
||||
3. smoke parser shrinkage
|
||||
- Move coverage from smoke/fallback parser into LinuxCNC `linuxcnc-rs274` source-linked paths.
|
||||
- Delete or bypass smoke branches when source-linked behavior covers them.
|
||||
|
||||
## Fast Loop
|
||||
|
||||
1. Pick one blocker-reducing or executable-coverage slice.
|
||||
2. Find the LinuxCNC source/config/remap with `rg`.
|
||||
3. Add/update a probe, source-linked test, fixture, manifest, or shim.
|
||||
4. Keep the change within one workstream.
|
||||
5. Run required checks.
|
||||
6. Commit in Chinese and push once.
|
||||
7. Report source basis, changed files, checks, push status, and remaining risk.
|
||||
|
||||
## Required Checks
|
||||
|
||||
For simulator code, fixtures, manifests, shims, probes, or build scripts:
|
||||
|
||||
```bash
|
||||
./test-native.sh
|
||||
./test-linuxcnc-source-link.sh
|
||||
```
|
||||
|
||||
For switchkins/remap table generation:
|
||||
|
||||
```bash
|
||||
./check-linuxcnc-switchkins-remap-table.sh linuxcnc-kinematics-source-files.txt
|
||||
```
|
||||
|
||||
For instruction-only documentation changes, `git diff --check` is sufficient; state that full simulator checks were not run.
|
||||
|
||||
## Anti-Stall Policy
|
||||
|
||||
- Do not spend consecutive iterations on docs/source-map-only changes unless the user explicitly requests instruction edits.
|
||||
- A source-map guard must protect a new source path, prove a blocker boundary, or unblock build/test flow.
|
||||
- If source discovery stalls, switch lanes instead of inventing behavior.
|
||||
- Prefer executable probes over prose.
|
||||
- Prefer blocker shrinkage over broader coverage when both are available.
|
||||
|
||||
## Commit And Sync
|
||||
|
||||
- Commit coherent slices after checks pass.
|
||||
- Push after successful commits.
|
||||
- If HTTP credentials are unavailable, report once and continue local work.
|
||||
- If credentials are available outside the repo, use temporary non-interactive askpass/helper and do not store secrets in tracked files.
|
||||
|
||||
## Source Pointers
|
||||
|
||||
- RS274: `../linuxcnc/src/emc/rs274ngc/`
|
||||
- Kinematics: `../linuxcnc/src/emc/kinematics/`
|
||||
- Tooldata: `../linuxcnc/src/emc/tooldata/`
|
||||
- Python plugin: `../linuxcnc/src/emc/pythonplugin/`
|
||||
- Canon: `../linuxcnc/src/emc/nml_intf/canon.hh`
|
||||
- Sim configs/remaps: `../linuxcnc/configs/sim/`
|
||||
|
||||
## Current Priority
|
||||
|
||||
Continue from about 72% completion by reducing the remaining hard blockers:
|
||||
|
||||
1. Python/remap inert shim convergence.
|
||||
2. tooldata mmap backend replacement.
|
||||
3. smoke parser shrinkage into LinuxCNC source-linked execution.
|
||||
Reference in New Issue
Block a user