16 KiB
16 KiB
sgClaw 系统架构全景图
文档版本: 1.0
适用项目: sgClaw
编制日期: 2026-04-15
1. 系统边界总览
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) — 传统嵌入模式
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) — 独立服务模式
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 内部模块关系
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. 安全模型三层防线
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 体系与执行路径
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)
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)
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 的交互边界
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 工具权限控制 |