[RFC] Pipeline Next：引入编译期 IR、结构化终态与证据代际

[Windsland52]

背景

我对 MaaFramework Pipeline 协议、当前实现、文档/Schema、公开 Issue，以及 M9A、MaaEnd、MFABD2、
MAA_SnowBreak 等实际项目做了一轮系统性梳理。结论是：Pipeline 的 happy path 已经很好用，下一阶段最值得投入的
不是继续增加孤立字段，而是补齐编译、运行身份、结构化终态、证据帧、Controller capability 和资源代际等公共契约。

这份研究不是把所有项目故障都归因 MaaFramework。报告单独区分了：

• 项目资源/状态机/API 使用问题；
• 当前固定基线可直接确认的实现缺陷；
• 多个项目只能通过 Custom、Profile patch 或命名约定规避的协议局限。

完整报告与 46 轮证据档案：
MaaFramework Pipeline 协议研究总报告与 Pipeline Next RFC 草案

证据边界

主要源码基线为 MaaFramework 1a9f032c491ea515b74bf0956c02f1aa957a6e3c、MaaUtils
323297f1b76661d4d8d120ded27a798e9ff03eda、M9A 6fa9a0f6ba014a427fad9f5bd3b5fc8f3de6107a 和
MaaEnd 54d7c829dac4d8a5564be89a83292d76559d1955。没有 Sentry 访问，也没有完成全部真实 Controller/模型/宿主的
动态 conformance；报告把这些保留为测试计划，不用静态分析冒充动态复现，也不以公开 Issue 数量冒充故障发生率。

几个当前可直接确认的切入点

• #1314 / #1315：
  PipelineDumper 的 And/Or inline sub-recognition 与空 ColorMatch 无法由当前 Parser 重新加载，说明 Parser、Dumper、
  Schema 还没有共同的 canonical representation。
• #900：Context.run_task 运行真实子任务并写 RuntimeCache，但不产生
  Tasker.Task lifecycle event，父子运行关系无法从回调重建。
• #1258：部分 action 早期失败返回空 ActionResult，丢失
  action id/name/type；Action.Starting 后的 stop 路径还可能没有配对 terminal。
• #838：Resource/Controller 的失败原因不足，是更广泛的 typed outcome
  问题的一部分。
• #1417：NN 模型 adapter/manifest 是领域协议化的现有入口。

此外，固定基线还能看到 callback self-remove/unregister 生命周期、共享 Resource/Controller 的 stop scope、截图 job 只读
全局 cache、Record/Replay capability/参数不一致、MultiSwipe/Scroll/LongPress 等确定性问题。它们适合分别修复和建回归，
不建议等待一个“大版本重写”。

建议的 Pipeline Next 骨架

1. Pipeline compiler + canonical typed IR

V1/V2/vNext 都先编译到同一个 IR，Schema 负责 authoring shape，compiler 负责引用、类型、能力、预算、Profile/override、
路径和控制流语义。必须满足：

parse(authoring) -> canonical IR -> dump -> parse -> equivalent IR

2. RunGraph + typed Outcome

Task、Context child task、Node、Reco、Action、Agent 和 Controller operation 使用共同的：

run_id / operation_id / parent / owner / generation / deadline / budget

Starting 后 terminal 恰好一次；Succeeded、Failed、Cancelled、TimedOut、Unsupported、Invalid、DependencyFailed 可区分，
并保留 phase/cause/partial effect。

3. FrameSnapshot + BindingSnapshot + Capability

• capture 按 operation id 返回不可变 FrameSnapshot；last-good 只能显式选择；
• recognition、target、action、artifact 都引用 frame/resource generation；
• Tasker 运行期间绑定不可漂移；共享 Resource/Controller 有 owner/lease 和 stop isolation；
• Controller 声明 input/lifecycle/capture capability，unsupported/degraded 不再静默冒充 success。

4. 在公共骨架上增量提供领域 profile

• OCR text match / visual input；
• gesture、InputText、KeySpec、typed Scroll；
• ProcessSpec、AppLifecycleSpec；
• Feature asset / ModelManifest；
• RecordingManifest / ReplayResult；
• exact / retry / until 与 progress observation。

兼容原则

不建议 flag-day V6。旧字段通过 legacy adapter 保留原语义，例如 OCR expected 的 regex-search、repeat 的 last-wins、
StartApp/StopApp 的 dispatch-only 和 Scroll 的 legacy native unit；新资源则可以声明 minimum protocol/required capability，
旧 runtime 不支持时 fail closed，不能静默忽略。

建议实施顺序

1. 先修 Parser/Dumper round-trip、Action identity/terminal、sink 生命周期、取消所有权和按 operation 的截图结果；
2. compiler 以 shadow mode 编译现有 V1/V2 corpus，比较新旧结果；
3. 并行引入 BundleManifest、Run/Outcome/Event/Frame/Capability 新 API；
4. 再按真实项目痛点迁移领域 profile；
5. 最后依据生态迁移情况启用 strict mode 和逐项 deprecation。

完整报告里附有 10 个可拆 P0 PR、P1/P2 切片、compiler diagnostics 和跨平台 conformance matrix。本 Discussion 的目的
不是请求一次性实现全部内容，而是先确认以下方向是否值得形成正式 RFC：

1. 是否认同以 compiler/canonical IR 作为 Pipeline 语义中心？
2. 是否认同 RunGraph/Outcome/FrameSnapshot/Capability 作为识别和动作共用骨架？
3. 是否认同通过 legacy adapter 保持兼容，而不静默重解释旧字段？
4. P0 是否应优先处理 round-trip、terminal、callback、cancel ownership 和 frame identity？

欢迎指出已经存在但本报告遗漏的能力、与现有架构冲突的假设，以及更适合拆出的独立 Issue。