meswork/cnc
6
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

按原因重写高效迭代规则

Browse Source 
结论：针对长期迭代仍未完成的问题，明确慢因集中在 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
2026-06-06 12:31:05 +08:00
parent 681d1976e9
commit a03f27d12c
2 changed files with 204 additions and 105 deletions
Download Patch File Download Diff File Expand all files Collapse all files

188
AGENTS.md
View File

@@ -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