PRA-only-demo/docs/rpa-core-refactor-tasks.md

rpa-core 能力层抽离改造任务清单

目标：把 src/main/capabilities/ + src/main/engine/ 抽成零 Electron 依赖的独立包， 先在当前 demo 验证，最终以包为单位迁入 D:\code\Agent-Employee。 风险评估见对话记录（2026-11-04），任务编号 R1~R10 对应风险清单。

总体原则

1. 单一源：包建成后 demo 与未来宿主都通过 workspace 引用，任何时候禁止复制代码（R3）。
2. 行为不变：抽离期间能力行为保持不变，靠现有 vitest 套件做安全网。
3. 先断依赖再抽象：Electron 依赖清零优先于 driver 接口美化。

---

阶段 0 — 基线与护栏

• 0.1 确认基线全绿 npm run test + npm run typecheck 全部通过，记录通过数作为回归基线。
• 0.2 确定包位置与工作区结构 建 packages/rpa-core/，demo 的 package.json 加 workspaces 配置，源码从 src/main 移入后以 @rpa/core 引用回主进程。
• 0.3 生成能力目录快照 用 npm run catalog 的产物做一份快照（能力 id / 参数 / 描述清单），抽离完成后 diff 必须为零，作为行为回归基准。

阶段 1 — 建包与纯 Node 能力搬运

• 1.1 包骨架 packages/rpa-core：package.json（deps: exceljs / pdf-lib / nodemailer / basic-ftp / adm-zip / pngjs）、tsconfig.json、独立 vitest 配置（R6：包内保留 vitest，不迁 bun test）。
• 1.2 领域类型解耦（R2） 搬 engine/（registry / types / runtime / expression），将 shared/types 依赖改为包内自有领域类型（FlowDefinition / FlowNode / CatalogComponent / RunError）。宿主后续做模型映射，不把画布模型塞进包。
• 1.3 全局状态收拢为工厂（R4） 新增 createEngine() 工厂：excel-store 的模块级 Map 缓存、session 的 globalElementWaitMs 等进程级状态挂到引擎实例上；registry 注册目标从全局单例改为引擎实例。
• 1.4 搬运纯 Node 能力 files / data / data-extended / http / ftp / mail / mssql / mysql / pg / excel（exceljs）/ word / pdf / office-file / time / crypto / data-table 等不依赖 Electron 的能力文件。
• 1.5 搬运对应测试 上述能力的 *.test.ts 一并移入包内，路径修正后全量跑绿。
• 1.6 demo 主进程改为引用包 src/main 里被搬走的部分改 import @rpa/core，npm run test 全绿、catalog 快照 diff 为零。

阶段 2 — 断 Electron 依赖

• 2.1 定义 HostBridge 接口 包内声明 HostBridge：clipboard / dialog / screen / userAgentDataPath 等宿主能力；demo 的 Electron 主进程提供实现并注入。
• 2.2 改造直接依赖 Electron 的能力（3 处） capabilities/human-dialog.ts（BrowserWindow）、capabilities/window-extended.ts（screen）、capabilities/ai-service.ts（settings）→ 走 HostBridge 注入。
• 2.3 浏览器子系统切分（R1） browser/external.ts + transport.ts 的外部浏览器 CDP 路径搬进包；session.ts 中依赖内置 BrowserWindow 的部分留在宿主适配层，包内通过 BrowserLike 接口（types.ts 已有）注入。
• 2.4 防回归护栏 在包内加依赖检查脚本（或 ESLint no-restricted-imports 规则）：禁止 import "electron" 及对 src/main 的相对引用，CI 里跑。
• 2.5 Electron 相关能力留守清单 overlay / desktop-pick / vision-lab / fixture server / human-dialog 的 UI 部分：明确标记"宿主适配层"，从包中排除，记录在包 README。

阶段 3 — Driver 抽象（Windows 自动化能力）

• 3.1 拆出 powershell 助手（R5） powershell() / psString() / USER32 从 capabilities/desktop.ts 移到 driver/windows/powershell.ts；修正 11 个引用文件的 import；测试全绿。
• 3.2 定义 AutomationDriver 接口 按域拆分：mouse / keyboard / window / element（UIA）/ screen。接口签名以现有 PowerShell 能力的输入输出为准，不重新发明。
• 3.3 现有实现包进 WindowsDriver desktop / desktop-uia / window-extended / remaining-core / system-extended / common-final / message / utility-extended 中的 user32/UIA 调用改为面向接口；WindowsDriver 内部仍用 PowerShell 实现（行为不变）。
• 3.4 driver 注入与平台标记 引擎创建时注入 driver；能力目录（catalog）加 platforms: ["win32"] 字段，渲染层据此置灰。
• 3.5（可选，迁移前不阻塞）PowerShell 常驻 worker 单进程 JSON 行协议替代每次 spawn；powershell() 接口签名不变，内部切换。性能优化项，放在功能等价验收之后。

阶段 4 — Tool 契约（为 Agent-Employee 做）

• 4.1 能力 schema 化 每个能力导出结构化定义：参数类型 / 返回值 / 超时 / 错误码 / 是否需要截图回传。新能力一律按此格式写。
• 4.2 注册机制显式化 取消 import 副作用注册，改为显式 registerAll(engine) 导出，宿主可按子集注册。
• 4.3 错误契约规范化（R9） RuntimeError 错误码枚举固化，中文 message 保留，增加机器可读字段，供 Agent 侧消费。

阶段 5 — 独立验证

• 5.1 CLI host 写 scripts/rpa-cli.ts：Node 直接拉起 createEngine() + WindowsDriver，跑通 5 个代表能力（1 个桌面、1 个 Excel、1 个 HTTP、1 个文件、1 个窗口）。
• 5.2 Bun 冒烟（R6/R7） 在 Agent-Employee 环境用 bun test 跑包内纯逻辑测试，验证 exceljs / pdf-lib 等依赖在 Bun 下正常；onnxruntime 相关暂不进包，另行验证。
• 5.3 demo 全量回归 demo 切到 workspace 引用后：test + typecheck + catalog 快照 diff 三项全绿。

阶段 6 — 迁入 Agent-Employee

• 6.1 ADR 评审 按 Agent-Employee 流程提交架构决策记录：包边界 / HostBridge 契约 / driver 生命周期。
• 6.2 包迁入 packages/ 整体搬入，改为 bun workspace 成员；demo 侧保留只读引用或解除引用。
• 6.3 宿主适配层 按 Agent-Employee 的 product-shell 契约写 host 适配（clipboard / dialog / screen / BrowserLike 实现）。
• 6.4 权限与治理对接（R10） System_ExecuteCommand 等危险能力接入其权限模型；能力目录与插件体系对齐。

---

风险 → 任务映射

风险	缓解任务
R1 浏览器子系统耦合 Electron	2.3
R2 领域模型冲突	1.2、阶段 4
R3 代码漂移	0.2、总原则 1
R4 模块级全局状态	1.3
R5 powershell 助手位置	3.1
R6 测试运行器不兼容	1.1、5.2
R7 原生依赖 Bun 兼容	5.2（能力层已确认为纯 JS）
R8 注册副作用	4.2
R9 错误契约	4.3
R10 权限治理	6.4

明确不迁入包的部分

• src/renderer/（React 渲染层，Agent-Employee 用 SolidJS，不迁移）
• overlay.ts / desktop-pick.ts / vision-lab.ts / fixture/（Electron 窗口强耦合，留宿主）
• local-vision/（onnxruntime-node 原生依赖，Bun 兼容性单独立项验证）
• flows.ts / run/manager.ts / settings.ts（应用级编排与持久化，属宿主职责）