# sgClaw 系统架构全景图

**文档版本**: 1.0<br>
**适用项目**: sgClaw<br>
**编制日期**: 2026-04-15

---

## 1. 系统边界总览

```mermaid
graph TB
    subgraph BrowserHost["浏览器宿主 (SuperRPA / Chromium)"]
        direction TB
        H1["Launch Config<br/>启动配置"]
        H2["Chromium 子进程管理<br/>启动/监控 sgClaw"]
        H3["Browser Command 执行器<br/>click/type/navigate/eval/..."]
        H4["HMAC 复检 + 域名校验<br/>宿主侧安全边界"]
        H5["Frontend Bundle<br/>展示面 (Vue 2 页面)"]

        H1 --> H2
        H2 --> H3
        H3 --> H4
        H4 -.展示.-> H5
    end

    subgraph sgClawProcess["sgClaw 进程 (Rust)"]
        direction TB
        S1["Transport 层<br/>STDIO / WebSocket"]
        S2["Security 层<br/>MAC Policy + HMAC 签名"]
        S3["Agent 层<br/>消息路由 + 任务分发"]
        S4["Compat 层<br/>ZeroClaw 运行时 + Skill 工具链"]
        S5["Browser Backend 抽象<br/>Pipe / WS / Callback / Bridge"]
        S6["Config 层<br/>Runtime Config + 环境变量"]

        S1 --> S2
        S2 --> S3
        S3 --> S4
        S4 --> S5
        S6 -.配置注入.-> S4
    end

    subgraph ZeroClawCore["ZeroClaw 核心 (vendored)"]
        direction TB
        Z1["Planner / Executor<br/>任务分解与执行"]
        Z2["Tool Loop<br/>工具调用循环"]
        Z3["Skills / Memory<br/>技能加载与记忆"]
        Z4["Provider Dispatch<br/>LLM 路由"]
        Z5["Prompt Builder<br/>System Prompt 组装"]

        Z1 --> Z2
        Z2 --> Z3
        Z3 --> Z4
        Z5 --> Z1
    end

    subgraph ExternalServices["外部服务"]
        direction TB
        E1["LLM Provider<br/>DeepSeek / OpenAI / Claude"]
        E2["平台浏览器页面<br/>业务页面 + 隐藏域"]
    end

    BrowserHost <-->|"STDIO JSON Line<br/>AgentMessage / BrowserMessage"| sgClawProcess
    sgClawProcess <-->|"Rust API 调用|vendored"| ZeroClawCore
    ZeroClawCore <-->|"HTTP API|内部调用"| ExternalServices
    sgClawProcess <-->|"Pipe Mode: STDIO<br/>Service Mode: WS|Browser Backend| ExternalServices
```

---

## 2. 双部署模式架构

### 2.1 Pipe Mode (STDIO) — 传统嵌入模式

```mermaid
sequenceDiagram
    participant Host as 浏览器宿主 (Chromium)
    participant Pipe as StdioTransport
    participant MAC as MAC Policy
    participant Agent as Agent / TaskRunner
    participant ZC as ZeroClaw Runtime
    participant Backend as PipeBrowserBackend
    participant Tool as BrowserPipeTool
    participant HostExec as 宿主 Command 执行器

    Note over Host,HostExec: Pipe Mode: 一问一答式 STDIO

    Host->>Pipe: Init {version, hmac_seed, capabilities}
    Pipe->>Pipe: derive_session_key(hmac_seed)
    Pipe-->>Host: InitAck {version, agent_id, supported_actions}

    Host->>Agent: SubmitTask {instruction, page_url, page_title}
    Agent->>Agent: resolve_submit_instruction()
    alt deterministic_submit (如 线损。。。)
        Agent->>Agent: 生成 DeterministicExecutionPlan
        Agent->>Tool: execute_browser_script_skill_raw_output
    else 通用 LLM 驱动
        Agent->>ZC: 构造 ZeroClaw Agent
        ZC->>Tool: tool loop: browser_action
    end

    Tool->>MAC: validate(domain, action)
    MAC-->>Tool: allow / deny

    Tool->>Backend: invoke(action, params)
    Backend->>Pipe: AgentMessage::Command {seq, action, params, hmac}
    Pipe-->>Host: stdout: Command JSON

    Host->>HostExec: 执行浏览器命令
    HostExec-->>Host: 执行结果
    Host->>Pipe: BrowserMessage::Response {seq, success, data}
    Pipe-->>Backend: Response 回包
    Backend-->>Tool: CommandOutput
    Tool-->>ZC: ToolResult
    ZC-->>Agent: tool loop 继续或完成
    Agent-->>Host: TaskComplete {success, summary}
```

### 2.2 Service Mode (TCP + WebSocket) — 独立服务模式

```mermaid
sequenceDiagram
    participant Console as 前端控制台 (浏览器)
    participant WSS as WebSocket Server<br/>(127.0.0.1:42321)
    participant Agent as Agent / TaskRunner
    participant Callback as BrowserCallbackBackend
    participant HTTP as Callback HTTP Server<br/>(127.0.0.1:17888)
    participant Helper as Helper Page<br/>(浏览器内嵌辅助页)
    participant Target as 目标业务页面

    Note over Console,Target: Service Mode: 持久化服务 + Helper Page 桥接

    Console->>WSS: WebSocket Connect
    WSS->>Callback: 创建会话

    Console->>WSS: ClientMessage::SubmitTask
    WSS->>Agent: 分发任务
    Agent->>Callback: BrowserBackend::invoke()

    callback Backend 内部流程:
    Callback->>Helper: 通过 HTTP Server 推送 Command
    Helper->>Target: sgBrowserExcuteJsCodeByDomain<br/>在目标域执行 JS

    Target-->>Helper: callBackJsToCpp / XHR POST
    Helper->>HTTP: POST /sgclaw/callback/events
    HTTP-->>Callback: Callback 事件回传

    Callback-->>Agent: CommandOutput
    Agent-->>WSS: ServiceMessage::TaskComplete
    WSS-->>Console: WebSocket 推送结果
```

---

## 3. sgClaw 内部模块关系

```mermaid
graph LR
    subgraph EntryPoints["入口点"]
        E1["src/main.rs<br/>sgclaw::run()"]
        E2["src/service/mod.rs<br/>service::run()"]
    end

    subgraph PipeLayer["pipe 层 — 传输与协议"]
        P1["StdioTransport<br/>STDIO 读写"]
        P2["BrowserMessage / AgentMessage<br/>消息枚举定义"]
        P3["Handshake<br/>握手协议"]
        P4["BrowserPipeTool<br/>发送 Command / 等待 Response"]
        P5["HMAC 签名<br/>sign_command"]
    end

    subgraph SecurityLayer["security 层 — 安全策略"]
        M1["MacPolicy<br/>从 rules.json 加载规则"]
        M2["Domain Allowlist<br/>域名白名单校验"]
        M3["Action Allowlist/Blocklist<br/>动作黑白名单"]
    end

    subgraph AgentLayer["agent 层 — 消息路由与任务分发"]
        A1["handle_browser_message_with_context<br/>消息分发"]
        A2["TaskRunner<br/>任务解析与执行"]
        A3["resolve_submit_instruction<br/>Deterministic Submit 检测"]
    end

    subgraph CompatLayer["compat 层 — ZeroClaw 兼容"]
        C1["RuntimeEngine<br/>构建 Agent 实例"]
        C2["ToolPolicy<br/>工具权限控制"]
        C3["BrowserScriptSkillTool<br/>Skill browser_script 执行"]
        C4["DeterministicSubmit<br/>线损确定性提交"]
        C5["BrowserToolAdapter<br/>ZeroClaw 工具适配"]
        C6["ConfigAdapter<br/>配置转换"]
    end

    subgraph BrowserLayer["browser 层 — 浏览器后端"]
        B1["BrowserBackend trait<br/>统一接口"]
        B2["PipeBrowserBackend<br/>Pipe Mode 实现"]
        B3["WsBrowserBackend<br/>WebSocket 直接连接"]
        B4["BrowserCallbackBackend<br/>Helper Page 桥接"]
        B5["BridgeBrowserBackend<br/>网桥模式"]
    end

    subgraph ServiceLayer["service 层 — 服务模式"]
        SV1["WebSocket Server<br/>TCP 监听"]
        SV2["Session Manager<br/>单客户端单任务"]
        SV3["Callback HTTP Server<br/>辅助页通信"]
    end

    subgraph ConfigLayer["config 层 — 运行时配置"]
        CF1["SgClawSettings<br/>从 JSON / 环境变量加载"]
        CF2["Provider Config<br/>API Key / Model"]
        CF3["Backend Selection<br/>Pipe vs Service"]
    end

    E1 --> P1
    E2 --> SV1

    P1 --> P2
    P2 --> P3
    P3 --> P4
    P4 --> P5

    P5 --> M1
    M1 --> M2
    M1 --> M3

    M3 --> A1
    A1 --> A2
    A2 --> A3

    A3 --> C1
    A3 --> C4
    C1 --> C2
    C1 --> C3
    C2 --> C5
    C6 --> C1

    C3 --> B1
    C4 --> B1
    C5 --> B1

    B1 --> B2
    B1 --> B3
    B1 --> B4
    B1 --> B5

    SV1 --> SV2
    SV1 --> SV3
    SV2 --> B4

    CF1 --> CF2
    CF1 --> CF3
    CF3 --> A1
```

---

## 4. 安全模型三层防线

```mermaid
graph TB
    subgraph Layer1["第一层: 握手与会话完整性"]
        L1A["Browser 发送 Init<br/>携带 hmac_seed"]
        L1B["sgClaw 回 InitAck<br/>分配 agent_id"]
        L1C["派生 Session Key<br/>SHA256(hmac_seed + salt)"]
        L1D["未完成握手<br/>拒绝进入运行态"]

        L1A --> L1B --> L1C --> L1D
    end

    subgraph Layer2["第二层: Rust 侧 MAC Policy"]
        L2A["加载 rules.json<br/>version, domains, actions"]
        L2B["Domain 白名单校验<br/>strip scheme/path/port"]
        L2C["Action 黑白名单<br/>allowed + blocked 双重过滤"]
        L2D["本地仪表盘特殊处理<br/>__sgclaw_local_dashboard__"]

        L2A --> L2B
        L2A --> L2C
        L2A --> L2D
    end

    subgraph Layer3["第三层: 宿主侧命令执行约束"]
        L3A["序列号关联校验"]
        L3B["HMAC-SHA256 签名验证"]
        L3C["域名与页面上下文匹配"]
        L3D["非法参数拒绝执行"]

        L3A --> L3B --> L3C --> L3D
    end

    Layer1 ==>|"Session Key"| Layer2
    Layer2 ==>|"Command + HMAC"| Layer3
```

---

## 5. Skill 体系与执行路径

```mermaid
graph TB
    subgraph SkillDefinition["Skill 定义 (SKILL.toml)"]
        SD1["skill metadata<br/>name, version, description"]
        SD2["tools 数组<br/>kind: browser_script / http_request / ..."]
        SD3["prompts 数组<br/>触发条件描述"]
        SD4["scripts/ 目录<br/>JS 脚本文件"]
    end

    subgraph SkillLoading["Skill 加载"]
        SL1["ZeroClaw Skill Loader<br/>从 skillsDir 扫描"]
        SL2["BrowserScriptSkillTool<br/>为每个 tool 创建执行器"]
        SL3["命名: {skill_name}.{tool_name}"]
    end

    subgraph ExecutionPaths["执行路径"]
        EP1["路径 A: LLM 驱动<br/>Agent tool loop → browser_action"]
        EP2["路径 B: Deterministic Submit<br/>指令匹配 → 直接执行 (无 LLM)"]
        EP3["路径 C: Direct Skill Runtime<br/>配置指定 skill → 直接执行"]
    end

    subgraph BrowserExecution["浏览器侧执行"]
        BE1["Eval 包装<br/>(function() { const args = {...}; ... })()"]
        BE2["Action::Eval<br/>通过 BrowserBackend 执行"]
        BE3["返回 ToolResult<br/>结构化结果"]
    end

    SD1 --> SD2 --> SD4
    SD2 --> SD3

    SD1 --> SL1 --> SL2 --> SL3

    SL3 --> EP1
    SL3 --> EP2
    SL3 --> EP3

    EP1 --> BE1
    EP2 --> BE1
    EP3 --> BE1

    BE1 --> BE2 --> BE3
```

---

## 6. Helper Page 机制 (Service Mode)

```mermaid
graph TB
    subgraph sgClawService["sgClaw Service 进程"]
        WS["WebSocket Server<br/>:42321"]
        HTTP["HTTP Server<br/>:17888"]
        CB["BrowserCallbackBackend"]
    end

    subgraph BrowserTabs["浏览器 Tab 页"]
        Helper["Helper Page Tab<br/>/sgclaw/browser-helper.html"]
        Target1["业务页面 1<br/>20.76.57.61:18080/..."]
        Target2["业务页面 2<br/>25.215.213.128:18080/..."]
    end

    subgraph HelperPage["Helper Page 内部"]
        HP1["WebSocket 连接<br/>ws://127.0.0.1:12345"]
        HP2["轮询 Command<br/>GET /sgclaw/callback/commands/next"]
        HP3["推送 Events<br/>POST /sgclaw/callback/events"]
        HP4["回调函数注册<br/>sgclawOnClickProbe / sgclawOnEval / ..."]
    end

    WS -->|"WebSocket"| CB
    CB -->|"推送 Command"| HTTP
    HTTP -->|long-poll| HP2

    HP1 -->|"浏览器 WebSocket API"| Target1
    HP1 -->|"浏览器 WebSocket API"| Target2

    HP2 -->|"执行 JS 命令<br/>sgBrowserExcuteJsCodeByDomain|Target1
    HP2 -->|"执行 JS 命令<br/>sgBrowserExcuteJsCodeByDomain|Target2

    Target1 -->|"callBackJsToCpp|HP4
    HP3 -->|"XHR POST|HTTP
    HP4 --> HP3

    HTTP -->|"Callback 事件|CB
    CB -->|"ToolResult|WS
```

---

## 7. 线损确定性提交流程 (Deterministic Submit)

```mermaid
sequenceDiagram
    participant User as 用户
    participant Host as 浏览器宿主
    participant Agent as Agent / TaskRunner
    participant DS as DeterministicSubmit
    participant Skill as BrowserScriptSkillTool<br/>(collect_lineloss)
    participant Backend as BrowserBackend
    participant Browser as 浏览器页面<br/>(线损域)
    participant Rust as Rust 侧<br/>xlsx 导出

    User->>Host: 输入: "帮我查本月线损率。。。"
    Host->>Agent: SubmitTask {instruction}

    Agent->>DS: decide_deterministic_submit()
    Note over DS: 指令以 "。。。" 结尾<br/>且包含 "线损" 关键词
    DS-->>Agent: Execute(DeterministicExecutionPlan)

    Agent->>Skill: execute_browser_script_skill_raw_output()
    Skill->>Backend: Action::Eval {script: collect_lineloss.js}
    Backend->>Browser: sgBrowserExcuteJsCodeByDomain<br/>(20.76.57.61, js_code)

    Browser->>Browser: validatePageContext(args)
    Browser->>Browser: buildMonthRequest / buildWeekRequest
    Browser->>Browser: $.ajax 查询线损 API
    Browser-->>Backend: 返回 report-artifact JSON
    Backend-->>Skill: ToolResult
    Skill-->>Agent: artifact {status, rows, column_defs}

    Agent->>Rust: export_lineloss_xlsx(artifact)
    Rust->>Rust: 生成 .xlsx 文件
    Rust-->>Agent: 导出完成
    Agent-->>Host: TaskComplete {success: true}
    Host-->>User: 展示结果 + 打开 Excel
```

---

## 8. 平台浏览器与 sgClaw 的交互边界

```mermaid
graph TB
    subgraph PlatformBrowser["平台浏览器 (Chromium)"]
        direction TB
        subgraph PlatformPages["平台场景页面"]
            PP1["场景页 Vue 实例<br/>window.mac"]
            PP2["mutableSystemList<br/>子系统账号池"]
            PP3["getLogint / loginStatusTing<br/>子系统登录编排"]
        end

        subgraph TargetPages["目标业务页面"]
            TP1["线损系统<br/>20.76.57.61:18080"]
            TP2["其他子系统"]
        end

        subgraph BrowserCapabilities["浏览器特权能力"]
            BC1["sgBrowserExcuteJsCodeByDomain<br/>按域名执行 JS"]
            BC2["sgHideBrowerserOpenPage<br/>打开隐藏页面"]
            BC3["sgBrowserCallAfterLoaded<br/>页面加载后执行 JS"]
            BC4["callBackJsToCpp<br/>JS → C++ 回调"]
        end

        PP1 --> PP2
        PP1 --> PP3
    end

    subgraph sgClawProcess["sgClaw 进程"]
        direction TB
        subsgClawTransport["Transport 层"]
        subgClawSecurity["MAC Policy + HMAC"]
        subgClawAgent["Agent / TaskRunner"]
        subgClawCompat["Compat 层"]
        subgClawBackend["Browser Backend"]
    end

    subgClawTransport <-->|"STDIO JSON Line<br/>AgentMessage / BrowserMessage|PlatformBrowser
    subgClawAgent --> subgClawCompat
    subgClawCompat --> subgClawBackend
    subgClawBackend -->|"BrowserAction<br/>sgBrowserExcuteJsCodeByDomain|BC1
    subgClawBackend -->|"BrowserAction<br/>sgHideBrowerserOpenPage|BC2
    subgClawBackend -->|"BrowserAction<br/>sgBrowserCallAfterLoaded|BC3

    BC4 -.回调.-> subgClawBackend

    PlatformBrowser -.安全边界.-> sgClawProcess

    classDef browserSide fill:#e3f2fd,stroke:#1565c0,color:#000
    classDef sgclawSide fill:#fff3e0,stroke:#e65100,color:#000
    classDef interaction fill:#f3e5f5,stroke:#7b1fa2,color:#000

    class PlatformBrowser,PlatformPages,TargetPages,BrowserCapabilities browserSide
    class sgClawProcess,subgClawTransport,subgClawSecurity,subgClawAgent,subgClawCompat,subgClawBackend sgclawSide
```

---

## 9. 模块文件映射

| 模块 | 主要文件 | 职责 |
|---|---|---|
| **pipe 传输层** | `src/pipe/mod.rs`, `src/pipe/transport.rs`, `src/pipe/handshake.rs`, `src/pipe/browser_tool.rs` | STDIO 读写、握手、消息编码解码、HMAC 签名、Command 发送与 Response 等待 |
| **security 安全层** | `src/security/mod.rs`, `src/security/mac_policy.rs`, `src/security/hmac.rs` | MAC Policy 加载与校验、Session Key 派生、命令签名 |
| **agent 消息路由** | `src/agent/mod.rs`, `src/agent/task_runner.rs` | 接收 BrowserMessage 并分发、任务解析、Deterministic Submit 检测 |
| **browser 后端抽象** | `src/browser/mod.rs`, `src/browser/callback_backend.rs`, `src/browser/callback_host.rs`, `src/browser/ws_protocol.rs` | BrowserBackend trait 定义、Pipe/WS/Callback/Bridge 四种实现 |
| **compat 兼容层** | `src/compat/mod.rs`, `src/compat/runtime.rs`, `src/compat/deterministic_submit.rs`, `src/compat/browser_script_skill_tool.rs` | ZeroClaw 运行时构建、线损确定性提交、Skill browser_script 执行 |
| **service 服务模式** | `src/service/mod.rs`, `src/service/session.rs` | WebSocket 服务器、客户端会话管理、单任务并发模型 |
| **config 运行时配置** | `src/config/mod.rs`, `src/config/settings.rs` | SgClawSettings 加载、Provider 配置、Backend 选择 |
| **runtime 运行时引擎** | `src/runtime/mod.rs`, `src/runtime/engine.rs`, `src/runtime/tool_policy.rs` | RuntimeEngine 构建 Agent、ToolPolicy 工具权限控制 |