230e3c79ec
- dev-conventions：平台标记收敛为注册分组表单一源，能力文件不得散写 process.platform - rpa-core-migration-guide：重写为通俗版（现状/搬迁步骤/三端计划） - gen-word-flow.py：Word 报告加工流程生成脚本（此前漏交）
5.2 KiB
5.2 KiB
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 层禁令（现有代码不追溯，新代码必须遵守）
- 禁止
import ... from "electron"需要剪贴板/对话框/截屏/屏幕信息时：先看 Node 等价物（fs/os/child_process）， 确实需要宿主能力时在 RunContext 或参数中注入，并在代码处注释// HostBridge 候选。 - 禁止横向依赖宿主模块
L1 内禁止
import "../settings"、"../logger"、"../flows"等。配置走参数/ctx，日志走ctx.log。 - 禁止私起 PowerShell 进程
所有 PowerShell 调用必须使用
capabilities/desktop.ts导出的powershell()/psString()。 禁止自己execFile("powershell.exe", ...)。原因：将来统一切换为常驻 worker（任务 3.5）。 - 禁止新增模块级可变全局状态
不写模块顶层
const cache = new Map()/let globalXxx。需要跨调用状态时挂在显式 store 或 RunContext 上（目标形态：createEngine()实例持有）。 - 禁止把 PowerShell 逻辑写成不可拆的内联串 复杂脚本提取为独立函数/常量，便于将来搬进 WindowsDriver。
三、能力编写规范（tool 友好，为 Agent-Employee 准备）
- 结构化进出：参数从
args对象取具名字段，返回结构化对象或原始值； 禁止返回"为 UI 拼接的字符串"（渲染层需要展示时自行格式化）。 - 必有超时：涉及外部交互（进程/网络/窗口等待）的能力必须有 timeout 参数和默认值。
- 错误契约：失败抛
RuntimeError(code, message, { recommendation })； code 用稳定英文枚举（必须登记在packages/rpa-core/src/engine/error-codes.ts的RUNTIME_ERROR_CODES，任务 4.3 起机器可读），message 中文，recommendation 给可执行建议。禁止裸 throw string。 - 平台标记（单一源，三端优先 win）：平台归属只有一处权威——注册分组表
（迁入前固化为
register-all.ts的PLATFORM_GROUPS，现阶段按分组在 catalog 构建时统一标win32）。 能力文件不得自带平台标记、不得散写process.platform判断（例外白名单单独维护）；meta.platforms与 catalog 的platformTag都从分组表派生，一致性由测试守卫。 现阶段所有能力只标win32，darwin/linux仅在类型枚举里占位，不填任何数据； 将来支持新平台 = 新增分组 + 表里加一行，不做别的。 - 可测试：每个能力有同名
*.test.ts（vitest），与实现同目录。 - 结构化 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 禁令约束。