Skip to content

01-architecture.md

Latest commit

 

History

History
301 lines (252 loc) · 16.9 KB

01-architecture.md

File metadata and controls

301 lines (252 loc) · 16.9 KB
Raw

01 · 总体架构

1. 架构总览

重要定位（v2 修订）：Agent-RPA 是一个无内置 Agent 的确定性底座。"思考"（规划、决策选哪个元素、改写失败步骤）由外部 Agent 提供，通过一个可插拔的 认知端口（Cognition Port） 接入。底座自己只做确定性、0 Token 的事（录制、结晶、回放、隐身执行、编排治理）。这样任何 Agent（Cursor / Claude / Codex / openclaw / 自研）都能"带上自己的脑子"来驱动这套"手脚"。

Agent-RPA 分为三个自有平面 + 一个外部可插拔平面：

flowchart TB
    subgraph EXTERNAL["外部 · 可插拔 Agent 驱动（不属于底座，见 10）"]
        direction LR
        AGD1["Cursor(MCP)"]
        AGD2["Claude / Claude Code"]
        AGD3["Codex(mcp-server)"]
        AGD4["openclaw"]
        AGD5["自研 / 通用 OpenAI 兼容"]
    end
    HU["人类（审批 / 处理升级）"]

    subgraph IF["① 适配面 · Adapter Plane"]
        MCP["MCP Server（inbound：Agent 驱动底座）"]
        API["本地 REST/gRPC API"]
        PORT["Cognition Port（outbound：底座回调 Agent）"]
        ADP["Agent Driver Adapters<br/>(MCP/API/CLI 三类)"]
    end

    subgraph CTRL["② 控制面 · Control Plane（Go 守护进程，0 Token）"]
        ORCH["Orchestrator 编排"]
        REG["Skill Registry 技能注册表"]
        REC["Recorder 录制器"]
        CRYS["Crystallizer 结晶器(确定性核心)"]
        INTP["Replay Interpreter 回放解释器"]
        HEAL["Self-Heal Coordinator 自愈协调"]
        BATCH["Batch/Queue 批量与队列(见 11)"]
        VAULT["Vault 密钥/身份库"]
        LOCREPO["Locator Repository 定位器仓库"]
        OBS["Observability 观测"]
    end

    subgraph EXEC["③ 执行面 · Execution Plane（隐身阶梯 · 可插拔传输）"]
        POOL["Browser/Session/Profile Pool"]
        subgraph DRV["Transport Drivers（浏览器节点）"]
            T0["T0 TLS-HTTP"]
            T1["T1 Patchright"]
            T2["T2 裸CDP/nodriver"]
            T3["T3 极限档"]
        end
        MM["Multimodal Sensing 多模态感知(见 12)"]
        BEH["Behavior Synthesizer 行为合成"]
        FP["Fingerprint/Coherence 指纹一致性"]
    end

    AGD1 & AGD2 & AGD3 & AGD4 & AGD5 -->|inbound 调用| MCP
    MCP --> ORCH
    API --> ORCH
    HU -.审批/升级.-> MCP

    ORCH -->|需要认知时 outbound| PORT
    PORT --> ADP
    ADP -.回调.-> AGD1 & AGD2 & AGD3 & AGD4 & AGD5

    ORCH -->|探索:录制| REC
    REC --> CRYS
    CRYS -->|写入技能| REG
    REC -->|驱动执行| POOL

    ORCH -->|回放/批量| INTP
    BATCH --> INTP
    INTP -->|读技能| REG
    INTP -->|驱动执行| POOL
    INTP -->|失败| HEAL
    HEAL -->|L2/L3 认知请求| PORT
    HEAL -->|回写| REG

    POOL --> DRV
    DRV --> MM
    DRV --> BEH
    DRV --> FP
    INTP --> LOCREPO
    REC --> LOCREPO
    ORCH --> VAULT
    ORCH --> OBS
Loading

读图要点（v2 关键变化）：

  • 底座无内置 Agent：原"认知面（Planner-Actor-Validator）"被移出底座——它属于外部 Agent 驱动。底座通过 Cognition Port 在需要"思考"时回调它们（见 10）。
  • 两个方向的集成：inbound（Agent 经 MCP/API 驱动底座做探索/回放）与 outbound（底座经 Cognition Port 回调某个 Agent 做自愈/无人值守探索）。
  • Token 只花在外部 Agent 侧：底座自身的录制、结晶、回放、批量都是 0 Token；只有当 Cognition Port 被调用（探索、L2/L3 自愈）才由外部 Agent 消耗 Token。
  • 技能注册表是交汇点：探索链路（Recorder+Crystallizer）写技能，回放/批量链路读技能。
  • 执行面对上只暴露统一原语（含多模态感知），底层传输档位 T0–T3 透明可热切换。

2. 已确定的技术栈决策（摘要）

详细对比、取舍与替代方案见 08 · 技术选型。这里给出结论，便于架构 Review。

平面 选择 关键理由（从目标出发）
适配面 Go：MCP Server（inbound）+ gRPC/REST + Cognition Port（outbound） + Agent 驱动适配器 让任意 Agent（含本 AI）零摩擦驱动；底座反过来也能回调 Agent 做自愈
认知（不属于底座） 外部可插拔 Agent 驱动（Cursor/Claude/Codex/openclaw/自研）；无人值守自愈的默认 healer 模型可配置，子 Agent 指定 Fable 5 底座不绑定任何 LLM/Agent；Planner-Actor-Validator 由外部 Agent 承担（见 10）
控制面 Go 单二进制守护进程 贴合 go/src；并发/守护/单文件分发强；清晰的 Orchestrator↔Robot 边界
执行面 可插拔传输 + 隐身阶梯；高强度档=裸 CDP 直驱系统 Chrome（nodriver 系参考实现） 重估的核心：Playwright 控制面过不了自动化协议指纹层，高强度必须放弃它
传输接口 gRPC over UDS（本地）；BrowserNode 契约 语言选择藏在接口后，低后悔；未来服务化直接换成 TCP/mTLS

架构不变量（Invariants）——任何实现都不得违背：

  • I-1 传输是接口，不是具体库；上层不得依赖某个传输的私有能力。
  • I-2 技能包只存"做什么"；"怎么做"由执行面按身份画像重合成。
  • I-3 指纹面从单一 (profile, seed) 派生、跨面自洽；不做逐面随机。
  • I-4 回放/批量期底座零 LLM 调用；任何 Token 消耗都发生在外部 Agent 侧（经 Cognition Port）且被计量。
  • I-5 机密只存 Vault；技能包/日志只见 %变量% 占位。
  • I-6（新增） 底座不内置 Agent：一切"思考"经 Cognition Port 委托给可插拔 Agent 驱动；底座在无任何 Agent/LLM 密钥时，仍能完成纯确定性回放与批量。

3. 组件目录（Component Catalog）

组件 平面 职责 对应 RPA 概念 详见
MCP Server / API 适配 inbound：对 Agent 暴露 explore/run/observe/skill/batch 等工具 —（Agent 时代新增） 06
Cognition Port + Adapters 适配 outbound：底座回调外部 Agent 做规划/决策/自愈；含 Cursor/Claude/Codex/openclaw 适配器 —（Agent 时代新增） 10
（Planner-Actor-Validator） 外部 Agent 规划/单步决策/校验——由外部 Agent 驱动承担，不属于底座 Studio 的"人在设计" 10 / 02
Recorder 控制 探索期确定性记录语义动作/多模态定位器/断言候选 Studio 录制引擎 02
Crystallizer 控制 确定性把探索轨迹结晶成参数化技能包（可选 Agent 辅助去噪/参数化） "录制→脚本"，但自动 02 / 07
Orchestrator 控制 运行调度、并发、生命周期、护栏 Orchestrator 05
Batch/Queue 控制 参数模板、批量导入、工作队列（0 Token 批量回放） Queues 11
Skill Registry 控制 技能存储/版本/检索/依赖 流程库 / Process 05 / 07
Replay Interpreter 控制 0 Token 解释执行技能动作图 Robot 执行器 02
Self-Heal Coordinator 控制 分级自愈调度：L1 本地 0Token；L2/L3 经 Cognition Port 回调 Agent —（自愈新增） 02 / 10
Locator Repository 控制 多模态定位器存储/韧性排序/复用 Object Repository 03 / 12
Vault 控制 凭据/代理/身份 Profile 的机密治理 Assets / Credentials 05
Observability 控制 运行留痕（截图/动作/网络摘要）、指标、审计 Orchestrator 日志 05
Browser/Session/Profile Pool 执行 浏览器启停、会话/Profile 复用与隔离 Robot 运行时 04
Transport Drivers (T0–T3) 执行 隐身阶梯：不同抗检测强度的可插拔驱动 —（新增，含拟人回放） 03 / 04
Multimodal Sensing 执行 截图/AX-tree/DOM/OCR/坐标/网络多通道感知与融合 —（新增） 12
Behavior Synthesizer 执行 Bezier/Fitts/lognormal 轨迹与时序合成 RPA 的"拟人操作" 03
Fingerprint/Coherence 执行 (profile,seed) 派生的一致性指纹 —（新增） 03

4. 主链路一：探索（花 Token，产出技能）

谁在思考：Planner/Actor/Validator 由外部 Agent 驱动承担（图中 AGENT）。底座提供感知与执行原语 + 录制，并在探索结束做确定性结晶。Agent 既可以经 inbound MCP 亲自逐步驱动（observe/act/extract），也可以由底座在 outbound 模式下托管循环——两种姿势见 10。

sequenceDiagram
    autonumber
    participant AGENT as 外部 Agent 驱动
    participant MCP as MCP/适配面
    participant ORCH as Orchestrator
    participant POOL as Browser Pool
    participant REC as Recorder
    participant CRYS as Crystallizer
    participant REG as Skill Registry

    AGENT->>MCP: explore_task(意图, 目标站, 产出schema, 约束)
    MCP->>ORCH: 创建探索 Run（含站点策略/护栏）
    ORCH->>POOL: 申请隐身会话（选身份Profile+传输档位）
    POOL-->>ORCH: session 就绪（真实Chrome+一致画像）
    loop 每个子任务（Agent 承担 Plan/决策/校验）
        MCP->>POOL: observe(截图+AX-tree+DOM 多模态)
        POOL-->>AGENT: 多模态页面状态
        AGENT->>MCP: act/extract（决策由 Agent 做）
        MCP->>POOL: 拟人执行
        MCP->>REC: 记录语义动作/多模态定位器/断言候选
        alt Agent 校验通过
            AGENT-->>MCP: 继续下一步
        else Agent 校验失败
            AGENT-->>MCP: 重决策/重试（Agent 侧）
        end
    end
    AGENT->>MCP: 整体目标达成
    MCP->>CRYS: 移交录制轨迹
    CRYS->>CRYS: 确定性去噪/参数化/定位器生成/断言固化
    CRYS->>REG: 写入技能包（版本化）
    ORCH-->>MCP: 返回结构化结果 + skill_id
    MCP-->>AGENT: 结果 + 可复用技能引用 + 参数模板(见 11)
Loading

关键设计点：

  • 感知是多模态（截图 + AX-tree + DOM，必要时 OCR/坐标，见 12）：截图给视觉布局，AX-tree 给稳定 ref，供 Agent 决策、供 Recorder 生成多模态定位器。
  • 思考在 Agent、记录在底座：决策/校验由外部 Agent 做；底座只负责多模态感知、拟人执行、确定性录制与结晶（I-6）。
  • 校验闭环由 Agent 提供：Agent 把"页面漂移/走错"判定为失败并重决策——这是可自愈的前提；底座把它固化为断言。
  • Recorder 边探索边采集：对每个成功动作即时生成 ≥2 种定位器与断言候选，交给 Crystallizer。

5. 主链路二：0 Token 回放 + 分级自愈

flowchart TD
    START["run_skill(skill_id, 参数)"] --> LOADSKILL["加载技能包 + 绑定变量"]
    LOADSKILL --> SESS["申请隐身会话<br/>(同身份Profile/或按策略轮换)"]
    SESS --> STEP{"取下一个动作"}
    STEP -->|无更多| DONE["产出结构化结果 ✅"]
    STEP -->|有| LOC["按多模态定位器解析元素<br/>(AX-ref→CSS→XPath→视觉→语义)"]

    LOC -->|命中| DOACT["行为合成器拟人执行<br/>(轨迹/时序每次重采样)"]
    LOC -->|未命中| H1

    DOACT --> ASSERT{"断言校验"}
    ASSERT -->|通过| STEP
    ASSERT -->|失败| H1

    subgraph HEAL["分级自愈（成本递增）"]
        H1["L1 本地重定位（底座 0 Token）<br/>AX/视觉/语义多路兜底 + 多模态融合"]
        H1 -->|成功| PATCH
        H1 -->|失败| H2["L2 经 Cognition Port 回调 Agent<br/>只修这一步（Agent 侧 Token）"]
        H2 -->|成功| PATCH
        H2 -->|失败| H3["L3 经 Cognition Port 请 Agent<br/>重探索该子流程（Agent 侧 Token）"]
        H3 -->|成功| PATCH
        H3 -->|失败| ESC["升级人工 / 标记技能失效"]
        PATCH["回写技能包 + 升版本"]
    end

    PATCH --> STEP
    ESC --> FAILEND["结束并上报 ❌"]
Loading

关键设计点（借鉴 Stagehand 的 self-healing cache + workflow-use 的 fallback）：

  • 成本递增的自愈阶梯：L1 是底座本地 0 Token 的多路定位+多模态融合，吸收绝大多数漂移；L2/L3 才经 Cognition Port 回调外部 Agent（Token 花在 Agent 侧，I-4/I-6）。
  • 自愈的两种在场性：交互式回放中若有 Agent 在场，L2/L3 回给同一个 Agent（带其上下文）；无人值守批量时用配置的默认 healer Agent 驱动（见 10）。
  • 修复即回写：任何一级修复成功都更新技能包并升版本，使"同一漂移"下次回放回到 0 Token。
  • 回放期照样拟人：确定性动作的轨迹/时序仍由行为合成器重新采样（I-2）。

6. 部署视图：Orchestrator ↔ 浏览器节点（复刻 RPA 拆分）

flowchart LR
    subgraph AGENTS["外部 Agent 驱动（可插拔，不属于底座）"]
        AGENT["Cursor/Claude/Codex/openclaw/本 AI"]
    end
    subgraph HOST["本地 Mac（darwin/arm64，最优隐身宿主）"]
        subgraph CORE["praxisd（Go 单二进制守护进程）"]
            MCP2["MCP/API 端点(inbound)"]
            ORCH2["Orchestrator + Registry + Interpreter + Batch + Vault"]
            PORT2["Cognition Port(outbound)"]
        end
        subgraph NODES["Transport Drivers（受控子进程）"]
            N1["driver-http (T0)"]
            N2["driver-pw (T1, Patchright)"]
            N3["driver-cdp (T2, nodriver 系)"]
            N4["driver-cdp+ (T3, 极限档)"]
        end
        CHROME["系统 Chrome（真实二进制，headful）"]
    end
    AGENT -->|inbound: MCP 驱动探索/回放| MCP2
    PORT2 -.->|outbound: 回调自愈/无人值守探索| AGENT
    ORCH2 <-->|gRPC over UDS<br/>BrowserNode 契约| NODES
    N2 --> CHROME
    N3 --> CHROME
    N4 --> CHROME
Loading
  • 底座与 Agent 双向解耦：Agent 经 inbound MCP 驱动底座；底座经 outbound Cognition Port 回调 Agent（自愈/无人值守）。Agent 可在别处运行（另一进程/机器），底座无内置脑（I-6）。
  • 单主机、本地优先：核心与驱动都在你的 Mac 上，驱动真实系统 Chrome——基准里最"形状一致"的隐身形态。
  • 驱动 = 独立子进程：崩溃隔离、语言隔离（T2 可用 Python nodriver，核心仍是 Go）、可独立升级。
  • 未来服务化：把 UDS 换成 mTLS+TCP、把 NODES 扩成多台"形状一致的执行节点"，即得多机 Robot 集群（05 详述）。

7. Token 花在哪里（成本模型）

flowchart LR
    A["NL 意图"] -->|首次探索：$$$| B["技能包 v1"]
    B -->|回放：$0| C1["结果#1"]
    B -->|回放：$0| C2["结果#2"]
    B -->|回放遇漂移·L1：$0| C3["结果#3 + 技能 v1.1"]
    B -->|回放遇硬漂移·L2：$| C4["结果#4 + 技能 v1.2"]
Loading
  • 一次性探索成本被后续 N 次 0 Token 回放摊薄——这正是"RPA 中间地带"的经济性来源。
  • 自愈成本是长尾：设计目标是让 L1（0 Token）吸收绝大多数漂移，L2/L3 仅偶发。

8. 与其它文档的衔接

  • 技能怎么生成、结构如何、如何自愈 → 02 + 07
  • 隐身阶梯每档到底做什么、如何选档 → 03
  • 浏览器/会话/Profile 生命周期与驱动契约 → 04
  • 编排、队列、Vault、观测、存储模型 → 05
  • Agent 如何调用、与 Skills 对齐 → 06
  • Agent 驱动可插拔（Cognition Port + 适配器）→ 10
  • 批量执行与参数模板 → 11
  • 多模态感知与融合 → 12

验收检查表（本篇）

  • 底座无内置 Agent；认知经 Cognition Port 外置且可插拔（I-6）。
  • Token 只在外部 Agent 侧发生并被计量（I-4）。
  • 传输为可插拔接口，隐身阶梯 T0–T3 可热切换（I-1）。
  • 探索与回放两条主链路在图上闭环，交汇于技能注册表。
  • 自愈为成本递增阶梯且修复回写（对应 SC7）。
  • 部署为 Go 核心 + 子进程驱动，本地驱动真实 Chrome（对应 SC3/SC5）。