Machine 类型几乎是空壳

[yzxoi]

#7 · Machine 类型空壳讨论

类型

HITL — 这是设计风格选择。需要用户判断 machine / accelerator 这一层是 type-heavy 还是 function-heavy 风格。

要做什么

决定 Machine 类型是保留作为未来扩展占位，还是降级为自由函数。落地后代码意图明确：要么 Machine 持有更多状态、暴露 step()，要么 Machine 类型消失，由 pub async fn drive(...) 直接担纲。

端到端可观察行为（取决于决策方向）：

• 选项 A 保留：API 不变；为未来扩展（metrics / step / hooks）留位
• 选项 B 降级：API 变化；CLI 改用 drive(...) 函数；少一层概念

验收标准

• 用户在评论区记录决策方向
• 实现选定方向并通过 cargo build --workspace
• CLI 行为不变（输出、动画一致）
• 如果选 B：所有调用 Machine::run 的代码已迁移
• 对应 ADR / 注释记录决策

依赖

• 与 Accelerator 已增强，但其定位与 Machine 的关系仍需设计讨论 #18（Accelerator wrapper）一起决定风格方向更连贯。

现象

crates/machine/src/machine.rs:12-19:

pub struct Machine { policy: Box<dyn Policy> }

impl Machine {
    pub fn new(policy: Box<dyn Policy>) -> Self { Self { policy } }
    pub async fn run(&self, purpose: &Purpose, ctx: &mut Context,
                     env: &mut Environment, resources: &mut Resources) { ... }
}

唯一字段是 policy。run 方法的 ctx/env/res 都从参数传入。本质等价于自由函数。

影响

• 类型表面冗余（一个字段、一个方法的 wrapper）
• 跟 Accelerator::fire（自由函数）风格不一致
• 但保留为未来扩展占位也合理

解决路径

选项 A — 保留 struct

理由：

• 未来扩展空间：持有内部状态（round counter, metrics, retry budget...）
• 暴露 step() 接口做单步 driving
• 跟 actor 模型对齐
• API 稳定性：函数变 struct 是 break change，反之亦然

选项 B — 降级为函数

pub async fn drive(policy: &dyn Policy, purpose: &Purpose,
                   ctx: &mut Context, env: &mut Environment, resources: &mut Resources)

跟 Accelerator::fire 风格一致。CLI 改用函数调用。

决策依据

跟 #18 (Accelerator wrapper) 一起决定。问题本质是：

machine / accelerator 这一层是不是要走 strong type, weak function 风格？

• 是：保留 Machine + Accelerator，未来给它们加状态/方法
• 否：都降级成函数

风险

• 降级是 break change，影响 cli/cmd/run.rs
• workspace 内调用面有限，改动可控

工作量

选项 A：0 工作量（保持现状）。
选项 B：1 小时。