Laetoly 如何为预览解析 G-code：Worker 流程、模态运动与已知限制

G-code 解析并不是一个统一的操作。一个程序可能涉及文本识别、模态状态、坐标解释、几何构建以及控制器特有的行为。本文只描述当前 Laetoly 源码证据在三个入口处所能说明的内容：前端预览 Worker、Java 后端解析器，以及 Python 刀路命令。现有记录都是静态源码快照，它们既不能证明这几条路径共用同一条运行时流水线，也不能证明某个文件一定能正确加工。

前端预览从 Worker 开始

在 Web 前端中，G-code 预览组件不会在页面主线程上解析程序。它会启动一个专门用于解析的独立 Web Worker，把 Worker 发回的消息转交给组件处理，并包含一条错误路径：当 Worker 报告错误时，正在等待的解析请求会被拒绝，而不是一直悬而未决。这说明浏览器一侧存在一条边界：解析工作位于消息接口之后，负责绘制预览的页面只与它交换消息。

仅凭这次源码审阅，还无法说明一次解析请求的完整生命周期、每一种消息结构，或者最终显示的几何是否正确。这些都需要浏览器测试夹具和运行时检查。源码记录也指出，在声称渲染几何正确之前，仍需检查对 Worker 结果的处理。

Worker 初始化解析状态

在 Worker 内部，解析流程会先统计输入行数、选择校验模式、创建校验器，并建立解析状态。这个状态从默认的定位、单位和进给率设置开始，并分别为已解析的点和仍在拼接中的路径段准备好存放位置。这些细节描述的是该流程如何开始；它们并不能证明所有 G-code 方言、设置程序段或之后的状态变化都得到了处理。

校验器配置了坐标和激光功率限制。这些限制属于这个代码快照，而不是通用的机器行程、安全限制或产品规格。它们不应被照搬到机器设置指南中，也不应被表述为受支持的行程尺寸。这些证据是静态的，而且该仓库快照被标记为有未提交修改，因此在作为发布承诺公开之前，还需要对照版本进行复核。

区分文本解析与机器语义很重要。识别一个运动指令字或维护解析状态，只是判断控制器会做什么的一部分。预览可以把识别出的路径可视化，但这并不能证明目标机器接受文件中的每一条指令、每一个偏置或每一种模式。现有证据明确地把“识别出的指令字”与“完整的加工语义”区分开来。

后端解析器跟踪的模态状态更有限

Java 后端有自己的解析器。输入为空或只有空白时，不会生成任何指令。对于其他输入，解析器会保存一个单位模式和一个模态运动值，把程序拆分成行、去掉注释、把每一行拆成指令字，并检查其中的 G-code 数值。它把 G20 和 G21 分别当作英寸和毫米模式，并把 G0 或 G1 记为模态运动，用于之后只包含坐标的行。

遇到 G2、G3 或 G80 时，同一个解析器会清除记住的直线运动。源码中说明了原因：尚不支持圆弧插补，清除记住的运动可以避免把之后的圆弧坐标当作直线处理。这是一个很好的例子，说明解析器的限制被明确处理：一条指令可以被识别，而它完整的运动语义仍然不受支持。

在这个有限的例子里，“模态”指的是：当后续坐标程序段省略了运动指令字时，解析器会沿用之前的运动选择。这并不意味着每一种模态代码都已实现。源码明确列出了它会保留的 G0、G1 行为，以及会清除该状态的 G2、G3 和 G80 情况。技术说明应当把这个清单写清楚，而不是笼统地概括成“Laetoly 支持模态 G-code”，却不说明是哪些模式、哪个解析器。

单位状态是解析器中另一个独立的部分。它从毫米模式开始，看到 G20 或 G21 时才改变。单位影响数值如何被解释；它与记住的运动指令字不是同一个状态。阅读解析器时把这两部分状态分开，有助于避免把每一个 G-code 指令字都当作在修改解析器的同一部分。

这些代码证据能够支持的，是关于这个解析器如何把输入拆成指令字、如何决定模态运动的说明。它不能证明完全符合某个 G-code 标准、兼容所有控制器，或者机器能正确执行。Java 解析器与前端 Worker 是两条独立的证据记录，因此两处对相同指令字的处理看起来一致，并不足以证明两套实现的行为完全相同。

驱动程序提供刀路生成入口

用 Python 编写的本地驱动程序中，有一个命令的既定用途是把 SVG 输入转换为 G-code 刀路。它声明的输入包括刀具尺寸与类型、切削类型与深度、进给与下刀速率、主轴转速、安全高度、优化与简化选项、铣削方向，以及其他精加工或挖槽设置。换句话说，驱动程序接收一幅图形和加工选项，负责生成程序；而 Web 预览和后端解析器则是使用程序的一方。

这是关于一个接口及其声明输入的证据。审阅的源码并未展示完整的几何计算、所有分支、生成的 G-code，也没有与实际切削结果进行比较。因此，它可以支持一篇讲解命令边界的源码导读，但不能支持“某组特定参数会生成安全或精确刀路”这样的说法。

讲解时把三条路径分开

证据包涵盖前端 Worker、后端解析器和驱动程序的刀路命令。它们代表不同的源码入口。除非运行时追踪能够证明某个产品流程是如何把它们连接起来的，否则图表或文章都应把它们标注为分别检查的路径。如果画一条从 Python 刀路生成器指向浏览器 Worker 的简单箭头，就会暗示当前快照并未证明的调用关系。

这条边界对工程师很有用，因为它指明了下一步该调查什么。要建立端到端的契约，需要记录实际的界面请求、Worker 的输入和输出、任何后端解析请求，以及驱动程序生成的产物。然后用同一个示例程序在这几层之间进行比较，并记录所用的源码版本。在完成这些工作之前，结论应当与支持它的那部分源码绑定。

更强的运行时证据能补充什么

浏览器测试夹具可以把一个已知的小型 G-code 文件送入前端预览组件，并记录 Worker 的请求、响应、错误以及生成的几何。这样可以针对特定的浏览器构建和输入，测试从界面到预览的路径。但它并不会自动证明后端 Java 解析器或 Python 驱动程序使用相同的规则。

后端需要自己的解析器测试夹具。用例应当包括：设置运动指令字的一行、紧随其后只含坐标的一行、一次单位切换，以及一个不受支持的圆弧后面再跟一个坐标程序段。预期结果应当对照当前的解析器源码，以及项目打算支持的公开行为来检查。一个夹具的结果只是关于这些用例的证据，并不构成符合标准的声明。

驱动程序需要单独的 SVG 输入和生成结果检查。记录所选的刀具和工序设置，检查生成的文件，并与受控的预期形状进行比较。实际切削则是更进一步的验证步骤，需要特定的机器、材料、刀具和装夹。目前对该命令入口的审阅不包含这样的测试结果，因此本文对切削质量不作任何声明。

执行这些检查时，应把输入、输出、源码版本和测试条件一起保存。如果某个源码文件发生变化，在把文章中的描述视为最新之前，应对照新版本重新审阅。证据包已经为每条选定记录保存了仓库版本、未提交修改状态、文件指纹和源码位置；这些字段有助于准确定位某个说法所描述的是哪一个快照。

阅读解析器证据的稳妥方法

审阅解析器时，请把以下五个问题分开：

1. 识别： 解析器会检查哪些指令字或指令族？
2. 状态： 它会保留哪些单位、模式或模态运动值？
3. 几何： 实际会生成哪些点或路径段，在什么条件下生成？
4. 校验： 哪些检查会拒绝或限制输入？这些边界是产品默认值还是针对特定机器的数值？
5. 执行： 同一个文件是否已在目标控制器和机器设置上验证过？

这里描述的记录回答了前两个问题的一部分，并展示了一些接口。它们并没有解决几何和执行这两个问题。前端证据要求在声称渲染几何正确之前先进行浏览器夹具测试；后端源码记录了一个不支持圆弧插补的情况；驱动程序的证据只覆盖了该命令的入口。

本文不声明什么

这篇源码导读不声明解析器的性能、对标准的符合程度、完整的圆弧支持、机器兼容性、控制器安全性或经过验证的加工结果。它不把受支持的指令清单当作完整语义的证明，也不会把一个有未提交修改的源码快照当成对每个发布版本的承诺。

这些限制本身就是技术结论的一部分。一篇严谨的解析器文章应当说明现有源码能证明什么、证据在哪里停止，并在用受控夹具测试之前，保持运行时行为的开放性。对 CNC 软件来说，这种区分能帮助读者理解软件是如何组织的，而不会把一次静态源码审阅误认为一次机器测试。