495 lines
16 KiB
Markdown
495 lines
16 KiB
Markdown
# 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 工具权限控制 |
|