88 lines
7.6 KiB
Markdown
88 lines
7.6 KiB
Markdown
# EasyCon 平台化与插件化整合方案 v5
|
||
|
||
审阅日期：2026-11-03。决策来源：主人当日要求。
|
||
分析基线：dev 82555df3；ng 4f04fd50。当前工作树检出 ng 的 detached HEAD；两者不得混称。
|
||
详细代码证据与影响表见 EasyCon/EasyCon-device-convergence.md。本文件为路线图，不代表实现或真机验收已经完成。
|
||
|
||
## 1. 总目标与边界
|
||
|
||
保持现有 GUI、CLI、ECS 脚本、设备控制和工作流的用户功能，逐步形成 Rust 基础能力平台与 Web 主前端。Avalonia 保留为经典前端，按能力逐项接新服务，不一次重写。
|
||
|
||
Rust 基础平台保持设备协议无关：串口、TCP、蓝牙等是传输后端；EasyCon/Pokeldn 握手、编码、探查、ACK、节流和固件操作归 .NET 单端维护。蓝牙需明确 BLE GATT 与经典串口等不同能力，不能假定都是 TCP 式字节流。
|
||
协议稳定前不在 Rust 维护第二份实现；以后是否迁移协议另行评估，不作为本路线完成条件。
|
||
|
||
## 2. 审阅后修正的现状
|
||
|
||
- 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 或进程协议。
|
||
|
||
## 3. 目标结构
|
||
|
||
Web / 经典 GUI / CLI
|
||
→ 版本化控制 API 与能力目录
|
||
→ 运行管理、配置 Profile、任务/插件注册、审计策略
|
||
→ Rust 媒体/视觉/IR/通用传输，以及 .NET ECS 执行与设备协议提供者
|
||
→ 物理设备与原生库
|
||
|
||
服务只对前端暴露稳定能力和完成语义，不把固件帧格式泄漏进 Web 或工作流。
|
||
借鉴 DSH 的作用域、服务依赖、声明式装配、可逆注册与策略管线；不照搬其所有核心都动态插件化的实现规模。
|
||
|
||
## 4. 分阶段实施与验收
|
||
|
||
### 阶段 0：兼容基线与公共契约
|
||
|
||
整理功能矩阵，分别标记 dev 已有、ng 已有、待补：连接、手柄、采集、OCR、ECS、Flow、固件操作、Agent、编辑器与配置。
|
||
冻结逻辑输入与完成状态，区分 Accepted（已接受）、Written（已写出）、设备确认；会话代次、请求号、取消、超时和释放未确认都进入契约。
|
||
脚本 C#/C VM 使用既有对拍测试；传输和服务用 mock、回环与故障注入，不把 S-01..S-19 当成所有模块的统一测试规范。
|
||
验收：功能矩阵、API 草案和基线用例齐全，现有路径仍可使用。
|
||
|
||
### 阶段 1：协议单端化与传输收敛
|
||
|
||
先从 Rust 上层抽出中立逻辑输入端口，保留 IR 动作和 RunScope 的独占、复位、清理语义。
|
||
推荐过渡方案：.NET 暂时自行持有其协议设备的串口，对 Rust 提供窄逻辑输入服务；Rust 通用传输可供其他消费者使用，但不得同时打开同一设备。
|
||
这是工程建议，不是要求 .NET 永久绕开 Rust 传输。将来确有统一 I/O 需求，再评估让 .NET 协议经 Rust 字节服务读写。
|
||
.NET 的普通 down/up 目前主要表达接受请求，需补逐事务完成回执，不能把入队或 BytesSent 一概当固件确认。
|
||
接好替代提供者、迁移协议测试并通过兼容检查后，才移除 Rust 协议后端和自动探查，再收敛为 easycon-transport；不能先删再补。
|
||
传输层只负责枚举、连接、读写、有限超时、控制线和关闭。DTR/RTS、清缓冲须显式配置；短读短写、背压、断开与代次需明确。
|
||
验收：Rust 无固件编码与握手副本；旧动作和工作流保持兼容；同端点只由一个所有者持有；断链不重放交付未知的数据。
|
||
|
||
### 阶段 2：统一运行宿主与流程
|
||
|
||
将 GUI/CLI 重复的启动、连接、采集和释放编排收敛到 Profile 与运行管理。
|
||
Profile 描述提供者和依赖，不承担协议实现。资源登记即记录释放器，停止按依赖逆序回收；运行取消与清理使用独立生命周期。
|
||
Rust RunScope 和 .NET CapabilityLease 保持各自正确的资源语义，经服务契约衔接；不直接跨语言共享内存对象。
|
||
.NET ScriptHostAssembler 继续是能力装配唯一点，插件只提供候选，不反射改写任意 CapabilitySet。
|
||
验收：启动失败能回滚，停止后无卡键、订阅或连接残留；经典 GUI 与 CLI 功能不退化。
|
||
|
||
### 阶段 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 尚无运行/停止接口。
|
||
采用先接替代提供者再剥离协议的顺序，保留端点独占、复位和清理优先级。详细类型去留与调用点清单保留在审计报告中。
|
||
本轮只整合文档与静态审阅，未改产品代码、未运行构建测试或真实设备操作；兼容性属于各阶段验收目标，不宣称已经验证。
|