163 lines
5.9 KiB
Markdown
163 lines
5.9 KiB
Markdown
# L1 — 系统架构与安全模型层
|
||
|
||
**文档版本**: 2.0
|
||
**适用项目**: sgClaw（ZeroClaw 重构版）
|
||
**编制日期**: 2026-03-26
|
||
|
||
---
|
||
|
||
## 1. 架构总览
|
||
|
||
重构后的 sgClaw 架构要点很简单：浏览器宿主负责页面执行，Rust 进程负责任务解释与协议编排，ZeroClaw 作为兼容运行时被接入到 Rust 侧，而不是直接替代整个系统。
|
||
|
||
```
|
||
┌──────────────────────────────┐
|
||
│ Browser Host / Chromium Side │
|
||
│ - 启动 sgClaw 子进程 │
|
||
│ - 发送 init / submit_task │
|
||
│ - 执行 command 并回 response │
|
||
└──────────────┬───────────────┘
|
||
│ STDIO + JSON Line
|
||
┌──────────────▼───────────────┐
|
||
│ sgClaw Rust Runtime │
|
||
│ - 握手与消息循环 │
|
||
│ - MAC Policy │
|
||
│ - BrowserPipeTool │
|
||
│ - Planner fallback │
|
||
│ - ZeroClaw compat runtime │
|
||
└──────────────┬───────────────┘
|
||
│ Provider API / Local Config
|
||
┌──────────────▼───────────────┐
|
||
│ Model Provider │
|
||
│ - DeepSeek/OpenAI-compatible │
|
||
│ - 仅在配置存在时启用 │
|
||
└──────────────────────────────┘
|
||
```
|
||
|
||
架构上最重要的变化是：当前系统不是“完整 ZeroClaw 产品”，而是“保留现有浏览器协议的前提下，把 ZeroClaw 作为兼容执行内核引入”。
|
||
|
||
---
|
||
|
||
## 2. 运行时分层
|
||
|
||
### 2.1 浏览器宿主层
|
||
|
||
宿主负责三类职责：
|
||
|
||
- 启动和托管 sgClaw Rust 子进程。
|
||
- 按协议发送 `init`、`submit_task`、`response`。
|
||
- 执行 Rust 发来的浏览器命令并回包。
|
||
|
||
sgClaw 仓库本身不包含 Chromium/C++ 实现代码，因此 L1 只定义宿主责任边界，不再把外部仓库中的假定文件结构写成“当前仓库现状”。
|
||
|
||
### 2.2 Rust 控制层
|
||
|
||
Rust 侧是当前仓库的事实主体，职责包括：
|
||
|
||
- 在 [`src/lib.rs`](/home/zyl/projects/sgClaw/claw/src/lib.rs) 中建立 `StdioTransport`。
|
||
- 完成握手、加载 `rules.json`、创建 `BrowserPipeTool`。
|
||
- 在消息循环中接收浏览器消息并分发到执行层。
|
||
- 把执行日志和任务结果回传给宿主。
|
||
|
||
### 2.3 执行层
|
||
|
||
执行层当前有两条路径：
|
||
|
||
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。
|
||
|
||
这两条路径共存，是当前重构期的核心现实。文档必须保留这一点，否则会误导实现和联调。
|
||
|
||
---
|
||
|
||
## 3. ZeroClaw 重构的架构意义
|
||
|
||
ZeroClaw 在本项目中的角色不是“大而全框架接管一切”，而是解决三个具体问题：
|
||
|
||
- 统一模型 Provider 抽象。
|
||
- 为后续记忆、工具调度、可观测性留出标准扩展位。
|
||
- 在不改浏览器协议的前提下，替换任务执行内核。
|
||
|
||
当前兼容层的限制也必须明确：
|
||
|
||
- 只注册一个工具：`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 侧可以独立迭代 planner 和 ZeroClaw 路径。
|
||
- 产品文档、测试和协议标准可以围绕同一条 contract 收敛。
|
||
|
||
### 5.3 先做最小工具面，再扩动作
|
||
|
||
原因：
|
||
|
||
- 当前最稳定的是 `click/type/navigate/getText`。
|
||
- 动作越多，宿主和模型之间的契约越难稳定。
|
||
- 在规则文件仍只开放 4 个动作的前提下，文档不应提前放大能力范围。
|
||
|
||
---
|
||
|
||
## 6. 架构结论
|
||
|
||
L1 层面可以把 sgClaw 定义为：一个通过固定浏览器协议接入宿主、以 Rust 为控制层、以 ZeroClaw 为兼容执行核、以 MAC Policy 为最小安全边界的浏览器智能体运行时。
|
||
|
||
这一定义与当前仓库实现保持一致，也为后续继续扩展动作、工具和记忆系统保留了清晰边界。
|