From b4aaba4dbe3dbf7f7c38c842b166951f4dd3b95d Mon Sep 17 00:00:00 2001 From: yu <1919727607@qq.com> Date: Fri, 6 Nov 2026 09:43:46 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20V2=20=E6=8B=8D=E6=9D=BF=20ADR-R3(C#?= =?UTF-8?q?=E6=A1=8C=E9=9D=A2=E6=89=A7=E8=A1=8C=E8=B7=AF=E7=BA=BF)?= =?UTF-8?q?=E4=B8=8EADR-R6(=E6=8C=89=E8=83=BD=E5=8A=9B=E5=9F=9F=E6=8B=86?= =?UTF-8?q?=E5=88=86=E9=83=A8=E7=BD=B2)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .workbuddy/memory/2026-11-05.md | 5 +++++ docs/rpa-core-migration-guide-v2.md | 27 +++++++++++++++++---------- 2 files changed, 22 insertions(+), 10 deletions(-) diff --git a/.workbuddy/memory/2026-11-05.md b/.workbuddy/memory/2026-11-05.md index 470b99f..2bf7ac2 100644 --- a/.workbuddy/memory/2026-11-05.md +++ b/.workbuddy/memory/2026-11-05.md @@ -281,3 +281,8 @@ - RPA 侧确认：createEngine() 仍无注入参数、desktop.ts:9 模块加载时捕获 driver（非 win32 import 即抛）、5 处动态 electron import、check-deps 正则盲区实测、catalog 3 个 platformTag=1 脏值 - 交付：docs/rpa-core-migration-guide-v2.md（架构图/模块对应表/接入点 A1-A10 七要素/0-6 阶段/10 风险/10 验收/6 ADR+3 Q 待确认）+ v2-diff.md（V1 逐项判定 + 审查报告 12 条修正） - 提交 a8f75c6 + 收录审查报告一笔 + +## ADR-R3/R6 拍板（11-06 09:40） +- 用户确认两项关键决策：①桌面点击逻辑改写进对面 C# 原生进程（PowerShell 通道仅限 demo）；②按能力域拆分部署（纯 Node 域→backend plugin-worker，桌面/视觉/弹窗域→用户电脑 Electron 宿主） +- V2 文档已更新：§0 结论、§10 拆"已拍板/待评审"、A6 改哪侧、阶段 0 范围、风险 R1/R2 降级为已缓解 +- 剩余 4 ADR（R1/R2/R4/R5）+ 3 Q 留待与对面对评审 diff --git a/docs/rpa-core-migration-guide-v2.md b/docs/rpa-core-migration-guide-v2.md index e053612..6b37486 100644 --- a/docs/rpa-core-migration-guide-v2.md +++ b/docs/rpa-core-migration-guide-v2.md @@ -17,9 +17,9 @@ 4. **两条硬边界不变且加严**（用户红线）： - 所有带副作用的能力必须经 capability-gateway（授权→租约→幂等→执行→审计），**不得绕行**； - rpa-core **不得依赖 Electron 主进程**（当前仍有 5 处动态 import，是接入阻塞项）。 -5. **新增 6 项 ADR 待确认**（见 §10），其中最关键的两项： - - **ADR-R3 桌面执行安全模型冲突**：RPA 驱动 = spawn 任意 PowerShell 脚本；对面安全模型 = 受信 C# 原生进程 + `*.exe` 白名单 + 明文约束"不执行任意 PowerShell"。必须二选一，不能装作兼容。 - - **ADR-R6 部署拓扑**：backend 执行面跑在服务器（PostgreSQL/容器），而 RPA 桌面能力只能在用户 Windows 桌面交互会话里跑（对面自己也把 windows-runner 留宿主）。rpa-core 的哪些部分跑 backend、哪些跑宿主桌面进程，是迁移前必须定的大前提。 +5. **6 项 ADR 中最关键的 2 项已拍板（2026-11-06）**，其余 4 项带去对面对评审（见 §10）： + - **✅ 已拍板 ADR-R3 桌面执行安全模型冲突**：RPA 驱动原为 spawn 任意 PowerShell 脚本，与对面"受信 C# 原生进程 + `*.exe` 白名单 + 明文约束不执行任意 PowerShell"正面冲突。决定：**接受 C# 路线**——把 RPA 五域执行逻辑移植进 windows-runner 原生进程（扩展 actuate 半边），PowerShell 通道仅限本 demo 使用。 + - **✅ 已拍板 ADR-R6 部署拓扑**：服务器没有鼠标/键盘/屏幕，桌面与视觉能力物理上无法在 backend 跑（对面 windows-runner 同样留宿主）。决定：**按能力域拆分部署**——纯 Node 域进 backend plugin-worker，桌面/视觉/弹窗域装进用户电脑的 Electron 宿主，同一份 rpa-core 按 PLATFORM_GROUPS 分组加载，不维护两份代码。 --- @@ -226,7 +226,7 @@ - **AE 位置**：`computer-control`（仅契约+3 纯函数）、`windows-plugin`（WindowsRunner{click;type;readText;snapshot} 无实现、native-observer.ts observe-only）、`services/windows-runner/native/*.cs`（FlaUI UIA3 observe-only）。 - **兼容性**：**安全模型冲突**——RPA 驱动 spawn 任意 PowerShell；对面白名单只许 `*.exe`、明文"不执行任意 PowerShell"、证据要求 SHA-256。 - **问题**：RPA 的执行半边（click/type）正是对面缺口，但实现方式过不了对面安全门。 -- **改哪侧**：双侧（视 ADR-R3）。 +- **改哪侧**：双侧（ADR-R3 已拍板：C# 扩展 actuate，见 §10）。 - **方案**：推荐——把 RPA WindowsDriver 的五域执行逻辑**移植进 windows-runner 的 C# 原生进程**（ FlaUI/CGEvent 等价实现 + 现成协议加 actuate 操作），RPA 侧 driver 抽象保留、Windows 实现改为可指向"原生进程通道"或"本地 PowerShell 通道"（后者仅 demo 使用，明确标注不走宿主治理）；策略校验/证据断言复用对面 `assertComputerActionAllowed`/`assertComputerResultEvidence`。 - **验收**：click/type 经策略校验（白名单进程/窗口、allowInput）+ 证据落盘；宿主拒绝时零副作用；同目标 observe→actuate→observe 闭环一致。 @@ -278,7 +278,7 @@ | 阶段 | 内容 | 前置 | 验收门 | |---|---|---|---| -| **0 事实确认**（双侧，1 次评审会） | 过 §10 六项 ADR；对面确认 CapabilityDefinition 平台字段、utilityExtended 对应 scope | 无 | ADR 有书面结论 | +| **0 事实确认**（双侧，1 次评审会） | 过 §10 剩余 4 项 ADR（R3/R6 已拍板）+ 3 项 Q；对面确认 CapabilityDefinition 平台字段、utilityExtended 对应 scope；同步 R3/R6 结论给对面并预估 C# actuate 扩展量 | 无 | ADR 有书面结论 | | **1 RPA 侧收口**（本仓库） | A3 四件（取消贯通/状态映射/重试元数据/Graph Validator）+ A1 注入参数 + A9（Electron 残留、check-deps 升级、依赖闭包）+ A2 的 ADR 固化 + catalog 脏值清洗 + rpa-cli 重写（显式注册、经 engine 取 handler） | 无 | 审查报告 §7 第一/二阶段清单全绿；纯 Node 环境 Core 全量加载 | | **2 迁入与 adapter 骨架** | git subtree 迁包改名 @agent-worker/rpa-core；bun@1.4.3 test 冒烟（exceljs/pdf/PowerShell 编码）；新建 @agent-worker/rpa-adapter（CapabilityRunner + ref 映射 + 状态映射表）；demo 侧冻结 | 阶段 1 + ADR-R1/R2 | bun test 纯逻辑全绿；未经 gateway 不可达 handler；719 映射完整性测试 | | **3 垂直切片** | 一个文件能力 + 一个 HTTP 能力走通：workflow-engine create/start → gateway authorize → adapter → rpa-core handler → 事件/证据回传 → cancel 中途取消；方案 A（rpa.flow.execute 整体注册） | 阶段 2 | 取消/审批/审计全链有证据；对面 Run 终态与 RunResult 一致 | @@ -296,8 +296,8 @@ | # | 风险 | 等级 | 缓解 | |---|---|---|---| -| R1 | 桌面安全模型冲突（PowerShell vs 原生进程白名单）导致桌面能力无法过审 | 高 | 阶段 0 就把 ADR-R3 定死；并行准备 C# 移植估算 | -| R2 | 部署拓扑错配：rpa-core 整包进 backend，但桌面/视觉能力只能在用户桌面跑 | 高 | ADR-R6 先定：纯 Node 能力 → plugin-worker；桌面/视觉 → 宿主桌面进程加载同一包的子集 | +| R1 | ~~桌面安全模型冲突~~ → **已缓解（ADR-R3 拍板 C# 路线）**：残余风险转为 C# 移植工作量与工期 | 中 | 阶段 0 与对面确认 actuate 扩展量；RPA 五域逻辑先行整理成移植清单 | +| R2 | ~~部署拓扑错配~~ → **已缓解（ADR-R6 拍板按域拆分）**：残余风险为宿主进程加载子集的工程实现 | 中 | 阶段 2 按 PLATFORM_GROUPS 分组做宿主子集加载验证 | | R3 | Registry 全局单例在多租户 backend 的隔离缺陷 | 高 | 短期按 ADR-R1 限定部署模型；长期 engine-scoped registry 列入 backlog | | R4 | 浏览器双路径重复投资 | 中 | ADR-R4 一票定路径；未选路径冻结不投入 | | R5 | 719 能力的治理映射与元数据补齐工作量失控 | 中 | 脚本从 catalog 生成初稿 + 人工只审高风险域；分批（阶段 5） | @@ -322,16 +322,23 @@ --- -## 10. 待确认清单（ADR，不猜测） +## 10. 决策与待确认清单 + +### 已拍板（2026-11-06，本方负责人确认） + +| ADR | 问题 | 决定 | +|---|---|---| +| R3 | 桌面执行安全模型：RPA PowerShell 驱动 vs 对面"受信 C# 原生进程"红线 | **C# 扩展 actuate**：把 RPA 五域执行逻辑移植进 windows-runner 原生进程；PowerShell 通道仅限本 demo，不进宿主 | +| R6 | 部署拓扑：rpa-core 各域跑在哪 | **按能力域拆分部署**：纯 Node 域→backend plugin-worker；桌面/视觉/弹窗域→用户电脑 Electron 宿主；同一包按 PLATFORM_GROUPS 分组加载，不维护两份代码 | + +### 待对面对评审确认（不猜测） | ADR | 问题 | 建议倾向 | |---|---|---| | R1 | Registry 作用域：backend 是否多租户/多权限域并存？ | 短期全局表 + 语义真实化；长期 engine-scoped | | R2 | 集成形态：RPA 流程=单个 capability（方案 A）还是节点=step 映射（方案 B）？ | 方案 A 起步 | -| R3 | 桌面执行安全模型：RPA PowerShell 驱动 vs 对面"受信 C# 原生进程"红线 | C# 扩展 actuate，PowerShell 通道仅限 demo | | R4 | 浏览器双路径：Playwright（自管）vs RPA CDP（接管用户浏览器/登录态） | 宿主动作走 Playwright；RPA 路径作为接管场景第二 runner | | R5 | 包消费方式：确认 Bun 源码消费 + bun 版本矩阵（1.4.3？） | 源码消费（与对面现状一致） | -| R6 | 部署拓扑：rpa-core 各域分别跑在 backend plugin-worker 还是宿主桌面进程？ | 纯 Node 域→backend；桌面/视觉/弹窗域→宿主进程（同一包按域加载） | | Q1 | CapabilityDefinition 是否需要 platform 字段（对面清单未见） | 待对面确认 | | Q2 | utilityExtended（命令执行）对应哪个 PermissionScope（13 项中无直接对应） | 待对面确认（可能需扩 scope） | | Q3 | human-dialog 弹窗宿主落点：desktop Electron 窗口 or 宿主网页？ | 待确认（倾向 Electron 桌面宿主） |