2026-11-03 21:14:55 -05:00
|
|
|
|
# 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 })`；
|
2026-11-04 00:41:24 -05:00
|
|
|
|
code 用稳定英文枚举（必须登记在 `packages/rpa-core/src/engine/error-codes.ts`
|
|
|
|
|
|
的 `RUNTIME_ERROR_CODES`，任务 4.3 起机器可读），message 中文，recommendation 给可执行建议。禁止裸 throw string。
|
2026-11-05 04:02:10 -05:00
|
|
|
|
4. **平台标记（单一源，三端优先 win）**：平台归属只有一处权威——注册分组表
|
|
|
|
|
|
（迁入前固化为 `register-all.ts` 的 `PLATFORM_GROUPS`，现阶段按分组在 catalog 构建时统一标 `win32`）。
|
|
|
|
|
|
能力文件**不得**自带平台标记、**不得**散写 `process.platform` 判断（例外白名单单独维护）；
|
|
|
|
|
|
`meta.platforms` 与 catalog 的 `platformTag` 都从分组表派生，一致性由测试守卫。
|
|
|
|
|
|
现阶段所有能力只标 `win32`，`darwin`/`linux` 仅在类型枚举里占位，**不填任何数据**；
|
|
|
|
|
|
将来支持新平台 = 新增分组 + 表里加一行，不做别的。
|
2026-11-03 21:14:55 -05:00
|
|
|
|
5. **可测试**：每个能力有同名 `*.test.ts`（vitest），与实现同目录。
|
2026-11-04 00:41:24 -05:00
|
|
|
|
6. **结构化 meta（任务 4.1 起，新能力强制）**：`register(ids, handler, meta)` 第三参
|
|
|
|
|
|
必填 `CapabilityMeta`（summary / params / returns / timeoutMs / errorCodes /
|
|
|
|
|
|
needsScreenshot / platforms）。老能力逐步补齐，review 时放行不带 meta 的旧文件改动。
|
2026-11-03 21:14:55 -05:00
|
|
|
|
|
|
|
|
|
|
## 四、新能力验收 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 禁令约束。
|
