# 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`（应用级编排与持久化，属宿主职责）