# @rpa/core

RPA 能力层包：零 Electron 依赖的流程引擎、能力注册表与能力实现。
抽离路线见 `docs/rpa-core-refactor-tasks.md`，开发规范见 `docs/dev-conventions.md`。

## 包边界

| 模块 | 说明 |
|---|---|
| `src/engine/` | 注册表、运行时、表达式、`createEngine()` 工厂、`host-bridge.ts` 宿主桥 |
| `src/driver/` | `types.ts` 五域 AutomationDriver 接口（mouse/keyboard/window/screen/element）+ `windows/powershell.ts` 进程助手 + `windows/windows-driver.ts` PowerShell 实现 |
| `src/capabilities/` | 能力实现（副作用注册，经 `@rpa/core/capabilities` 拉起） |
| `src/browser/` | 外部浏览器 CDP：`external.ts`（Edge/Chrome 进程管理）+ `transport.ts`（CdpTransport 接口、ExternalTransport） |

## HostBridge 契约（决策点 4 最小面）

宿主（Electron 主进程 / 未来 Agent-Employee product-shell）启动时注入：

```ts
import { setHostBridge, setSubflowSource } from "@rpa/core";

setHostBridge({
  createFormWindow({ title }) { /* 返回 HostDialogWindow 适配（BrowserWindow） */ },
  dipToScreenPoint(p) { /* screen.dipToScreenPoint */ },
  screenToDipPoint(p) { /* screen.screenToDipPoint */ },
  loadAiConfig() { /* settings.aiConfig */ }
});
setSubflowSource({ listFlows, getFlow }); // 子流程仓库
```

未注入时的行为：window-extended 的 DPI 换算回退恒等（与旧 vitest 行为一致）；
ai-service 返回空配置（requireAiConfig 统一抛 `ai_not_configured`）；
human-dialog 抛 `host_unavailable`。

## Electron 相关能力留守清单（宿主适配层，不入包）

- `src/main/browser/session.ts`：BrowserSession 编排 + 内置运行浏览器（依赖 `BrowserWindow` 与应用生命周期）
- `src/main/browser/transport.ts`：`EmbeddedTransport`（包装 `webContents.debugger`）
- `src/main/capabilities/browser*.ts` / `web-batch2.ts` / `web-crawl.ts`：经 BrowserSession 操作浏览器窗口
- `src/main/capabilities/ai-caps.ts`：AI 编排能力（依赖宿主注入的 chatCompletion 配置面，可随后续阶段评估迁入）
- `src/main/overlay.ts` / `desktop-pick.ts` / `vision-lab.ts` / `fixture/`：Electron 窗口强耦合
- `src/main/local-vision/`：onnxruntime-node 原生依赖，Bun 兼容性单独立项验证
- `src/main/flows.ts` / `run/` / `settings.ts`：应用级编排与持久化

## 依赖护栏

`npm run check:deps`（根目录亦可）扫描 `src/**`：禁止 `import "electron"`、
相对引用逃出包 `src/`、引用宿主 `src/main`。阶段 2 起为提交前必跑项。

## Driver（阶段 3）

- 五域接口 `AutomationDriver`（决策点 6）：`RpaEngine.driver` 默认 `new WindowsDriver()`，
  `createEngine()` 可注入自定义实现（CLI/Linux driver 等未来形态）。
- 驱动只承载**原始注入原语**（单次 SetCursorPos / SendKeys / 窗口操作）；拟真抖动、
  DIP 坐标换算、多步组合等策略留在能力文件，保证机械替换不改时序行为。
- element 域实现承载在 `capabilities/desktop-uia.ts`（经 `setElementDriverImplementation`
  注册到 WindowsDriver），handler 层面向 driver 的收口在阶段 5/6 按需进行。
- `powershell()` 助手统一位于 `driver/windows/powershell.ts`，包内能力禁止自行
  `execFile("powershell.exe")`（check:deps 与 review 双重把关）。
- 平台标记：`npm run catalog` 构建时按组填充 `platformTag: "win32"`（desktop/app/
  office/vision 组），渲染层置灰延后（决策点 7）。