G-code F 进给速度驱动 RUN 执行修复文档
生成时间：2026-06-22
1. 问题结论
当前 RUN 链路已经能完成：
1. 打开 LinuxCNC G-code 程序。
2. 通过 task/HAL runtime 推进状态。
3. 更新当前行、高亮行、DRO、axisPose、执行轨迹和 task/HAL feedback。
但当前 RUN 还没有按 G-code 的真实进给速度执行。
当前关键问题：
G-code interpreter 能解析 F。
execution-timing.js 能基于 F / 距离 / INI 限速做 feed-based timing estimate。
但是 task/HAL RUN 执行链路没有把 F 用作真实运行速度。
C++ wrapper 层固定写入 velocity=60。
activeLine 按 task cycle 推进一行，而不是按 段距离 / F / elapsed time 推进。
因此现有浏览器 RUN 证据只能证明：
task/HAL feedback 正在产生；
UI 当前行与 task/HAL active line 同步；
DRO 与 runtime axisPose 同步；
执行轨迹可见；
不能证明：
程序按 G-code F 进给速度、G93/G94 模态、rapid/feed 区分、override、段距离真实定时执行。
2. 当前源码证据
2.1 固定 velocity=60
文件：
wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_task_hal_wasm.cpp
函数：
enqueue_linear_move_from_line(TaskRuntime &state, const std::string &line)
当前逻辑：
command << ",\"velocity\":60}";
影响：
1. 每条 G-code 运动行传给 motion runtime 的速度都是 60 units/s。
2. JS 状态层把 currentVel * 60 转成 mm/min。
3. 在 mm 单位下 UI 看到的速度固定为 3600 mm/min。
4. G-code 行中的 F159 / F318 / F636 等不会影响 RUN 实际速度。
2.2 按 task cycle 推进一行
文件：
wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_task_hal_wasm.cpp
函数：
lctask_run_cycles(long task_period_ns, long servo_period_ns, int task_cycles)
当前逻辑：
for (int i = 0; i < task_cycles; ++i) {
state.task_cycle += 1;
if (state.interp_state == "READING" && state.next_program_line < state.opened_line_count) {
enqueue_linear_move_from_line(state, state.program_lines[state.next_program_line]);
...
}
lcmot_step_servo(...);
}
影响：
1. 每个 task cycle 至多 enqueue 一条程序行。
2. active line 由 cycle 数推进。
3. 长段、短段、F 快、F 慢不会改变行推进节奏。
4. 这不是真实 LinuxCNC planner/task/motion 的时间语义。
2.3 interpreter 已有 F 信息
文件：
web-rtcp-5axis-sim-plan/app/src/runtime/linuxcnc-interpreter-runtime.js
已有能力：
1. feedRatesBySourceLine(programText) 从 G-code 中提取 F。
2. parseLinuxCncCanonicalMotion(...) 把 activeFeedRate 写入 motion event 的 feedRate。
3. linearUnitsBySourceLine(...) 跟踪 G20/G21。
输出 motion event 已包含：
{
type,
line,
axes,
feedRate,
linearUnits,
...
}
2.4 timing estimate 已有 F 计算
文件：
web-rtcp-5axis-sim-plan/app/src/runtime/execution-timing.js
已有能力：
1. 按 motion event feedRate 计算 requestedLinearVelocity。
2. 按 profile/INI max velocity 限速。
3. 按 linear distance / angular distance 计算 segment durationSeconds。
4. 处理 feedOverride / rapidOverride。
但当前边界是：
semanticBoundary = linuxcnc_canonical_motion_timing_estimate_not_planner_queue
说明它是估算，不是 task/HAL RUN 的权威执行节奏。
3. 修复目标
3.1 必须达成
修复后 RUN 必须满足：
1. G-code 中 F 值进入 task/HAL RUN 执行链路。
2. G94 units/min 模式下，feed move 的速度来自当前 modal F。
3. G0/STRAIGHT_TRAVERSE 使用 rapid velocity / rapid override / INI max velocity。
4. activeLine 按 elapsed execution time 与当前段完成度推进。
5. 长距离低 F 段明显运行更久。
6. 短距离高 F 段明显更快完成。
7. UI currentVelocity 不再固定 3600 mm/min。
8. DRO/axisPose 可以在段内插值，而不是只在行边界跳变。
9. 现有 RUN gate、task/HAL session、status loop、STOP/ABORT/STEP 不回退。
3.2 第一阶段不强求
以下可以作为第二阶段：
1. 完整 LinuxCNC trajectory planner queue 动力学一致性。
2. 加速度/jerk/圆弧真实插补完全对齐 LinuxCNC。
3. G93 inverse-time feed 的完整五轴角度/线性混合真实语义。
4. 硬件 realtime HAL 驱动。
但第一阶段至少不能继续固定 velocity=60。
4. 推荐实现方案
4.1 不要继续在 C++ wrapper 中逐行粗解析 G-code
当前 C++ wrapper 的 enqueue_linear_move_from_line() 是字符串扫描：
查找 XYZABC 字母；
strtod 读取数值；
没有模态；
没有 F；
没有 G90/G91；
没有 G20/G21；
没有 G93/G94；
没有 G0/G1/G2/G3 区分；
这个方向继续扩展会很脆弱。
推荐改为：
JS interpreter runtime 继续负责生成 canonical motion events。
JS 侧把 canonical motion + timing segments 传入 task/HAL runtime session。
C++ task/HAL wrapper 不再直接解析 G-code 行来生成 velocity。
C++ task/HAL wrapper 按已解析 motion segment 执行。
4.2 新增 task/HAL program motion plan
在 wasm-port/runtime/sdk/src/linuxcnc-task-hal.js 增加可选 API：
loadProgramMotionPlan({
programPath,
motion,
timing,
linearUnits,
})
在 C++ wrapper 增加导出：
int lctask_load_program_motion_plan_json(const char *plan_json);
motion plan 中至少包含：
{
"programPath": "...",
"segments": [
{
"line": 8,
"type": "STRAIGHT_FEED",
"motionClass": "feed",
"axes": { "x": 6.302, "y": -11.560, "z": 27.743, "a": -71.841, "c": -35.930 },
"startAxes": { "...": 0 },
"feedRate": 318,
"linearUnits": "mm",
"velocityMmPerMin": 318,
"durationSeconds": 0.42,
"startSeconds": 1.25,
"elapsedSeconds": 1.67
}
]
}
4.3 C++ task runtime 状态新增字段
TaskRuntime 增加：
struct MotionSegment {
int line = 0;
std::string type;
std::string motion_class;
double start_seconds = 0.0;
double duration_seconds = 0.0;
double velocity_mm_per_min = 0.0;
std::map<std::string, double> start_axes;
std::map<std::string, double> end_axes;
};
std::vector<MotionSegment> motion_plan;
int active_segment_index = 0;
double run_elapsed_seconds = 0.0;
double run_start_seconds = 0.0;
4.4 RUN 周期推进改为按 elapsed time
当前：
每 task cycle enqueue 一行。
修复后：
每次 lctask_run_cycles 根据 task_period_ns * task_cycles 增加 run_elapsed_seconds。
根据 run_elapsed_seconds 找到 active segment。
按 segment progress 插值 axisPose。
把 currentVel/requestedVel 设置为 segment.velocityMmPerMin / 60。
activeLine = segment.line。
segment 完成后才进入下一 segment。
伪代码：
int lctask_run_cycles(long task_period_ns, long servo_period_ns, int task_cycles)
{
const double delta_seconds = (task_period_ns / 1e9) * task_cycles;
state.run_elapsed_seconds += delta_seconds;
const MotionSegment *segment = find_segment_at_time(state.motion_plan, state.run_elapsed_seconds);
if (!segment) {
state.interp_state = "IDLE";
state.exec_state = "DONE";
return step_servo(...);
}
const double local = state.run_elapsed_seconds - segment->start_seconds;
const double progress = clamp(local / segment->duration_seconds, 0.0, 1.0);
AxisPose pose = interpolate(segment->start_axes, segment->end_axes, progress);
forward_motion_sample({
line: segment->line,
axes: pose,
currentVel: segment->velocity_mm_per_min / 60.0,
requestedVel: segment->velocity_mm_per_min / 60.0,
inPosition: progress >= 1.0
});
step_servo(...);
}
4.5 motion runtime command schema
当前 motion command 是：
{
"type": "EMC_TRAJ_LINEAR_MOVE",
"line": 12,
"x": 1,
"velocity": 60
}
建议新增或扩展为：
{
"type": "EMC_TRAJ_LINEAR_SAMPLE",
"line": 12,
"x": 1.2,
"y": 3.4,
"z": 5.6,
"a": -70,
"c": 20,
"currentVel": 5.3,
"requestedVel": 5.3,
"segmentProgress": 0.35,
"source": "feed_timed_motion_plan"
}
如果不想新增 command type，也可以继续使用 EMC_TRAJ_LINEAR_MOVE，但必须：
1. velocity 来自 segment.velocityMmPerMin / 60。
2. axes 是当前插值位置，而不是只用 segment end。
3. status 能保留 line/progress/currentVel。
5. G94 速度规则
5.1 G94 units per minute
在 TRAJ.LINEAR_UNITS=mm 时：
F318 => 318 mm/min
在 TRAJ.LINEAR_UNITS=inch 或 G20 active 时：
F10 => 10 inch/min => 254 mm/min
计算：
velocity_mm_per_min = feedRate * linearUnitScaleToMm * feedOverride
duration_seconds = linearDistanceMm / (velocity_mm_per_min / 60)
5.2 Rapid
G0 / STRAIGHT_TRAVERSE：
velocity_mm_per_min = min(INI max velocity, profile max velocity) * rapidOverride
duration_seconds = distance / velocity
5.3 Angular axes
第一阶段可沿用 execution-timing.js 现有策略：
linearSeconds = linearDistanceMm / linearVelocity
angularSeconds = angularDistanceDeg / angularVelocity
durationSeconds = max(linearSeconds, angularSeconds)
这至少能避免旋转轴运动被零时长吞掉。
5.4 G93 inverse time
LinuxCNC impeller 程序包含：
G93
...
G1 ... F159
G93 的 F 不是 units/min，而是 inverse time。第一阶段有两种策略：
方案 A：先检测 G93，明确标注 unsupported，RUN gate 阻止真实 feed mode 运行。
方案 B：实现基础 inverse-time：duration_minutes = 1 / F，duration_seconds = 60 / F。
推荐：
第一阶段实现方案 B。
原因：
1. test_linuxcnc_source/impeller-7bl-xyzac.ngc 使用 G93。
2. 如果不支持 G93，就无法验证用户当前指定测试文件的真实进给语义。
3. 对 inverse-time，F 直接定义该运动块完成时间，适合第一阶段验证。
需要在 interpreter motion event 中增加：
feedMode: "inverse-time" | "units-per-minute"
或至少在 timing 阶段通过 source line 扫描维护 G93/G94 模态。
6. 代码修改落点
6.1 linuxcnc-interpreter-runtime.js
新增：
feedModeBySourceLine(programText)
识别：
G93 => inverse-time
G94 => units-per-minute
motion event 增加：
feedMode: activeFeedMode
6.2 execution-timing.js
修改 buildTimingSegment(...)：
if event.feedMode === "inverse-time":
durationSeconds = 60 / feedRate
velocityMmPerMin = linearDistanceMm / durationSeconds * 60
else:
保持 G94 units/min 逻辑
注意：
1. G93 中 F 必须大于 0。
2. G93 中如果缺 F，应保留上一个 modal F 或报错，按 LinuxCNC 语义确认。
3. velocity 仍要可被 INI max velocity 限制还是忠实 inverse-time，需要明确。第一阶段建议记录 requested 与 capped 两个值。
6.3 store.js
在 initializeTaskHalSession 后或 RUN_INTERPRETER_PROGRAM 完成后，把当前 programExecution.motion 与 programExecutionTiming.segments 传给 task/HAL runtime：
await state.taskHalRuntime.loadProgramMotionPlan({
programPath: session.programPath,
motion: state.programExecution.motion,
timing: state.programExecutionTiming,
linearUnits: state.profile.traj.linearUnits,
});
需要保证：
1. LOAD_LINUXCNC_GCODE_SOURCE 后 interpreter 已完成。
2. task/HAL openProgram 的 programPath 与 motion plan programPath 一致。
3. 如果 motion plan 不存在，RUN gate 应阻止“真实进给速度 RUN”，不能悄悄回退 velocity=60。
6.4 linuxcnc-task-hal.js
新增 SDK 方法：
loadProgramMotionPlan(plan) {
const rc = callWithJson(mod, "lctask_load_program_motion_plan_json", plan);
if (rc !== 0) throw new Error(...);
}
6.5 linuxcnc_task_hal_wasm.hh
新增声明：
int lctask_load_program_motion_plan_json(const char *plan_json);
6.6 linuxcnc_task_hal_wasm.cpp
新增：
1. MotionSegment 数据结构。
2. 简单 JSON plan parser，或复用现有轻量 json_number_after 风格解析数组。
3. lctask_load_program_motion_plan_json。
4. lctask_run_cycles 按 elapsed time 找 segment。
5. 删除或隔离 fixed velocity=60 的 fallback。
要求：
fixed velocity=60 只能作为 explicit fixture fallback。
真实 RUN 路径不允许使用它。
7. 测试计划
7.1 Node 单元测试：F 值改变 duration
新增测试：
web-rtcp-5axis-sim-plan/tests/node/verify_feed_rate_execution_timing.mjs
用例：
G90 G94
G1 X10 F60
G1 X20 F600
M2
期望：
第一段 10mm @ 60mm/min => 10s。
第二段 10mm @ 600mm/min => 1s。
duration ratio ≈ 10:1。
7.2 Node 单元测试：G93 inverse time
用例：
G90 G93
G1 X10 F2
G1 X20 F10
M2
期望：
F2 => 60/2 = 30s。
F10 => 60/10 = 6s。
7.3 task/HAL runtime 测试：速度不固定
新增或扩展：
web-rtcp-5axis-sim-plan/tests/node/verify_run_feedback_loop.mjs
断言：
1. RUN feedback currentVelocityMmPerMin 不等于固定 3600。
2. 不同 F 段采样到不同 requested/current velocity。
3. activeLine 不再每 task cycle 固定递增一行。
4. 慢速段停留采样数 > 快速段。
7.4 浏览器证据测试
扩展：
qa/web-rtcp-5axis-site-test/capture-test-linuxcnc-source-run.mjs
新增报告字段：
feedMode
feedRate
segmentDurationSeconds
segmentProgress
requestedVelocityMmPerMin
currentVelocityMmPerMin
报告验收：
1. impeller G93 行显示 inverse-time。
2. 采样 velocity 随当前 segment 变化。
3. 当前行停留时间与 F 值/段时长一致。
4. Word 报告中列出 F、feedMode、duration、velocity 的采样表。
8. 验收标准
修复完成必须通过：
node web-rtcp-5axis-sim-plan/tests/node/verify_feed_rate_execution_timing.mjs
node web-rtcp-5axis-sim-plan/tests/node/verify_run_feedback_loop.mjs
node web-rtcp-5axis-sim-plan/tests/node/verify_linear_unit_conversion.mjs
npm --prefix web-rtcp-5axis-sim-plan/app run build
npm --prefix web-rtcp-5axis-sim-plan/app run smoke:node
node qa/web-rtcp-5axis-site-test/capture-test-linuxcnc-source-run.mjs
并满足：
1. 不再出现所有 RUN 样本 velocity=3600 的固定速度现象。
2. C++ task/HAL RUN 主路径不再写死 velocity=60。
3. G94 F60/F600 用例体现 10:1 段时长差异。
4. G93 F2/F10 用例体现 5:1 段时长差异。
5. test_linuxcnc_source/impeller-7bl-xyzac.ngc 的 RUN 报告包含 feedMode/feedRate/duration 证据。
6. STOP/ABORT/STEP 现有测试不回退。
9. 风险与注意事项
9.1 不要伪造 LinuxCNC 语义
如果还没有完整 planner，就必须在状态中明确：
semanticBoundary = feed_timed_canonical_motion_runtime
不要标称为真实 LinuxCNC planner。
9.2 不要把 estimate 当作硬件实时
第一阶段可以做到：
canonical motion + feed mode + timing driven browser simulation
不能声称：
hardware realtime LinuxCNC execution
9.3 G93 是当前 impeller 文件的关键
test_linuxcnc_source/impeller-7bl-xyzac.ngc 开头有：
M428 ;TCP:xyzac
G93
S600 M3
因此如果不处理 G93，针对该文件的“真实 F 速度”验证仍然不完整。
10. 建议实施顺序
1. 给 interpreter motion event 增加 feedMode。
2. 给 execution-timing.js 增加 G93 duration。
3. 写 verify_feed_rate_execution_timing.mjs，先证明 timing 正确。
4. 给 task/HAL SDK/WASM 增加 loadProgramMotionPlan。
5. 改 lctask_run_cycles，按 elapsed time 和 segment progress 推进。
6. 改 store，把 motion plan 注入 task/HAL session。
7. 扩展 verify_run_feedback_loop，证明 velocity 不固定、慢段停留更久。
8. 扩展浏览器 RUN 报告，输出 feedMode/feedRate/duration/progress。
9. 重跑 build、smoke、浏览器报告。
10. 更新 working_run 和 gptlog-process。