方案 v5：四插件点挂 Maa v2 + 流程级 F1-F5 + 阶段路线修订

README.md

@@ -1,87 +1,83 @@
-# EasyCon 平台化与插件化整合方案 v5
+# EasyCon 插件化方案 v5 —— 与 Maa v2 设计大纲融合
+基于 dev@82555df3 · 参照 docs/Maa-EasyCon-dev维护与v2设计大纲-20261020.md（主人自己的取舍）
+与 DeepSeek Harness(Cordis) 插件机制 · 2026-11-03 · 喵月
+v1/v2/v3/v4 作废声明见文末。
 
-审阅日期：2026-11-03。决策来源：主人当日要求。
-分析基线：dev 82555df3；ng 4f04fd50。当前工作树检出 ng 的 detached HEAD；两者不得混称。
-详细代码证据与影响表见 EasyCon/EasyCon-device-convergence.md。本文件为路线图，不代表实现或真机验收已经完成。
+## 一、定位修正：插件化 = Maa v2 的扩展层，不另起炉灶
 
-## 1. 总目标与边界
+主人 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 公共子集。
 
-保持现有 GUI、CLI、ECS 脚本、设备控制和工作流的用户功能，逐步形成 Rust 基础能力平台与 Web 主前端。Avalonia 保留为经典前端，按能力逐项接新服务，不一次重写。
+**本方案不做的事**：另造 PluginKit 宿主、引入 DI 容器、发明新的贡献模型。
+**本方案做的事**：把"插件"定义为 **v2 节点目录与 Maa 适配层的第三方扩展单元**——
+插件交付的东西，正是 v2 大纲已经预留挂点的四类对象。
 
-Rust 基础平台保持设备协议无关：串口、TCP、蓝牙等是传输后端；EasyCon/Pokeldn 握手、编码、探查、ACK、节流和固件操作归 .NET 单端维护。蓝牙需明确 BLE GATT 与经典串口等不同能力，不能假定都是 TCP 式字节流。
-协议稳定前不在 Rust 维护第二份实现；以后是否迁移协议另行评估，不作为本路线完成条件。
+## 二、四个插件点（全部挂在 v2 已规划的挂点上）
 
-## 2. 审阅后修正的现状
+| 插件点 | 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） |
 
-- ng/device 目前存在串口传输和两套协议实现，不是已经完成的通用串口/TCP/蓝牙平台；TCP 与蓝牙通用后端尚待补充。
-- ng 已有媒体、视觉原语、IR、RunScope 和项目运行宿主；Web 控制台具备设备、媒体与工作流选择接口，尚无完整工作流运行/停止接口。
-- .NET Flow 的 /api/nodes 不能直接当作 Rust 原语目录；前端自动呈现需要先建设统一描述契约及适配器。
-- ECS 的 .ecm 模块系统是编译模块机制，不等于宿主插件系统；现有脚本可以包装为任务包，但需验证配置、资源路径和触发兼容，不能称零成本迁移。
-- BuiltinMap 是运行期接缝，不证明新增名字就能通过编译、链接与 MCU 执行；新增脚本函数须贯通声明、绑定、链接和宿主分发，PC 专属函数需明确拒绝 MCU 目标。
-- Rust crate 内注册属于内置扩展，不等于动态插件。Rust 原生 ABI 不稳定，初期不承诺动态加载 Rust DLL；如确需运行时扩展，另评估稳定 C ABI 或进程协议。
+**关键对齐**：④ 正是把 DSH 的 ToolRegistry/SkillRegistry 机制移植进 v2 决策节点——
+LLM 工具即 Flow 决策节点，Agent 即可编排的 provider。DSH 的审批 waterfall 也顺带补上 §7 短板"工具无审批闸门"。
 
-## 3. 目标结构
+## 三、插件宿主（薄层，~300 行，放 Core/Plugins 或独立 EasyCon.PluginKit）
 
-Web / 经典 GUI / CLI
-→ 版本化控制 API 与能力目录
-→ 运行管理、配置 Profile、任务/插件注册、审计策略
-→ Rust 媒体/视觉/IR/通用传输，以及 .NET ECS 执行与设备协议提供者
-→ 物理设备与原生库
+不引 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 短板）。
 
-服务只对前端暴露稳定能力和完成语义，不把固件帧格式泄漏进 Web 或工作流。
-借鉴 DSH 的作用域、服务依赖、声明式装配、可逆注册与策略管线；不照搬其所有核心都动态插件化的实现规模。
+脚本插件的双路径：
+- 经典路径：.ecs 模块（C# 双端引擎，.ecm 缓存）；
+- IR 路径：Rust IR + 原语（ng 分支）——同一 manifest 两种引擎实现，按宿主选择。
+两条路径关系按 v2 大纲：PC 高层执行属 v2 优化方向，MCU 仍走 ECX + C VM；互操作待 V2-3。
 
-## 4. 分阶段实施与验收
+## 四、与 ng（Rust 基础核心）的关系
 
-### 阶段 0：兼容基线与公共契约
+- 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 仍是源格式。
 
-整理功能矩阵，分别标记 dev 已有、ng 已有、待补：连接、手柄、采集、OCR、ECS、Flow、固件操作、Agent、编辑器与配置。
-冻结逻辑输入与完成状态，区分 Accepted（已接受）、Written（已写出）、设备确认；会话代次、请求号、取消、超时和释放未确认都进入契约。
-脚本 C#/C VM 使用既有对拍测试；传输和服务用 mock、回环与故障注入，不把 S-01..S-19 当成所有模块的统一测试规范。
-验收：功能矩阵、API 草案和基线用例齐全，现有路径仍可使用。
+## 五、阶段（与 V2 大纲对齐）
 
-### 阶段 1：协议单端化与传输收敛
+| 阶段 | 内容 | 对应 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、发布 | — |
 
-先从 Rust 上层抽出中立逻辑输入端口，保留 IR 动作和 RunScope 的独占、复位、清理语义。
-推荐过渡方案：.NET 暂时自行持有其协议设备的串口，对 Rust 提供窄逻辑输入服务；Rust 通用传输可供其他消费者使用，但不得同时打开同一设备。
-这是工程建议，不是要求 .NET 永久绕开 Rust 传输。将来确有统一 I/O 需求，再评估让 .NET 协议经 Rust 字节服务读写。
-.NET 的普通 down/up 目前主要表达接受请求，需补逐事务完成回执，不能把入队或 BytesSent 一概当固件确认。
-接好替代提供者、迁移协议测试并通过兼容检查后，才移除 Rust 协议后端和自动探查，再收敛为 easycon-transport；不能先删再补。
-传输层只负责枚举、连接、读写、有限超时、控制线和关闭。DTR/RTS、清缓冲须显式配置；短读短写、背压、断开与代次需明确。
-验收：Rust 无固件编码与握手副本；旧动作和工作流保持兼容；同端点只由一个所有者持有；断链不重放交付未知的数据。
+（与 ng 阶段 A/E 并行推进：A 补原子能力，插件化在 C#/Maa 层演进，互不阻塞。）
 
-### 阶段 2：统一运行宿主与流程
+## 六、验收
+1. 一个第三方节点插件在不改 FlowNodeCatalog 源码的情况下被画布发现并执行；
+2. 一个 CustomRecognition 插件保持旧 OpenCV 分值语义（对拍旧阈值）；
+3. 一个 .ecs 模块包被 LSP/编译器/运行时三方一致识别；
+4. agent.analyze provider 契约冻结文档 + 一个 mock provider 通过超时/取消/权限测试；
+5. 审批 waterfall 拒绝高危工具执行有审计记录；
+6. 现有 .ecs 脚本、Flow 工作流零回归（黄金回放）。
 
-将 GUI/CLI 重复的启动、连接、采集和释放编排收敛到 Profile 与运行管理。
-Profile 描述提供者和依赖，不承担协议实现。资源登记即记录释放器，停止按依赖逆序回收；运行取消与清理使用独立生命周期。
-Rust RunScope 和 .NET CapabilityLease 保持各自正确的资源语义，经服务契约衔接；不直接跨语言共享内存对象。
-.NET ScriptHostAssembler 继续是能力装配唯一点，插件只提供候选，不反射改写任意 CapabilitySet。
-验收：启动失败能回滚，停止后无卡键、订阅或连接残留；经典 GUI 与 CLI 功能不退化。
+## 七、明确不做
+- 不引 DI 容器；不做插件间安全隔离；不改 1920×1080 标签基准；
+- 不把 Maa 原生对象泄漏进 Flow/模块公共接口；
+- 不在本轮实现 agent/jev 具体算法（先冻结核同契约）；
+- 不把 MCU 能力查询/容量预检/固件协议升级混入插件化。
 
-### 阶段 3：插件体系与 Agent 策略
-
-优先支持任务包（ECS 或 IR 工作流加资源/配置）、提供者模块、Agent 工具/技能。
-manifest 声明 ID、版本、宿主 API 范围、依赖、平台/运行目标、配置及能力需求；不同执行引擎通过适配器接入，不承诺相同入口直接跨语言执行。
-统一注册中心记录所有者、依赖和释放器。依赖缺失/循环、名字冲突、启动失败有明确诊断；运行中使用的提供者不得强行卸载。
-工具统一走校验→策略/审批→执行→审计，Agent 循环消费接口；密钥存储作为独立平台服务。
-先静态内置与启动期加载，后评估 C# ALC 热卸载；ALC 是加载边界，不是安全沙箱。同进程插件的能力声明也不能阻止其绕过宿主直接访问系统。
-验收：任务包安装/停用可逆；一个 OCR 提供者或工具扩展不改主流程；审批拒绝不执行工具。
-
-### 阶段 4：Web 功能逐项迁移与经典前端并存
-
-先接设备管理、预览、任务运行/取消、日志与配置，再迁脚本编辑/LSP、标签编辑、Flow 画布、Agent 和插件管理。
-补完整的工作流运行/停止/状态 API；能力目录由 .NET Flow 与 Rust 原语分别适配到统一描述，前端据目录生成可支持的控件。
-经典 GUI 先保留原执行路径；按垂直功能逐项改为同一服务的客户端，避免同时大改全部 UI 与后端。
-验收：逐项对照阶段 0 的功能矩阵；Web 已迁功能通过等价测试后才切默认入口，经典前端可独立回退。
-
-### 阶段 5：扩充原子能力与交付
-
-按需求补窗口采集、PP-OCR 检测、TypeText、TCP/蓝牙等能力，不要求先补完才开始平台迁移。
-完善服务版本协商、原生依赖打包、跨平台 CI、升级回退和实物测试；协议仍由 .NET 单端维护。
-验收：协议、运行宿主与原生依赖分别版本化；发布包包含必要提供者；未实测平台和硬件明确列出。
-
-## 5. 本轮审阅结论与限制
-
-pi 报告已阅读，并抽查 transport.rs、PadSession.cs、web-host 路由等关键证据：当前 Rust 只有串口、.NET 接受/写出语义存在差异、Web 尚无运行/停止接口。
-采用先接替代提供者再剥离协议的顺序，保留端点独占、复位和清理优先级。详细类型去留与调用点清单保留在审计报告中。
-本轮只整合文档与静态审阅，未改产品代码、未运行构建测试或真实设备操作；兼容性属于各阶段验收目标，不宣称已经验证。
+## 八、v1-v4 作废与延续说明
+- v1（main 版，反射填 CapabilitySet）违反装配唯一点红线，作废；
+- v2（原料贡献者）覆盖面窄，作废；其"插件不装配、只贡献"思想保留在 §二；
+- v3（三面注册）面 A/C 思想并入②④，面 B 归入阶段 E 传输深化后评估；
+- v4（平台路线图）的分层盘点、Rust 迁移策略、前端矩阵、验收总表全部并入本文件 §一/四/五/七。