# EasyCon 插件化方案 v5 —— 与 Maa v2 设计大纲融合
基于 dev@82555df3 · 参照 docs/Maa-EasyCon-dev维护与v2设计大纲-20261020.md（主人自己的取舍）
与 DeepSeek Harness(Cordis) 插件机制 · 2026-11-03 · 喵月
v1/v2/v3/v4 作废声明见文末。

## 一、定位修正：插件化 = Maa v2 的扩展层，不另起炉灶

主人 10-20 的 v2 大纲已经定了大方向：
- 三入口共存：ECS 直达 / Maa Pipeline + RunEcs / 现有 Flow（兼容入口）；
- 信息→决策→执行三层节点目录；数据边与执行边分开；
- Maa 适配层五组件（CustomController/CustomRecognition/MaaOcr/RunEcs/ResourceGeneration）；
- V2-0 契约冻结 → V2-1 适配器 → V2-2 run.ecs → V2-3 Pipeline/Flow 互操作 → V2-4 决策节点 → V2-5 MCU 公共子集。

**本方案不做的事**：另造 PluginKit 宿主、引入 DI 容器、发明新的贡献模型。
**本方案做的事**：把"插件"定义为 **v2 节点目录与 Maa 适配层的第三方扩展单元**——
插件交付的东西，正是 v2 大纲已经预留挂点的四类对象。

## 二、四个插件点（全部挂在 v2 已规划的挂点上）

| 插件点 | v2 挂点（已有设计） | 插件交付物 | 门槛 |
|---|---|---|---|
| ① Flow 节点插件 | FlowNodeCatalog（节点目录）+ FlowNodeRuntime | 新节点类型：信息/决策/执行（如 MQTT 订阅节点、直播间弹幕节点、串口设备节点） | 节点契约（输入输出 schema、超时、取消、权限），对齐 v2 §4.4 决策节点要求 |
| ② Maa 动作/识别插件 | Maa 适配层（EasyConCustomController/CustomRecognition/MaaOcr/RunEcs 的同类扩展） | CustomAction/CustomRecognition 的第三方实现（新识别算法、新执行器） | 实现 Maa 接口 + 能力租约借用规则（v2 §4.2） |
| ③ ECS 模块包 | ECS 模块系统（.ecs/.ecm/.eci，Merkle 缓存已成熟） | 脚本模块包：lib/ 模块 + extern FFI 声明 + stdlib 扩展函数（如 HTTP_GET、MQTT） | 模块接口哈希兼容；extern 的 DLL 随包分发（路径规则见 ModuleSystem §6） |
| ④ Agent provider | v2 §4.4 预留的 `agent.analyze`/`jev.analyze` 决策节点——**大纲明言 provider 契约待冻结** | agent provider（LLM 分析节点后端）、jev provider（契约冻结后实现） | provider 契约先冻结：超时/取消/输入输出 schema/只读或可执行权限（对齐 DSH ToolDefinition + 审批 waterfall） |

**关键对齐**：④ 正是把 DSH 的 ToolRegistry/SkillRegistry 机制移植进 v2 决策节点——
LLM 工具即 Flow 决策节点，Agent 即可编排的 provider。DSH 的审批 waterfall 也顺带补上 §7 短板"工具无审批闸门"。

## 三、插件宿主（薄层，~300 行，放 Core/Plugins 或独立 EasyCon.PluginKit）

不引 DI 容器；只做四件事，全部服务于 v2 已有组件：
1. **发现与清单**：plugins/<name>/plugin.json（name/version/kind/dependencies/entry/权限声明），
   依赖拓扑排序，环形检测；
2. **注册分发**：按 kind 把插件注册进 FlowNodeCatalog / Maa 适配层 / 模块路径 / provider 表；
3. **可逆生命周期**：注册即登记释放器，Stop 逆序回滚（对齐 cordis effect；能力租约沿用 v2 契约）；
4. **权限门控**：插件声明只读/可执行权限；可执行类（pad.*、run.ecs）挂审批 waterfall（顺治 §7 短板）。

脚本插件的双路径：
- 经典路径：.ecs 模块（C# 双端引擎，.ecm 缓存）；
- IR 路径：Rust IR + 原语（ng 分支）——同一 manifest 两种引擎实现，按宿主选择。
两条路径关系按 v2 大纲：PC 高层执行属 v2 优化方向，MCU 仍走 ECX + C VM；互操作待 V2-3。

## 四、与 ng（Rust 基础核心）的关系

- nextgen/ 的 18 项原语 = Rust 侧原子能力； Flow 画布节点已由 `GET /api/nodes` 提供——
  **Rust 新原语 → 目录登记 → 画布自动出现**，本身就是"原语插件"的现成通路（无需新机制）；
- 协议边界不变：EasyCon/Pokeldn 协议由 dotnet 独家维护直至冻结（主人 11-03 拍板）；
  pi 报告（EasyCon-device-convergence.md）的收敛清单作为阶段 A 任务执行；
- IR 与 ECS 双轨按 v2 大纲：IR 组合子可引用 run.ecs（V2-3 互操作），ECS 仍是源格式。

## 五、阶段（与 V2 大纲对齐）

| 阶段 | 内容 | 对应 v2 |
|---|---|---|
| M-0 契约冻结 | 插件 manifest v1 + provider 契约（agent/jev：超时/取消/schema/权限） | V2-4 的前置 |
| M-1 节点插件 | FlowNodeCatalog 开放注册 + 1 个样板节点插件 | 对应 v2 节点目录 |
| M-2 脚本任务包 | .ecs/IR 任务包 + 触发声明 + ezcon plugins 子命令 | — |
| M-3 Maa 插件 | CustomAction/CustomRecognition 第三方实现接入 | 对应 V2-1/V2-2 |
| M-4 审批 waterfall | 工具执行管线 + ISecretStore | 顺治 §7 短板 |
| 收尾 | 文档、CI、发布 | — |

（与 ng 阶段 A/E 并行推进：A 补原子能力，插件化在 C#/Maa 层演进，互不阻塞。）

## 六、验收
1. 一个第三方节点插件在不改 FlowNodeCatalog 源码的情况下被画布发现并执行；
2. 一个 CustomRecognition 插件保持旧 OpenCV 分值语义（对拍旧阈值）；
3. 一个 .ecs 模块包被 LSP/编译器/运行时三方一致识别；
4. agent.analyze provider 契约冻结文档 + 一个 mock provider 通过超时/取消/权限测试；
5. 审批 waterfall 拒绝高危工具执行有审计记录；
6. 现有 .ecs 脚本、Flow 工作流零回归（黄金回放）。

## 七、明确不做
- 不引 DI 容器；不做插件间安全隔离；不改 1920×1080 标签基准；
- 不把 Maa 原生对象泄漏进 Flow/模块公共接口；
- 不在本轮实现 agent/jev 具体算法（先冻结核同契约）；
- 不把 MCU 能力查询/容量预检/固件协议升级混入插件化。

## 八、v1-v4 作废与延续说明
- v1（main 版，反射填 CapabilitySet）违反装配唯一点红线，作废；
- v2（原料贡献者）覆盖面窄，作废；其"插件不装配、只贡献"思想保留在 §二；
- v3（三面注册）面 A/C 思想并入②④，面 B 归入阶段 E 传输深化后评估；
- v4（平台路线图）的分层盘点、Rust 迁移策略、前端矩阵、验收总表全部并入本文件 §一/四/五/七。