refactor(tool): 拆分运行入口与 Tool facade

[MRNIU]

Summary

• 将 QEMU、U-Boot 和 board runner 从直接挂在 Tool 上的实现拆到模块级函数，运行入口改为接收显式的 process context、artifacts、arch/debug 等输入。
• 保留现有 Tool runner/config 方法作为兼容 wrapper，并逐函数标注这些旧入口会在调用方迁移后移除。
• 将 TFTP 和 menuconfig 相关路径解析改为使用显式项目布局、变量作用域和运行产物状态，减少 runner 模块对完整 Tool 的依赖。
• legacy_context 继续只负责 InvocationState 与旧 AppContext 的状态桥接，并标注这些桥接 helper 的临时性质。

Approach

这次变更保留 Tool 作为现有 public API 的兼容 facade，但让 QEMU、U-Boot、board 和 TFTP 的核心流程依赖更窄的输入结构。Tool 负责把当前 invocation/build/runtime state 组装成 runner input，然后委托给对应模块函数；新代码可以直接调用模块级 API，旧调用方仍可通过 Tool 方法工作。

Changed Modules

• ostool/src/run/qemu.rs: 提供显式 QemuRunInput 和模块级 QEMU config/run helper。
• ostool/src/run/uboot.rs: 提供显式 UbootRunInput，并让本地/远程 U-Boot runner 消费该输入。
• ostool/src/run/tftp.rs: TFTP server helper 改为接收 manifest dir 和 runtime artifacts，而不是完整 Tool。
• ostool/src/board/mod.rs: board run config 与 prepared board flow 改为使用显式 scope/input。
• ostool/src/menuconfig.rs: QEMU config path 查询改为走显式 workspace/runtime arch。
• ostool/src/tool.rs: 收敛为兼容 facade，保留旧 public runner/config 入口并委托到模块函数。
• ostool/src/legacy_context.rs: 标注旧 AppContext 桥接 helper 的兼容层性质。

Compatibility

• CLI、配置文件格式和 runtime 行为预期保持不变。
• 既有 Tool public runner/config 方法仍保留，调用方不需要立即迁移。
• 新增的 runner input/helper 主要用于缩小内部模块依赖面，不新增用户可见配置项。

Verification

已运行通过：

• cargo fmt --all -- --check
• CARGO_BUILD_JOBS=1 cargo check -p ostool --target x86_64-unknown-linux-gnu --all-features
• CARGO_BUILD_JOBS=1 cargo test -p ostool -- --nocapture
• CARGO_BUILD_JOBS=1 cargo clippy -p ostool --all-targets --all-features -- -D warnings
• CARGO_BUILD_JOBS=1 cargo build -p ostool --target x86_64-unknown-linux-gnu --all-features
• git diff --check

Risks / Follow-up

• 本 PR 只做 host-side Rust 验证，没有实际启动 QEMU、U-Boot 或远程开发板 session。
• Tool 兼容 facade 仍然存在；后续调用方迁移完成后，可以删除这些旧入口和对应桥接 helper。

[mai-team-app]

Code Review: refactor(tool) - 拆分运行入口与 Tool facade

总体评价

这是一个质量很高的重构 PR。将 QEMU、U-Boot、board 和 TFTP 的 runner 逻辑从 Tool impl 块中提取到模块级函数，并引入 QemuRunInput / UbootRunInput 等窄输入结构，大幅减少了 runner 模块对完整 Tool 的依赖。兼容性 wrapper 保留完整，且每个都有明确的移除标注，便于后续迁移。

设计方面

输入边界清晰: QemuRunInput 和 UbootRunInput 只包含 runner 实际需要的字段（process_context、artifacts、arch、debug），而非整个 Tool。

向后兼容: Tool 上的旧 public 方法全部保留为 compatibility wrapper，现有调用方无需改动。

U-Boot 运行镜像语义改进: 从 ensure_runtime_bin() + require_bin() 改为 runtime_image()，允许 ELF-only 的 U-Boot artifact 直接进入运行路径，同时在缺失镜像时返回更明确的错误信息。

QEMU to_bin 语义明确化: to_bin=true 时在 module-level run_qemu_with_config 入口检查 BIN artifact 是否存在，将准备 BIN 的责任推给调用方。Tool::run_qemu wrapper 仍然调用 ensure_runtime_bin() 以保持兼容。

细节确认

• process_context.workdir() 与旧的 manifest_dir() 值相同（Tool::process_context() 用 self.manifest_dir.clone() 作为 workdir），TFTP 调用语义无变化。
• legacy_context.rs 中的 bridge helper 标注清晰，方便后续清理。
• resolve_qemu_config_path 工具函数删除，只保留 resolve_qemu_config_path_in_dir，减少不必要的间接层。

测试覆盖

新增三个针对性测试：

1. run_qemu_with_to_bin_rejects_elf_only_artifacts - 验证 QEMU to_bin=true 在缺少 BIN 时的错误路径
2. uboot_run_input_accepts_elf_only_artifacts - 验证 U-Boot 输入结构接受 ELF-only artifact
3. run_uboot_rejects_missing_runtime_image - 验证 U-Boot 缺失 runtime image 时的错误信息

既有测试也已同步更新。

小建议（非阻塞）

• UbootRunInput 和 QemuRunInput 的字段可见性不一致：QemuRunInput 字段用了 pub(crate)，UbootRunInput 字段是私有的。从一致性角度可以考虑统一。
• 未来移除兼容 wrapper 时，建议同时删除 run_board_with_build_config 这个 private 中间方法。

结论

代码质量好，方向正确，测试充分。Approve。

Powered by mimo-v2.5-pro

[MRNIU]

UbootRunInput 和 QemuRunInput 一致性问题已修复

[mai-team-app]

Code Review: refactor(tool) - 拆分运行入口与 Tool facade

总体评价

这是一个结构清晰的重构 PR。将 QEMU、U-Boot、board 和 TFTP 的 runner 逻辑从 impl Tool 提取为模块级函数，引入 QemuRunInput / UbootRunInput 等窄输入结构，显著降低了 runner 模块对完整 Tool 的耦合度。兼容 wrapper 保留完整且标注了移除时机，方便后续逐步迁移。

设计亮点

• 输入边界清晰: QemuRunInput 和 UbootRunInput 只封装 runner 实际需要的字段（process_context、artifacts、arch、debug），字段私有 + new() 构造函数，控制组装入口。
• 向后兼容完整: Tool 上的旧 public 方法全部保留为 compatibility wrapper，现有调用方无需立即修改。
• U-Boot 运行镜像语义改进: 从 ensure_runtime_bin() + require_bin() 改为 runtime_image()，允许 ELF-only artifact 直接进入 U-Boot 运行路径，缺失镜像时错误信息也更明确（"U-Boot runner requires a prepared runtime image"）。
• QEMU to_bin 检查前置: run_qemu_with_config 在模块级入口检查 BIN artifact 存在性，而 Tool::run_qemu wrapper 仍调用 ensure_runtime_bin() 保持兼容。
• Runner / QemuRunner 去生命周期: 原先 QemuRunner<'a> 和 Runner<'a, B> 持有 &'a mut Tool，重构后分别持有 QemuRunInput / UbootRunInput（owned），不再引入生命周期约束。

行为变更确认

• Tool::run_uboot() 不再自动调用 ensure_runtime_bin()，BIN 准备责任推到调用方。对于通过 board 路径进入的场景，prepare_runtime_artifacts() 已覆盖该步骤；直接调用 run_uboot() 时 ELF 也可作为 runtime image 使用。变更合理。
• manifest_dir() accessor 移除后，TFTP 通过 input.process_context.workdir() 获取同等路径（ProcessContext::workdir() 来源于 Tool::manifest_dir），语义一致。
• resolve_qemu_config_path wrapper 删除，只保留 resolve_qemu_config_path_in_dir，减少不必要的间接层。

测试覆盖

新增三个针对性测试：

1. run_qemu_with_to_bin_rejects_elf_only_artifacts — 验证 QEMU to_bin=true 在缺少 BIN 时的错误路径
2. uboot_run_input_accepts_elf_only_artifacts — 验证 U-Boot 输入结构接受 ELF-only artifact
3. run_uboot_rejects_missing_runtime_image — 验证 U-Boot 缺失 runtime image 时的错误信息

既有测试也已同步更新（QemuRunner 使用 qemu_input() helper 构造输入，resolve_qemu_config_path 调用改为 resolve_qemu_config_path_in_dir）。

小建议（非阻塞）

• legacy_context.rs 文档注释风格：/// 和 // 混用在同一类 helper 上。建议统一为 ///（doc comment）以保持 rustdoc 一致性。
• 未来移除兼容 wrapper 时，建议同时清理 run_board_with_build_config 这个 private 中间方法。

结论

重构方向正确，兼容性处理得当，测试覆盖充分，代码质量好。Approve。

Powered by mimo-v2.5-pro

[MRNIU]

Code Review: refactor(tool) - 拆分运行入口与 Tool facade

总体评价

这是一个结构清晰的重构 PR。将 QEMU、U-Boot、board 和 TFTP 的 runner 逻辑从 impl Tool 提取为模块级函数，引入 QemuRunInput / UbootRunInput 等窄输入结构，显著降低了 runner 模块对完整 Tool 的耦合度。兼容 wrapper 保留完整且标注了移除时机，方便后续逐步迁移。

设计亮点

• 输入边界清晰: QemuRunInput 和 UbootRunInput 只封装 runner 实际需要的字段（process_context、artifacts、arch、debug），字段私有 + new() 构造函数，控制组装入口。
• 向后兼容完整: Tool 上的旧 public 方法全部保留为 compatibility wrapper，现有调用方无需立即修改。
• U-Boot 运行镜像语义改进: 从 ensure_runtime_bin() + require_bin() 改为 runtime_image()，允许 ELF-only artifact 直接进入 U-Boot 运行路径，缺失镜像时错误信息也更明确（"U-Boot runner requires a prepared runtime image"）。
• QEMU to_bin 检查前置: run_qemu_with_config 在模块级入口检查 BIN artifact 存在性，而 Tool::run_qemu wrapper 仍调用 ensure_runtime_bin() 保持兼容。
• Runner / QemuRunner 去生命周期: 原先 QemuRunner<'a> 和 Runner<'a, B> 持有 &'a mut Tool，重构后分别持有 QemuRunInput / UbootRunInput（owned），不再引入生命周期约束。

行为变更确认

• Tool::run_uboot() 不再自动调用 ensure_runtime_bin()，BIN 准备责任推到调用方。对于通过 board 路径进入的场景，prepare_runtime_artifacts() 已覆盖该步骤；直接调用 run_uboot() 时 ELF 也可作为 runtime image 使用。变更合理。
• manifest_dir() accessor 移除后，TFTP 通过 input.process_context.workdir() 获取同等路径（ProcessContext::workdir() 来源于 Tool::manifest_dir），语义一致。
• resolve_qemu_config_path wrapper 删除，只保留 resolve_qemu_config_path_in_dir，减少不必要的间接层。

测试覆盖

新增三个针对性测试：

1. run_qemu_with_to_bin_rejects_elf_only_artifacts — 验证 QEMU to_bin=true 在缺少 BIN 时的错误路径
2. uboot_run_input_accepts_elf_only_artifacts — 验证 U-Boot 输入结构接受 ELF-only artifact
3. run_uboot_rejects_missing_runtime_image — 验证 U-Boot 缺失 runtime image 时的错误信息

既有测试也已同步更新（QemuRunner 使用 qemu_input() helper 构造输入，resolve_qemu_config_path 调用改为 resolve_qemu_config_path_in_dir）。

小建议（非阻塞）

• legacy_context.rs 文档注释风格：/// 和 // 混用在同一类 helper 上。建议统一为 ///（doc comment）以保持 rustdoc 一致性。
• 未来移除兼容 wrapper 时，建议同时清理 run_board_with_build_config 这个 private 中间方法。

结论

重构方向正确，兼容性处理得当，测试覆盖充分，代码质量好。Approve。

Powered by mimo-v2.5-pro

legacy_context.rs 文档后面会删掉，注释风格问题暂不修改

[MRNIU]

@ZR233 hi，麻烦 review