# L3 — 数据流与 Skill 体系层

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

**读者**: 高级开发者、联调工程师、后续扩展设计人员

---

## 1. 端到端数据流

当前主链路的数据流如下：

```
Browser Host
  └─ submit_task
       ↓
sgClaw Transport / Handshake
  └─ handle_browser_message
       ↓
Execution Path Select
  ├─ planner fallback
  └─ zeroclaw compat runtime
       ↓
browser_action
       ↓
AgentMessage::Command
       ↓
Browser executes action
       ↓
BrowserMessage::Response
       ↓
log_entry / task_complete
```

这条链路里没有独立 Skill 执行器，也没有独立任务编排数据库。  
因此 L3 的重点不再是“描述一个理想化智能体平台”，而是说明当前仓库里真实存在的数据流状态机。

---

## 2. 任务生命周期

### 2.1 启动阶段

1. 浏览器宿主拉起 sgClaw 进程。
2. 宿主发送 `init`。
3. sgClaw 返回 `init_ack`。
4. `StdioTransport` 进入阻塞接收循环。

此阶段的目标是建立会话、版本和 HMAC 基线。

### 2.2 任务接收阶段

宿主发送：

```json
{ "type": "submit_task", "instruction": "..." }
```

Rust 侧在 [`src/agent/mod.rs`](/home/zyl/projects/sgClaw/claw/src/agent/mod.rs) 中接收后，不直接执行页面命令，而是先决定走哪条执行路径。

### 2.3 执行路径选择

#### 路径 A：planner fallback

条件：没有可用的 `DEEPSEEK_*` 环境配置。  
行为：使用仓库内置 planner 直接产生若干步骤，并逐个调用 `BrowserPipeTool`。

特点：

- 依赖更少。
- 逻辑可预测。
- 适合协议联调和最小功能验证。

#### 路径 B：ZeroClaw compat runtime

条件：存在有效模型配置。  
行为：构建 ZeroClaw Agent，注册 `browser_action` 工具，消费 `TurnEvent`，再通过 `BrowserPipeTool` 下发动作。

特点：

- 可以承载更自然的 agent 行为。
- 为后续记忆、可观测性与 provider 扩展保留接口。
- 当前仍严格受单工具和四动作约束。

---

## 3. 单步动作数据流

无论走哪条路径，真正触达浏览器时的数据流是一致的：

1. 生成动作  
说明：动作最终都被规约成 `Action + params + expected_domain`。

2. 本地策略校验  
说明：`BrowserPipeTool` 在发送前执行 MAC Policy 校验。

3. 组装命令  
说明：生成 `AgentMessage::Command`，写入 `seq` 与 `security.hmac`。

4. 浏览器执行  
说明：宿主按其自身执行器把命令转换为页面动作。

5. 接收回包  
说明：Rust 侧等待同 `seq` 的 `BrowserMessage::Response`。

6. 形成观察结果  
说明：根据 `success`、`data`、`aom_snapshot` 和 `timing` 形成下一步输入或最终结果。

这意味着“智能体行为”和“浏览器动作执行”之间的接口已经被压缩到非常薄的一层，这是 ZeroClaw 重构最有价值的结构变化。

---

## 4. 日志与结果流

当前会对宿主输出两类业务级反馈：

### 4.1 `log_entry`

用途：

- 向上层 UI 或调试台报告过程信息。
- 对齐 ZeroClaw 的 `TurnEvent` 与 fallback 步骤日志。

典型内容：

- 当前准备执行的动作。
- compat runtime 中转译出的事件摘要。
- 执行中的信息性提示。

### 4.2 `task_complete`

用途：

- 明确任务是否成功。
- 返回最终摘要文案。

这是上层产品最稳定的完成态信号，不应依赖 stderr 日志或内部推理文本。

---

## 5. Skill 体系的当前定义

“L3 是灵魂”的前提，不是把 Skill 写得越来越玄，而是把 Skill 在当前阶段的真实语义说清楚。

### 5.1 当前不存在独立 Skill 引擎

当前仓库中没有独立的：

- Skill 脚本目录加载流程
- Skill 注册表
- Skill 沙箱执行器
- Skill 版本与签名校验主链路

因此不能再把 Skill 描述为已落地子系统。

### 5.2 当前可以保留的 Skill 语义

在 ZeroClaw 重构版里，Skill 更准确的含义是：

- 面向未来的“可复用任务模式”抽象。
- 可能由提示词、模板、预设工具组合或 planner 规则来承载。
- 最终仍要落到统一的 `browser_action` 契约。

换句话说，当前 Skill 不是一个运行时目录，而是一种产品与执行层之间的抽象语言。

### 5.3 Skill 演进约束

后续如果重新引入 Skill 子系统，必须满足：

- Skill 的输出仍服从 `browser_action` 或其后继正式工具契约。
- Skill 不能绕过 `rules.json` 的安全边界。
- Skill 文档不能先于代码宣称“已具备自治学习能力”。

---

## 6. 配置与记忆的当前状态

### 6.1 配置

当前真正参与执行的关键配置来自 [`src/config/settings.rs`](/home/zyl/projects/sgClaw/claw/src/config/settings.rs)：

- `DEEPSEEK_API_KEY`
- `DEEPSEEK_BASE_URL`
- `DEEPSEEK_MODEL`

这些配置决定是否启用 compat runtime，以及模型请求如何路由。

### 6.2 记忆

ZeroClaw compat 路径中已经接入 memory adapter，但在产品能力层面仍应描述为：

- 已为记忆能力预留接入位。
- 当前主要价值在于兼容运行时需要，而非对外主卖点。
- 还不能把它描述成稳定的长期知识库产品能力。

---

## 7. L3 结论

L3 的核心不是“把所有未来能力都放进一个宏大数据流图”，而是说明当前系统如何把自然语言任务压缩成可验证、可回包、可受控的浏览器动作。

重构后的灵魂有三点：

- 任务入口统一。
- 动作契约统一。
- 执行路径可替换，但协议和安全边界不变。