# L4 — 工程实现与部署拓扑层

**文档版本**: 2.0  
**适用项目**: sgClaw（ZeroClaw 重构版）  
**编制日期**: 2026-03-26

**读者**: 开发者、测试工程师、联调工程师

---

## 1. 当前仓库结构

本仓库已经收敛为以 Rust Runtime 为主、文档为辅的产品内核仓库。  
不再把外部浏览器仓库和旧验证页当作本仓库的主实现面。

```
claw/
├── Cargo.toml
├── resources/
│   └── rules.json
├── src/
│   ├── main.rs
│   ├── lib.rs
│   ├── agent/
│   ├── compat/
│   ├── config/
│   ├── llm/
│   ├── pipe/
│   └── security/
├── tests/
├── third_party/
│   └── zeroclaw/
├── docs/
│   ├── L0-...md
│   ├── L1-...md
│   ├── L2-...md
│   ├── L3-...md
│   ├── L4-...md
│   ├── 浏览器对接标准.md
│   ├── plans/
│   └── archive/
└── frontend/
    ├── README.md
    └── archive/
```

工程上应把 `third_party/zeroclaw` 理解为“已 vendored 的兼容依赖”，而不是单独维护的兄弟项目。

---

## 2. 关键实现文件

### 2.1 入口与装配

- [`src/main.rs`](/home/zyl/projects/sgClaw/claw/src/main.rs)
- [`src/lib.rs`](/home/zyl/projects/sgClaw/claw/src/lib.rs)

职责：

- 初始化二进制入口。
- 建立标准输入输出 transport。
- 完成握手。
- 将消息循环交给 `agent`。

### 2.2 协议与浏览器工具

- [`src/pipe/protocol.rs`](/home/zyl/projects/sgClaw/claw/src/pipe/protocol.rs)
- [`src/pipe/browser_tool.rs`](/home/zyl/projects/sgClaw/claw/src/pipe/browser_tool.rs)
- [`src/pipe/handshake.rs`](/home/zyl/projects/sgClaw/claw/src/pipe/handshake.rs)

职责：

- 定义 wire message。
- 维护 `seq` 和 HMAC。
- 提供命令发送与响应等待能力。

### 2.3 执行路径

- [`src/agent/mod.rs`](/home/zyl/projects/sgClaw/claw/src/agent/mod.rs)
- [`src/agent/runtime.rs`](/home/zyl/projects/sgClaw/claw/src/agent/runtime.rs)
- [`src/compat/runtime.rs`](/home/zyl/projects/sgClaw/claw/src/compat/runtime.rs)
- [`src/compat/browser_tool_adapter.rs`](/home/zyl/projects/sgClaw/claw/src/compat/browser_tool_adapter.rs)

职责：

- 决定 fallback 或 compat 执行。
- 把统一工具契约映射到浏览器协议。
- 在 ZeroClaw turn 事件与宿主日志之间做桥接。

### 2.4 安全与配置

- [`src/security/mac_policy.rs`](/home/zyl/projects/sgClaw/claw/src/security/mac_policy.rs)
- [`src/config/settings.rs`](/home/zyl/projects/sgClaw/claw/src/config/settings.rs)
- [`resources/rules.json`](/home/zyl/projects/sgClaw/claw/resources/rules.json)

职责：

- 维护运行时安全边界。
- 从环境变量读取 provider 配置。

---

## 3. 构建与运行

### 3.1 本地构建

当前仓库以 Cargo 为主：

```bash
cargo build
```

发布构建：

```bash
cargo build --release
```

如果需要做协议或兼容层改动，优先先跑测试，再谈部署。

### 3.2 运行前提

sgClaw 不是独立交互式 CLI 产品，正常运行前提是：

- 有浏览器宿主进程作为父进程。
- 宿主通过 STDIO 与 sgClaw 通信。
- 宿主实现 `init/submit_task/response` 协议。

直接在终端里执行二进制，只能用于开发级调试，不代表真实产品启动方式。

### 3.3 模型配置

启用 ZeroClaw compat runtime 的关键环境变量：

```bash
DEEPSEEK_API_KEY=...
DEEPSEEK_BASE_URL=...
DEEPSEEK_MODEL=...
```

若这些变量不存在或不完整，系统会退回 planner fallback。

---

## 4. 测试拓扑

当前测试覆盖重点是“协议与兼容性”，而不是 UI 演示。

主要测试类别包括：

- `pipe_protocol_test.rs`
- `pipe_handshake_test.rs`
- `browser_tool_test.rs`
- `runtime_task_flow_test.rs`
- `agent_runtime_test.rs`
- `compat_runtime_test.rs`
- `compat_browser_tool_test.rs`
- `compat_config_test.rs`
- `compat_memory_test.rs`
- `compat_cron_test.rs`

建议执行：

```bash
cargo test
```

这组测试表达了一个重要工程事实：当前系统的稳定核心是协议、runtime 选择和 compat 适配，而不是旧版前端验证页。

---

## 5. 部署边界

### 5.1 本仓库负责什么

- 提供 sgClaw Rust 二进制。
- 提供规则文件。
- 提供协议文档和测试基线。

### 5.2 外部宿主负责什么

- 拉起并托管 sgClaw 进程。
- 提供页面执行能力。
- 实现命令落地、响应回传和宿主侧校验。

### 5.3 不在本仓库内交付的内容

- Chromium 工程源码与 BUILD 配置。
- Side Panel 成品前端。
- 生产部署脚本、安装包、发布流水线。

L4 的工程边界必须按仓库现实写清楚，否则会把“外部依赖”误写成“本仓库已交付”。

---

## 6. 部署建议拓扑

一个最小可工作的部署拓扑如下：

```
Browser Host Process
  ├─ launches sgclaw binary
  ├─ writes init / submit_task to stdin
  ├─ reads command / log / task_complete from stdout
  └─ executes page actions in host environment

sgclaw binary
  ├─ loads resources/rules.json
  ├─ verifies action/domain
  ├─ optionally calls provider API
  └─ waits for browser response
```

这就是当前版本真正需要被实现和联调的部署模型。

---

## 7. 工程结论

L4 层面的核心结论只有两点：

1. 本仓库已经从“带演示页的杂糅目录”收敛为“Rust Runtime + 协议文档 + 测试”的内核仓库。
2. ZeroClaw 重构后的工程重点，是保证 compat runtime、fallback runtime、浏览器协议三者在同一 contract 上工作。