docs: redefine sgclaw as hardened zeroclaw runtime
This commit is contained in:
zyl
@@ -8,25 +8,34 @@
|
||||
|
||||
## 1. 架构总览
|
||||
|
||||
重构后的 sgClaw 架构要点很简单：浏览器宿主负责页面执行，Rust 进程负责任务解释与协议编排，ZeroClaw 作为兼容运行时被接入到 Rust 侧，而不是直接替代整个系统。
|
||||
重构后的 sgClaw 架构要点应当这样理解：zeroclaw 是能力本体，sgClaw 是安全封装层，浏览器宿主是一个受保护的特权执行面。当前代码尚未完全落到这个目标结构，但主线架构口径必须先统一。
|
||||
|
||||
```
|
||||
┌──────────────────────────────┐
|
||||
│ Browser Host / Chromium Side │
|
||||
│ - 启动 sgClaw 子进程 │
|
||||
│ - 发送 init / submit_task │
|
||||
│ - 执行 command 并回 response │
|
||||
│ - 复检 HMAC / domain / params │
|
||||
│ - 执行 browser command 并回包 │
|
||||
└──────────────┬───────────────┘
|
||||
│ STDIO + JSON Line
|
||||
┌──────────────▼───────────────┐
|
||||
│ sgClaw Rust Runtime │
|
||||
│ sgClaw Security Envelope │
|
||||
│ - 握手与消息循环 │
|
||||
│ - MAC Policy │
|
||||
│ - BrowserPipeTool │
|
||||
│ - Planner fallback │
|
||||
│ - ZeroClaw compat runtime │
|
||||
│ - Runtime / Tool Policy │
|
||||
│ - Config Adaptation │
|
||||
└──────────────┬───────────────┘
|
||||
│ Provider API / Local Config
|
||||
│ 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 │
|
||||
@@ -34,7 +43,7 @@
|
||||
└──────────────────────────────┘
|
||||
```
|
||||
|
||||
架构上最重要的变化是：当前系统不是“完整 ZeroClaw 产品”，而是“保留现有浏览器协议的前提下，把 ZeroClaw 作为兼容执行内核引入”。
|
||||
架构上最重要的变化是：sgClaw 不应被定义为“浏览器专用 agent”，而应被定义为“保留现有浏览器协议前提下，对 zeroclaw 做安全化封装的运行时分发”。
|
||||
|
||||
---
|
||||
|
||||
@@ -50,7 +59,7 @@
|
||||
|
||||
sgClaw 仓库本身不包含 Chromium/C++ 实现代码，因此 L1 只定义宿主责任边界，不再把外部仓库中的假定文件结构写成“当前仓库现状”。
|
||||
|
||||
### 2.2 Rust 控制层
|
||||
### 2.2 sgClaw 安全/控制层
|
||||
|
||||
Rust 侧是当前仓库的事实主体，职责包括：
|
||||
|
||||
@@ -58,10 +67,20 @@ Rust 侧是当前仓库的事实主体，职责包括：
|
||||
- 完成握手、加载 `rules.json`、创建 `BrowserPipeTool`。
|
||||
- 在消息循环中接收浏览器消息并分发到执行层。
|
||||
- 把执行日志和任务结果回传给宿主。
|
||||
- 决定哪些 zeroclaw 能力能够暴露给当前运行环境。
|
||||
|
||||
### 2.3 执行层
|
||||
### 2.3 zeroclaw 核心层
|
||||
|
||||
执行层当前有两条路径：
|
||||
主线目标中，zeroclaw 应承担：
|
||||
|
||||
- prompt/system sections 组装
|
||||
- skills / memory / routing
|
||||
- tool loop 与 provider 协调
|
||||
- 通用 agent 能力而非仅浏览器能力
|
||||
|
||||
### 2.4 当前实现的过渡态
|
||||
|
||||
当前执行层仍有两条路径：
|
||||
|
||||
1. `planner fallback`
|
||||
说明：当未配置 `DEEPSEEK_API_KEY` 等环境变量时，使用仓库内置的轻量 planner 执行。
|
||||
@@ -69,23 +88,25 @@ Rust 侧是当前仓库的事实主体，职责包括：
|
||||
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 在本项目中的角色不是“大而全框架接管一切”，而是解决三个具体问题：
|
||||
ZeroClaw 在本项目中的角色不是“大而全框架接管一切”，也不是“被 sgClaw 套壳后只剩一个 browser_action 工具”，而是系统能力本体。sgClaw 应该在它上面解决三个具体问题：
|
||||
|
||||
- 统一模型 Provider 抽象。
|
||||
- 为后续记忆、工具调度、可观测性留出标准扩展位。
|
||||
- 在不改浏览器协议的前提下，替换任务执行内核。
|
||||
- 统一模型 Provider 抽象、skills、memory 和 tool loop。
|
||||
- 在不改浏览器协议的前提下，把高风险执行约束到受保护的工具面。
|
||||
- 让浏览器成为特权执行面，而不是反过来让浏览器定义整个 runtime。
|
||||
|
||||
当前兼容层的限制也必须明确：
|
||||
|
||||
- 只注册一个工具：`browser_action`。
|
||||
- 只开放 4 个动作：`click/type/navigate/getText`。
|
||||
- 不以 ZeroClaw 的全量工具生态作为对外能力宣称。
|
||||
- 不以 ZeroClaw 的全量工具生态作为当前对外能力宣称。
|
||||
|
||||
这些限制是当前实现状态，不是目标架构原则。
|
||||
|
||||
---
|
||||
|
||||
@@ -142,21 +163,21 @@ ZeroClaw 在本项目中的角色不是“大而全框架接管一切”，而
|
||||
原因：
|
||||
|
||||
- 浏览器宿主联调成本最低。
|
||||
- Rust 侧可以独立迭代 planner 和 ZeroClaw 路径。
|
||||
- Rust 侧可以独立演进 zeroclaw runtime 与安全策略，而不破坏宿主联调。
|
||||
- 产品文档、测试和协议标准可以围绕同一条 contract 收敛。
|
||||
|
||||
### 5.3 先做最小工具面，再扩动作
|
||||
### 5.3 先做最小特权工具面，再扩动作
|
||||
|
||||
原因：
|
||||
|
||||
- 当前最稳定的是 `click/type/navigate/getText`。
|
||||
- 动作越多，宿主和模型之间的契约越难稳定。
|
||||
- 动作越多，宿主和 runtime 之间的契约越难稳定。
|
||||
- 在规则文件仍只开放 4 个动作的前提下，文档不应提前放大能力范围。
|
||||
|
||||
---
|
||||
|
||||
## 6. 架构结论
|
||||
|
||||
L1 层面可以把 sgClaw 定义为：一个通过固定浏览器协议接入宿主、以 Rust 为控制层、以 ZeroClaw 为兼容执行核、以 MAC Policy 为最小安全边界的浏览器智能体运行时。
|
||||
L1 层面可以把 sgClaw 定义为：一个通过固定浏览器协议接入宿主、以 Rust 为安全与控制层、以 zeroclaw 为能力核心、以 MAC Policy 与宿主复检为受保护执行边界的安全加固运行时分发。
|
||||
|
||||
这一定义与当前仓库实现保持一致，也为后续继续扩展动作、工具和记忆系统保留了清晰边界。
|
||||
这一定义既承认当前仓库仍存在 browser-first compat 的过渡实现，也为后续把 runtime 真正收口到 zeroclaw-first 主线保留了清晰边界。
|
||||
|
||||
Reference in New Issue
Block a user