# 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 用稳定英文枚举（必须登记在 `packages/rpa-core/src/engine/error-codes.ts`
   的 `RUNTIME_ERROR_CODES`，任务 4.3 起机器可读），message 中文，recommendation 给可执行建议。禁止裸 throw string。
4. **平台标记**：Windows 专用能力（user32/UIA/COM）在 catalog 注册时带
   `platforms: ["win32"]`；能用纯 Node 实现的能力不调 PowerShell。
5. **可测试**：每个能力有同名 `*.test.ts`（vitest），与实现同目录。
6. **结构化 meta（任务 4.1 起，新能力强制）**：`register(ids, handler, meta)` 第三参
   必填 `CapabilityMeta`（summary / params / returns / timeoutMs / errorCodes /
   needsScreenshot / platforms）。老能力逐步补齐，review 时放行不带 meta 的旧文件改动。

## 四、新能力验收 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 禁令约束。