413 lines
16 KiB
HTML
413 lines
16 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="zh-CN">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>sgClaw 系统架构全景图</title>
|
|
<script src="https://cdn.jsdelivr.net/npm/mermaid@10.9.5/dist/mermaid.min.js"></script>
|
|
<style>
|
|
*{margin:0;padding:0;box-sizing:border-box}
|
|
body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Hiragino Sans GB","Microsoft YaHei",sans-serif;background:#0d1117;color:#c9d1d9;line-height:1.6}
|
|
.header{background:linear-gradient(135deg,#1a1a2e,#16213e,#0f3460);padding:3rem 2rem;text-align:center;border-bottom:3px solid #e65100}
|
|
.header h1{font-size:2.5rem;color:#e6edf3;margin-bottom:.5rem}
|
|
.header .subtitle{color:#8b949e;font-size:.95rem}
|
|
.container{max-width:1400px;margin:0 auto;padding:2rem}
|
|
.section{background:#161b22;border:1px solid #30363d;border-radius:12px;margin-bottom:2rem;overflow:hidden}
|
|
.section-header{background:linear-gradient(90deg,#1a1a2e,#16213e);padding:1.2rem 1.5rem;border-bottom:1px solid #30363d;display:flex;align-items:center;gap:1rem}
|
|
.section-number{background:#e65100;color:#fff;width:36px;height:36px;border-radius:50%;display:flex;align-items:center;justify-content:center;font-weight:700;font-size:1.1rem}
|
|
.section-title{font-size:1.3rem;color:#e6edf3;font-weight:600}
|
|
.section-body{padding:1.5rem;overflow-x:auto}
|
|
.mermaid{display:flex;justify-content:center;padding:1rem 0}
|
|
.mermaid svg{max-width:100%;height:auto}
|
|
.file-table{width:100%;border-collapse:collapse;margin-top:1rem}
|
|
.file-table th,.file-table td{padding:.75rem 1rem;text-align:left;border-bottom:1px solid #21262d}
|
|
.file-table th{background:#1a1a2e;color:#e65100;font-weight:600}
|
|
.file-table td:first-child{color:#58a6ff;font-family:"SF Mono",Monaco,Consolas,monospace;font-size:.85rem}
|
|
.file-table tr:hover{background:rgba(230,81,0,.05)}
|
|
.footer{text-align:center;padding:2rem;color:#484f58;font-size:.85rem;border-top:1px solid #21262d}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<div class="header">
|
|
<h1>sgClaw 系统架构全景图</h1>
|
|
<div class="subtitle">浏览器宿主 x Rust 安全控制层 x ZeroClaw 能力核心 - 双部署模式 三层安全防线 Skill 体系</div>
|
|
</div>
|
|
<div class="container">
|
|
|
|
<div class="section">
|
|
<div class="section-header">
|
|
<div class="section-number">1</div>
|
|
<div class="section-title">系统边界总览 - 四大区域与数据流向</div>
|
|
</div>
|
|
<div class="section-body">
|
|
<div class="mermaid">
|
|
graph TB
|
|
BH["浏览器宿主\n受保护的安全边界\n启动和托管sgClaw子进程"]
|
|
SP["sgClaw进程\nRust安全控制层\nZeroClaw为能力核心"]
|
|
ZC["ZeroClaw核心\nvendored crate\n任务分解 工具循环 LLM路由"]
|
|
ES["外部服务\nLLM API和业务浏览器页面"]
|
|
BH <-- "STDIO JSON Line 进程间通信协议" --> SP
|
|
SP <-- "Rust API调用 vendored库" --> ZC
|
|
ZC <-- "HTTP API 或内部调用" --> ES
|
|
SP <-- "Browser Backend Pipe或WS" --> ES
|
|
classDef hostClass fill:#1a3a5c,stroke:#4a9eff,color:#e6edf3
|
|
classDef sgclawClass fill:#4a2c17,stroke:#e65100,color:#e6edf3
|
|
classDef zcClass fill:#2d1f3d,stroke:#9c27b0,color:#e6edf3
|
|
classDef extClass fill:#1f3d2d,stroke:#4caf50,color:#e6edf3
|
|
class BH hostClass
|
|
class SP sgclawClass
|
|
class ZC zcClass
|
|
class ES extClass
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section">
|
|
<div class="section-header">
|
|
<div class="section-number">2</div>
|
|
<div class="section-title">双部署模式 - Pipe Mode STDIO一问一答</div>
|
|
</div>
|
|
<div class="section-body">
|
|
<div class="mermaid">
|
|
sequenceDiagram
|
|
participant Host as 浏览器宿主
|
|
participant Pipe as StdioTransport
|
|
participant MAC as MAC Policy
|
|
participant Agent as Agent/TaskRunner
|
|
participant ZC as ZeroClaw Runtime
|
|
participant Tool as BrowserPipeTool
|
|
participant Exec as 宿主命令执行器
|
|
Note over Host,Exec: Pipe Mode 一问一答式STDIO通信
|
|
Host->>Pipe: Init 握手:携带版本号 HMAC种子 能力列表
|
|
Pipe->>Pipe: derive_session_key 派生会话密钥
|
|
Pipe-->>Host: InitAck 确认:返回agent_id和支持动作
|
|
Host->>Agent: SubmitTask 提交任务
|
|
Agent->>Agent: 检测确定性提交模式
|
|
alt 确定性提交
|
|
Agent->>Agent: 生成执行计划
|
|
Agent->>Tool: 直接执行Skill
|
|
else LLM驱动
|
|
Agent->>ZC: 构造ZeroClaw Agent
|
|
ZC->>Tool: tool loop调用
|
|
end
|
|
Tool->>MAC: 校验域名和动作
|
|
MAC-->>Tool: 允许或拒绝
|
|
Tool->>Pipe: 写入Command JSON
|
|
Pipe-->>Host: 浏览器接收命令
|
|
Host->>Exec: 执行浏览器命令
|
|
Exec-->>Host: 返回执行结果
|
|
Host->>Pipe: Response回包
|
|
Pipe-->>Tool: 结果回传
|
|
Tool-->>ZC: ToolResult
|
|
ZC-->>Agent: 继续或完成
|
|
Agent-->>Host: TaskComplete
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section">
|
|
<div class="section-header">
|
|
<div class="section-number">3</div>
|
|
<div class="section-title">双部署模式 - Service Mode TCP加WebSocket加Helper Page桥接</div>
|
|
</div>
|
|
<div class="section-body">
|
|
<div class="mermaid">
|
|
sequenceDiagram
|
|
participant Console as 前端控制台
|
|
participant WS as WebSocket Server
|
|
participant Agent as Agent/TaskRunner
|
|
participant CB as BrowserCallbackBackend
|
|
participant HTTP as Callback HTTP Server
|
|
participant Helper as Helper Page
|
|
participant Target as 目标业务页面
|
|
Note over Console,Target: Service Mode 持久化服务+Helper Page桥接
|
|
Console->>WS: WebSocket Connect
|
|
WSS->>CB: 创建会话
|
|
Console->>WS: SubmitTask
|
|
WS->>Agent: 分发任务
|
|
Agent->>CB: invoke执行
|
|
CB->>HTTP: POST Command到队列
|
|
HTTP-->>Helper: long-poll返回Command
|
|
Helper->>Target: sgBrowserExcuteJsCodeByDomain执行JS
|
|
Target-->>Helper: callBackJsToCpp回调
|
|
Helper->>HTTP: POST事件回传
|
|
HTTP-->>CB: Callback事件
|
|
CB-->>Agent: CommandOutput
|
|
Agent-->>WS: TaskComplete
|
|
WS-->>Console: 推送结果
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section">
|
|
<div class="section-header">
|
|
<div class="section-number">4</div>
|
|
<div class="section-title">sgClaw 内部模块关系图</div>
|
|
</div>
|
|
<div class="section-body">
|
|
<div class="mermaid">
|
|
graph LR
|
|
E1["main.rs Pipe模式入口"]
|
|
E2["service模式入口"]
|
|
P1["StdioTransport STDIO读写"]
|
|
P2["消息枚举定义"]
|
|
P3["Handshake握手协议"]
|
|
P4["BrowserPipeTool发送等待响应"]
|
|
P5["HMAC签名防篡改"]
|
|
M1["MacPolicy加载解析"]
|
|
M2["Domain白名单标准化比对"]
|
|
M3["Action黑白名单双重过滤"]
|
|
A1["消息分发handle_browser_message"]
|
|
A2["TaskRunner任务解析"]
|
|
A3["Deterministic Submit指令检测"]
|
|
C1["RuntimeEngine构建Agent"]
|
|
C2["ToolPolicy工具权限"]
|
|
C3["BrowserScriptSkillTool执行器"]
|
|
C4["DeterministicSubmit线损快速通道"]
|
|
C5["BrowserToolAdapter工具适配"]
|
|
B1["BrowserBackend统一接口"]
|
|
B2["PipeBrowserBackend实现"]
|
|
B3["WsBrowserBackend实现"]
|
|
B4["BrowserCallbackBackend实现"]
|
|
SV1["WebSocket Server监听"]
|
|
SV2["Session Manager单客户端单任务"]
|
|
SV3["Callback HTTP Server监听"]
|
|
CF1["SgClawSettings加载"]
|
|
CF2["Provider Config"]
|
|
CF3["Backend Selection选择"]
|
|
E1 --> P1 --> P2 --> P3 --> P4 --> P5 --> M1
|
|
M1 --> M2
|
|
M1 --> M3 --> A1 --> A2 --> A3
|
|
A3 --> C1 --> C2 --> C5 --> B1
|
|
A3 --> C4 --> B1
|
|
CF1 --> C1
|
|
B1 --> B2
|
|
B1 --> B3
|
|
B1 --> B4
|
|
E2 --> SV1 --> SV2 --> B4
|
|
SV1 --> SV3
|
|
CF1 --> CF2
|
|
CF1 --> CF3 --> A1
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section">
|
|
<div class="section-header">
|
|
<div class="section-number">5</div>
|
|
<div class="section-title">安全模型 - 三层防线</div>
|
|
</div>
|
|
<div class="section-body">
|
|
<div class="mermaid">
|
|
graph TB
|
|
L1A["浏览器发送Init携带hmac_seed"]
|
|
L1B["sgClaw回InitAck分配agent_id"]
|
|
L1C["派生Session Key SHA256"]
|
|
L1D["未完成握手拒绝运行"]
|
|
L1A --> L1B --> L1C --> L1D
|
|
L2A["加载rules.json解析规则"]
|
|
L2B["Domain白名单校验去掉协议路径端口"]
|
|
L2C["Action黑白名单双重过滤"]
|
|
L2D["本地仪表盘特殊处理"]
|
|
L2A --> L2B
|
|
L2A --> L2C
|
|
L2A --> L2D
|
|
L3A["序列号关联校验"]
|
|
L3B["HMAC-SHA256签名验证"]
|
|
L3C["域名与页面上下文匹配"]
|
|
L3D["非法参数拒绝执行"]
|
|
L3A --> L3B --> L3C --> L3D
|
|
L1D ==> L2A
|
|
L2B ==> L3A
|
|
L2C ==> L3A
|
|
L2D ==> L3A
|
|
classDef l1Class fill:#1a3a5c,stroke:#4a9eff,color:#e6edf3
|
|
classDef l2Class fill:#4a2c17,stroke:#e65100,color:#e6edf3
|
|
classDef l3Class fill:#2d1f3d,stroke:#9c27b0,color:#e6edf3
|
|
class L1A,L1B,L1C,L1D l1Class
|
|
class L2A,L2B,L2C,L2D l2Class
|
|
class L3A,L3B,L3C,L3D l3Class
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section">
|
|
<div class="section-header">
|
|
<div class="section-number">6</div>
|
|
<div class="section-title">Skill体系与执行路径</div>
|
|
</div>
|
|
<div class="section-body">
|
|
<div class="mermaid">
|
|
graph TB
|
|
SD1["SKILL.toml元数据"]
|
|
SD2["tools数组kind定义"]
|
|
SD3["prompts数组触发条件"]
|
|
SD4["scripts目录JS脚本"]
|
|
SL1["ZeroClaw Skill Loader扫描"]
|
|
SL2["BrowserScriptSkillTool创建执行器"]
|
|
SL3["命名规范skill.tool"]
|
|
EP1["路径A LLM驱动"]
|
|
EP2["路径B Deterministic Submit"]
|
|
EP3["路径C Direct Skill Runtime"]
|
|
BE1["Eval包装脚本注入args"]
|
|
BE2["Action Eval执行"]
|
|
BE3["返回ToolResult结构化JSON"]
|
|
SD1 --> SD2 --> SD4
|
|
SD2 --> SD3
|
|
SD1 --> SL1 --> SL2 --> SL3
|
|
SL3 --> EP1
|
|
SL3 --> EP2
|
|
SL3 --> EP3
|
|
EP1 --> BE1 --> BE2 --> BE3
|
|
EP2 --> BE1
|
|
EP3 --> BE1
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section">
|
|
<div class="section-header">
|
|
<div class="section-number">7</div>
|
|
<div class="section-title">Helper Page机制 - Service Mode核心桥接</div>
|
|
</div>
|
|
<div class="section-body">
|
|
<div class="mermaid">
|
|
graph TB
|
|
WS["WebSocket Server监听42321"]
|
|
HTTP["Callback HTTP Server监听17888"]
|
|
CB["BrowserCallbackBackend交互"]
|
|
Helper["Helper Page Tab辅助页"]
|
|
Target1["业务页面1线损系统"]
|
|
Target2["业务页面2平台页面"]
|
|
HP1["WebSocket连接特权API"]
|
|
HP2["轮询Command长轮询"]
|
|
HP3["推送Events POST回调"]
|
|
HP4["回调函数注册"]
|
|
WS --> CB --> HTTP --> HP2
|
|
HP1 --> Target1
|
|
HP1 --> Target2
|
|
HP2 --> Target1
|
|
HP2 --> Target2
|
|
Target1 --> HP4 --> HP3 --> HTTP
|
|
HTTP --> CB --> WS
|
|
classDef svcClass fill:#4a2c17,stroke:#e65100,color:#e6edf3
|
|
classDef tabClass fill:#1a3a5c,stroke:#4a9eff,color:#e6edf3
|
|
classDef hpClass fill:#2d1f3d,stroke:#9c27b0,color:#e6edf3
|
|
class WS,HTTP,CB svcClass
|
|
class Helper,Target1,Target2 tabClass
|
|
class HP1,HP2,HP3,HP4 hpClass
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section">
|
|
<div class="section-header">
|
|
<div class="section-number">8</div>
|
|
<div class="section-title">线损确定性提交流程 - 用户输入到Excel导出</div>
|
|
</div>
|
|
<div class="section-body">
|
|
<div class="mermaid">
|
|
sequenceDiagram
|
|
participant User as 用户
|
|
participant Host as 浏览器宿主
|
|
participant Agent as Agent/TaskRunner
|
|
participant DS as DeterministicSubmit
|
|
participant Skill as collect_lineloss
|
|
participant Backend as BrowserBackend
|
|
participant Browser as 线损浏览器页面
|
|
participant Rust as Rust xlsx导出
|
|
User->>Host: 输入指令:帮我查本月线损率
|
|
Host->>Agent: SubmitTask
|
|
Agent->>DS: decide_deterministic_submit
|
|
Note over DS: 指令以句号结尾且包含线损关键词
|
|
DS-->>Agent: Execute执行计划
|
|
Agent->>Skill: execute_browser_script
|
|
Skill->>Backend: Action Eval
|
|
Backend->>Browser: sgBrowserExcuteJsCodeByDomain
|
|
Browser->>Browser: validatePageContext
|
|
Browser->>Browser: buildRequest
|
|
Browser->>Browser: ajax查询API
|
|
Browser-->>Backend: 返回JSON
|
|
Backend-->>Skill: ToolResult
|
|
Skill-->>Agent: artifact
|
|
Agent->>Rust: export_lineloss_xlsx
|
|
Rust->>Rust: 生成xlsx文件
|
|
Rust-->>Agent: 导出完成
|
|
Agent-->>Host: TaskComplete
|
|
Host-->>User: 展示结果打开Excel
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section">
|
|
<div class="section-header">
|
|
<div class="section-number">9</div>
|
|
<div class="section-title">平台浏览器与sgClaw交互边界</div>
|
|
</div>
|
|
<div class="section-body">
|
|
<div class="mermaid">
|
|
graph TB
|
|
PlatformBrowser["平台浏览器Chromium"]
|
|
sgClawProcess["sgClaw进程Rust"]
|
|
PP1["场景页Vue实例window.mac"]
|
|
PP2["mutableSystemList子系统账号池"]
|
|
PP3["getLogint登录编排方法"]
|
|
TP1["线损系统20.76.57.61"]
|
|
TP2["其他子系统"]
|
|
BC1["sgBrowserExcuteJsCodeByDomain按域名执行JS"]
|
|
BC2["sgHideBrowerserOpenPage打开隐藏页面"]
|
|
BC3["sgBrowserCallAfterLoaded加载后执行JS"]
|
|
BC4["callBackJsToCpp JS到C++回调"]
|
|
T1["Transport层STDIO传输"]
|
|
T2["MAC Policy加HMAC安全校验"]
|
|
T3["Agent/TaskRunner任务分发器"]
|
|
T4["Compat层ZeroClaw兼容"]
|
|
T5["Browser Backend浏览器后端"]
|
|
PP1 --> PP2
|
|
PP1 --> PP3
|
|
PP3 -.-> TP1
|
|
T1 --> PlatformBrowser
|
|
PlatformBrowser --> T1
|
|
T3 --> T4 --> T5
|
|
T5 --> BC1
|
|
T5 --> BC2
|
|
T5 --> BC3
|
|
BC4 -.-> T5
|
|
PlatformBrowser -.-> sgClawProcess
|
|
classDef browserSide fill:#1a3a5c,stroke:#4a9eff,color:#e6edf3
|
|
classDef sgclawSide fill:#4a2c17,stroke:#e65100,color:#e6edf3
|
|
class PlatformBrowser,PP1,PP2,PP3,TP1,TP2,BC1,BC2,BC3,BC4 browserSide
|
|
class sgClawProcess,T1,T2,T3,T4,T5 sgclawSide
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="section">
|
|
<div class="section-header">
|
|
<div class="section-number">10</div>
|
|
<div class="section-title">模块文件映射表</div>
|
|
</div>
|
|
<div class="section-body">
|
|
<table class="file-table">
|
|
<thead><tr><th>模块</th><th>主要源文件</th><th>职责说明</th></tr></thead>
|
|
<tbody>
|
|
<tr><td>pipe传输层</td><td>src/pipe/mod.rs transport.rs handshake.rs browser_tool.rs</td><td>STDIO读写 握手流程 消息编码解码 HMAC签名</td></tr>
|
|
<tr><td>security安全层</td><td>src/security/mod.rs mac_policy.rs hmac.rs</td><td>MAC Policy加载 域名白名单 动作黑白名单 HMAC签名</td></tr>
|
|
<tr><td>agent消息路由</td><td>src/agent/mod.rs task_runner.rs</td><td>消息分发 任务解析 Deterministic Submit检测</td></tr>
|
|
<tr><td>browser后端抽象</td><td>src/browser/mod.rs callback_backend.rs callback_host.rs ws_protocol.rs</td><td>BrowserBackend接口 Pipe/WS/Callback实现</td></tr>
|
|
<tr><td>compat兼容层</td><td>src/compat/mod.rs runtime.rs deterministic_submit.rs browser_script_skill_tool.rs</td><td>ZeroClaw运行时构建 线损快速通道 Skill执行</td></tr>
|
|
<tr><td>service服务模式</td><td>src/service/mod.rs session.rs</td><td>WS服务器 单客户端单任务模型</td></tr>
|
|
<tr><td>config配置</td><td>src/config/mod.rs settings.rs</td><td>Settings加载 Provider配置 Backend选择</td></tr>
|
|
<tr><td>runtime引擎</td><td>src/runtime/mod.rs engine.rs tool_policy.rs</td><td>Agent实例构建 ToolPolicy权限控制</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
</div>
|
|
<div class="footer">sgClaw 系统架构全景图 - 2026-04-15 - 基于 Mermaid.js 10.9.5</div>
|
|
<script>
|
|
mermaid.initialize({ startOnLoad:true, theme:'dark', securityLevel:'loose', logLevel:'warn' });
|
|
</script>
|
|
</body>
|
|
</html> |