files 能力增强与 vision 校验修复；落盘 rpa-core 抽离改造任务清单与开发规范
This commit is contained in:
yu authored and trae-solo-agent committed
1 parent
1ff6f59990
commit
f35f0ac979
10 files changed
+577
-81
No files matched your search
@@ -0,0 +1,79 @@
|
||||
# RPA Studio 开发规范（v1 · 面向 rpa-core 抽离）
|
||||
|
||||
> 生效日期：2026-11-04。
|
||||
> 背景：本平台继续作为日常开发载体；所有新代码必须同时满足"当前可用"和"将来可直接搬入
|
||||
> `packages/rpa-core`（最终迁入 Agent-Employee）"。迁移路线与任务清单见
|
||||
> `docs/rpa-core-refactor-tasks.md`，本规范是它的日常执行约束。
|
||||
|
||||
## 核心思想
|
||||
|
||||
**迁移不是将来的改造，而是现在每次写代码时的选择。** 遵守本规范写的能力，抽包时是搬运；
|
||||
违反规范写的能力，抽包时是返工。
|
||||
|
||||
---
|
||||
|
||||
## 一、分层归属（硬性规则）
|
||||
|
||||
| 层 | 目录 | 判别标准 | 未来去向 |
|
||||
|---|---|---|---|
|
||||
| **L1 包内层** | `src/main/engine/`、`src/main/capabilities/` 大部分、`src/main/browser/external.ts`、`transport.ts` | 不依赖 Electron 窗口即可运行 | rpa-core 包 |
|
||||
| **L2 宿主层** | `src/main/index.ts`、`overlay`、`desktop-pick`、`vision-lab`、`fixture/`、`local-vision/`、`flows`、`run/`、`settings`、`logger`、`browser/session.ts` 内置浏览器部分 | 需要 Electron 窗口/应用生命周期 | 宿主适配层 |
|
||||
|
||||
**判别口诀**：这个能力在没有窗口的 CLI 里能跑吗？能 → L1；不能 → L2。
|
||||
|
||||
---
|
||||
|
||||
## 二、L1 层禁令（现有代码不追溯，新代码必须遵守）
|
||||
|
||||
1. **禁止 `import ... from "electron"`**
|
||||
需要剪贴板/对话框/截屏/屏幕信息时：先看 Node 等价物（fs/os/child_process），
|
||||
确实需要宿主能力时在 RunContext 或参数中注入，并在代码处注释 `// HostBridge 候选`。
|
||||
2. **禁止横向依赖宿主模块**
|
||||
L1 内禁止 `import "../settings"`、`"../logger"`、`"../flows"` 等。配置走参数/ctx，日志走 `ctx.log`。
|
||||
3. **禁止私起 PowerShell 进程**
|
||||
所有 PowerShell 调用必须使用 `capabilities/desktop.ts` 导出的 `powershell()` / `psString()`。
|
||||
禁止自己 `execFile("powershell.exe", ...)`。原因：将来统一切换为常驻 worker（任务 3.5）。
|
||||
4. **禁止新增模块级可变全局状态**
|
||||
不写模块顶层 `const cache = new Map()` / `let globalXxx`。需要跨调用状态时挂在显式 store
|
||||
或 RunContext 上（目标形态：`createEngine()` 实例持有）。
|
||||
5. **禁止把 PowerShell 逻辑写成不可拆的内联串**
|
||||
复杂脚本提取为独立函数/常量，便于将来搬进 WindowsDriver。
|
||||
|
||||
## 三、能力编写规范（tool 友好，为 Agent-Employee 准备）
|
||||
|
||||
1. **结构化进出**：参数从 `args` 对象取具名字段，返回结构化对象或原始值；
|
||||
禁止返回"为 UI 拼接的字符串"（渲染层需要展示时自行格式化）。
|
||||
2. **必有超时**：涉及外部交互（进程/网络/窗口等待）的能力必须有 timeout 参数和默认值。
|
||||
3. **错误契约**：失败抛 `RuntimeError(code, message, { recommendation })`；
|
||||
code 用稳定英文枚举，message 中文，recommendation 给可执行建议。禁止裸 throw string。
|
||||
4. **平台标记**：Windows 专用能力（user32/UIA/COM）在 catalog 注册时带
|
||||
`platforms: ["win32"]`；能用纯 Node 实现的能力不调 PowerShell。
|
||||
5. **可测试**：每个能力有同名 `*.test.ts`（vitest），与实现同目录。
|
||||
|
||||
## 四、新能力验收 checklist
|
||||
|
||||
- [ ] 归属判定正确（L1/L2 口诀）
|
||||
- [ ] 无 electron / 宿主模块 import（L1 时）
|
||||
- [ ] PowerShell 只经 `powershell()` 助手（如需要）
|
||||
- [ ] 无新增模块级全局状态
|
||||
- [ ] 结构化参数/返回 + 超时 + RuntimeError 错误契约
|
||||
- [ ] catalog 注册完整（含 platforms 标记）
|
||||
- [ ] 有测试，`npm run test` + `npm run typecheck` 全绿
|
||||
|
||||
## 五、渐进收紧节奏
|
||||
|
||||
规范随改造阶段自动收紧，不必一步到位：
|
||||
|
||||
| 里程碑（见任务清单） | 规范变化 |
|
||||
|---|---|
|
||||
| 现在 | 本文第二节禁令生效（靠 review 执行） |
|
||||
| 阶段 2 完成 | L1 禁 electron 升级为 ESLint no-restricted-imports 强制 |
|
||||
| 阶段 3 完成 | `powershell()` 收口进 `driver/windows/`，L1 禁止直接引用 |
|
||||
| 阶段 4 完成 | 无 schema 的新能力不允许进 catalog |
|
||||
|
||||
## 六、明确不动的部分
|
||||
|
||||
- 现有 77 处 PowerShell 调用点：**不做预防性重构**，统一等阶段 3 的 driver 抽象一次性处理。
|
||||
之前只修 bug、只加能力，不重写。
|
||||
- 渲染层（React）按产品需求正常开发，不为其迁移性投资。
|
||||
- `local-vision/`、`overlay/` 等宿主层模块正常开发，不受 L1 禁令约束。
|
||||
@@ -0,0 +1,116 @@
|
||||
# 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`（应用级编排与持久化，属宿主职责）
|
||||
Reference in new issue
Block a user