执行摘要

• 一句话：为内联 model args 加 shell 引号，修复 MoE 参数被 glob 展开
• 推荐动作：值得精读。这是一个小而精的启动器修复：token 级 shlex.quote + round-trip 测试的设计思路可直接复用——它既解决了 shell 注入/展开风险，又用 'quoted 后 shlex.split 与原 argv 一致' 的判据锁死了转义正确性，避免过度转义。建议重点关注 shell_safe_model_args 的 None 分支设计（把 FSDP 特例收进函数内部）和快照最小 churn 策略（shlex.quote 只在必要时加引号），以及 CI 评论区对 'lane 无真实覆盖' 的反思——它提醒我们绿色 CI 不等于测试真的跑了。

功能与动机

在 op8-16 把 model args 展开内联进命令后，--moe-layer-freq 这类含方括号的 token 直接拼接进 shell 命令行会被当作 glob 展开（测试注释原话: '--moe-layer-freq [0,0,0,1,1] is a glob; unquoted it expands against the launch directory'），导致训练进程收到错乱甚至静默错误的参数。shell_safe_model_args 的 docstring 也写明: "For callers splicing the args into a command line, where --moe-layer-freq [1,1,1] is a glob."。该 PR 是 #1837 tracking issue 中列出的 #1911 项，PR body 声明依赖 ci-megatron-pr: tom/refactor-miles-repo-megatron/op8-13。

实现拆解

实现分四步：

1. 新增 shell 安全包装函数（miles/utils/external_utils/model_args_utils.py）：新增 shell_safe_model_args(model_type: str | None) -> str，内部先调用 load_model_args() 取原始参数字符串，按空白拆分成 token 后用 shlex.quote() 逐个引用再拼接。设计要点是 token 级引用而非整串引用，避免将整段参数折叠成单个 argv；同时把原来的 model_type is None 三元分支收进函数内部，FSDP 等无 megatron 配置的后端返回空字符串，不贡献任何 argv。

2. 替换全部内联调用点（miles/utils/external_utils/command_utils.py、examples/experimental/formal_math/single_round/run_minimal.py、docker/npu_patch/miles.patch）：convert_checkpoint 中 torchrun 拼装的 load_model_args(megatron_model_type) 换成 shell_safe_model_args(megatron_model_type)；execute_train 中原来的 load_model_args(...) if megatron_model_type is not None else "" 直接替换为 shell_safe_model_args(megatron_model_type)；formal_math 示例与 NPU patch 同步替换，保证所有入口行为一致。

3. 重新生成 launch 快照（tests/snapshots/launch_scripts/py/scripts/ 下约 20 个 golden 文件）：凡包含 --moe-layer-freq 的命令行都加上单引号（如 --moe-layer-freq '[0,0,0,1,1]'），普通参数（如 --num-layers 36）因 shlex.quote 只在必要时转义而保持原样，快照 churn 最小化。

4. 测试配套（tests/fast/utils/external_utils/test_model_args_utils.py、tests/fast/utils/test_command_utils.py）：TestShellSafeModelArgs 覆盖四类行为——需要引号的 glob token、无需引号的普通 token、空 model_type 返回空串、以及 shlex.split 往返一致；test_command_utils 新增两个端到端断言，验证 execute_train 生成的 ray job submit 命令中 --moe-layer-freq 被引号包裹，且 submitted 命令尾部的训练参数区与 load_model_args 声明的 argv 完全一致。

关键文件：

• miles/utils/external_utils/model_args_utils.py（模块 参数加载；类别 source；类型 data-contract；符号 shell_safe_model_args）: 核心变更文件，新增 shell_safe_model_args()，把 load_model_args 的产物按 token 级 shlex.quote 转义，并吸收 None 分支（FSDP 场景返回空串）。
• miles/utils/external_utils/command_utils.py（模块 命令工具；类别 source；类型 dependency-wiring；符号 convert_checkpoint, execute_train）: 两个主要调用点 convert_checkpoint 与 execute_train 从 load_model_args 切换到 shell_safe_model_args，是行为变更的落地入口。
• tests/fast/utils/external_utils/test_model_args_utils.py（模块 参数加载；类别 test；类型 test-coverage；符号 TestShellSafeModelArgs, test_quotes_the_tokens_a_shell_would_reinterpret, test_leaves_ordinary_tokens_alone, test_survives_a_shell_round_trip_unchanged）: 新增 TestShellSafeModelArgs 四个单元测试，直接锁定 shell_safe_model_args 的转义边界与 None 行为，是契约的源头保护。
• tests/fast/utils/test_command_utils.py（模块 命令工具；类别 test；类型 test-coverage；符号 test_quotes_the_model_args_the_shell_would_otherwise_reinterpret, test_model_args_survive_a_shell_round_trip_unchanged）: 新增两个集成测试，验证 execute_train 实际生成的提交命令中 --moe-layer-freq 被引用，且 round-trip 后 argv 与模型脚本声明一致，防止回归。
• examples/experimental/formal_math/single_round/run_minimal.py（模块 示例脚本；类别 source；类型 dependency-wiring）: 示例启动器同步切换到 shell_safe_model_args，保证示例与框架入口行为一致，避免示例继续暴露未转义问题。
• docker/npu_patch/miles.patch（模块 NPU 补丁；类别 infra；类型 infrastructure）: NPU 镜像使用的 miles patch 同步替换 model args 拼接逻辑，保证 NPU 侧命令也带引号；但 patch 文件本身无 fast 测试覆盖，存在漂移风险。
• tests/snapshots/launch_scripts/py/scripts/run_deepseek.py/train.txt（模块 快照文件；类别 docs；类型 documentation）: 代表性快照：--moe-layer-freq 从裸方括号变为单引号包裹，是行为变更在 golden 文件中的直接体现，其余约 20 个快照同模式更新。

关键符号：shell_safe_model_args, convert_checkpoint, execute_train

关键源码片段

miles/utils/external_utils/model_args_utils.py

核心变更文件，新增 shell_safe_model_args()，把 load_model_args 的产物按 token 级 shlex.quote 转义，并吸收 None 分支（FSDP 场景返回空串）。

# miles/utils/external_utils/model_args_utils.py
​
def shell_safe_model_args(model_type: str | None) -> str:
    """为把 args 拼进命令行的人准备的转义版本：--moe-layer-freq [1,1,1] 在 shell 里是 glob。"""
    if model_type is None:
        # FSDP 等后端没有 megatron 模型配置，必须不贡献任何 argv；
        # 这里把原来调用点的三元分支收进函数内部，调用方不再需要记忆这个特例。
        return ""
    # 先按空白拆分再逐 token 引用，而不是整体引用：
    # 整体引用会把整段参数变成单个 argv，训练进程将无法解析。
    # shlex.quote 只在 token 含特殊字符时加引号，普通参数（如 --num-layers 36）
    # 保持原样，快照不会无谓 churn。
    return " ".join(shlex.quote(token) for token in load_model_args(model_type).split())

miles/utils/external_utils/command_utils.py

两个主要调用点 convert_checkpoint 与 execute_train 从 load_model_args 切换到 shell_safe_model_args，是行为变更的落地入口。

# miles/utils/external_utils/command_utils.py 中 execute_train 的 ray job 提交路径
​
if get_bool_env_var("MILES_SCRIPT_ENABLE_RAY_SUBMIT", "1"):
    # 旧代码是 load_model_args(...) if megatron_model_type is not None else ""，
    # None 特例现在由 shell_safe_model_args 内部消化，语义不变但更内聚。
    model_args = shell_safe_model_args(megatron_model_type)
    exec_command_cpu(
        f"export no_proxy=127.0.0.1 && export PYTHONUNBUFFERED=1 && "
        f"ray job submit --address=http://127.0.0.1:8265 "
        f"--runtime-env-json={shlex.quote(runtime_env_json)} "
        f"-- python3 {train_script} "
        f"{model_args} " # 含 [0,0,0,1,1] 的 token 已被引号包裹
        f"{train_args}"
    )

tests/fast/utils/test_command_utils.py

新增两个集成测试，验证 execute_train 实际生成的提交命令中 --moe-layer-freq 被引用，且 round-trip 后 argv 与模型脚本声明一致，防止回归。

# tests/fast/utils/test_command_utils.py
​
def test_model_args_survive_a_shell_round_trip_unchanged(self, commands):
    """引号正确的判据：shlex.split 拆回的 argv 必须与模型脚本声明完全一致。
    既不能让 glob 把 [0,0,0,1,1] 展开成文件列表，也不能因过度转义改变参数值。
    """
    command_utils.execute_train(
        train_args="", num_gpus_per_node=8, megatron_model_type="deepseek-v3-5layer"
    )
​
    declared = load_model_args("deepseek-v3-5layer").split()
    submitted = shlex.split(commands[-1])
​
    # 只比对命令尾部的训练参数区（头部还有 ray job submit 等前缀），
    # 保证训练进程收到的 argv 与模型脚本声明逐 token 相等。
    assert submitted[len(submitted) - len(declared):] == declared

评论区精华

本 PR 的 PR review 无文字评论（yueming-yuan 直接 APPROVED），但 issue 评论区有作者（fzyzcjy，经 Claude Code 自动发布）关于 CI 的密集诊断，核心交锋如下：

"op8-9's inline base64: payload needs the matching Megatron-LM change, which CI was not told to check out. Fixed by declaring the dependency in the PR description."

"No tests found for hw=CUDA, suite=stage-c-8-gpu-h100 ... So those SUCCESS marks mean 'ran nothing', not 'passed'." —— 指出该 GPU lane 此前从未有真实覆盖，run-ci-image label 强制 --match-all-labels 后才暴露出测试。

关于两个遗留失败："one is an image regression, the other is a code regression from a specific main commit. Neither is from this chain" —— 通过将 PR 固定到 dev-202607240207 旧镜像做实验，证明 qwen3_5_35b_a3b_lora_ci.py 的 cuDNN 失败是共享镜像（TransformerEngine 2.17 相关）回归，而 fsdp_colocated_2xGPU 超时在旧镜像上仍复现，属 main 代码回归。

"traced it to a python-version-dependent Path.exists() behaviour on the CPU runner" —— 快照测试的 PermissionError 根因是 Path.exists() 的 Python 版本差异，修复后 stage-a/b-cpu 全绿。

• base64 内联 payload 的跨仓库依赖未声明 (correctness): 在 PR body 声明 ci-megatron-pr: tom/refactor-miles-repo-megatron/op8-13 依赖后，stage-c-4-gpu-h200 8/8 通过，确认修复。
• stage-c-8-gpu-h100 此前从未有真实覆盖 (testing): 该 lane 历史 SUCCESS 均为空跑，失败无法用排除法归因到本 PR；此讨论暴露了 CI label 体系的覆盖盲区。
• 两个遗留 GPU 失败为 pre-existing 但机制不同 (correctness): 两个失败均非本链引起，且机制不同；PR 结论为'与 main 当前状态同样绿'，image pin 实验后回滚。
• Path.exists() 的 Python 版本依赖导致 CPU runner 快照测试失败 (correctness): 修复后 stage-a-cpu 全部 shard 与 stage-b-cpu 全绿。
• 镜像 pin 实验定位两个失败 (other): 实验成功拆分两个失败机制，随后回滚 pin，不影响本 PR 合并。

风险与影响

• 风险：
  1. 启动命令文本契约变更：execute_train 与 convert_checkpoint 生成的命令行字符串发生变化（带引号的 --moe-layer-freq），依赖这些命令原始文本的外部工具、CI 门禁或用户脚本需同步适配；快照已同步更新，但仓库外消费者无法感知。
  2. 跨仓库合并顺序约束：op8-9 引入的 base64: 内联 payload 依赖 Megatron-LM 分支 tom/refactor-miles-repo-megatron/op8-13 的 resolve_file_arg，本 PR body 已声明该依赖，但若 Megatron 侧未先合并，CI 会出现 ENAMETOOLONG 类失败。
  3. 转义语义边界：shlex.quote 按 POSIX shell 语义转义，若某模型 args token 本身含单引号（嵌套引号），转义后 round-trip 虽保持正确，但命令可读性下降；当前测试只覆盖 deepseek-v3-5layer 一种含方括号场景，其他特殊字符（通配符 *、分号、$ 等）未被快照显式锁定。
  4. NPU 侧同步风险：docker/npu_patch/miles.patch 同步了替换，但 patch 文件本身不经过 fast 测试直接验证，若上游代码在 patch 生成后又变化会产生漂移。
     - 影响：影响范围集中在 launch 命令生成路径：所有经 command_utils.execute_train 提交的 ray job 训练命令、convert_checkpoint 的 torchrun 转换命令、formal_math 示例、以及 NPU 镜像 patch 中的命令拼装。对用户而言，含方括号列表的 MoE 参数（--moe-layer-freq）、含特殊字符的路径等此前可能被 shell glob 展开导致静默错误，现在会被正确引用；普通参数命令文本不变，快照 diff 因此非常收敛。对团队而言，新增的 round-trip 测试为模型 args 内联机制提供了可回归的契约保障，后续修改 scripts/models/*.py 模型定义时若破坏 argv 语义会被 CI 立即拦截。
     - 风险标记：启动命令文本契约变更, 跨仓库依赖需先合并, 镜像 patch 无直接测试覆盖, 快照基线大范围更新

关联脉络

• PR #2279 Run the launch script snapshot tests by hand instead of in CI: 同一套 tests/snapshots/launch_scripts 快照体系与 manual 测试目录的后续演进：本 PR 为快照引入大量带引号的 golden 文件，2279 将这些快照测试从 CI 移出改为手动执行，说明团队对该套测试的运行成本做了后续调整。
• PR #1908 Snapshot test the argv of all model scripts: #1837 链上 op8-14，为本 PR 提供了 argv 快照基线——快照锁定了 shell 时代各模型的 argv，本 PR 的引号变更正是在该基线上对模型 args 内联机制做转义修正。
• PR #1909 Expand the model args in python before building the command: #1837 链上 op8-16，是本 PR 的直接前置：它在 python 中展开 model args 拼进命令，才暴露出方括号 token 未加引号的问题，本 PR 为其补上 shell 安全转义。
• PR #1905 Remove non-reproducible file arguments by supporting inline base64 payloads: #1837 链上 op8-9，其 base64: 内联 payload 依赖 Megatron-LM 侧分支，本 PR 的 CI 讨论中多次出现该依赖的排查与声明（ENAMETOOLONG 修复）。