253 lines
6.9 KiB
Markdown
253 lines
6.9 KiB
Markdown
# 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 事件与宿主日志之间做桥接。
|
||
|
||
说明：
|
||
|
||
- `src/agent/runtime.rs` 与 `src/agent/planner.rs` 属于过渡性轻量路径，不应再被写成长期产品主线。
|
||
- 主线目标应是“sgClaw security layer + zeroclaw core runtime”，而不是长期保留 browser-only compat 分叉。
|
||
|
||
### 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 / skills 等运行时配置，并逐步向 zeroclaw-first 配置模型收敛。
|
||
|
||
---
|
||
|
||
## 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。这个行为是当前实现状态，不是长期架构推荐。
|
||
|
||
### 3.4 浏览器配置文件
|
||
|
||
当宿主以 `--config-path=<workspace_root>/sgclaw_config.json` 拉起 `sgclaw` 时，`sgclaw` 会自己读取该 JSON 文件，而不是要求宿主额外复制 skills。
|
||
|
||
当前支持的关键字段：
|
||
|
||
```json
|
||
{
|
||
"apiKey": "sk-...",
|
||
"baseUrl": "https://api.deepseek.com",
|
||
"model": "deepseek-chat",
|
||
"skillsDir": "skill_lib"
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- `skillsDir` 可省略。
|
||
- 若省略，则默认使用 `<workspace_root>/.sgclaw-zeroclaw-workspace/skills`。
|
||
- 若为相对路径，则相对于 `sgclaw_config.json` 所在目录解析。
|
||
- 若指向某个 skill repo 根目录，且其下存在 `skills/` 子目录，运行时会自动落到该 `skills/` 目录。
|
||
- 因此 SuperRPA 侧只需要负责传递 `--config-path`，skill 查找策略由 `sgclaw` 自己控制。
|
||
- 长期看，这个文件应表达 zeroclaw-first 的 runtime/profile/tool policy 配置，而不仅是 provider shim。
|
||
|
||
---
|
||
|
||
## 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 选择和 zeroclaw 接入，而不是旧版前端验证页。
|
||
|
||
---
|
||
|
||
## 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 重构后的工程重点，是把工程形态从“browser-first compat”收口为“zeroclaw-first runtime + sgClaw security envelope”，同时保持浏览器协议稳定。
|