claw/docs/L4-工程实现与部署拓扑层.md

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

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

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

---

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
• src/lib.rs

职责：

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

2.2 协议与浏览器工具

• src/pipe/protocol.rs
• src/pipe/browser_tool.rs
• src/pipe/handshake.rs

职责：

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

2.3 执行路径

• src/agent/mod.rs
• src/agent/runtime.rs
• src/compat/runtime.rs
• 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
• src/config/settings.rs
• resources/rules.json

职责：

• 维护运行时安全边界。
• 读取 provider / skills 等运行时配置，并逐步向 zeroclaw-first 配置模型收敛。

---

3. 构建与运行

3.1 本地构建

当前仓库以 Cargo 为主：

cargo build

发布构建：

cargo build --release

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

3.2 运行前提

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

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

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

3.3 模型配置

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

DEEPSEEK_API_KEY=...
DEEPSEEK_BASE_URL=...
DEEPSEEK_MODEL=...

若这些变量不存在或不完整，系统会退回 planner fallback。这个行为是当前实现状态，不是长期架构推荐。

3.4 runtime config 文件

当 host 以 --config-path=<workspace_root>/sgclaw_config.json 拉起 sgclaw 时，sgclaw 会自己读取该 JSON 文件，而不是要求宿主额外复制 skills。

当前支持的关键字段：

{
  "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/ 目录。
• 因此 host 只需要负责传递 runtime config 路径，skill 查找策略由 sgclaw 自己控制。
• 长期看，这个文件应表达 zeroclaw-first、planner-first 的 runtime/profile/tool policy 配置，而不仅是 provider shim。

3.5 launch config 文件与 fallback

launch config 由 host 读取，不由 sgClaw 自己解析。设计冻结后的推荐路径为：

<profile>/superrpa/sgclaw_launch_config.json

该文件承载的字段应包括：

• binary
• args
• env
• working_dir
• runtime_config_path
• frontend_bundle_dir

加载规则必须保持稳定：

1. host 优先读取 profile-local launch config
2. 若 binary 缺失或无效，则回退到浏览器已知可启动的默认 sgClaw 路径
3. 若 runtime_config_path 缺失，则回退到 <profile>/superrpa/sgclaw_config.json
4. 若 frontend_bundle_dir 缺失或无效，则回退到 bundled frontend resources

这样做的目的不是削弱宿主管控，而是把高频变化项从编译期常量改成运行期可替换对象。

3.6 frontend bundle 装载拓扑

frontend bundle 的部署方式应当是“外部 bundle 优先，内置资源兜底”：

host
  ├─ validate frontend_bundle_dir
  ├─ if valid: load external frontend bundle
  └─ else: load bundled frontend resources

这意味着后续改浮窗 UI、验收页面或 planner 展示逻辑，不应再默认要求重编 Chromium。

---

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

建议执行：

cargo test

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

---

5. 部署边界

5.1 本仓库负责什么

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

5.2 外部宿主负责什么

• 读取并校验 launch config。
• 拉起并托管 sgClaw 进程。
• 提供页面执行能力。
• 实现命令落地、响应回传和宿主侧校验。
• 装载 frontend bundle，并在无效时回退到内置资源。

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

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

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

---

6. 部署建议拓扑

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

Browser Host Process
  ├─ reads launch config
  ├─ launches sgclaw binary
  ├─ writes init / submit_task to stdin
  ├─ reads command / log / task_complete from stdout
  ├─ executes page actions in host environment
  └─ loads external frontend bundle or bundled resources

sgclaw binary
  ├─ loads runtime config
  ├─ loads resources/rules.json
  ├─ runs planner-first execution
  ├─ 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”，同时保持浏览器协议稳定。
3. host、launch config、runtime config、frontend bundle、planner-first 必须在文档、代码和验收中使用同一套术语，避免再次把前端逻辑上移到 sgClaw 之外。