360 lines
10 KiB
Markdown
360 lines
10 KiB
Markdown
# L2 — 核心模块与接口契约层
|
||
|
||
**文档版本**: 2.1<br>
|
||
**适用项目**: sgClaw（ZeroClaw 重构版）<br>
|
||
**编制日期**: 2026-03-29
|
||
|
||
**读者**: 架构工程师、实现工程师、联调工程师
|
||
|
||
---
|
||
|
||
## 1. 模块地图
|
||
|
||
当前仓库中的有效模块结构如下：
|
||
|
||
```
|
||
src/
|
||
├── main.rs
|
||
├── lib.rs
|
||
├── agent/
|
||
├── compat/
|
||
├── config/
|
||
├── llm/
|
||
├── pipe/
|
||
└── security/
|
||
```
|
||
|
||
模块边界按职责划分为五层：
|
||
|
||
| 层级 | 模块 | 责任 |
|
||
|---|---|---|
|
||
| 传输层 | `pipe` | 定义消息、握手、序列号、收发与命令等待 |
|
||
| 安全层 | `security`、`resources/rules.json` | 域名、动作与 pipe 命令边界控制 |
|
||
| 运行时入口层 | `lib.rs`、`agent` | 接收任务、选择执行路径、回传日志与结果 |
|
||
| 适配层 | `compat`、`config` | 把 sgClaw 宿主环境映射到 zeroclaw 运行时；当前仍带有过渡性限制 |
|
||
| 核心能力层 | `third_party/zeroclaw` | prompt、skills、memory、tool loop、provider 抽象 |
|
||
|
||
本轮冻结后还需要一组跨仓统一术语：
|
||
|
||
- `host`
|
||
指 SuperRPA 浏览器宿主，只拥有安全边界、进程托管和展示装配权。
|
||
- `launch config`
|
||
指由 `host` 读取的启动描述文件。
|
||
- `runtime config`
|
||
指由 sgClaw 读取的运行时策略文件。
|
||
- `frontend bundle`
|
||
指由 `host` 装载的前端展示资源。
|
||
- `planner-first`
|
||
指 sgClaw / zeroclaw 先产生计划、前端先展示计划、随后再执行的运行时行为。
|
||
|
||
---
|
||
|
||
## 2. 核心模块职责
|
||
|
||
### 2.1 `src/lib.rs`
|
||
|
||
[`src/lib.rs`](/home/zyl/projects/sgClaw/claw/src/lib.rs) 是运行时总装入口，负责：
|
||
|
||
- 创建 `StdioTransport`。
|
||
- 调用 `perform_handshake`。
|
||
- 加载默认规则文件 `resources/rules.json`。
|
||
- 构造 `BrowserPipeTool`。
|
||
- 进入长循环，接收浏览器消息并交给 `agent::handle_browser_message`。
|
||
|
||
这里没有业务 UI、任务队列或调度中心逻辑，只有最小可运行闭环。
|
||
|
||
### 2.2 `src/agent/mod.rs`
|
||
|
||
[`src/agent/mod.rs`](/home/zyl/projects/sgClaw/claw/src/agent/mod.rs) 当前决定执行路径：
|
||
|
||
- 收到 `BrowserMessage::SubmitTask` 时优先尝试读取 `SgClawSettings`。
|
||
- 环境配置存在，则走 `compat::runtime::execute_task_with_sgclaw_settings`。
|
||
- 环境配置不存在，则直接返回“未配置大语言模型”，而不是再把生产 submit 流量导回旧 planner。
|
||
|
||
这就是当前系统的“路由器”。但文档上应把它理解为过渡性 runtime selector，而不是最终产品架构中心。长期看，`planner-first`、provider 选择与 backend 选择都应由 `runtime config` 显式驱动。
|
||
|
||
### 2.3 `src/agent/runtime.rs`
|
||
|
||
该文件现在应被视为 `legacy/dev-only` 模块，只保留仓库内的轻量 LLM/tool 调用逻辑用于局部验证，核心特点：
|
||
|
||
- 工具名固定为 `browser_action`。
|
||
- schema 只允许 `click/type/navigate/getText`。
|
||
- 每次工具调用前后发送 `log_entry`。
|
||
- 结果失败时直接返回 `PipeError::Protocol`。
|
||
- 不参与当前生产浏览器 submit 路由。
|
||
|
||
### 2.4 `src/compat/runtime.rs`
|
||
|
||
[`src/compat/runtime.rs`](/home/zyl/projects/sgClaw/claw/src/compat/runtime.rs) 是当前 ZeroClaw 接入的关键模块：
|
||
|
||
- 负责构造 ZeroClaw config。
|
||
- 负责创建 provider。
|
||
- 负责把 `BrowserPipeTool` 包装成 ZeroClaw Tool。
|
||
- 负责消费 ZeroClaw `TurnEvent` 并桥接为 `log_entry`。
|
||
|
||
重要事实：
|
||
|
||
- 当前 compat 层只向 ZeroClaw 注册一个工具。
|
||
- `allowed_tools` 被收敛到 `browser_action`。
|
||
- 这意味着当前代码还没有把 sgClaw 做成 zeroclaw-first runtime。
|
||
- 这是一种实现限制，不应被文档提升为产品原则。
|
||
|
||
### 2.7 host / launch config / runtime config 契约
|
||
|
||
跨仓接口收口后，`host` 与 sgClaw 的最小契约应为：
|
||
|
||
| 对象 | 读取方 | 责任 | 失败时兜底 |
|
||
|---|---|---|---|
|
||
| `launch config` | `host` | 解析 `binary`、`args`、`env`、`working_dir`、`runtime_config_path`、`frontend_bundle_dir` | 回退到浏览器内置默认启动策略 |
|
||
| `runtime config` | sgClaw | 解析 provider、model、planner mode、backend、skills policy | 回退到 sgClaw 默认运行时配置 |
|
||
| `frontend bundle` | `host` | 提供浮窗/面板展示资源 | 回退到浏览器内置 WebUI 资源 |
|
||
|
||
这里的关键点是：`host` 只负责校验和装配，不负责决定 planner、model routing 或 business behavior。
|
||
|
||
### 2.8 launch config 文件路径与回退规则
|
||
|
||
设计冻结口径如下：
|
||
|
||
- profile-local `launch config` 路径：`<profile>/superrpa/sgclaw_launch_config.json`
|
||
- profile-local `runtime config` 路径：`<profile>/superrpa/sgclaw_config.json`
|
||
- profile-local hooks / rules 仍沿用：
|
||
- `<profile>/superrpa/hooks.json`
|
||
- `<profile>/superrpa/rules.json`
|
||
|
||
`launch config` 的回退规则必须保持稳定：
|
||
|
||
1. 优先读取 `<profile>/superrpa/sgclaw_launch_config.json`
|
||
2. 缺失或解析失败时，回退到当前浏览器内置默认启动参数
|
||
3. `runtime_config_path` 缺失时，回退到 `<profile>/superrpa/sgclaw_config.json`
|
||
4. `frontend_bundle_dir` 缺失、无效或校验失败时，回退到 bundled frontend resources
|
||
|
||
### 2.9 frontend bundle 与 planner-first 契约
|
||
|
||
`frontend bundle` 只能消费这些由 `host` 转发的运行时状态：
|
||
|
||
- 当前状态与日志
|
||
- planner 输出
|
||
- 会话消息
|
||
- 最终执行结果
|
||
|
||
`frontend bundle` 不能直接拥有：
|
||
|
||
- provider 切换决策权
|
||
- planner 开关控制权
|
||
- executor 旁路能力
|
||
|
||
因此 `planner-first` 的契约应是：
|
||
|
||
1. sgClaw / zeroclaw 产生计划
|
||
2. `frontend bundle` 先展示计划
|
||
3. 经运行时确认后再执行
|
||
|
||
这是一条 runtime contract，不是一条前端内部约定。
|
||
|
||
### 2.5 `src/pipe/browser_tool.rs`
|
||
|
||
该模块承担真实浏览器命令发送职责，也是当前系统中最重要的特权工具面桥接层：
|
||
|
||
- 为每个命令分配 `seq`。
|
||
- 计算 HMAC。
|
||
- 发送 `AgentMessage::Command`。
|
||
- 阻塞等待对应 `BrowserMessage::Response`。
|
||
- 在超时、响应错配、校验失败时返回错误。
|
||
|
||
它是 Rust 侧最重要的协议执行点。架构上应把它理解为“privileged browser surface adapter”，而不是“整个 runtime 本体”。
|
||
|
||
### 2.6 `src/security/mac_policy.rs`
|
||
|
||
安全策略只认规则文件与 pipe contract，不认模型意图。
|
||
规则来源为 [`resources/rules.json`](/home/zyl/projects/sgClaw/claw/resources/rules.json)，当前默认约束是：
|
||
|
||
- 允许域名：`oa.example.com`、`erp.example.com`、`hr.example.com` 及 demo 域名。
|
||
- 允许动作：`click`、`type`、`navigate`、`getText`。
|
||
- 显式阻断：`eval`、`executeJsInPage`。
|
||
|
||
---
|
||
|
||
## 3. 协议契约
|
||
|
||
### 3.1 消息类型
|
||
|
||
[`src/pipe/protocol.rs`](/home/zyl/projects/sgClaw/claw/src/pipe/protocol.rs) 定义了三类浏览器到 Rust 的消息：
|
||
|
||
```rust
|
||
BrowserMessage::Init
|
||
BrowserMessage::SubmitTask
|
||
BrowserMessage::Response
|
||
```
|
||
|
||
以及四类 Rust 到浏览器的消息：
|
||
|
||
```rust
|
||
AgentMessage::InitAck
|
||
AgentMessage::LogEntry
|
||
AgentMessage::TaskComplete
|
||
AgentMessage::Command
|
||
```
|
||
|
||
### 3.2 `Init` / `InitAck`
|
||
|
||
握手字段：
|
||
|
||
- `version`
|
||
- `hmac_seed`
|
||
- `capabilities`
|
||
|
||
Rust 返回：
|
||
|
||
- `version`
|
||
- `agent_id`
|
||
- `supported_actions`
|
||
|
||
注意：`supported_actions` 是协议枚举能力，不等于当前策略白名单。
|
||
|
||
### 3.3 `Command`
|
||
|
||
命令消息结构：
|
||
|
||
```json
|
||
{
|
||
"seq": 1,
|
||
"type": "command",
|
||
"action": "click",
|
||
"params": { "selector": "#submit" },
|
||
"security": {
|
||
"expected_domain": "erp.example.com",
|
||
"hmac": "<hex>"
|
||
}
|
||
}
|
||
```
|
||
|
||
契约重点：
|
||
|
||
- `seq` 必须单调递增。
|
||
- `action` 必须是协议枚举之一。
|
||
- `expected_domain` 必须参与安全校验。
|
||
- `hmac` 必须由当前会话密钥计算。
|
||
|
||
### 3.4 `Response`
|
||
|
||
浏览器回包结构：
|
||
|
||
```json
|
||
{
|
||
"seq": 1,
|
||
"type": "response",
|
||
"success": true,
|
||
"data": {},
|
||
"aom_snapshot": [],
|
||
"timing": {
|
||
"queue_ms": 0,
|
||
"exec_ms": 12
|
||
}
|
||
}
|
||
```
|
||
|
||
Rust 侧依赖此消息完成工具调用闭环。
|
||
`seq` 不匹配、超时或缺失都应视为协议错误。
|
||
|
||
### 3.5 与浏览器对接标准的关系
|
||
|
||
[`docs/浏览器对接标准.md`](/home/zyl/projects/sgClaw/claw/docs/浏览器对接标准.md) 是联调规范。
|
||
L2 是产品内核视角的契约说明。两者关系如下：
|
||
|
||
- L2 负责解释“为什么有这些字段、这些模块如何依赖它们”。
|
||
- 对接标准负责约束“浏览器宿主必须如何实现 wire contract”。
|
||
|
||
---
|
||
|
||
## 4. 动作契约
|
||
|
||
### 4.1 协议枚举
|
||
|
||
协议层已经定义了以下动作枚举：
|
||
|
||
- `click`
|
||
- `type`
|
||
- `navigate`
|
||
- `getText`
|
||
- `getHtml`
|
||
- `waitForSelector`
|
||
- `pageScreenshot`
|
||
- `select`
|
||
- `scrollTo`
|
||
- `getAomSnapshot`
|
||
- `storageSet`
|
||
- `storageGet`
|
||
- `zombieSpawn`
|
||
- `zombieKill`
|
||
|
||
### 4.2 当前生效动作
|
||
|
||
当前文档、规则和工具 schema 必须以“生效动作”为准，而不是“预留枚举”为准。
|
||
生效动作只有 4 个：
|
||
|
||
- `click`
|
||
- `type`
|
||
- `navigate`
|
||
- `getText`
|
||
|
||
约束来源有三处，三者必须一致：
|
||
|
||
1. `resources/rules.json`
|
||
2. `src/agent/runtime.rs` 的 tool definition
|
||
3. `src/compat/browser_tool_adapter.rs` 的 `parameters_schema` 与 `parse_action`
|
||
|
||
这三者表达的是“当前特权浏览器工具面”的开放范围，而不是 sgClaw 整体 runtime 的长期能力上限。
|
||
|
||
---
|
||
|
||
## 5. `browser_action` 工具契约
|
||
|
||
### 5.1 工具名
|
||
|
||
固定为：
|
||
|
||
```text
|
||
browser_action
|
||
```
|
||
|
||
### 5.2 参数 schema
|
||
|
||
当前有效参数：
|
||
|
||
- `action`
|
||
- `expected_domain`
|
||
- `selector`
|
||
- `text`
|
||
- `url`
|
||
- `clear_first`
|
||
|
||
其中：
|
||
|
||
- `click` 通常需要 `selector`
|
||
- `type` 通常需要 `selector` 与 `text`
|
||
- `navigate` 通常需要 `url`
|
||
- `getText` 通常需要 `selector`
|
||
|
||
### 5.3 失败语义
|
||
|
||
工具执行失败分两类：
|
||
|
||
1. 参数级失败
|
||
说明：缺少必填字段、动作不支持、参数类型错误。
|
||
|
||
2. 协议级失败
|
||
说明：MAC 不通过、浏览器回包 `success=false`、响应超时、序列号异常。
|
||
|
||
这两类失败最终都会转为任务失败并通过 `task_complete` 回传。
|
||
|
||
---
|
||
|
||
## 6. 接口演进原则
|
||
|
||
L2 之后的扩展应遵守以下原则：
|
||
|
||
- 新增动作先进入协议枚举，再补规则白名单，再开放给 tool schema。
|
||
- 不允许只改文档或只改提示词就宣称动作可用。
|
||
- 兼容层与 fallback 路径必须对外保持同一工具名和同一主契约。
|
||
- 浏览器宿主联调时以 wire contract 为最高优先级，不把模型行为假设写进协议。
|