cnc/AGENTS.md

项目核心目标与执行纲领

1. 唯一使命

本项目（位于 CNC/ 目录）的唯一目标是创建一个与 LinuxCNC 完全对标的 G 代码解释器。 所有代码修改、测试、文档工作，都必须围绕“对齐 LinuxCNC 官方源码的行为”这一最高准则展开。

2. 自动连续工作流（步步为营）

• 主动循环：在完成一个语法功能的修复/新增并成功通过所有测试后，严禁等待。必须立即、主动地执行以下循环：
  1. 扫描项目，找出下一个与 LinuxCNC 源码有差异或尚未实现的功能点。
  2. 开始新一轮的“分析-计划-实现-验证”循环。
• 小步快跑：每次循环只聚焦于一个极小的语法差异点或功能点。例如：
  • 修复一个 G 代码的参数解析行为。
  • 添加一个缺失的错误检查逻辑。
  • 调整一个 M 代码的副作用。
• 中断条件：只有在以下情况才停止自动循环，并向用户报告：
  • 遇到一个无法自行解决的编译错误或逻辑矛盾（需附上详细分析）。
  • 扫描后发现项目行为已与 LinuxCNC 源码在所有已知功能上完全一致。
  • 用户明确发出“停止”指令。

3. 代码行为准则

• 源码唯一真源：当对 G/M 代码的行为有任何疑问时，以 LinuxCNC 项目（尤其是 src/emc/rs274ngc/ 目录）中的 C 源码实现为最终唯一标准，而非文档描述或直觉。
• 严格对标：行为必须与 LinuxCNC 一致，包括但不限于：
  • 错误号（Interp::error 的数字）
  • 错误发生时的程序状态（是否继续解析、是否写入输出文件）
  • 数值解析规则（如：不允许科学计数法，禁止前导零过多等）。
  • 模态状态变化规则。

4. 测试铁律

• 修改必有测试：任何代码修改，都必须伴随至少一个用于验证该行为的自动化测试用例。
• 本地测试优先：实现前，应优先编写一个能展示差异的、会失败的测试用例，然后再修改代码使其通过。
• 测试命令：修改完成后，必须运行以下命令来验证：
  • ./test-native.sh （本地快速测试套件）
  • ./test-linuxcnc-source-link.sh （针对直接链接 LinuxCNC 后端的完整测试）

5. 环境与项目结构

• 主工作目录：所有命令和执行都基于 CNC/ 根目录。
• 关键目录：
  • src/emc/rs274ngc/：LinuxCNC 解释器核心源码所在，是对标的根本依据。
  • smoke_tests/ 或 tests/：存放对标测试用例的目录。
  • .agents/skills/：存放自动化技能文件。