sgClaw 系统架构全景图

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

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

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: 推送结果

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

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

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

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

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

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