From 226ec0cf63454adae34a3a8f1a3b3db201265c51 Mon Sep 17 00:00:00 2001
From: ca1e <ca1e@users.noreply.gitea.local>
Date: Tue, 3 Nov 2026 22:08:30 +0800
Subject: [PATCH] =?UTF-8?q?EasyCon=20=E5=B9=B3=E5=8F=B0=E5=8C=96=20+=20?=
 =?UTF-8?q?=E6=8F=92=E4=BB=B6=E5=8C=96=E6=95=B4=E5=90=88=E6=96=B9=E6=A1=88?=
 =?UTF-8?q?=20v5=EF=BC=88=E5=88=86=E9=98=B6=E6=AE=B5=E8=B7=AF=E7=BA=BF?=
 =?UTF-8?q?=E3=80=81=E5=8D=8F=E8=AE=AE=E5=8D=95=E7=AB=AF=E8=BE=B9=E7=95=8C?=
 =?UTF-8?q?=E3=80=81=E9=AA=8C=E6=94=B6=E6=A0=87=E5=87=86=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..bf19b59
--- /dev/null
+++ b/README.md
@@ -0,0 +1,87 @@
+# 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 尚无运行/停止接口。
+采用先接替代提供者再剥离协议的顺序，保留端点独占、复位和清理优先级。详细类型去留与调用点清单保留在审计报告中。
+本轮只整合文档与静态审阅，未改产品代码、未运行构建测试或真实设备操作；兼容性属于各阶段验收目标，不宣称已经验证。