67 lines
10 KiB
Markdown
67 lines
10 KiB
Markdown
|
# 迁入指南 V1 → V2 差异清单（含审查报告修正记录）
|
|||
|
|
|
|||
|
|
> 配套文档：`docs/rpa-core-migration-guide-v2.md`（V2 正文）。
|
|||
|
|
> 本文记录三件事：① V1 各断言在真实源码下的判定；② 审查报告（docs/RPA-Review-Full.md）与真实源码不一致处的修正及理由；③ V2 新增内容清单。
|
|||
|
|
> 核查基线：2026-11-06 双侧真实工作区源码。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 一、V1（rpa-core-migration-guide.md）逐项判定
|
|||
|
|
|
|||
|
|
分类口径：**保留** / **需要修改** / **过时或不再适用** / **尚未实现（V1 写成了现状或反之）**。
|
|||
|
|
|
|||
|
|
| # | V1 断言/内容 | 判定 | 真实源码依据（2026-11-06） |
|
|||
|
|
|---|---|---|---|
|
|||
|
|
| 1 | 包现状：719 能力、34 域、宿主桥 4 方法、五域 Driver | **保留** | 实测 capabilityCount()=719；DOMAINS/PLATFORM_GROUPS 34 域；host-bridge.ts 仍 4 方法+SubflowSource 2 方法 |
|
|||
|
|
| 2 | "完全不依赖 Electron，check:deps 谁加就报错" | **过时（不实）** | vision.ts:18,66,432 + cv-vision.ts:51,213 共 5 处动态 `import("electron")`；check-deps.mjs:20 正则 `import\s+` 对 `import("electron")` 零匹配（实测），护栏从未能拦住 |
|
|||
|
|
| 3 | "npm run rpa-cli 证明能独立跑" | **需要修改** | rpa-cli.ts:25 仍有副作用全量 import、:53-59 全局 getHandler 直调，只能证明能力可跑，不能证明注入/隔离/无 Electron |
|
|||
|
|
| 4 | 第 -1 步："对面 7 个契约包每个只有 1-9 个声明文件，都是空壳" | **过时（核心叙事失效）** | workflow-engine 25 文件完整实现；capability-gateway 321 行实现；browser-plugin 已接 playwright-core（358 行 Runner）；windows-plugin 新增 native-observer.ts（292 行）；runtime-governance 有 readiness 投影；windows-runner 17 文件（C# FlaUI observe-only）。仍空壳的只剩 computer-control Runner 与 WindowsRunner.click/type |
|
|||
|
|
| 5 | "迁入本质 = 拿 rpa-core 实现去填对面的契约" | **需要修改** | 改为"接底座 + 让路"：不重复造状态机/浏览器/UIA 观察，RPA 补的是执行半边（WindowsRunner.click/type、CDP 接管场景）与 719 能力规模 |
|
|||
|
|
| 6 | 第 0 步作业 #2"重新生成 catalog 让 platformTag 生效（当时没生效）" | **已完成（V1 写成待办）** | 2026-11-05 已重生成：win32=687 / null=326；残留 3 个数字 1 脏值待清洗 |
|
|||
|
|
| 7 | 第 0 步作业 #1 Bun 冒烟 | **尚未实现** | bun 未安装，未跑过任何 Bun test |
|
|||
|
|
| 8 | 第 0 步作业 #3 注册方式决策 | **需要修改** | 并入 ADR-R1（全局表 vs engine-scoped）；rpa-cli 仍用旧方式 |
|
|||
|
|
| 9 | 第 1 步：搬包位置 `code/backend/packages/rpa-core`、改名 `@agent-worker/rpa-core`、git subtree、demo 冻结 | **保留** | backend package.json workspaces 含 `packages/*`、全包 `@agent-worker/*` 前缀、`workspace:*` 源码消费——核实无误 |
|
|||
|
|
| 10 | 第 2 步 A：capability-gateway"对照后改，不自建 allowlist" | **需要修改** | gateway 已实现（authorize/execute/租约 60s/幂等/高影响审批），工作是写 adapter 而非"对照设计" |
|
|||
|
|
| 11 | 第 2 步 A：workflow-engine"状态模型对齐" | **需要修改** | 对面状态机已实现并稳定（含 waiting_approval/waiting_user/unknown 态）；RPA 侧缺 waiting_user/unknown；集成形态二选一（ADR-R2） |
|
|||
|
|
| 12 | 第 2 步 A：computer-control/windows-plugin "五域 driver 与契约对照" | **需要修改** | 契约依旧（Runner 无实现），但出现新硬约束：对面安全模型禁止任意 PowerShell（native-observer.ts 约束注释 + *.exe 白名单）→ ADR-R3 |
|
|||
|
|
| 13 | 第 2 步 B：内置浏览器"最大变数，对面还没定型" | **过时（变数已收敛）** | PlaywrightBrowserRunner 已实现（白名单三重检+证据）；变数变为"双路径取舍"（ADR-R4） |
|
|||
|
|
| 14 | 第 2 步 B：宿主桥 4 方法 + SubflowSource 2 方法注入 | **保留**（落点补充） | 对面 desktop 主进程无现成宿主桥，但有等价物（identity-login-window/execution-context/zoom.ts）；新增 ScreenCaptureHost 注入面（vision 迁移所需） |
|
|||
|
|
| 15 | 第 2 步 B："AI 能力接对面模型网关" | **保留并具体化** | model-gateway 已实现（stream + ModelControlPlane 每次调用授权）；RPA ai-service 仍读 HostBridge.loadAiConfig，改造点明确 |
|
|||
|
|
| 16 | 第 3 步 7 条验收 | **需要修改** | 扩充为 10 条总验收（加 gateway 零调用、取消传播、双 Engine 隔离、Graph Validator、纯 Node 加载） |
|
|||
|
|
| 17 | 三端计划"搬家前 5 件小事" | **已完成（V1 写成待办）** | ① PLATFORM_GROUPS 单一源+守卫测试 ✅ ② 驱动自动选+platform_unsupported ✅ ③ COM 分组核查 ✅ ④ 5 个测试补 skipIf ✅ ⑤ driver/platform.ts 收拢 ✅（2026-11-05 落地） |
|
|||
|
|
| 18 | 三端计划"搬家之后按平台写驱动" | **保留**（补约束） | 驱动实现统一走 ADR-R3 原生通道；Linux 容器不能跑桌面 Runner（对面 README 约束） |
|
|||
|
|
| 19 | 附 10 决策 #2"保留全局注册表"、#9"注册双入口过渡" | **需要修改（重开 ADR）** | 与对面多租户/插件模型冲突，重开 ADR-R1；其余 8 个决策维持 |
|
|||
|
|
| 20 | "浏览器：外部浏览器(CDP)进包，内置浏览器留宿主"（决策 5） | **保留**（补 ADR） | 仍成立，但需 ADR-R4 明确与 Playwright 的关系 |
|
|||
|
|
|
|||
|
|
## 二、审查报告（RPA-Review-Full.md）与真实源码不一致的修正
|
|||
|
|
|
|||
|
|
以真实源码为准，逐条记录修正理由：
|
|||
|
|
|
|||
|
|
| # | 审查报告断言 | 真实源码（2026-11-06） | 修正理由 |
|
|||
|
|
|---|---|---|---|
|
|||
|
|
| 1 | §3 P1-NEW-03 / 附录 P0-03：Engine 完全无注入，`driver` 固定 `new WindowsDriver()` | **部分过时**：driver 已改惰性 getter，非 win32 抛 platform_unsupported（engine.ts:47-61 + error-codes.ts:43 + engine-driver.test.ts） | 报告基于 11-06 前的 ZIP 快照；此后落地了"驱动按平台自动选择"。但"createEngine() 无注入参数"这一半仍属实 |
|
|||
|
|
| 2 | §8.3 / 附录 P1-01：catalog 1016 项里 1013 项 platformTag=null、3 项数字 1，"平台标记从未生效" | **部分过时**：现为 win32=687 / null=326 / 数字 1=3 | PLATFORM_GROUPS 单一源落地后重生成过 catalog。"3 个数字 1 脏值透传（build-catalog.mjs:246 对 truthy 不清洗）"仍属实，保留为待办 |
|
|||
|
|
| 3 | §12.4："跟随前台标签页无条件取 pages[0]" | **需限定范围**：followForegroundTab 本身仍取 pages[0]（session.ts:211），但 withElementOnce/locateOnce 已改两段式（当前页优先、失败才跟随，:296-307/:518-523）；evaluate 默认 follow=true 仍会先切 | 该缺陷的暴露面已从"所有元素操作"缩小到"跟随函数本身+evaluate 默认路径"，严重度下调，但未根除 |
|
|||
|
|
| 4 | §6 P0 行"Engine 无 Driver 注入；能力使用 defaultEngine" | **属实且更严重**：desktop.ts:9 在模块加载时捕获 `defaultEngine.driver`，非 win32 上 import 即抛错（比报告写的"使用时才碰到"更早暴露） | 复核确认，问题加重一档 |
|
|||
|
|
| 5 | §3 P1-NEW-02：包依赖缺 @napi-rs/canvas/pdfjs-dist/@cantoo/pdf-lib | **属实（复核确认）**：rpa-core/package.json:17-32 仍缺这 3 项，main/exports 直指 src | 无修正，维持 P1 |
|
|||
|
|
| 6 | §12.1：locate 与 withElement 对 xpath/Shadow DOM 支持不一致 | **属实（复核确认）**：locateOnce :465-517 仅 text/aria/else 三分支 | 无修正，维持 P1 |
|
|||
|
|
| 7 | §12.3：CDP send() 无单命令超时/AbortSignal | **属实（复核确认）**：transport.ts:96-118 | 无修正，维持 P1 |
|
|||
|
|
| 8 | 附录 P2-04：AI 请求无调用方 signal | **属实（复核确认）**：ChatCompletionOptions（ai-service.ts:39-48）无 signal 字段 | 无修正，维持 P2 |
|
|||
|
|
| 9 | §12.5：桌面拾取无 AbortSignal | **属实（复核确认）**：desktop-pick.ts 全文零 signal 命中（取消是热键+轮询自有机制） | 无修正，维持 P1 |
|
|||
|
|
| 10 | §2.2 "尚未完成 Agent-Employee 真实契约的编译级对接；当前没有 Agent-Employee 目标仓库真实源码作为本轮输入" | **已过时**：本机已有 D:/code/Agent-Employee 真实工作区，V2 已完成逐接口核查 | V2 的核查基线即基于该仓库 |
|
|||
|
|
| 11 | 附录 §8 ADR 表"Driver 契约：RPA Driver 是否直接实现 computer-control？建议对齐宿主契约" | **升级为阻塞项**：对面的安全约束（禁任意 PowerShell、*.exe 白名单）与 RPA 驱动实现方式正面冲突，不是"对齐一下"而是二选一（V2 ADR-R3） | native-observer.ts 设计约束注释明示"不执行任意 PowerShell"，为 V1 快照中没有的新事实 |
|
|||
|
|
| 12 | 报告整体：审查对象是资料库 ZIP 快照（无 node_modules、未装依赖） | **V2 基线升级**：真实工作区 + 依赖已装 + 可实测（正则盲区构造用例、catalog python 统计、tsx 实测 capabilityCount=719） | 结论可信度提升；仍保留"未做实机 E2E/联调"的边界 |
|
|||
|
|
|
|||
|
|
## 三、V2 相对 V1 的新增内容
|
|||
|
|
|
|||
|
|
1. **双侧事实清单**（V2 §2/§3）：24 项 RPA 侧 + 12 项宿主侧，全部带 `文件:行号` 证据与状态标记——V1 无此层。
|
|||
|
|
2. **宿主侧巨变披露**：plugin-registry/plugin-worker（对面真实插件宿主）、model-gateway、Java 控制面（Spring Boot 454 文件、OpenAPI+Outbox、端口分工）、evidence-store——V1 完全未提。
|
|||
|
|
3. **6 项 ADR + 3 项 Q 待确认**（V2 §10），其中 R3（桌面安全模型）、R6（部署拓扑）为 V1 未识别的新阻塞项。
|
|||
|
|
4. **逐接入点七要素详单**（V2 §7，A1-A10）：RPA 位置/AE 位置/兼容性/问题/改哪侧/方案/验收——V1 只有粗粒度对齐表。
|
|||
|
|
5. **模块对应关系表**（V2 §6）：双侧模块一一对应 + 关系 + 现状。
|
|||
|
|
6. **分阶段实施计划**（V2 §8）：0-6 阶段每阶段带硬验收门；新增"阶段 0 事实确认会"。
|
|||
|
|
7. **风险清单 10 项**（V2 §9）：新增 R1 安全模型冲突、R2 部署拓扑、R10 底座演进过期风险。
|
|||
|
|
8. **能力治理映射方案**：719 能力 ↔ PermissionScope 13 项的映射生成策略（脚本从 catalog 生成 + 高风险域人工审）——V1 只说"不自建 allowlist"。
|
|||
|
|
9. **宿主桥注入面扩容预案**：4 方法 → +ScreenCaptureHost/DisplayCoordinateService（vision 迁移必需），V1 的 4 方法清单不再完整。
|
|||
|
|
10. **明确"未实现/设计中"口径**：computer-control Runner、WindowsRunner.click/type、MacDriver/LinuxDriver、Graph Validator、bun 冒烟、ScreenCaptureHost 全部标为未实现，防止把计划写成现状（用户红线 #7）。
|