diff --git a/.agents/skills/align-linuxcnc/SKILL.md b/.agents/skills/align-linuxcnc/SKILL.md index b0e9d04..89041af 100644 --- a/.agents/skills/align-linuxcnc/SKILL.md +++ b/.agents/skills/align-linuxcnc/SKILL.md @@ -1,44 +1,92 @@ -# 技能：对齐 LinuxCNC G 代码 (align-linuxcnc) +--- +name: align-linuxcnc +description: Use this skill for this CNC Web/WASM simulator whenever evaluating progress or changing LinuxCNC G-code behavior, RS274 source integration, kinematics, M428/M429/M430 remaps, tool data, modal state, parameters, tests, fixtures, build scripts, or bridge code. +--- -## 触发条件 -目标：对标 LinuxCNC，分阶段完善 Web 版数控系统仿真的 WASM 程序，逐步补齐完整功能并严格测试。 +# Align LinuxCNC -近期重点： -- 刀补 -- 坐标系 -- 固定循环 -- 五轴 / RTCP -- M428、M429、M430 -- 子程序调用 +## Mission -实现约束：若 WASM 编译后涉及文件读写，可考虑使用 OPFS 满足文件处理需求。 -继续进一步完善程序，步步为营。G代码语法，与linuxcnc一致。程序主要来源于linuxcnc项目中的源程序。功能和G代码与linuxcnc对标。 +Advance the simulator only by aligning it with LinuxCNC source behavior. The +project goal is a LinuxCNC-source-backed Web/WASM CNC simulator, not a +from-scratch compatible interpreter. -## 标准作业程序（S.O.P.） -严格遵循以下“分析-计划-实现-验证”循环，每一步都要遵循“最小变更原则”。 +## Hard Constraints -### 阶段 1：差异分析与目标选择 -1. **扫描当前代码**：使用 `grep` 或代码导航工具，在 `src/` 目录下寻找已实现的 G/M 代码处理逻辑。 -2. **对比 LinuxCNC 源码**：查阅 LinuxCNC 官方仓库中对应的源码文件（如 `src/emc/rs274ngc/rs274ngc_return.hh` 和 `interp_execute.cc` 等）。 -3. **找出一个差异点**：从以下角度寻找**一个**最微小的差异： - - **数值解析**：如科学计数法、前导零、特殊字符处理。 - - **参数范围与处理**：字参数（如 F、S、P 的值域）和表达式参数。 - - **错误检查**：缺少某个 LinuxCNC 已实现但本项目尚未实现的 `CHK` 或 `CHKS` 校验逻辑。 - - **模态状态**：某个 G 代码组内部的状态切换不完全一致。 -4. **以书面形式明确目标**：在回复的开始，用一句话清晰说明本次要修复的具体差异点。例如：“**目标：对齐科学计数法解析行为。LinuxCNC 不允许 `1e3`，本项目当前会将其解析为 `1000`，需修复为解析失败。**” +- Port-first: prefer direct LinuxCNC source porting, trimming, wrapping, or + platform adaptation over project-authored replacements. +- Do not write independent functional CNC behavior. +- Do not use intuition or documentation as the final behavioral source. +- Before any functional change, locate LinuxCNC source in `../linuxcnc/src` or + `../linuxcnc/configs`. +- Allowed code: LinuxCNC source port/wrap/trim/adaptation, platform shims, + thin wasm/API/event bridges, generated fixtures, tests, build scripts, docs. +- Temporary smoke paths may be tested, but should shrink over time. +- Browser-side WASM filesystem access must use OPFS-backed storage. -### 阶段 2：编写测试（先写测试） -1. **创建失败的测试**：在 `tests/` 或相应目录下，先编写一个能够清晰验证此行为的、**预期会失败**的测试用例。 -2. **运行测试以确认失败**：执行 `./test-native.sh`，确保因为新测试而导致整体测试失败，这验证了测试的有效性。 +## Work Directory -### 阶段 3：实施代码修改（小步快跑） -1. **定位源码**：找到项目中对应该行为的实现位置。 -2. **参考 LinuxCNC 源码实现**：严格模仿 LinuxCNC 源码中的数据结构、算法和函数调用方式来进行修改。 -3. **最小化修改**：只改动实现该功能的**最小必要代码行**。严禁“顺便”重构无关代码。 -4. **保留接口一致性**：确保修改后的函数签名、返回值和副作用与 LinuxCNC 源码中的对应实现完全一致。 +```bash +cd /home/cnc/桌面/cnc/wasm-simulator +git status --short +``` -### 阶段 4：验证与循环 -1. **运行本地测试**：执行 `./test-native.sh`。如果失败，分析错误并修复，直到通过。 -2. **运行完整回归测试**：执行 `./test-linuxcnc-source-link.sh`。如果失败，修复到通过为止。 -3. **记录与完成**：在回复中简要报告：“差异点 `[目标]` 已修复，测试全部通过。准备进行下一轮分析。” -4. **无条件循环**：报告完成后，**必须立即、自动地**将思维跳转回**阶段 1**，并开始寻找下一个差异点。**严禁在报告完成后停止，除非已达到 AGENTS.md 中定义的中断条件。** \ No newline at end of file +Related roots: + +- Project root: `/home/cnc/桌面/cnc` +- LinuxCNC source: `/home/cnc/桌面/cnc/linuxcnc` or `$LINUXCNC_ROOT` +- LinuxCNC unit tests: `/home/cnc/桌面/cnc/linuxcnc/unit_tests` + +## Required Checks + +For code or generated fixture changes, run: + +```bash +./test-native.sh +./test-linuxcnc-source-link.sh +``` + +For switchkins/remap table changes, also run: + +```bash +./check-linuxcnc-switchkins-remap-table.sh linuxcnc-kinematics-source-files.txt +``` + +## Fast Loop + +1. Pick one tiny gap. +2. Find the LinuxCNC source/config/remap. +3. Add or update a source-backed test/fixture. +4. Implement only bridge/shim/wrapper/generator changes. +5. Run required tests. +6. Report percent complete, source basis, changed files, and tests. + +## Source Pointers + +- RS274: `../linuxcnc/src/emc/rs274ngc/` +- Kinematics: `../linuxcnc/src/emc/kinematics/` +- Tooldata: `../linuxcnc/src/emc/tooldata/` +- Canon: `../linuxcnc/src/emc/nml_intf/canon.hh` +- Sim remaps/configs: `../linuxcnc/configs/sim/` + +Useful project docs: + +- `docs/linuxcnc-source-policy.md` +- `docs/linuxcnc-porting.md` +- `docs/linuxcnc-rs274-source-map.md` +- `linuxcnc-rs274-source-files.txt` +- `linuxcnc-rs274-wasm-source-files.txt` +- `linuxcnc-kinematics-source-files.txt` + +## Current Baseline + +Completion estimate: about 72%. + +Strong areas: source manifests, native/source-linked RS274 runners, broad +G-code regression corpus, generated M428/M429/M430 switchkins remap fixtures, +Node/browser WASM smoke coverage. + +Main remaining risks: smoke parser removal, Python/Boost.Python remap +replacement, dynamic loading shims, tooldata/HAL/filesystem assumptions, +continued source-backed expansion of kinematics/RTCP coverage, and real browser +verification that WASM file reads/writes persist through OPFS. diff --git a/AGENTS.md b/AGENTS.md index 99240d8..d57ce50 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,40 +1,130 @@ -# 项目核心目标与执行纲领 +# CNC Project Agent Guide +工作树已经有一批未提交修改，太大了。我把这批改动按 6 个上下文拆更合适 +switchkins/remap 生成器和表 +linuxcnc-kinematics 源清单 +WASM 文件系统和 OPFS 持久化 +浏览器端应用接入 +Node / browser 烟测 +源码链接、构建和文档约束 +## Mission -## 1. 唯一使命 -本项目（位于 `CNC/` 目录）的唯一目标是**创建一个与 LinuxCNC 完全对标的 G 代码解释器**。 -所有代码修改、测试、文档工作，都必须围绕“对齐 LinuxCNC 官方源码的行为”这一最高准则展开。 +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. -## 2. 自动连续工作流（步步为营） -- **主动循环**：在完成一个语法功能的修复/新增并成功通过所有测试后，**严禁等待**。必须立即、主动地执行以下循环： - 1. 扫描项目，找出下一个与 LinuxCNC 源码有差异或尚未实现的功能点。 - 2. 开始新一轮的“分析-计划-实现-验证”循环。 -- **小步快跑**：每次循环只聚焦于**一个**极小的语法差异点或功能点。例如： - - 修复一个 G 代码的参数解析行为。 - - 添加一个缺失的错误检查逻辑。 - - 调整一个 M 代码的副作用。 -- **中断条件**：只有在以下情况才停止自动循环，并向用户报告： - - 遇到一个无法自行解决的编译错误或逻辑矛盾（需附上详细分析）。 - - 扫描后发现项目行为已与 LinuxCNC 源码在所有已知功能上**完全一致**。 - - 用户明确发出“停止”指令。 +## Work Roots -## 3. 代码行为准则 -- **源码唯一真源**：当对 G/M 代码的行为有任何疑问时，以 LinuxCNC 项目（尤其是 `src/emc/rs274ngc/` 目录）中的 C 源码实现为最终唯一标准，而非文档描述或直觉。 -- **严格对标**：行为必须与 LinuxCNC 一致，包括但不限于： - - 错误号（`Interp::error` 的数字） - - 错误发生时的程序状态（是否继续解析、是否写入输出文件） - - 数值解析规则（如：不允许科学计数法，禁止前导零过多等）。 - - 模态状态变化规则。 +- Project root: `/home/cnc/桌面/cnc` +- Simulator root: `/home/cnc/桌面/cnc/wasm-simulator` +- LinuxCNC source: `/home/cnc/桌面/cnc/linuxcnc` or `$LINUXCNC_ROOT` +- LinuxCNC unit tests: `/home/cnc/桌面/cnc/linuxcnc/unit_tests` -## 4. 测试铁律 -- **修改必有测试**：任何代码修改，都必须伴随至少一个用于验证该行为的自动化测试用例。 -- **本地测试优先**：实现前，应优先编写一个能展示差异的、会失败的测试用例，然后再修改代码使其通过。 -- **测试命令**：修改完成后，必须运行以下命令来验证： - - `./test-native.sh` （本地快速测试套件） - - `./test-linuxcnc-source-link.sh` （针对直接链接 LinuxCNC 后端的完整测试） +Start every change with: -## 5. 环境与项目结构 -- **主工作目录**：所有命令和执行都基于 `CNC/` 根目录。 -- **关键目录**： - - `src/emc/rs274ngc/`：LinuxCNC 解释器核心源码所在，是对标的根本依据。 - - `smoke_tests/` 或 `tests/`：存放对标测试用例的目录。 - - `.agents/skills/`：存放自动化技能文件。 \ No newline at end of file +```bash +cd /home/cnc/桌面/cnc/wasm-simulator +git status --short +``` + +## Non-Negotiable Rules + +- 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. + +## Source-First Workflow + +1. Pick one small missing source-backed bridge point or behavior gap. +2. Locate the LinuxCNC source/config/remap first. Prefer: + + ```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. +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. + +## Required Checks + +For code, generated fixture, or source-manifest changes: + +```bash +./test-native.sh +./test-linuxcnc-source-link.sh +``` + +For generated switchkins/remap table changes, also run: + +```bash +./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. + +## Current Completion Baseline + +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`. +- 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. + +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. + +## Stop Conditions + +Stop and report if: + +- LinuxCNC source behavior cannot be located. +- A compile/link error cannot be resolved without inventing behavior. +- Tests expose a contradiction between project bridge code and LinuxCNC source. +- The user explicitly asks to stop. diff --git a/wasm-simulator b/wasm-simulator index 1498d98..5ec10ab 160000 --- a/wasm-simulator +++ b/wasm-simulator @@ -1 +1 @@ -Subproject commit 1498d9830d7b34205e28312c509dd596738750e6 +Subproject commit 5ec10abf38f963fdc4b8b06a0dd9149c0cdf910b