每轮只推进合理适量的上下文、禁止顺手扩功能 smoke：同步第6组指针
This commit is contained in:
cnc
@@ -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.
|
||||||
|
---
|
||||||
|
|
||||||
## 触发条件
|
# Align LinuxCNC
|
||||||
目标：对标 LinuxCNC，分阶段完善 Web 版数控系统仿真的 WASM 程序，逐步补齐完整功能并严格测试。
|
|
||||||
|
|
||||||
近期重点：
|
## Mission
|
||||||
- 刀补
|
|
||||||
- 坐标系
|
|
||||||
- 固定循环
|
|
||||||
- 五轴 / RTCP
|
|
||||||
- M428、M429、M430
|
|
||||||
- 子程序调用
|
|
||||||
|
|
||||||
实现约束：若 WASM 编译后涉及文件读写，可考虑使用 OPFS 满足文件处理需求。
|
Advance the simulator only by aligning it with LinuxCNC source behavior. The
|
||||||
继续进一步完善程序，步步为营。G代码语法，与linuxcnc一致。程序主要来源于linuxcnc项目中的源程序。功能和G代码与linuxcnc对标。
|
project goal is a LinuxCNC-source-backed Web/WASM CNC simulator, not a
|
||||||
|
from-scratch compatible interpreter.
|
||||||
|
|
||||||
## 标准作业程序（S.O.P.）
|
## Hard Constraints
|
||||||
严格遵循以下“分析-计划-实现-验证”循环，每一步都要遵循“最小变更原则”。
|
|
||||||
|
|
||||||
### 阶段 1：差异分析与目标选择
|
- Port-first: prefer direct LinuxCNC source porting, trimming, wrapping, or
|
||||||
1. **扫描当前代码**：使用 `grep` 或代码导航工具，在 `src/` 目录下寻找已实现的 G/M 代码处理逻辑。
|
platform adaptation over project-authored replacements.
|
||||||
2. **对比 LinuxCNC 源码**：查阅 LinuxCNC 官方仓库中对应的源码文件（如 `src/emc/rs274ngc/rs274ngc_return.hh` 和 `interp_execute.cc` 等）。
|
- Do not write independent functional CNC behavior.
|
||||||
3. **找出一个差异点**：从以下角度寻找**一个**最微小的差异：
|
- Do not use intuition or documentation as the final behavioral source.
|
||||||
- **数值解析**：如科学计数法、前导零、特殊字符处理。
|
- Before any functional change, locate LinuxCNC source in `../linuxcnc/src` or
|
||||||
- **参数范围与处理**：字参数（如 F、S、P 的值域）和表达式参数。
|
`../linuxcnc/configs`.
|
||||||
- **错误检查**：缺少某个 LinuxCNC 已实现但本项目尚未实现的 `CHK` 或 `CHKS` 校验逻辑。
|
- Allowed code: LinuxCNC source port/wrap/trim/adaptation, platform shims,
|
||||||
- **模态状态**：某个 G 代码组内部的状态切换不完全一致。
|
thin wasm/API/event bridges, generated fixtures, tests, build scripts, docs.
|
||||||
4. **以书面形式明确目标**：在回复的开始，用一句话清晰说明本次要修复的具体差异点。例如：“**目标：对齐科学计数法解析行为。LinuxCNC 不允许 `1e3`，本项目当前会将其解析为 `1000`，需修复为解析失败。**”
|
- Temporary smoke paths may be tested, but should shrink over time.
|
||||||
|
- Browser-side WASM filesystem access must use OPFS-backed storage.
|
||||||
|
|
||||||
### 阶段 2：编写测试（先写测试）
|
## Work Directory
|
||||||
1. **创建失败的测试**：在 `tests/` 或相应目录下，先编写一个能够清晰验证此行为的、**预期会失败**的测试用例。
|
|
||||||
2. **运行测试以确认失败**：执行 `./test-native.sh`，确保因为新测试而导致整体测试失败，这验证了测试的有效性。
|
|
||||||
|
|
||||||
### 阶段 3：实施代码修改（小步快跑）
|
```bash
|
||||||
1. **定位源码**：找到项目中对应该行为的实现位置。
|
cd /home/cnc/桌面/cnc/wasm-simulator
|
||||||
2. **参考 LinuxCNC 源码实现**：严格模仿 LinuxCNC 源码中的数据结构、算法和函数调用方式来进行修改。
|
git status --short
|
||||||
3. **最小化修改**：只改动实现该功能的**最小必要代码行**。严禁“顺便”重构无关代码。
|
```
|
||||||
4. **保留接口一致性**：确保修改后的函数签名、返回值和副作用与 LinuxCNC 源码中的对应实现完全一致。
|
|
||||||
|
|
||||||
### 阶段 4：验证与循环
|
Related roots:
|
||||||
1. **运行本地测试**：执行 `./test-native.sh`。如果失败，分析错误并修复，直到通过。
|
|
||||||
2. **运行完整回归测试**：执行 `./test-linuxcnc-source-link.sh`。如果失败，修复到通过为止。
|
- Project root: `/home/cnc/桌面/cnc`
|
||||||
3. **记录与完成**：在回复中简要报告：“差异点 `[目标]` 已修复，测试全部通过。准备进行下一轮分析。”
|
- LinuxCNC source: `/home/cnc/桌面/cnc/linuxcnc` or `$LINUXCNC_ROOT`
|
||||||
4. **无条件循环**：报告完成后，**必须立即、自动地**将思维跳转回**阶段 1**，并开始寻找下一个差异点。**严禁在报告完成后停止，除非已达到 AGENTS.md 中定义的中断条件。**
|
- 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.
|
||||||
|
|||||||
160
AGENTS.md
160
AGENTS.md
@@ -1,40 +1,130 @@
|
|||||||
# 项目核心目标与执行纲领
|
# CNC Project Agent Guide
|
||||||
|
工作树已经有一批未提交修改，太大了。我把这批改动按 6 个上下文拆更合适
|
||||||
|
switchkins/remap 生成器和表
|
||||||
|
linuxcnc-kinematics 源清单
|
||||||
|
WASM 文件系统和 OPFS 持久化
|
||||||
|
浏览器端应用接入
|
||||||
|
Node / browser 烟测
|
||||||
|
源码链接、构建和文档约束
|
||||||
|
## Mission
|
||||||
|
|
||||||
## 1. 唯一使命
|
Build a browser/WebAssembly CNC simulator whose G-code behavior is aligned
|
||||||
本项目（位于 `CNC/` 目录）的唯一目标是**创建一个与 LinuxCNC 完全对标的 G 代码解释器**。
|
with LinuxCNC source. This is not an independent compatible interpreter; it is
|
||||||
所有代码修改、测试、文档工作，都必须围绕“对齐 LinuxCNC 官方源码的行为”这一最高准则展开。
|
a port, trim, wrapper, or platform adaptation of LinuxCNC behavior.
|
||||||
|
|
||||||
## 2. 自动连续工作流（步步为营）
|
## Work Roots
|
||||||
- **主动循环**：在完成一个语法功能的修复/新增并成功通过所有测试后，**严禁等待**。必须立即、主动地执行以下循环：
|
|
||||||
1. 扫描项目，找出下一个与 LinuxCNC 源码有差异或尚未实现的功能点。
|
|
||||||
2. 开始新一轮的“分析-计划-实现-验证”循环。
|
|
||||||
- **小步快跑**：每次循环只聚焦于**一个**极小的语法差异点或功能点。例如：
|
|
||||||
- 修复一个 G 代码的参数解析行为。
|
|
||||||
- 添加一个缺失的错误检查逻辑。
|
|
||||||
- 调整一个 M 代码的副作用。
|
|
||||||
- **中断条件**：只有在以下情况才停止自动循环，并向用户报告：
|
|
||||||
- 遇到一个无法自行解决的编译错误或逻辑矛盾（需附上详细分析）。
|
|
||||||
- 扫描后发现项目行为已与 LinuxCNC 源码在所有已知功能上**完全一致**。
|
|
||||||
- 用户明确发出“停止”指令。
|
|
||||||
|
|
||||||
## 3. 代码行为准则
|
- Project root: `/home/cnc/桌面/cnc`
|
||||||
- **源码唯一真源**：当对 G/M 代码的行为有任何疑问时，以 LinuxCNC 项目（尤其是 `src/emc/rs274ngc/` 目录）中的 C 源码实现为最终唯一标准，而非文档描述或直觉。
|
- Simulator root: `/home/cnc/桌面/cnc/wasm-simulator`
|
||||||
- **严格对标**：行为必须与 LinuxCNC 一致，包括但不限于：
|
- LinuxCNC source: `/home/cnc/桌面/cnc/linuxcnc` or `$LINUXCNC_ROOT`
|
||||||
- 错误号（`Interp::error` 的数字）
|
- LinuxCNC unit tests: `/home/cnc/桌面/cnc/linuxcnc/unit_tests`
|
||||||
- 错误发生时的程序状态（是否继续解析、是否写入输出文件）
|
|
||||||
- 数值解析规则（如：不允许科学计数法，禁止前导零过多等）。
|
|
||||||
- 模态状态变化规则。
|
|
||||||
|
|
||||||
## 4. 测试铁律
|
Start every change with:
|
||||||
- **修改必有测试**：任何代码修改，都必须伴随至少一个用于验证该行为的自动化测试用例。
|
|
||||||
- **本地测试优先**：实现前，应优先编写一个能展示差异的、会失败的测试用例，然后再修改代码使其通过。
|
|
||||||
- **测试命令**：修改完成后，必须运行以下命令来验证：
|
|
||||||
- `./test-native.sh` （本地快速测试套件）
|
|
||||||
- `./test-linuxcnc-source-link.sh` （针对直接链接 LinuxCNC 后端的完整测试）
|
|
||||||
|
|
||||||
## 5. 环境与项目结构
|
```bash
|
||||||
- **主工作目录**：所有命令和执行都基于 `CNC/` 根目录。
|
cd /home/cnc/桌面/cnc/wasm-simulator
|
||||||
- **关键目录**：
|
git status --short
|
||||||
- `src/emc/rs274ngc/`：LinuxCNC 解释器核心源码所在，是对标的根本依据。
|
```
|
||||||
- `smoke_tests/` 或 `tests/`：存放对标测试用例的目录。
|
|
||||||
- `.agents/skills/`：存放自动化技能文件。
|
## 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.
|
||||||
|
|||||||
Submodule wasm-simulator updated: 1498d9830d...5ec10abf38
Reference in New Issue
Block a user