From 0aeb7ce083b00f17ed0929099fd2e9e680cd9816 Mon Sep 17 00:00:00 2001 From: ca1e Date: Wed, 4 Nov 2026 10:39:45 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B9=E6=A1=88=20v5=EF=BC=9A=E5=9B=9B?= =?UTF-8?q?=E6=8F=92=E4=BB=B6=E7=82=B9=E6=8C=82=20Maa=20v2=20+=20=E6=B5=81?= =?UTF-8?q?=E7=A8=8B=E7=BA=A7=20F1-F5=20+=20=E9=98=B6=E6=AE=B5=E8=B7=AF?= =?UTF-8?q?=E7=BA=BF=E4=BF=AE=E8=AE=A2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 136 ++++++++++++++++++++++++++---------------------------- 1 file changed, 66 insertions(+), 70 deletions(-) diff --git a/README.md b/README.md index bf19b59..a28ad77 100644 --- a/README.md +++ b/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//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 迁移策略、前端矩阵、验收总表全部并入本文件 §一/四/五/七。