# L1 — 系统架构与安全模型层 **文档版本**: 2.0 **适用项目**: sgClaw（ZeroClaw 重构版） **编制日期**: 2026-03-26 --- ## 1. 架构总览 重构后的 sgClaw 架构要点应当这样理解：zeroclaw 是能力本体，sgClaw 是安全封装层，浏览器宿主是一个受保护的特权执行面。当前代码尚未完全落到这个目标结构，但主线架构口径必须先统一。 ``` ┌──────────────────────────────┐ │ Browser Host / Chromium Side │ │ - 启动 sgClaw 子进程 │ │ - 发送 init / submit_task │ │ - 复检 HMAC / domain / params │ │ - 执行 browser command 并回包 │ └──────────────┬───────────────┘ │ STDIO + JSON Line ┌──────────────▼───────────────┐ │ sgClaw Security Envelope │ │ - 握手与消息循环 │ │ - MAC Policy │ │ - BrowserPipeTool │ │ - Runtime / Tool Policy │ │ - Config Adaptation │ └──────────────┬───────────────┘ │ zeroclaw APIs / Local Config ┌──────────────▼───────────────┐ │ ZeroClaw Core Runtime │ │ - Prompt Builder │ │ - Skills / Memory │ │ - Tool Loop / Routing │ │ - Provider Dispatch │ └──────────────┬───────────────┘ │ Provider API / Optional Tools ┌──────────────▼───────────────┐ │ Model Provider │ │ - DeepSeek/OpenAI-compatible │ │ - 仅在配置存在时启用 │ └──────────────────────────────┘ ``` 架构上最重要的变化是：sgClaw 不应被定义为“浏览器专用 agent”，而应被定义为“保留现有浏览器协议前提下，对 zeroclaw 做安全化封装的运行时分发”。 --- ## 2. 运行时分层 ### 2.1 浏览器宿主层 宿主负责三类职责： - 启动和托管 sgClaw Rust 子进程。 - 按协议发送 `init`、`submit_task`、`response`。 - 执行 Rust 发来的浏览器命令并回包。 sgClaw 仓库本身不包含 Chromium/C++ 实现代码，因此 L1 只定义宿主责任边界，不再把外部仓库中的假定文件结构写成“当前仓库现状”。 ### 2.2 sgClaw 安全/控制层 Rust 侧是当前仓库的事实主体，职责包括： - 在 [`src/lib.rs`](/home/zyl/projects/sgClaw/claw/src/lib.rs) 中建立 `StdioTransport`。 - 完成握手、加载 `rules.json`、创建 `BrowserPipeTool`。 - 在消息循环中接收浏览器消息并分发到执行层。 - 把执行日志和任务结果回传给宿主。 - 决定哪些 zeroclaw 能力能够暴露给当前运行环境。 ### 2.3 zeroclaw 核心层 主线目标中，zeroclaw 应承担： - prompt/system sections 组装 - skills / memory / routing - tool loop 与 provider 协调 - 通用 agent 能力而非仅浏览器能力 ### 2.4 当前实现的过渡态 当前执行层仍有两条路径： 1. `planner fallback` 说明：当未配置 `DEEPSEEK_API_KEY` 等环境变量时，使用仓库内置的轻量 planner 执行。 2. `ZeroClaw compat runtime` 说明：当提供模型配置后，通过 [`src/compat/runtime.rs`](/home/zyl/projects/sgClaw/claw/src/compat/runtime.rs) 构造 provider、memory 和 `browser_action` 工具，把任务交给 vendored ZeroClaw Agent。 这两条路径是当前代码现实，但都不应被写成长期产品定义。长期目标是“zeroclaw-first runtime + sgClaw security layer”，而不是 browser-only compat。 --- ## 3. ZeroClaw 重构的架构意义 ZeroClaw 在本项目中的角色不是“大而全框架接管一切”，也不是“被 sgClaw 套壳后只剩一个 browser_action 工具”，而是系统能力本体。sgClaw 应该在它上面解决三个具体问题： - 统一模型 Provider 抽象、skills、memory 和 tool loop。 - 在不改浏览器协议的前提下，把高风险执行约束到受保护的工具面。 - 让浏览器成为特权执行面，而不是反过来让浏览器定义整个 runtime。 当前兼容层的限制也必须明确： - 只注册一个工具：`browser_action`。 - 只开放 4 个动作：`click/type/navigate/getText`。 - 不以 ZeroClaw 的全量工具生态作为当前对外能力宣称。 这些限制是当前实现状态，不是目标架构原则。 --- ## 4. 安全模型 ### 4.1 安全目标 系统安全目标不是“模型永远正确”，而是“即使模型给出错误指令，也只能在受限边界内执行”。 ### 4.2 三层安全约束 #### 第一层：握手与会话完整性 - 浏览器必须先发 `init`。 - sgClaw 必须回 `init_ack`。 - 会话级 `hmac_seed` 用于后续命令签名。 - 未完成握手，不进入运行态。 #### 第二层：Rust 侧 MAC Policy [`src/security/mac_policy.rs`](/home/zyl/projects/sgClaw/claw/src/security/mac_policy.rs) 从 [`resources/rules.json`](/home/zyl/projects/sgClaw/claw/resources/rules.json) 加载规则，校验： - 目标域名是否在 `domains.allowed` 中。 - 动作是否在 `pipe_actions.allowed` 中。 - 被明确封禁的动作是否命中 `pipe_actions.blocked`。 这意味着即便协议枚举中定义了更多动作，也不代表当前会话可以执行它们。 #### 第三层：宿主侧命令执行约束 浏览器宿主仍应在接收命令后做本地校验，包括： - 序列号关联。 - HMAC 校验。 - 域名与页面上下文匹配。 - 非法参数拒绝执行。 [`docs/浏览器对接标准.md`](/home/zyl/projects/sgClaw/claw/docs/浏览器对接标准.md) 是这一层的联调基线。 --- ## 5. 关键架构决策 ### 5.1 使用 STDIO 作为唯一主链路 原因： - 进程私有，外部进程不能直接接入。 - 与浏览器子进程托管方式天然匹配。 - 协议简单，适合 JSON Line 一问一答模型。 ### 5.2 保留协议前提下重构执行核 原因： - 浏览器宿主联调成本最低。 - Rust 侧可以独立演进 zeroclaw runtime 与安全策略，而不破坏宿主联调。 - 产品文档、测试和协议标准可以围绕同一条 contract 收敛。 ### 5.3 先做最小特权工具面，再扩动作 原因： - 当前最稳定的是 `click/type/navigate/getText`。 - 动作越多，宿主和 runtime 之间的契约越难稳定。 - 在规则文件仍只开放 4 个动作的前提下，文档不应提前放大能力范围。 --- ## 6. 架构结论 L1 层面可以把 sgClaw 定义为：一个通过固定浏览器协议接入宿主、以 Rust 为安全与控制层、以 zeroclaw 为能力核心、以 MAC Policy 与宿主复检为受保护执行边界的安全加固运行时分发。 这一定义既承认当前仓库仍存在 browser-first compat 的过渡实现，也为后续把 runtime 真正收口到 zeroclaw-first 主线保留了清晰边界。