223 lines
7.5 KiB
Markdown
223 lines
7.5 KiB
Markdown
# 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/runtime` 旧链路仍保留在仓库中，但已收敛为 `legacy/dev-only` 辅助模块。
|
||
- `zeroclaw` 已 vendored，但运行时还没有完全按 zeroclaw-first 方式释放能力。
|
||
|
||
因此 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) 中接收后，不应被理解为“直接开始网页自动化”，而是先决定当前任务使用什么 runtime/profile，并判断浏览器上下文是否真的必要。
|
||
|
||
### 2.3 当前执行路径选择（过渡态）
|
||
|
||
#### 路径 A：legacy planner/runtime（非生产 submit 主链）
|
||
|
||
条件：仅用于 dev/test 验证或保留回归覆盖。
|
||
行为：使用仓库内置 planner 或轻量 runtime 直接产生若干步骤，并逐个调用 `BrowserPipeTool`。
|
||
|
||
特点：
|
||
|
||
- 依赖更少。
|
||
- 逻辑可预测。
|
||
- 适合协议联调和最小功能验证。
|
||
- 不再承接生产浏览器 submit 流量。
|
||
|
||
#### 路径 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 步骤日志。
|
||
|
||
典型内容：
|
||
|
||
- 当前准备执行的动作。
|
||
- `planner_mode=zeroclaw_plan_first` 时由 sgClaw 先发出的计划预览。
|
||
- 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`](/home/zyl/projects/sgClaw/claw/src/config/settings.rs)。它已经不再只是单一 `DEEPSEEK_*` shim，而是开始承载 sgClaw 自己的运行时策略：
|
||
|
||
- `providers` / `active_provider`
|
||
- `planner_mode`
|
||
- `browser_backend`
|
||
- `office_backend`
|
||
- `skills_prompt_mode`
|
||
- `runtime_profile`
|
||
|
||
当前默认语义是：
|
||
|
||
- `providers` 为空时，仍兼容旧的 `apiKey/baseUrl/model` DeepSeek 单模型配置。
|
||
- `planner_mode=zeroclaw_plan_first` 时，由 sgClaw 在真实执行前先向宿主发送可展示的计划预览，前端只负责渲染。
|
||
- `browser_backend=superrpa` 时，浏览器高权限动作仍以宿主 pipe 为边界；sgClaw 只决定运行时策略，不把特权上移到前端。
|
||
- `office_backend=openxml` 时，导出类任务仍由 sgClaw 运行时选择实际导出工具。
|
||
|
||
这部分配置的目标很明确：让模型切换、planner 策略和运行时 backend 选择回到 sgClaw 自己，而不是继续散落在 SuperRPA 编译期常量或前端逻辑里。
|
||
|
||
### 6.2 记忆
|
||
|
||
ZeroClaw compat 路径中已经接入 memory adapter，但在产品能力层面仍应描述为：
|
||
|
||
- 已为记忆能力预留接入位。
|
||
- 当前主要价值在于兼容运行时需要，而非对外主卖点。
|
||
- 还不能把它描述成稳定的长期知识库产品能力。
|
||
|
||
---
|
||
|
||
## 7. L3 结论
|
||
|
||
L3 的核心不是“把所有未来能力都放进一个宏大数据流图”，也不是“把所有任务都解释成浏览器动作”，而是说明 sgClaw 如何把任务先交给 zeroclaw runtime，再把其中需要高风险外部执行的部分压缩成可验证、可回包、可受控的浏览器动作。
|
||
|
||
重构后的灵魂有三点：
|
||
|
||
- 任务入口统一。
|
||
- runtime 核心统一到 zeroclaw。
|
||
- 特权工具面可替换，但协议和安全边界不变。
|