claw/docs/L3-数据流与Skill体系层.md

L3 — 数据流与 Skill 体系层

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

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

---

1. 端到端数据流

主线目标中的数据流应当如下：

Client Surface
  └─ submit_task (+ optional browser context)
       ↓
sgClaw Transport / Handshake
  └─ sgClaw security envelope
       ↓
ZeroClaw-first runtime
  └─ runtime profile / tool policy
       ↓
Tool execution
  ├─ browser_action -> pipe -> browser host -> response
  └─ non-browser-safe future surfaces only when policy allows
       ↓
log_entry / task_complete

当前代码与上述目标之间仍有过渡态偏差：

• 浏览器是当前唯一成熟的特权工具面。
• planner fallback 与 browser-first compat runtime 仍然并存。
• zeroclaw 已 vendored，但运行时还没有完全按 zeroclaw-first 方式释放能力。

因此 L3 既要说明目标数据流，也要明确指出当前代码仍处于过渡收口阶段。

---

2. 任务生命周期

2.1 启动阶段

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

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

2.2 任务接收阶段

浏览器宿主当前发送：

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

Rust 侧在 src/agent/mod.rs 中接收后，不应被理解为“直接开始网页自动化”，而是先决定当前任务使用什么 runtime/profile，并判断浏览器上下文是否真的必要。

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 形成下一步输入或最终结果。

这意味着“runtime 决策”和“浏览器动作执行”之间的接口已经被压缩到非常薄的一层，这是 sgClaw 作为 zeroclaw 安全封装层最有价值的结构变化。

---

4. 日志与结果流

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

4.1 log_entry

用途：

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

典型内容：

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

4.2 task_complete

用途：

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

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

---

5. Skill 体系的当前定义

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

5.1 当前不应再设计独立于 zeroclaw 的 Skill 引擎

当前仓库中不应再把 Skill 理解为浏览器专用外挂子系统。sgClaw 已经 vendored zeroclaw，自带的 skill 体系才是主线。需要注意的是，当前运行时对它的使用仍不充分。

当前代码仍缺少或未完全释放的部分包括：

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

因此文档上不能再把 Skill 描述为“浏览器侧另起一套引擎”，而应描述为“应复用 zeroclaw-native 机制的能力层，当前实现仍在收口”。

5.2 当前可以保留的 Skill 语义

在 sgClaw 的主线架构里，Skill 更准确的含义是：

• 由 zeroclaw 管理的可复用任务模式、提示规范和可调用工具组合。
• 在 compact/full 模式下进入 system prompt 或按需通过 read_skill 读取。
• 当任务需要浏览器时，最终可落到统一的 browser_action 契约；当任务不需要浏览器时，不应强行绕浏览器一圈。

换句话说，Skill 不是“浏览器脚本目录”的别名，而是 zeroclaw runtime 的一部分。

5.3 Skill 演进约束

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

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

---

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

6.1 配置

当前真正参与执行的关键配置来自 src/config/settings.rs：

• DEEPSEEK_API_KEY
• DEEPSEEK_BASE_URL
• DEEPSEEK_MODEL

这些配置当前决定是否启用 compat runtime，以及模型请求如何路由。长期看，它们应收敛为 zeroclaw-first 的 sgClaw runtime 配置，而不是永远停留在 DeepSeek shim。

6.2 记忆

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

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

---

7. L3 结论

L3 的核心不是“把所有未来能力都放进一个宏大数据流图”，也不是“把所有任务都解释成浏览器动作”，而是说明 sgClaw 如何把任务先交给 zeroclaw runtime，再把其中需要高风险外部执行的部分压缩成可验证、可回包、可受控的浏览器动作。

重构后的灵魂有三点：

• 任务入口统一。
• runtime 核心统一到 zeroclaw。
• 特权工具面可替换，但协议和安全边界不变。