R
rpa_core 项目总览
从入口、调用链、桌面双后端到旧元素导入，一页看懂项目。
离线可打开 · 自包含 HTML
高层概览
这是一个 clean-room 的 RPA 运行时实验，核心目标是：
显式工作流语义、
隔离执行器、
类型化结果、
可复现运行。
当前仓库已经有三条执行主线：
browser.playwright、
python.worker、以及拆成
desktop.uia /
desktop.win32 的桌面自动化。
1. 仓库结构
rpa_core/
├─ src/rpa_core/
│ ├─ cli.py 命令入口：validate / run
│ ├─ catalog/ 读取命令 manifest
│ ├─ compiler/ Workflow -> ExecutionPlan
│ ├─ runtime/ orchestrator / resolver / events
│ ├─ executors/ browser / python / desktop.uia / desktop.win32
│ ├─ importer/ 旧元素静态导入
│ └─ model/ workflow / command / runtime / desktop 模型
├─ commands/ 命令契约（manifest）
├─ examples/ 示例 workflow / fixture
├─ tests/ 单测、契约测试、E2E
└─ .harness/ 里程碑、任务、ADR、门禁
入口`src/rpa_core/cli.py` 负责 validate / run。
契约`commands/` 里的 manifest 定义 executor、schema 和 effect policy。
运行`runtime/` 负责编排、引用解析、事件与结果落盘。
执行`executors/` 负责真正的浏览器、Python、桌面动作。
2. 运行管线
workflow.json
→
WorkflowCompiler
→
ExecutionPlan
→
Orchestrator
→
ExecutorRegistry
→
CommandExecutor
编排器会先按 manifest 校验输入和输出，再解析引用、路由到指定 executor，最后持久化 events.jsonl 和 result.json。
3. 核心调用链
CLI
└─ load_catalog(commands/)
└─ compile(workflow)
└─ Orchestrator.run(plan)
├─ 校验 manifest + schema
├─ 解析 inputs / steps / loop vars
├─ 根据 manifest.executor 选择执行器
├─ executor.execute(invocation)
└─ 写入 events.jsonl + result.json
4. 桌面双后端
UIA 路径
desktop.uia
├─ pywinauto backend = uia
├─ session 绑定 processId + windowHandle
├─ locator: automationId / controlType / name
└─ 适合 WinForms / WPF / 语义控件
Win32 路径
desktop.win32
├─ pywinauto backend = win32
├─ session 绑定 processId + windowHandle
├─ locator: title / className / handle / controlId / menuPath / foundIndex
└─ 适合记事本、菜单、对话框、经典 HWND 控件
5. 记事本流程
attachMain (win32)
→ menuSelect 文件 → 打开
→ attachDialog (win32)
→ findFileNameInput
→ inputPath
→ hotkey Enter
→ attachOpened (win32)
→ close sessions
这个切片展示了为什么项目要拆成两个显式桌面后端，而不是一个“自动猜”的统一驱动。
6. 旧元素导入器
tests/fixtures/legacy-elements/elements.json
→ LegacyElementImporter
→ ImportedElementCatalog
→ ImportedElement + DesktopLocator
→ diagnostics（忽略 / 缺失 / 歧义）
导入器只处理静态数据：把旧元素记录转换成类型化 locator 和 provenance，不导入或执行任何 rpa_script runtime 模块。
7. 先看哪些文件
src/rpa_core/model/workflow.py 工作流 ASTsrc/rpa_core/compiler/compiler.py 静态校验 / 计划生成src/rpa_core/runtime/orchestrator.py 执行与落盘src/rpa_core/executors/browser.py 浏览器执行器src/rpa_core/executors/python_worker.py Python worker 执行器src/rpa_core/executors/desktop.py UIA 桌面执行器src/rpa_core/executors/desktop_win32.py Win32 桌面执行器
commands/browser/ 浏览器命令契约commands/desktop/ UIA 命令契约commands/desktop_win32/ Win32 命令契约examples/windows-desktop/workflow.json 记事本示例tests/unit/test_legacy_element_importer.py 导入器契约.harness/ 任务、门禁、ADR
8. 心智模型
模型层 数据结构和协议定义在 model/。
契约层 commands/ 里的 manifest 定义 executor、schema、effect policy 和错误形状。
运行层 compiler / orchestrator 保持通用，不嵌 Windows 专用分支。
执行层 executors 负责 OS 相关逻辑、清理和超时。