每轮只推进合理适量的上下文、禁止顺手扩功能 smoke：同步第6组指针
This commit is contained in:
cnc
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. 唯一使命
|
||||
本项目（位于 `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/`：存放自动化技能文件。
|
||||
```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.
|
||||
|
||||
Reference in New Issue
Block a user