From a03f27d12ce98b16e449fade7ffc1a3e7792e4b6 Mon Sep 17 00:00:00 2001 From: cnc Date: Sat, 6 Jun 2026 12:31:05 +0800 Subject: [PATCH] =?UTF-8?q?=E6=8C=89=E5=8E=9F=E5=9B=A0=E9=87=8D=E5=86=99?= =?UTF-8?q?=E9=AB=98=E6=95=88=E8=BF=AD=E4=BB=A3=E8=A7=84=E5=88=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 结论：针对长期迭代仍未完成的问题，明确慢因集中在 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。 --- AGENTS.md | 188 ++++++++++++++++++++++++------------------------------ SKILL.md | 121 +++++++++++++++++++++++++++++++++++ 2 files changed, 204 insertions(+), 105 deletions(-) create mode 100644 SKILL.md diff --git a/AGENTS.md b/AGENTS.md index ab72c4e..aad6cee 100644 --- a/AGENTS.md +++ b/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 diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..e5e1d1b --- /dev/null +++ b/SKILL.md @@ -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.