# L1 — 系统架构与安全模型层

**文档版本**: 2.1<br>
**适用项目**: sgClaw（ZeroClaw 重构版）<br>
**编制日期**: 2026-03-29

---

## 1. 架构总览

重构后的 sgClaw 架构要点应当这样理解：`host`（SuperRPA）是受保护的宿主安全边界，`sgClaw` 是运行时能力编排层，`zeroclaw` 是 planner / model / skill 的能力本体，`frontend bundle` 只是展示面。当前代码尚未完全落到这个目标结构，但主线架构口径必须先统一。

```
┌──────────────────────────────┐
│ Browser Host / Chromium Side │
│ - 读取 launch config          │
│ - 启动 sgClaw 子进程          │
│ - 发送 init / submit_task     │
│ - 复检 HMAC / domain / params │
│ - 执行 browser command 并回包 │
│ - 选择 frontend bundle        │
└──────────────┬───────────────┘
               │ 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 做安全化封装的运行时分发”。同时 `host` 不再持有高频变化的业务策略，`launch config`、`runtime config` 和 `frontend bundle` 应成为运行时可替换对象。

---

## 2. 运行时分层

### 2.1 host（浏览器宿主）层

`host` 负责受保护边界内的四类职责：

- 读取并校验 `launch config`，决定进程如何被拉起。
- 启动和托管 sgClaw Rust 子进程。
- 按协议发送 `init`、`submit_task`、`response`。
- 执行 Rust 发来的浏览器命令并回包。
- 选择外部 `frontend bundle` 或内置资源作为展示面。

`host` 不拥有 planner、模型路由、skills 编排或业务策略定义。sgClaw 仓库本身不包含 Chromium/C++ 实现代码，因此 L1 只定义宿主责任边界，不再把外部仓库中的假定文件结构写成“当前仓库现状”。

### 2.2 sgClaw 安全/控制层

Rust 侧是当前仓库的事实主体，职责包括：

- 在 [`src/lib.rs`](/home/zyl/projects/sgClaw/claw/src/lib.rs) 中建立 `StdioTransport`。
- 完成握手、加载 `rules.json`、创建 `BrowserPipeTool`。
- 在消息循环中接收浏览器消息并分发到执行层。
- 把执行日志和任务结果回传给宿主。
- 读取 `runtime config`，决定 planner、provider、skills prompt mode、backend 选择等运行时行为。
- 决定哪些 zeroclaw 能力能够暴露给当前运行环境。

### 2.3 zeroclaw 核心层

主线目标中，zeroclaw 应承担：

- planner / executor 决策
- prompt/system sections 组装
- skills / memory / routing
- tool loop 与 provider 协调
- 通用 agent 能力而非仅浏览器能力

也就是说，`planner-first` 是 sgClaw / zeroclaw 运行时行为，不是 `frontend bundle` 或 `host` 页面逻辑。

### 2.4 展示层（frontend bundle）

前端展示层只拥有显示权，不拥有执行权。其职责应被限制为：

- 展示会话状态、日志、消息、验收结果。
- 将用户输入转成宿主可接受的事件。
- 呈现 `planner-first` 的可视化状态，例如“先展示计划，再执行”。

前端不应决定：

- 是否调用 planner
- 是否切换 provider / model
- 是否绕过 sgClaw / zeroclaw 执行

这些决策必须留在 sgClaw / zeroclaw 运行时。

### 2.5 当前实现的过渡态

当前执行层仍有两条路径：

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。

### 2.6 运行时配置边界

本轮架构冻结后，必须使用以下统一术语：

- `launch config`
  由 `host` 读取，描述 `binary`、`args`、`env`、`working_dir`、`runtime_config_path`、`frontend_bundle_dir` 等启动时边界。
- `runtime config`
  由 sgClaw 读取，描述 provider、model、planner mode、backend 选择、skills 策略等运行时行为。
- `frontend bundle`
  由 `host` 装载的展示资源目录，允许外部 bundle 优先、内置资源兜底。

这三类对象都应支持运行期调整；只有安全边界和能力暴露由 `host` 固化。

---

## 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 个动作的前提下，文档不应提前放大能力范围。

### 5.4 启动策略配置化，而不是编译期写死

原因：

- 更换 sgClaw binary 不应要求重编 Chromium。
- 切换 `runtime config` 不应要求重编 Chromium。
- 更换 `frontend bundle` 不应要求重编 Chromium。
- 安全边界仍由 `host` 控制，配置化不等于放弃校验。

### 5.5 planner-first 只属于运行时，不属于展示层

原因：

- “先展示计划，再执行”是执行引擎行为，不是前端动画效果。
- 前端只能显示 planner 状态，不能私自触发或跳过 planner。
- 验收必须同时覆盖视觉呈现和功能执行两个维度。

---

## 6. 架构结论

L1 层面可以把 sgClaw 定义为：一个通过固定浏览器协议接入 `host`、以 Rust 为安全与控制层、以 zeroclaw 为能力核心、以 `runtime config` 驱动执行行为、以 `frontend bundle` 作为仅展示界面、以 MAC Policy 与宿主复检为受保护执行边界的安全加固运行时分发。

这一定义既承认当前仓库仍存在 browser-first compat 的过渡实现，也为后续把 runtime 真正收口到 zeroclaw-first、planner-first 主线保留了清晰边界。