yu 7f5ef2f5df docs: 收录 RPA 项目技术审查与集成实施总方案（V2 修订的上游输入）

2026-11-06 09:09:46 +08:00

60 KiB

Raw Permalink Blame History

RPA 项目技术审查与 Agent-Employee 集成实施总方案

文档性质：统一总方案 + 最新源码复审记录。
审查对象：资料库中的 PRA-only-demo-main(2).zip（本轮解压源码快照）。
审查重点：RPA Core 边界、运行时安全、能力注册、驱动注入、平台适配、元素拾取、Agent-Employee 接入。
结论状态：静态源码审查；未将未执行的测试写成通过。

0. 执行摘要

这份文档统一此前几轮讨论、项目原有技术文档和两轮源码审查结论。它不是“项目已经成熟”的背书，而是当前代码能否安全演示、能否抽成可复用 RPA Core、能否接入 Agent-Employee 的事实清单与实施路线。

**总体判断：**项目已经从单纯 Electron Demo 走到有流程引擎、能力注册、驱动接口、元素拾取和能力目录的阶段；但当前 @rpa/core 还不能被认定为真正独立、可注入、可跨平台的执行内核。最主要的阻塞不在于“再加多少能力”，而在于执行取消/重试安全、Engine/Registry/Driver 生命周期、Electron 依赖残留、包依赖闭包和宿主治理契约。

当前建议：

Windows 10/11 演示优先，先收敛一条稳定端到端流程，不要为了演示临时扩展 Linux/macOS。
接入 Agent-Employee 前先修 P0/P1，尤其是取消与重试、Driver 注入、动态 Electron 依赖和包依赖闭包。
先做垂直切片：Gateway 授权 → RPA Runtime → 一个文件能力 → 一个浏览器能力 → 一个桌面能力 → 事件/证据回传，再逐批搬能力。
跨平台按能力域分批实现。当前代码是 Windows-first，不是 Windows/Linux/macOS 三端可用；类型里出现平台占位不代表已有实现。

1. 项目目标与已确认约束

以下是此前项目讨论中已经明确的目标，不是本轮从代码推断出来的事实：

项目定位：面向办公自动化的 RPA 平台，后续接入已有 Agent-Employee / opencode 底座。
用户负责 RPA 部分；商业项目已有独立的服务端 AI 组件，RPA Core 不应重复承担服务端模型部署职责。
总体方向：AI 模式 hybrid；部署方式 local；跨平台目标 all。
元素拾取策略：本地优先、云端兜底；hover 实时识别高亮，click 确认。
目标软件范围：Office、浏览器、Electron、Qt 以及自绘界面。
识别策略：UIA/Accessibility 等结构化接口优先，OCR/视觉模型补足；不把 YOLO 训练作为前置条件，也不把 SAM 作为当前主链路。
当前实际交付重点：Windows 10/11；Linux/macOS 是后续架构目标，不应在未完成驱动与平台能力矩阵前宣传已支持。
技术现状：Electron + Node.js + React + TypeScript；RPA Core 位于 packages/rpa-core，宿主 UI/拾取窗口仍在 src/main / renderer。

2. 当前架构画像

Electron Desktop Host
  ├─ Renderer / Flow Canvas / Properties UI
  ├─ Main Process
  │   ├─ flow persistence / settings / logging
  │   ├─ desktop picker / overlay / vision lab
  │   └─ host bridge initialization
  └─ @rpa/core (workspace package)
      ├─ Flow Runtime / expression / error model
      ├─ module-global Capability Registry
      ├─ capability handlers (files, HTTP, Office, desktop, OCR, vision...)
      ├─ WindowsDriver / PowerShell helpers
      ├─ HostBridge / SubflowSource module singletons
      └─ Browser CDP transport / external browser launcher

2.1 已经具备的基础

有独立的 packages/rpa-core 目录和包名 @rpa/core。
有 Flow Runtime、RunContext、NodeState、RuntimeError、能力注册表与能力元数据。
有 Windows PowerShell driver 封装及鼠标、键盘、窗口、屏幕、UIA 五域接口定义。
有 registerAll() 能力分组加载入口。
有 HostBridge / SubflowSource 抽象，减少部分宿主 API 的直接依赖。
有元素拾取相关代码、OCR/视觉能力、能力目录和较多单元/冒烟测试。

2.2 不能据此宣称已经完成的事项

Core 仍有动态 import("electron")，不是 Electron-free。
createEngine() 当前没有真正接收 Driver；registerAll(engine) 也没有把注册表绑定到该 Engine。
多个能力仍直接依赖 PowerShell、Win32、COM、Electron 屏幕截图 API。
当前没有 MacDriver / LinuxDriver。
@rpa/core 的 package manifest 没有声明源码实际使用的全部外部依赖。
尚未完成 Agent-Employee 真实契约的编译级对接。
本轮未运行 Vitest、typecheck、Electron build、Bun test、Windows 实机 E2E。

3. 本轮继续审查新增发现

P1-NEW-01：RPA Core 内仍有动态 Electron 依赖，依赖护栏漏检

证据：

packages/rpa-core/src/capabilities/vision.ts:18,66,432：动态 import("electron")，读取 desktopCapturer / screen。
packages/rpa-core/src/capabilities/cv-vision.ts:51,213：动态 import("electron")，获取截图与 DIP 坐标转换。
packages/rpa-core/scripts/check-deps.mjs:20-20,38-43：当前扫描表达式只匹配静态 import/export ... "specifier"，不匹配 import("electron")。
packages/rpa-core/src/engine/host-bridge.ts:6-8 与 docs/rpa-core-migration-guide.md:28 却声称 Core 禁止 Electron / 完全不依赖 Electron。

影响：

Node/Bun 独立运行时，调用视觉能力时会尝试加载 Electron；CLI 只跑未触发这些分支的能力，不能证明整个 Core 脱离 Electron。
Agent-Employee backend 若不是 Electron 主进程，视觉能力会在运行时失败或无法复用。
依赖护栏“通过”目前只能说明它没有识别到静态违规，不能作为边界验收证据。

整改：

将屏幕截图、显示器信息、DPI 换算抽成 ScreenCaptureHost / DisplayCoordinateService 接口，由 Electron Host 实现注入。
vision.ts、cv-vision.ts 只依赖接口，不再动态加载 Electron。
依赖护栏补动态 import、require()、createRequire() 与 import() 字符串扫描；最好使用 TypeScript AST，而不是继续堆正则。
CI 增加一个纯 Node/Bun 进程加载 Core 并实际调用视觉 Host mock 的测试。

**验收：**在没有 Electron 包可解析的 Node/Bun 环境下，Core 能加载；视觉能力在 Host 未注入时返回明确的 host_service_unavailable，注入 Fake Host 后可完成截图/坐标测试。

P1-NEW-02：`@rpa/core` 包依赖声明不完整

证据：

packages/rpa-core/src/capabilities/vision.ts 使用 @napi-rs/canvas。
packages/rpa-core/src/capabilities/pdf.ts 使用 pdfjs-dist、@napi-rs/canvas、@cantoo/pdf-lib。
packages/rpa-core/package.json 未声明上述三个依赖；它们目前只出现在根项目依赖（其中 @cantoo/pdf-lib、@napi-rs/canvas、pdfjs-dist）。
package-lock.json 的 packages/rpa-core workspace 条目同样未列出这些依赖。

**影响：**当前 monorepo 根目录安装时可能通过依赖提升“碰巧可用”，但把 packages/rpa-core 单独迁入 Agent-Employee 或单独安装时，相关能力可能出现 Cannot find package。这属于包边界和发布闭包问题。

**整改：**逐个核对 Core 的运行时外部依赖；凡 Core 源码运行时 import 的依赖，要么声明在 Core dependencies/optionalDependencies，要么从 Core 移除并由 Host 注入。原生模块需额外验证目标 OS 与 Bun/Node 兼容性。

**验收：**在隔离目录只安装 @rpa/core 声明的依赖，运行包加载、PDF/OCR/图像相关代表能力；不得依赖根项目的幽灵依赖。

P1-NEW-03：`registerAll(engine)` 参数和 Engine 实例没有实际隔离效果

证据：

packages/rpa-core/src/capabilities/register-all.ts:49-56 接收 engine，但只执行模块动态 import，最终仅 return engine。
packages/rpa-core/src/engine/registry.ts:33-34 的 handlers/metas 是模块级 Map。
packages/rpa-core/src/engine/runtime.ts:260 从全局 getHandler() 取 handler。
packages/rpa-core/src/engine/engine.ts:45-49 的 driver 固定为 new WindowsDriver()，createEngine() 无注入参数。
packages/rpa-core/src/capabilities/desktop.ts:9、common-final.ts:11、system-extended.ts:36、window-extended.ts:7 读取 defaultEngine.driver。

**影响：**调用者可能以为每个 Engine 有独立的 Driver、能力注册表和权限域，实际执行仍共享进程级注册表和默认 WindowsDriver。多 Agent、多桌面会话、测试并行、不同租户策略会互相污染。createEngine() 目前更像状态容器，不是完整隔离的执行实例。

整改：

先确定目标架构：建议 RpaEngine 持有 Registry、Driver、HostServices、SessionContext。
createEngine({ driver, host, registry, ... }) 显式注入。
handler 注册写入 engine.registry；Runtime 从 ctx.engine 或构造参数拿 handler，不读全局 Map。
能力 handler 不捕获 defaultEngine.driver；改为从 RunContext 注入的 execution services 读取。
过渡期如保留全局 API，明确标记 deprecated，不能让 registerAll(engine) 假装实例化注册。

**验收：**创建两个 Engine，分别注入 FakeDriverA/B 并注册不同能力集；并行运行时互不串用 Driver、handler、HostBridge、子流程源。

P1-NEW-04：CLI 冒烟测试不能证明 Engine 注入和 Core 独立性

证据：

scripts/rpa-cli.ts:24-25 同时 import { ... } from "@rpa/core" 和 import "@rpa/core/capabilities"（副作用全量注册）。
scripts/rpa-cli.ts:47-49 随后调用 createEngine() / registerAll(engine)，但该参数没有绑定 Registry。
scripts/rpa-cli.ts:53-58 通过全局 getHandler() 执行 handler，而不是通过 Engine 获取。
scripts/rpa-cli.ts:5-10 声称 5 项代表能力，实际执行了 Window_GetActiveWindow、Window_GetScreenSize、Excel_Cs_NewV5、File_Write、File_Read、Http_Get 共 6 次 handler 调用。

**影响：**CLI 可以验证某些能力在当前 Node + 根目录依赖 + Windows 环境下能运行，但不能验证 Driver 注入、Engine 隔离、显式注册、无 Electron 依赖或独立包依赖闭包。文档将它当成“零宿主独立运行”的证明，结论过度。

**整改：**移除副作用 import；测试只使用显式注册；通过 Engine API 获取 handler 并运行；测试 FakeDriver 注入；将 CLI 验收拆成纯 Node、Windows Host、Electron Host 三种，不把联网 HTTP 作为唯一固定验收依赖。

P1-NEW-05：迁移文档与任务清单互相矛盾，完成度表述不可信

证据：

docs/rpa-core-migration-guide.md:22 写“改造已全部完成”；第 28 行写 Core 完全不依赖 Electron。
docs/rpa-core-refactor-tasks.md:17-91 阶段 0 至阶段 6 的任务仍全部保留 [ ] 未勾选。
源码又存在动态 Electron import、Driver 注入缺失、包依赖缺项。

**影响：**接手者会按“已完成”理解架构状态，低估接入工作量；也无法判断哪些是设计目标、哪些是已验收能力。

**整改：**统一文档状态标记：已实现（代码定位）、已测试（测试证据）、已在目标宿主验证、计划中。每项完成必须附 commit / 测试命令 / 测试结果，不以文档描述代替代码事实。

4. 元素拾取与视觉定位：统一技术路线

元素拾取不应被等同为“找一个 AI 模型识别按钮”。办公 RPA 需要的是可执行、可复定位的 Target，而不仅是截图框。

4.1 建议识别优先级

结构化可访问性接口：Windows UIA；浏览器 DOM/CDP；macOS AX；Linux AT-SPI。
OCR + 几何关系：用于文字、标签、按钮文本与相邻控件关系，输出文字和 bounding box。
免训练视觉候选检测：当前模型实验可作为候选框生成器，但不要将模型类别直接当成业务语义。
模板/局部视觉匹配：对图标、无文本控件和自绘 UI 作兜底。
人工确认：候选冲突、低置信度或高风险动作时要求用户确认。

4.2 Selector 应保存“语义 + 定位证据”，而不是只存坐标

建议 Target 结构至少包含：

platform / app / process / window：目标环境身份；
accessibility：AutomationId、Name、ControlType、ClassName、祖先路径；
browser：URL/域名、frame、DOM role/aria-label/test id 等；
ocr：识别文本、语言、置信度、相对区域；
visual：bbox、截图裁剪 hash、模型标识、相似度；
fallback：最后一次屏幕坐标、DPI/缩放、窗口矩形、采集时间。

运行时定位顺序：结构化 selector → 同窗口/同 frame 限定查找 → OCR/视觉重定位 → 低置信度时停止并要求确认。禁止将拾取时 screen=x,y,w,h 当作长期稳定定位。

4.3 当前代码复核原则

之前报告指出的 candidateId 回填错位问题，在本次 ZIP 中已看到映射修复，不重复当作当前缺陷。
desktop-pick.ts 中候选排序、筛选与执行 selector 的一致性仍需专项回归，尤其 Edge debug/CDP、DPI、多屏和 hover 高频刷新。
vision.ts / cv-vision.ts 的 Electron 直接调用应迁到 Host 服务，不能放在可复用 Core 中。
OCR 是语义补充，不应单独负责确定控件类型；模型候选类别也不能直接映射成“登录按钮”等业务含义。

5. Agent-Employee 集成目标架构

Agent-Employee Workflow / Agent Runtime
        │
        ▼
RPA Adapter（唯一入口）
  ├─ Workflow/Step 状态映射
  ├─ Capability Gateway：授权、租约、审批、审计
  ├─ 参数/返回值 Schema 转换
  ├─ Trace / Event / Evidence 关联
  └─ 取消、超时、幂等与重试策略
        │
        ▼
RPA Core（每次执行/会话实例）
  ├─ Flow Validator
  ├─ Runtime / Expression / Error Contract
  ├─ Engine-scoped Registry
  ├─ Capability Handlers
  └─ Execution Context（AbortSignal / Trace / Permission / Evidence）
        │
        ├──────── Host Services（宿主注入）
        │          ├─ Browser Adapter
        │          ├─ Screenshot / Display / DPI
        │          ├─ Dialog / AI Config / Subflow Store
        │          └─ Event / Evidence Sink
        │
        └──────── Computer Control Driver
                   ├─ WindowsDriver（当前优先）
                   ├─ MacDriver（后续）
                   └─ LinuxDriver（后续）

权责原则：

Agent-Employee Workflow/Runtime 是宿主最终 Run/Step 状态的唯一权威来源；RPA Runtime 作为执行器或执行子流程，不另建第二套冲突状态系统。
Capability Gateway 是所有带副作用能力的唯一授权入口。RPA Core 不再另建一套与其冲突的 allowlist。
computer-control 是桌面观察/定位/动作契约的优先对齐对象；不要让 RPA Driver 与宿主契约长期并行。
HostServices 与 Driver 按 Engine/Session 注入，不使用模块级全局 setter 承载多租户/多桌面会话状态。
高风险能力（命令执行、键鼠注入、文件删除/覆盖、发送邮件/消息、数据库写操作）必须有权限、审批/租约、审计和资源范围。

6. 当前问题优先级总表

优先级	问题	接入影响	建议门槛
P0	超时只让外层 Promise reject，底层操作不一定停止	可能重叠执行、重复副作用	接入前修复
P0	取消状态与 NodeState 不一致；取消可能被当失败/跳过	宿主状态与执行状态冲突	接入前修复
P0	retry 默认策略过宽，非幂等动作可能重试	重复点击/输入/发信/覆盖	接入前修复
P0	Engine 无 Driver 注入；能力使用 defaultEngine	无法按会话隔离/测试替身	接入前修复
P1	Registry 模块级全局 Map，registerAll(engine) 不实例化注册	多 Agent/多权限域污染	接入前明确并改造
P1	HostBridge / SubflowSource 模块级单例	多宿主/多会话覆盖	接入前改造
P1	vision/cv-vision 动态依赖 Electron	Core 不能独立运行	迁移前修复
P1	Core manifest 缺失 canvas/pdf 依赖	单包安装不完整	迁移前修复
P1	CLI 依赖全局注册，不能证明注入/独立性	现有验收证据不足	重写验收
P1	Flow Graph 无完整 Validator	多出口/非法边可能静默部分执行	接入前补校验
P1	CapabilityMeta 缺权限/副作用/幂等字段	Gateway 映射不完整	Gateway 对接前补齐
P1	Windows 专属能力散落在能力层	平台能力边界不清	平台适配前整理
P1	catalog platformTag 类型异常	平台过滤/界面标记不可信	修复并加 schema test
P1	Agent-Employee 契约尚未逐接口编译验证	估算与实现存在偏差	联调前必须做
P1	BrowserSession 的 locate 与执行查找器语义不一致	拾取后 XPath/Shadow DOM 选择器可能执行失败	浏览器能力验收前修复
P1	iframe 未纳入拾取/定位/执行上下文	iframe 内元素无法保证端到端可用，跨域 iframe 尤其明显	浏览器能力验收前明确支持边界
P1	CDP 单条命令无响应超时	浏览器命令可能永久 pending，流程卡死	接入前补统一超时与清理
P1	外部浏览器“前台标签跟随”取 pages[0]	多标签时可能切错目标页	多标签回归前修复
P1	AI 拾取取消未贯穿检测/OCR任务	取消后后台推理仍可能继续，OCR 等待无硬超时	拾取稳定性验收前修复
P2	依赖护栏只扫静态 import，且只覆盖 TS/TSX	边界回归容易漏检	尽快增强
P2	AI 请求没有调用方 AbortSignal	拾取取消不能立即中止请求	交互体验整改
P2	包没有独立 build/pack 验收	迁移消费方式不稳定	发布前补齐

7. 执行安全整改方案

7.1 取消必须贯穿整条调用链

RunContext.signal → Runtime → Handler → Host/Driver → PowerShell 子进程 / HTTP / Browser CDP。每层都必须接收 signal，并在取消时清理资源。

PowerShell 子进程需要持有 ChildProcess 引用，收到 abort 后执行 terminate/kill；仅设置 execFile timeout 不等于响应上游取消。浏览器动作、等待、网络请求、OCR/AI 请求也应尽量可取消。

7.2 超时不等于操作已停止

当前 withTimeout() 只让外层 Promise reject，不保证底层 handler 结束。超时后必须先 abort 底层任务并等待其停止/清理，再决定是否重试；不能直接开始第二次点击或输入。

7.3 重试必须基于能力语义

新增能力元数据：sideEffect、idempotent、retryPolicy、permission、approvalRequired、resourceScope。非幂等能力默认不重试；只有明确幂等、可安全重复的操作才能自动重试。对“发送消息/邮件、提交表单、点击付款、删除/覆盖文件”等默认禁止盲目重试。

7.4 状态机

至少统一 pending → running → succeeded | failed | cancelled | skipped。取消不能被转成普通失败，也不能误走错误分支。RunResult、NodeState、Agent-Employee Step 状态需要一份映射表和契约测试。

8. 平台适配路线

8.1 当前定位

当前实际是 Windows-first：PowerShell、Win32、UIA、Office COM、Windows 剪贴板和屏幕 API 占据大量路径。platforms: ["win32"] 的类型声明只是当前标记，不是跨平台实现。

8.2 建议分阶段

阶段 A：Windows 可靠性：Windows 10/11、UIA、Edge/Chrome CDP、Office COM、DPI、多显示器、PowerShell 取消/超时、安装包资源。
阶段 B：Linux 桌面基础：先选 X11 或 Wayland 的支持边界；AT-SPI、输入注入、截图、窗口管理分别实现；Wayland 必须明确权限与限制。
阶段 C：macOS 桌面基础：Accessibility API、CGEvent/AppleScript、TCC 辅助功能和屏幕录制授权流程。
阶段 D：Office/文件能力矩阵：Windows COM；macOS AppleScript/Office；Linux LibreOffice 或标记不支持。每项能力逐个标平台，不能按“同名软件存在”推断等价。

8.3 平台标记单一来源

register-all.ts 的能力分组、CapabilityMeta.platforms、catalog.platformTag 必须由一份平台能力表派生；当前发现 catalog.json 中 1016 项里 1013 项 platformTag=null，另 3 项是数字 1，与 src/types.ts 的 string | null 不符。build-catalog.mjs 的 component.platformTag || ... 会保留 truthy 数字，必须增加 schema 校验并修复源数据。

9. 推荐实施顺序与阶段门禁

阶段 0：先固化演示基线（Windows）

冻结一个端到端演示流程，准备稳定的测试软件、数据和账号。
把必需节点与不稳定节点分开；演示脚本不得依赖外网随机响应。
验收：连续完整执行多轮；每轮有运行日志、节点状态、失败截图/证据；取消后无残留子进程/后台动作。

阶段 1：Core 接入前 P0

贯通 AbortSignal 和底层取消。
取消状态正确映射。
重试策略按幂等性约束。
Engine 真正支持 Driver/Host/Registry 注入。
验收：FakeDriver、超时、取消、重试、双 Engine 隔离测试全绿。

阶段 2：包边界闭环

移除 Core 动态 Electron import。
补齐/收敛 package dependencies。
依赖扫描升级为 AST 或覆盖动态 import/require。
重写 CLI，去掉副作用全量 import，验证 Engine-scoped registry。
验收：隔离安装、Node/Bun 纯 Core 加载、Host Mock 视觉路径。

阶段 3：Agent-Employee 契约对齐

获取目标仓库真实源码与当前 commit。
对 workflow-engine、capability-gateway、computer-control、windows-plugin、browser-plugin 的类型、生命周期、事件和错误模型逐接口对照。
输出 Adapter 映射表与 ADR，不根据迁移指南中的摘要直接开始实现。
验收：编译通过、Gateway 拒绝时 handler 零调用、事件/证据可追踪。

阶段 4：小范围垂直切片

先接一个纯文件能力、一个浏览器能力、一个桌面能力。
跑通授权、租约、审批、执行、取消、事件、证据回传。
验收后才开始分批迁移能力组。

阶段 5：能力规模化与跨平台

能力分组迁移、平台标记、风险元数据补齐。
Linux/macOS 按驱动和能力矩阵逐步开放，不做虚假全平台开关。

10. 交付给接入团队的材料清单

本总方案（本文件）。
docs/RPACore二次源码审查与接入整改报告.md：此前两轮源码审查细项与原始定位，作为附录参考。
docs/rpa-core-migration-guide.md：现有迁移指南，但其中“完全不依赖 Electron / 已全部完成”等表述应按本总方案纠正。
docs/rpa-core-refactor-tasks.md：原改造任务清单，当前勾选状态与迁移指南冲突，应重新按证据更新。
docs/06-AI拾取模型选型与RPA执行方案.md、docs/图像与OCR问题检测报告.md：拾取与视觉路线参考，需结合当前实现再次做 Windows 实机回归。

11. 本轮审查边界

已读取资料库中的最新 PRA-only-demo-main(2).zip，并检查 packages/rpa-core、核心运行时、注册入口、Driver、依赖护栏、CLI、catalog 和项目文档。
已核验 check-deps.mjs 的实现逻辑；该脚本的扫描方式确实漏掉动态 import("electron")。
未安装项目依赖；未执行 Vitest、TypeScript typecheck、Electron build、Bun test、打包和 Windows 实机 E2E。不得把这些项目标成“通过”。
当前没有 Agent-Employee 目标仓库真实源码作为本轮输入，因此本文件给出的是接入架构和待核验契约清单，不代表已完成目标仓库编译对接。
ZIP 中不包含 node_modules；本轮静态结论以该 ZIP 源码快照为准。

附录 A：此前二次源码审查细项

以下保留此前审查报告的完整细项，包括已修复问题回归、P0/P1/P2 代码定位、Graph Validator、HostBridge、Registry、平台标记、能力元数据和验收标准，避免统一文档时丢失前几轮审查证据。

RPACore 二次源码审查与 Agent-Employee 接入整改报告

审查对象：资料库中的 PRA-only-demo-main(2).zip（约 154.8 MB）
审查日期：2026-11-06
审查范围：packages/rpa-core/、流程运行时、能力注册、Driver/HostBridge、能力目录、桌面拾取与打包配置、原有迁移文档
审查方式：源码静态审查 + 项目结构/JSON/脚本检查；未在 Windows 真实桌面环境执行端到端测试。
重要说明：本报告区分“源码已确认”“设计风险/需产品语义确认”“尚未运行验证”，不把静态推断写成运行结果。

0. 总体结论

当前项目已经不是简单的 Electron 自动化 Demo：它有独立的 packages/rpa-core workspace、流程运行时、能力注册表、五域 Driver 类型、HostBridge、外部浏览器 CDP、桌面 UIA/视觉拾取以及较多能力测试。现有技术栈不需要推翻，真正需要解决的是运行时语义、依赖注入闭环、能力治理和平台边界。

但当前状态还不适合直接宣称“可无修改迁入 Agent-Employee”或“已具备跨平台能力”。建议定位为：Windows-first 的 RPA 能力包，已建立初步包边界，仍需完成执行语义与宿主契约收口。

本轮核验到的项目事实

ZIP 内约 272 个条目、约 230 个文件；packages/rpa-core/src 包含 35 个 *.test.ts 文件。
packages/rpa-core 的包名仍是 @rpa/core，private: true，入口直接指向 src/index.ts，尚未形成面向普通 Node/Bun 部署的独立构建产物契约。
node packages/rpa-core/scripts/check-deps.mjs 本次执行通过；这只证明该脚本当前扫描规则未发现违规 import，不等于包完全没有宿主/平台耦合。
resources/catalog.json 声明 1016 个组件：1013 个 platformTag 为 null，3 个 platformTag 是数字 1，与 CatalogComponent.platformTag: string | null 类型不一致。
electron-builder.config.mjs 当前已经把 resources/desktop-picker.ps1 放入 extraResources；AI 候选覆盖层当前用 candidateId 回传并按 ID 查找原候选。这两项是旧版元素拾取报告中的 P0，本次最新快照中已看到对应修正，不应继续作为“当前未修复问题”重复上报。

建议优先级

优先级	主题	结论
P0	超时、取消与重试的副作用安全	先处理；否则自动化可能出现重复点击/重复写入
P0	Engine/Driver/Registry/HostBridge 依赖闭环	接入前必须明确，否则宿主无法可靠隔离会话与权限域
P1	流程图结构校验和执行语义	防止无效图被静默部分执行
P1	能力元数据与 Capability Gateway	Agent 不应绕过授权直接调用高影响能力
P1	平台目录、Driver 边界与 Windows 专属能力	不应把“抽象接口存在”描述成 Linux/macOS 已支持
P1	包构建、Bun 兼容和集成验收	迁入前必须有目标运行时证据
P2	依赖扫描增强、注册冲突治理、可观测性	提高长期维护质量

1. P0：执行安全与依赖闭环

P0-01 超时只终止 Runtime 等待，不保证底层能力停止

源码位置：packages/rpa-core/src/engine/runtime.ts:33-55, 279-307；packages/rpa-core/src/engine/types.ts:118-137；packages/rpa-core/src/driver/windows/powershell.ts:45-69。

确认事实：withTimeout() 通过计时器拒绝外层 Promise；它没有创建并传递专属 AbortController，也没有在超时后通知 handler 停止。RunContext 虽然有 signal，但 AutomationDriver 的五域方法没有 signal 参数，PowerShell helper 也没有接受调用方 AbortSignal 的接口。PowerShell helper 自己有 30 秒等进程超时，但这与 Runtime 节点超时不是同一个取消链路。

影响：节点超时后 Runtime 可能已经开始重试，前一次 PowerShell/桌面操作却仍在执行。对点击、输入、删除、覆盖文件、发邮件、提交表单等非幂等动作，可能产生重复副作用。用户按取消后，运行状态结束也不代表底层操作已经停止。

整改：

为每次节点尝试创建独立 AbortController，把 Run 级 signal 与 Node 级 timeout 合并。
Handler/Driver/PowerShell/HTTP/浏览器操作逐层接收 signal；可取消的操作必须真实中止。
对不能中止的原生/外部动作，标记为 nonCancellable，超时后不得自动重试，必须等待进程退出或进入人工恢复状态。
将重试策略从“按错误码猜测是否可重试”改为能力元数据声明：idempotent、retryPolicy、sideEffectLevel。
默认重试次数设置保守上限；当前 retryCount 被允许到 100，且 isRetryable() 将大多数未知错误视为可重试，不适合作为有副作用能力的默认策略。

验收：构造一个执行 5 秒的 Fake Handler，节点 timeout 设 100ms；验证 100ms 后 handler 收到 abort 并停止；再构造“第一次执行延迟完成、第二次执行”的测试，证明不会发生并发重入。对文件写入/点击类能力增加“超时不自动重试”测试。

P0-02 取消时节点状态可能记录为 failed，而非 cancelled

源码位置：runtime.ts:326-351；types.ts:139-160。

确认事实：executeNode() 捕获异常后，普通错误分支会将状态设为 failed 或 skipped；RuntimeError("cancelled") 没有在节点状态层单独映射为 cancelled。Run 层随后可能返回 status: cancelled，但对应 NodeState 仍显示 failed/skipped。

影响：Agent-Employee 若要做步骤级恢复、审批、审计和用户界面状态展示，会遇到 Run 已取消但 Step 显示失败的语义冲突。

整改：在 executeNode catch 中优先判断 cancelled，写入 state.status = "cancelled"，不执行 skipOnError 和普通重试；统一发出 cancelled 事件，并记录取消原因/发起方。

验收：在节点执行中取消；断言 Run 与对应 NodeState 都是 cancelled，后续节点不执行，且不进入 error route。

P0-03 Engine 创建接口没有真正的 Driver 注入能力

源码位置：engine.ts:24-53；driver/types.ts:1-10, 158-165；packages/rpa-core/README.md:50-57。

确认事实：RpaEngine.driver 类字段固定 new WindowsDriver()；createEngine() 无参数。Driver 类型注释和 README 却声称 createEngine() 可注入自定义 Driver。

影响：不能注入 Agent-Employee computer-control 适配器，也不能在单测中使用 Fake Driver；非 Windows 平台创建 Engine 时仍会实例化 Windows 实现。

整改：提供 createEngine({ driver, registry, hostBridge, subflowSource, ... })，将默认 Driver 的选择放在平台工厂或宿主装配层；Engine 不应在跨平台包内部无条件创建 WindowsDriver。

验收：Fake Driver 注入测试覆盖 mouse/keyboard/window/screen/element；Linux/macOS 上若无 Driver，明确返回 platform_unsupported，不得误报初始化成功。

P0-04 Registry 与 Engine 生命周期不一致，`registerAll(engine)` 参数没有生效

源码位置：registry.ts:33-62；register-all.ts:49-57；runtime.ts:3, 260。

确认事实：handlers/metas 是模块级 Map；registerAll(engine) 只动态 import 模块，能力模块通过全局 register() 写入同一个 Registry；runFlow() 用全局 getHandler() 查找 handler。传入的 Engine 不决定注册目标。

决策背景：原迁移指南明确选择过“保留全局注册表”。因此问题不是简单的代码疏漏，而是既有决策带来的隔离限制。

整改建议：

短期单后端、单能力集合：可保留进程级 Registry，但把 API 改成语义真实的 loadCapabilities(groups)，文档明确不支持 Engine 级能力隔离。
长期多 Agent/多租户/不同权限域：改成 CapabilityRegistry 实例，由 Engine 持有；显式注册函数接收 Registry，运行时从 Engine Registry 取 handler。

验收：至少有两个 Engine A/B 的注册隔离测试（若采用实例级方案）；若暂时采用全局方案，测试需明确证明共享行为是预期设计，并验证重复注册、重复加载和冲突覆盖规则。

P0-05 HostBridge/SubflowSource 是模块级单例

源码位置：engine/host-bridge.ts（HostBridge 与 SubflowSource 的模块级变量/set/get）；ai-service.ts:20-24；human-dialog.ts；window-extended.ts。

确认事实：宿主桥通过模块级变量保存，setHostBridge() / getHostBridge() 读取同一进程级对象；子流程源也采用相同模式。

影响：多桌面会话、多 Engine、测试并行或多宿主容器时，后一次注入会覆盖前一次配置；AI 配置、DPI 换算、弹窗窗口工厂可能串到错误会话。

整改：把 HostServices 放入 Engine 构造依赖；若宿主明确只有一个全局桌面会话，可保留进程级服务，但应在 ADR 中限定部署模型，并提供 reset/restore 测试机制。不要让业务 handler 在模块导入时捕获全局桥对象。

验收：两个 Engine 注入不同 HostBridge，分别触发 AI 配置读取/DPI 转换/弹窗，结果不能交叉。

2. P1：流程图语义与运行时完整性

P1-01 执行器缺少运行前 Graph Validator

源码位置：runtime.ts:178-219；types.ts:115-145；runtime.error-route.test.ts:51-75。

确认事实：有边时，运行时选择一个起点（优先无入边 Trigger，其次任意无入边节点，再退回 top[0]），然后沿边递归执行；普通边通过 edges.find(...) 只取第一条非 error 边。访问过的节点由 visited 集合直接跳过。当前测试明确验证断开的 orphan 节点不执行，因此“孤立节点不执行”是现有行为，不应未经产品确认就当作 Bug。

风险：如果画布允许多个入口、一个节点多个普通出口、重复边、目标不存在、普通边形成环，运行时可能只执行其中一条路径或静默停止，且没有在执行前给出结构错误。流程编辑器允许的图结构与 Runtime 支持的图结构需要有统一契约。

整改：新增 validateFlowGraph(flow)，运行前检查：节点 ID 唯一；边 source/target 必须存在；入口数量与 Trigger 规则一致；普通出口基数符合节点类型；error handle 唯一；不允许意外环；容器子节点 slot 合法；孤立节点明确警告或拒绝。若业务确实支持多出口/并行，必须实现明确的调度语义，不能用 find() 随机取第一条。

验收：非法多出口、孤立节点、环、重复 ID、悬空边均在执行前得到稳定错误码；合法 IF/循环/异常分支测试保持通过。

P1-02 `skipOnError`、错误分支与 Stop/Break/Continue 的状态语义需统一

源码位置：runtime.ts:141-154, 203-211, 326-351。

风险：目前错误路由、skipOnError、Break/Continue/Stop 都在不同层捕获；需要明确一个节点失败后何时走 error edge、何时 skip 并走 normal edge、何时终止整个 Run。特别要保证 cancelled 不会被当作普通可跳过错误。

整改：定义一张状态转移表并由测试固定：成功→normal；可跳过失败→skipped+normal；不可跳过失败且有 error edge→error；无 error edge→Run failed；cancelled→Run cancelled 且不走 error edge；Stop→按产品定义终止状态；Break/Continue 只能在循环上下文捕获。

3. P1：能力元数据、安全治理与平台支持

P1-01 能力目录平台标记数据异常

源码位置：resources/catalog.json；src/types.ts:49-70；scripts/build-catalog.mjs:234-249。

确认事实：当前 catalog 有 1016 个组件，其中 1013 个 platformTag=null，3 个值为数字 1（Basic_BusinessOrderCount、Dialog_GetConfigV7、Dialog_GetConfigV5），但类型要求 string | null。构建脚本的 component.platformTag || ... 会把 truthy 的数字 1 原样保留，无法靠类型声明自动纠正 JSON 数据。

影响：前端/Agent 不能可靠判断某个能力在哪个平台可执行；类型层与运行时 JSON 事实不一致。

整改：平台支持使用统一枚举 win32 | darwin | linux 或 null；生成 catalog 时做 schema 校验并拒绝非字符串值；平台能力映射只保留一个权威来源，运行时元数据与构建期目录从同一份数据派生。当前只声明 Windows 已实现，其他平台标记为未支持，不要为了“跨平台目标”提前填支持标记。

验收：catalog 构建后 1016 条均通过 schema 校验；每个能力都有明确平台状态；Windows 专属能力不会被误标为跨平台。

P1-02 CapabilityMeta 不足以承载 Agent-Employee 权限治理

源码位置：registry.ts:7-31；能力目录 CatalogComponent.risk 在 types.ts:65。

确认事实：Registry 的元数据目前包含 summary/params/returns/timeout/errorCodes/needsScreenshot/platforms；目录只有 risk: low | high。未看到统一的权限范围、审批要求、幂等性、副作用类型、资源访问范围等完整治理元数据。

影响：Agent-Employee 的 capability-gateway 无法仅凭当前元数据可靠地决定授权、审批、租约范围和审计字段；若直接暴露全部 handler，会绕过宿主治理边界。

整改：在宿主适配层建立唯一 CapabilityRunner：授权 → 租约/策略校验 → 输入校验 → 执行 → 证据/审计。为能力补充结构化治理元数据，建议包含 riskLevel、permissions、approvalRequired、sideEffect、idempotent、platforms、timeoutBudget；字段最终以 Agent-Employee 契约为准。高影响能力不得通过全局 getHandler() 直接暴露给 Agent。

验收：命令执行、键鼠输入、文件删除/覆盖、邮件发送、网络写操作等均经过 Gateway；审批拒绝/租约过期时 handler 不会执行；审计可关联 Agent、Run、Capability、审批结果和执行结果。

P1-03 Driver 抽象尚未形成平台隔离边界

源码位置：driver/types.ts:133-165；driver/windows/windows-driver.ts；capabilities/desktop-uia.ts；capabilities/vision.ts、cv-vision.ts、remaining-core.ts、system-extended.ts、word.ts 等。

确认事实：五域接口存在，但 ScreenDriver 目前只有 size()；注释明确截图等 System.Drawing 操作仍可留在能力层。ElementDriver 通过 setElementDriverImplementation() 模块级 setter 接到 WindowsDriver；多个能力仍直接调用 PowerShell、Win32、COM 或 Windows 剪贴板。

影响：接口“看起来五域齐全”不等于能力层已平台无关。未来增加 Mac/Linux Driver 时，若不先盘点调用点，平台差异会继续散落在能力 handler 中。

整改：按能力建立 Windows-only 白名单；把截图、剪贴板、窗口/元素观察、键鼠动作、Office COM 等原语逐项归入 Driver/Host adapter；对不适合抽象的能力显式标记平台限制。不要为了抽象而一次性重写全部能力，按高频基础原语先收口。

验收：Core 通用层静态扫描不允许出现未列入白名单的 Windows API/PowerShell/COM 调用；Fake Driver 可覆盖核心自动化能力。

P1-04 跨平台目标与当前实现状态需要分开表达

确认事实：当前 WindowsDriver 使用 powershell.exe、user32.dll、Windows UIA、Office COM 等；外部浏览器启动和系统能力也存在 Windows 专属实现。没有看到可用的 MacDriver / LinuxDriver。

建议表述：项目目标是 Windows/Linux/macOS；当前可交付实现以 Windows 为主。Linux 需先明确 X11/Wayland 边界，macOS 需处理 Accessibility、Screen Recording 等系统授权；Office 自动化三端也不是同一套实现。不要将“接口预留”写成“已支持跨平台”。

4. P1/P2：包工程化与质量护栏

P1-05 `@rpa/core` 还不是完整的可发布包

源码位置：packages/rpa-core/package.json。

确认事实：包名为 @rpa/core，private: true，main / types / exports 直接指向 TypeScript 源文件；包脚本没有 build、pack 或 exports 产物检查。

影响：在当前 workspace/Bun 环境中可能可以直接消费 TS 源码，但不能据此推断它可被普通 Node.js、生产打包器或独立服务稳定消费。Agent-Employee backend 使用 Bun 的事实仍需在目标仓库实测。

整改：确定宿主采用源码 workspace 依赖还是构建产物依赖。若源码消费，锁定 Bun 版本并建立 Bun test/typecheck/运行测试；若产物消费，补 tsc/tsup 构建、exports 的 types/import/default 条目、files 白名单和 npm pack --dry-run 检查。

P2-01 依赖护栏是正则扫描，不是完整依赖边界证明

源码位置：packages/rpa-core/scripts/check-deps.mjs:20-55。

确认事实：脚本扫描 .ts/.tsx，用正则匹配静态 import/export ... from；没有覆盖 import("electron")、CommonJS require()、createRequire()、运行时拼接加载、.mjs/.js 文件，也没有校验包外部依赖 allowlist。当前脚本执行通过。

整改：保留快速扫描，同时增加 TypeScript AST 扫描；对 import()、require、createRequire 和禁用模块路径进行检查；另加 package.json 依赖审计和构建后 bundle 检查。脚本通过只能写成“当前规则扫描通过”，不要写成“彻底无 Electron 依赖”。

P2-02 Registry 重复注册与元数据覆盖规则不明确

源码位置：registry.ts:36-41。

确认事实：同 ID 再次注册会直接覆盖 handler；如果第二次注册没有 meta，旧的 meta 不会删除，可能出现 handler 已更新但 meta 仍是旧值。

整改：定义重复注册策略（拒绝/显式覆盖/版本化）；覆盖 handler 时同步处理 meta；注册冲突输出可审计信息。

P2-03 `registerAll()` 可能发生部分注册

源码位置：register-all.ts:49-56。

确认事实：按传入顺序逐组 import；如果前面几个组已加载、后续遇到未知组才抛错，会留下部分全局注册状态。

整改：先校验全部 group 名称，再执行加载；长期方案采用显式 Registry，支持事务式注册或失败回滚。

P2-04 AI 请求缺少调用方取消信号

源码位置：capabilities/ai-service.ts:39-76。

确认事实：AI 请求使用 AbortSignal.timeout(timeoutMs)，但 ChatCompletionOptions 没有调用方 signal 字段。交互式请求默认超时 45 秒；UI 拾取取消时不能从该 API 直接中止 HTTP 请求。

影响：界面退出后请求仍可能继续占用网络/服务端资源；连续识别可能造成无用请求并发。

整改：增加 signal?: AbortSignal，把用户取消与内部 timeout 合并；新请求开始时按业务策略取消旧请求；对 408/429/5xx 以外的错误明确重试策略。

5. 上一版元素拾取报告的回归核验

以下项目在 2026-11-01 的旧报告中列为高优先级，本次针对最新 ZIP 复核后状态如下：

旧问题	最新源码核验	当前结论
`desktop-picker.ps1` 未列入 electron-builder `extraResources`	`electron-builder.config.mjs:26-32` 已包含 `resources/desktop-picker.ps1`	已修复，仍需安装包实测资源路径
候选框排序后用数组下标回填错位	`desktop-pick.ts:238-253, 596-616` 使用 `candidateId` 识别和回查候选	已看到修复，不应再列为当前 Bug
视觉坐标执行路径与 UIA 执行路径不一致	旧报告指出过此风险；本次未完成所有 selector source 到执行器分发的逐函数回归	待专项复核，不在本报告宣称已修复
AI 请求超时/取消	Core AI API 目前有 timeout，但没有外部 AbortSignal	仍有取消链路缺口，见 P2-04

元素拾取总体仍建议维持“UIA 快路径 → 局部 OCR/CV → 低频 AI 兜底”的方向。普通 hover 不应触发大模型；AI 候选应绑定稳定 candidateId，并最终形成可重新定位的 ElementDescriptor，而不是只保存一次性屏幕坐标。

6. 推荐目标架构与接入边界

Agent-Employee workflow-engine
        |
        v
RPA Adapter / CapabilityRunner
  - 权限授权、租约、审批、审计
  - Run/Step 状态映射
  - 输入输出 schema 适配
        |
        v
RPA Core Engine (per execution/session)
  - Flow Validator + Runtime
  - CapabilityRegistry（建议长期实例级）
  - RunContext (signal / trace / evidence / variables)
        |
        +---- Capability Handlers
        |       - pure Node capabilities
        |       - Windows-only capability allowlist
        |
        +---- AutomationDriver (injected)
        |       - WindowsDriver
        |       - LinuxDriver (future)
        |       - MacDriver (future)
        |
        +---- HostServices (injected)
                - Browser adapter
                - Dialog / DPI / config
                - Subflow repository
                - Event / evidence sink

职责原则：

workflow-engine 是宿主权威 Run/Step 生命周期的候选所有者；RPA Core 提供流程执行算法或节点执行器。最终只能有一个权威状态源。
Capability Gateway 是所有高影响能力的唯一授权入口；Core 不另建一套冲突的权限系统。
computer-control 是桌面观察/定位/动作契约的优先对齐对象；RPA Core 的 Driver 不应与宿主契约长期并行演化。
HostServices/Browser/子流程存储由宿主注入，Core 不直接依赖 Electron BrowserWindow 或应用全局状态。

7. 整改顺序与验收门槛

第一阶段：执行安全（接入前）

P0-01 节点级 AbortSignal 贯通 Runtime → Handler → Driver/PowerShell/HTTP/Browser。
P0-02 取消状态映射一致，取消不触发 skip/error route/retry。
P0-03 非幂等能力默认不重试；能力元数据声明幂等性与重试策略。
P1-01 Graph Validator 覆盖入口、出口、环、悬空边、孤立节点和容器 slot。

第二阶段：依赖闭环（接入前）

P0-04 明确 Registry 是进程级还是 Engine 级，并更新 API/ADR。
P0-05 Engine 构造时注入 Driver 与 HostServices。
P1-02 registerAll() 与实际注册作用域一致，重复注册规则明确。
P1-03 建立 Capability Gateway 适配层和权限元数据映射。

第三阶段：平台与包工程化（联调阶段）

P1-04 catalog 平台标记修复并增加 schema 校验。
P1-05 完成 Driver/Windows-only 能力白名单。
P1-06 选定 Bun 源码消费或构建产物消费方案，执行 Bun typecheck/test/运行验证。
P2-01 AST 依赖检查覆盖动态 import/require。
P2-02 AI 取消信号与拾取流程取消联动。

接入验收最低标准

Core 在目标 Bun 版本下 typecheck/test 通过；不能以 Node 测试代替 Bun 验证。
Fake Driver 注入成功，核心能力不启动真实 PowerShell。
两个 Engine 的依赖/状态隔离行为符合 ADR。
所有有副作用能力经过 Capability Gateway，权限拒绝时 handler 零调用。
取消/超时/重试测试证明不会重复执行非幂等动作。
Graph Validator 能阻止非法流程在执行前运行。
catalog 平台字段通过 schema 校验，平台支持范围与真实实现一致。
Windows 10/11 实机完成 UIA、浏览器、Office、DPI、多屏幕、安装包资源和取消场景回归。

8. 需要与 Agent-Employee 团队共同确认的 ADR

ADR	必须确认的问题	建议
Registry 生命周期	一个 backend 是否存在多个 Agent/租户/权限域？	长期采用 Engine 级 Registry；短期单进程固定能力集可临时全局共享
Runtime 所有权	workflow-engine 还是 RPA Core 持有 Run/Step 最终状态？	宿主持有权威状态，Core 负责执行并回传事件
Driver 契约	RPA Driver 是否直接实现 computer-control？	对齐宿主契约，避免双份抽象
HostServices 作用域	一个进程是否会管理多个桌面会话？	按 Engine/Session 注入，不使用全局 setter
能力权限	哪些能力需要审批/租约/资源范围？	Capability Gateway 唯一入口
包消费方式	Bun 直接消费 TS 源码还是 Core 构建后消费？	以 backend 生产部署方式决定，并建立 CI 证明
平台范围	本轮交付是否只要求 Windows？	当前明确 Windows-first，Linux/macOS 分阶段验收

9. 审查限制与下一步

本次成功读取了资料库中的最新 ZIP，并对关键文件做静态核验。
本次执行了 check-deps.mjs，结果通过。
ZIP 未包含 node_modules，当前审查环境没有安装项目依赖，因此没有执行 Vitest、TypeScript typecheck、Electron build 或 E2E；这些结果均标记为“未验证”，不能写成通过。
没有 Agent-Employee 目标仓库源码可供本轮逐接口编译对接；其契约映射仍以原迁移指南中记录的接口信息为基础，正式集成前必须在目标仓库核对真实类型定义。
没有在真实 Windows 10/11 桌面执行 UIA、Office COM、Edge/CDP、多屏/DPI、安装包和 AI 取消链路。

最终建议：先修 P0 的取消/超时/重试和 Engine 依赖注入，再决定 Registry 作用域；不要先把 1016 个能力整体搬入宿主。先用一条小而完整的垂直切片（一个流程、一个浏览器能力、一个桌面能力、一个文件能力）跑通 Gateway → Runtime → Driver → Event/Evidence，再逐批迁移能力。

12. 第三轮深挖：Runtime、浏览器执行链与元素拾取

本节是对同一源码快照的进一步静态追踪。这里区分“代码路径已确认”和“运行时表现仍需实机复现”；没有把未执行的 Edge/Office/UIA 测试写成已复现故障。

12.1 P1：BrowserSession 的定位与执行查找器不一致，拾取结果不保证可执行

源码证据：

src/main/browser/session.ts:61-85：selectorSpec() 接受 css、xpath、text、aria 等类型，并可接收拾取器产生的 css selector。
src/main/browser/session.ts:243-291：withElementOnce() 对 XPath 使用 document.evaluate()；对 CSS >>> 分段逐层进入 shadowRoot。
src/main/browser/session.ts:463-503：locateOnce() 对 text、aria 有分支，但其余类型统一执行 document.querySelectorAll(spec.value)。因此 xpath 会被当作 CSS selector；css 中的 >>> 也会被当作普通 CSS 字符串。
src/main/browser/session.ts:562-565：click() 首先调用 locate()，之后才调用 withElement()。
src/main/browser/session.ts:623-627：type() 同样先调用 locate()。
src/main/browser/session.ts:672-681：getText(selector, attribute) 的属性分支再次直接调用 document.querySelector(spec.value)。

结论：

xpath://... 即使能通过 withElement() 找到，也会在 click() / type() 前置的 locate() 阶段走 CSS 查询路径。
拾取器会生成包含 Shadow DOM 路径分隔符 >>> 的 selector；withElement() 支持该语法，但 locate() 与 getText(attribute) 不支持。
因此“拾取器生成了 selector”不等于“所有浏览器操作都能消费这个 selector”。这属于明确的实现不一致，不是单纯的测试缺失。

**整改：**抽出唯一的 resolveElement(selector, context)，统一支持 CSS/XPath/Text/ARIA/Shadow DOM；locate/click/type/getText/getRegion/getElementInfo 全部复用同一个解析器。不要让每个方法各自拼 DOM 查询表达式。

**验收：**同一批 fixture 分别覆盖 CSS、XPath、text、ARIA、open Shadow DOM、多层 Shadow DOM；每个 selector 至少通过 locate、click、type、getText、getRegion。测试断言拾取产出的 selector 能被执行器直接消费。

12.2 P1：iframe 未进入浏览器拾取与执行上下文模型

源码证据：

PICKER_BOOTSTRAP_SOURCE（src/main/browser/session.ts:1390 起）将拾取脚本注入当前页面 document，使用 document.elementFromPoint、event.composedPath() 和 document.querySelectorAll()。
selectorSpec() / withElementOnce() / locateOnce() 均以当前 target 的主 document 为根，没有 frameId、frame URL、frame path 或 frame-specific execution context。
getElement() 生成的 CSS 路径只描述当前 document / ShadowRoot 树，不包含 iframe 边界。

**结论：**当前代码有 Shadow DOM 的部分穿透设计，但没有 iframe frame tree 的处理。跨域 iframe 内元素不能由顶层页面脚本直接访问；同源 iframe 也没有被当前 picker 主动递归遍历。不能把“支持 Shadow DOM”宣传成“支持 iframe”。

**整改：**基于 CDP Page.getFrameTree 建立 frame registry；为每个可访问 frame 建立 execution context，selector reference 携带 frameId 与 frame 内 selector；跨域 iframe 通过 CDP frame execution context 定位，而不是依赖顶层 JS 的同源访问。对于无法接管的特殊 frame，明确返回 unsupported / inaccessible。

**验收：**同源 iframe、跨域 iframe、嵌套 iframe、iframe 内 Shadow DOM 分别测试拾取、定位、点击、输入；页面导航和 frame 重建后 frameId 必须刷新。

12.3 P1：外部 CDP 单条命令没有超时和 pending 清理

源码证据：

packages/rpa-core/src/browser/transport.ts:96-117：send() 将请求写入 pending，等待对应 response；没有单次请求 timer / AbortSignal。
只有 WebSocket close/error 时 failAllPending() 才会清理 pending（transport.ts:76-78, 160-165）。
transport.ts:83-90：connect() 用 Promise.race() 做连接超时，但超时分支没有清理 timer，也没有关闭已经创建的 WebSocket transport。

**影响：**CDP 某条命令若既不返回响应、WebSocket 又没有断开，调用会一直 pending；上层 Runtime 的 withTimeout() 只能让节点 Promise 超时，不能清掉 transport 内部 pending 项。连接超时后底层 socket 也可能继续存活。

整改：send(method, params, { timeoutMs, signal }) 为每个 request 建 timer；超时后删除 pending 并 reject；连接超时必须清 timer、关闭 socket；所有 timer 在成功、失败、close 三条路径都清理。超时错误要保留 method、targetId、requestId。

**验收：**模拟不返回 response、WS 断线、连接握手超时、主动 close；断言 Promise 在期限内结束、pending 数回到 0、socket 不泄漏。

12.4 P1：所谓“跟随前台标签页”实际上取 `/json/list` 的第一项

源码证据：

src/main/browser/session.ts:205-213 的 followForegroundTab() 调用 listPageTargets() 后直接取 pages[0]。
src/main/browser/session.ts:1293-1305 的 picker followForegroundTab() 同样取 pages[0]。
packages/rpa-core/src/browser/external.ts:242-250 的 listPageTargets() 只是按 /json/list 返回顺序过滤并映射，没有查询实际窗口焦点或活动 target。
listTabs() 的 active 字段只是比较 page.id === this.activeTargetId（session.ts:1186-1193），代表当前 CDP session 绑定页，不代表用户实际看到的前台页。

**结论：**注释中的“前台标签页”与实现语义不一致。多标签场景下 /json/list 第一项不保证是当前活动标签页，可能切错页面，造成操作落在用户看不到的页面。

**整改：**明确产品语义到底是“用户前台页”还是“流程当前绑定页”。若要求真实前台页，使用可验证的活动 target 机制（并处理 Chromium 版本差异）；若只是流程绑定页，删除“前台跟随”逻辑和误导性注释，要求通过 targetId 明确切页。

**验收：**至少 3 个标签页，交替切换前台页，比较用户可见页、CDP 当前页、RPA active 标记；点击新标签、页面跳转、关闭标签时检查绑定状态。

12.5 P1：AI 桌面拾取取消未贯穿检测和 OCR，存在后台任务继续运行的路径

源码证据：

src/main/desktop-pick.ts:480-490：detection 先启动截图与 detectUiElements()，OCR recognizePane() 并行启动；这两个任务都没有接收 AbortSignal。
desktop-pick.ts:506-528：取消 watcher 只与 detection 做 Promise.race()；取消先发生时只结束外层等待，不会停止检测/截图/OCR底层工作。
desktop-pick.ts:557-589：OCR 后台任务独立运行并更新 overlay。
desktop-pick.ts:613-614：用户确认候选后直接 await detected.ocrTask，没有额外硬超时。
src/main/local-vision/pane-ocr-service.ts:88-112：recognizePane() 等待模型初始化和 ocr.detect()，接口没有 signal / timeout。

**影响：**用户取消时，CPU/GPU 推理或 OCR 仍可能继续；overlay 已销毁时后台检测后续仍可能访问窗口对象；用户确认后 OCR 若卡住，拾取流程可能超过 UI 的 180 秒候选等待期限继续挂起。

**整改：**为拾取建立统一 AbortController，贯通截图、检测、OCR、overlay 更新和 UIA enrichment；第三方模型不能中止时，至少在取消后丢弃结果、禁止更新 UI，并限制并发任务数。OCR 结果不应成为确认回填的无限等待条件：设定独立预算，超时允许以 AI 框 + UIA 结果回填，并将 OCR 标记为未完成。

**验收：**分别在截图、模型加载、检测、OCR、UIA enrichment 阶段取消；断言取消后不再更新 UI、不再启动后续步骤、overlay/hotkey/临时图片均清理；OCR 超时仍能按明确降级策略完成或失败。

12.6 P2：浏览器选择器属性读取路径存在二次解析偏差

getText(selector, attribute) 先经 locate() 成功，再在属性分支中直接 document.querySelector(spec.value)。即使 locate 未来补齐 XPath / Shadow DOM，属性分支仍会绕过统一解析器。应与 12.1 一并修复，不要单独打补丁。

12.7 当前测试证据不足：浏览器底层实现没有被集成测试覆盖

**源码核验：**当前 ZIP 中存在 src/main/capabilities/browser*.test.ts，但相关测试主要验证能力 handler 向 BrowserLike 转发参数及 mock 行为；未发现针对 src/main/browser/session.ts / packages/rpa-core/src/browser/transport.ts 的真实 DOM / CDP transport 单元测试。browser-common.test.ts 对 XPath 的测试验证的是把 xpath://button 传给 mock 的 getElement，并不验证 BrowserSession 能否解析 XPath。

建议新增测试层：

selector-resolver.test.ts：纯 DOM fixture，统一覆盖 CSS/XPath/Text/ARIA/Shadow DOM/iframe。
cdp-transport.test.ts：mock WebSocket，覆盖乱序响应、超时、close、断线和 pending 清理。
browser-session.integration.test.ts：使用真实 Chromium/Electron fixture 验证拾取 selector 到 click/type 的端到端一致性。
browser-multitab.test.ts：多 target 切换、前台页识别、页面导航与 target 生命周期。
desktop-picker-cancel.test.ts：各阶段取消、OCR 超时、overlay/hotkey/temp file 清理。

12.8 本轮深挖结论与修复顺序

顺序	事项	等级	建议处理
1	统一 selector resolver，修复 XPath / Shadow DOM 的 locate 执行不一致	P1	先修，直接影响浏览器自动化成功率
2	CDP request timeout、AbortSignal、pending 清理	P1	先修，避免浏览器节点永久挂起
3	iframe/frameId 支持边界与实现	P1	先明确 MVP 支持范围，再实现
4	修正前台标签语义，不能把 pages[0] 当 active	P1	多标签演示前修复
5	AI 拾取取消贯穿检测/OCR/资源清理	P1	桌面拾取稳定性验收前修复
6	增加 BrowserSession/CDP/Picker 真实集成测试	P1	修复后必须补证据

**本轮仍未执行：**Vitest、TypeScript typecheck、Electron build、真实 Edge/Chrome CDP 测试、Windows UIA/Office/DPI 实机测试。上述是源码级缺陷/风险定位，不等于已经在用户机器上复现。

60 KiB Raw Permalink Blame History Unescape Escape

RPA 项目技术审查与 Agent-Employee 集成实施总方案

0. 执行摘要

1. 项目目标与已确认约束

2. 当前架构画像

2.1 已经具备的基础

2.2 不能据此宣称已经完成的事项

3. 本轮继续审查新增发现

P1-NEW-01：RPA Core 内仍有动态 Electron 依赖，依赖护栏漏检

P1-NEW-02：@rpa/core 包依赖声明不完整

P1-NEW-03：registerAll(engine) 参数和 Engine 实例没有实际隔离效果

P1-NEW-04：CLI 冒烟测试不能证明 Engine 注入和 Core 独立性

P1-NEW-05：迁移文档与任务清单互相矛盾，完成度表述不可信

4. 元素拾取与视觉定位：统一技术路线

4.1 建议识别优先级

4.2 Selector 应保存“语义 + 定位证据”，而不是只存坐标

4.3 当前代码复核原则

5. Agent-Employee 集成目标架构

6. 当前问题优先级总表

7. 执行安全整改方案

7.1 取消必须贯穿整条调用链

7.2 超时不等于操作已停止

7.3 重试必须基于能力语义

7.4 状态机

8. 平台适配路线

8.1 当前定位

8.2 建议分阶段

8.3 平台标记单一来源

9. 推荐实施顺序与阶段门禁

阶段 0：先固化演示基线（Windows）

阶段 1：Core 接入前 P0

阶段 2：包边界闭环

阶段 3：Agent-Employee 契约对齐

阶段 4：小范围垂直切片

阶段 5：能力规模化与跨平台

10. 交付给接入团队的材料清单

11. 本轮审查边界

附录 A：此前二次源码审查细项

RPACore 二次源码审查与 Agent-Employee 接入整改报告

0. 总体结论

本轮核验到的项目事实

建议优先级

1. P0：执行安全与依赖闭环

P0-01 超时只终止 Runtime 等待，不保证底层能力停止

P0-02 取消时节点状态可能记录为 failed，而非 cancelled

P0-03 Engine 创建接口没有真正的 Driver 注入能力

P0-04 Registry 与 Engine 生命周期不一致，registerAll(engine) 参数没有生效

P0-05 HostBridge/SubflowSource 是模块级单例

2. P1：流程图语义与运行时完整性

P1-01 执行器缺少运行前 Graph Validator

P1-02 skipOnError、错误分支与 Stop/Break/Continue 的状态语义需统一

3. P1：能力元数据、安全治理与平台支持

P1-01 能力目录平台标记数据异常

P1-02 CapabilityMeta 不足以承载 Agent-Employee 权限治理

P1-03 Driver 抽象尚未形成平台隔离边界

P1-04 跨平台目标与当前实现状态需要分开表达

4. P1/P2：包工程化与质量护栏

P1-05 @rpa/core 还不是完整的可发布包

P2-01 依赖护栏是正则扫描，不是完整依赖边界证明

P2-02 Registry 重复注册与元数据覆盖规则不明确

P2-03 registerAll() 可能发生部分注册

P2-04 AI 请求缺少调用方取消信号

5. 上一版元素拾取报告的回归核验

6. 推荐目标架构与接入边界

7. 整改顺序与验收门槛

第一阶段：执行安全（接入前）

第二阶段：依赖闭环（接入前）

第三阶段：平台与包工程化（联调阶段）

接入验收最低标准

8. 需要与 Agent-Employee 团队共同确认的 ADR

9. 审查限制与下一步

12. 第三轮深挖：Runtime、浏览器执行链与元素拾取

12.1 P1：BrowserSession 的定位与执行查找器不一致，拾取结果不保证可执行

12.2 P1：iframe 未进入浏览器拾取与执行上下文模型

12.3 P1：外部 CDP 单条命令没有超时和 pending 清理

12.4 P1：所谓“跟随前台标签页”实际上取 /json/list 的第一项

12.5 P1：AI 桌面拾取取消未贯穿检测和 OCR，存在后台任务继续运行的路径

12.6 P2：浏览器选择器属性读取路径存在二次解析偏差

12.7 当前测试证据不足：浏览器底层实现没有被集成测试覆盖

12.8 本轮深挖结论与修复顺序

60 KiB

Raw Permalink Blame History

P1-NEW-02：`@rpa/core` 包依赖声明不完整

P1-NEW-03：`registerAll(engine)` 参数和 Engine 实例没有实际隔离效果

P0-04 Registry 与 Engine 生命周期不一致，`registerAll(engine)` 参数没有生效

P1-02 `skipOnError`、错误分支与 Stop/Break/Continue 的状态语义需统一

P1-05 `@rpa/core` 还不是完整的可发布包

P2-03 `registerAll()` 可能发生部分注册

12.4 P1：所谓“跟随前台标签页”实际上取 `/json/list` 的第一项