# sgClaw 本项目团队开发启动文档

**适用对象**：sgClaw Rust / Agent 项目开发团队（P1a、P1b）
**目标**：项目团队拿到本文档后即可独立启动 Rust 侧开发，并在一个周期后与浏览器团队完成 Pipe 联调。
**协议版本**：`1.0`
**冻结日期**：`2026-03-24`

---

## 1. 开发目标

本项目团队本周期只负责 sgClaw Rust 侧能力，不负责 Chromium 内部实现。

本周期结束时，Rust 侧必须具备以下能力：

1. 可作为浏览器子进程启动。
2. 通过 `stdin/stdout` 执行双向 `JSON Line` 通信。
3. 完成 `init -> init_ack` 握手。
4. 提供 `BrowserPipeTool`，可发送 `click/type/navigate/getText`。
5. 能等待并解析浏览器侧 `response`。
6. 能执行本地 `MAC Policy` 初步校验。

本周期不做：

1. 不切回 HTTP/TCP 演示通道。
2. 不依赖浏览器团队未完成的 UI。
3. 不把 pipe 协议和业务 skill 混在一起推进。
4. 不要求本周期完成完整 15 action。

---

## 2. Rust 团队负责的交付物

本周期交付以下文件或等价模块：

1. `src/main.rs`
2. `src/pipe/protocol.rs`
3. `src/pipe/handshake.rs`
4. `src/pipe/browser_tool.rs`
5. `src/pipe/mod.rs`
6. `src/security/mac_policy.rs`
7. `src/security/hmac.rs`
8. `tests/pipe_protocol_test.rs`
9. `tests/pipe_handshake_test.rs`
10. `tests/browser_tool_test.rs`
11. `tests/integration/handshake_flow_test.rs`

建议本周期目录保持如下：

```text
src/
  main.rs
  lib.rs
  pipe/
    mod.rs
    protocol.rs
    handshake.rs
    browser_tool.rs
  security/
    mod.rs
    hmac.rs
    mac_policy.rs
tests/
  pipe_protocol_test.rs
  pipe_handshake_test.rs
  browser_tool_test.rs
  integration/
    handshake_flow_test.rs
resources/
  rules.json
```

---

## 3. 冻结边界

### 3.1 本周期团队边界

P1a 负责：

1. Pipe 协议结构体。
2. 握手。
3. `BrowserPipeTool`。
4. HMAC 计算。
5. response 关联和超时处理。

P1b 负责：

1. 将 `BrowserPipeTool` 作为工具注册到后续 `AgentRuntime`。
2. 但本周期联调不阻塞于完整 ReAct Loop。

本周期联调最小成功标准是：

1. Rust 能发命令。
2. 浏览器能执行并返回。
3. Rust 能按 `seq` 收到正确 response。

### 3.2 进程与日志约束

1. `stdin` 只读协议消息。
2. `stdout` 只写协议消息。
3. 所有日志必须写到 `stderr`。
4. 遇到协议错误时返回结构化错误或退出，不允许把调试日志写进 `stdout`。

---

## 4. 冻结协议

### 4.1 Browser -> sgClaw

`init`

```json
{"type":"init","version":"1.0","hmac_seed":"0123456789abcdef","capabilities":["browser_action"]}
```

`response`

```json
{"type":"response","seq":1,"success":true,"data":{},"aom_snapshot":[],"timing":{"queue_ms":1,"exec_ms":20}}
```

### 4.2 sgClaw -> Browser

`init_ack`

```json
{"type":"init_ack","version":"1.0","agent_id":"uuid-v4","supported_actions":["click","type","navigate","getText","getHtml","waitForSelector","pageScreenshot","select","scrollTo","getAomSnapshot","storageSet","storageGet","zombieSpawn","zombieKill"]}
```

`command`

```json
{
  "type":"command",
  "seq":1,
  "action":"click",
  "params":{"selector":"#submit"},
  "security":{
    "expected_domain":"oa.example.com",
    "hmac":"<hex>"
  }
}
```

### 4.3 必须满足的协议规则

1. 编码为 UTF-8。
2. 每行一个完整 JSON。
3. 单消息最大 `1 MB`。
4. `seq` 从 `1` 开始递增。
5. 每个 `command.seq` 对应唯一 `response.seq`。
6. `version` 固定为 `1.0`。

---

## 5. Rust 侧实现要求

### 5.1 main.rs

本周期 `main` 的目标很简单：

1. 初始化日志到 `stderr`。
2. 用 `stdin/stdout` 执行握手。
3. 初始化 `BrowserPipeTool` 所需对象。
4. 保持进程存活，等待命令结果和后续任务。

如果当前代码还保留演示版 HTTP 入口，本周期必须恢复到 pipe 入口优先。

### 5.2 handshake.rs

必须实现：

1. 从 `stdin` 读取第一条 `init`。
2. 校验 `version`。
3. 从 `hmac_seed` 派生会话级 HMAC key。
4. 生成 `agent_id`。
5. 向 `stdout` 回写 `init_ack`。

失败条件：

1. 第一条消息不是 `init`。
2. `version` 不匹配。
3. `hmac_seed` 非法。

### 5.3 protocol.rs

必须定义：

1. `BrowserMessage`
2. `AgentMessage`
3. `SecurityFields`
4. `Timing`
5. `Action`

本周期最小 `Action` 必须覆盖：

1. `click`
2. `type`
3. `navigate`
4. `getText`

建议保留剩余 action 枚举，为后续扩展留口。

### 5.4 browser_tool.rs

必须实现：

1. 输入参数反序列化为 `Action`。
2. 调用本地 `MAC Policy` 做前置校验。
3. 分配递增 `seq`。
4. 计算 `security.hmac`。
5. 向 `stdout` 写出 `command`。
6. 等待同 `seq` 的 `response`。
7. 超时返回错误。

建议超时：

1. 握手超时：`5s`
2. 单 action 响应超时：`30s`

### 5.5 mac_policy.rs

本周期最小校验：

1. action 白名单。
2. 域名白名单。
3. storage key 前缀约束可后置。
4. 熔断器可后置，但接口要预留。

`rules.json` 建议格式：

```json
{
  "version": "1.0",
  "domains": {
    "allowed": ["oa.example.com", "erp.example.com", "hr.example.com"]
  },
  "pipe_actions": {
    "allowed": ["click", "type", "navigate", "getText"],
    "blocked": ["eval", "executeJsInPage"]
  }
}
```

---

## 6. 本周期开发顺序

### Day 1-2

1. 固定协议结构体。
2. 写 `pipe_protocol_test`。
3. 写 `pipe_handshake_test`。
4. 恢复 `stdin/stdout` 入口。

验收：

1. 能独立运行进程并手动喂一条 `init`。
2. 能正确输出 `init_ack`。

### Day 3-4

1. 完成 `BrowserPipeTool`。
2. 完成 HMAC 计算。
3. 完成基于 `seq` 的 response 匹配。
4. 与本地 mock 浏览器进程联通。

验收：

1. Rust 能发出 `click/type/navigate/getText` 四类命令。
2. mock response 能被正确接收。

### Day 5-6

1. 接入最小 `MAC Policy`。
2. 完成 integration test。
3. 准备联调脚本和示例 JSON。

验收：

1. 非白名单 action 在 Rust 侧被前置拒绝。
2. 域名不合法时直接失败。

### Day 7

1. 收口测试。
2. 输出联调说明。
3. 与浏览器团队联调。

---

## 7. Rust 团队自测清单

- [ ] `protocol.rs` 序列化/反序列化测试通过。
- [ ] `init -> init_ack` 测试通过。
- [ ] `version` 不匹配时握手失败。
- [ ] `hmac_seed` 非法时握手失败。
- [ ] `click/type/navigate/getText` 命令都能正确编码。
- [ ] `response.seq` 不匹配时不会误关联。
- [ ] 单 action 超时能返回错误。
- [ ] 非白名单 action 被 `MAC Policy` 拒绝。
- [ ] 日志只出现在 `stderr`。

---

## 8. 联调输入输出样例

### 8.1 手动运行握手

输入：

```json
{"type":"init","version":"1.0","hmac_seed":"00112233445566778899aabbccddeeff","capabilities":["browser_action"]}
```

期望输出：

```json
{"type":"init_ack","version":"1.0","agent_id":"00000000-0000-0000-0000-000000000000","supported_actions":["click","type","navigate","getText","getHtml","waitForSelector","pageScreenshot","select","scrollTo","getAomSnapshot","storageSet","storageGet","zombieSpawn","zombieKill"]}
```

### 8.2 最小命令样例

输出给浏览器：

```json
{"type":"command","seq":1,"action":"navigate","params":{"url":"https://oa.example.com/login"},"security":{"expected_domain":"oa.example.com","hmac":"<hex>"}}
```

浏览器回：

```json
{"type":"response","seq":1,"success":true,"data":{},"aom_snapshot":[],"timing":{"queue_ms":1,"exec_ms":50}}
```

---

## 9. 联调前必须提供的东西

本项目团队在联调前必须准备：

1. 可运行的 `sgclaw` 可执行文件或 debug 启动方式。
2. 协议样例文件。
3. `rules.json` 默认测试配置。
4. 四个最小 action 的参数样例。
5. 一份错误码表。
6. 一份 `stderr` 日志关键字段说明。

---

## 10. 周期结束验收标准

以下全部满足，Rust 团队本周期完成：

1. `sgclaw` 可以被浏览器作为子进程启动。
2. `init -> init_ack` 成功率 100%。
3. 能稳定发送 `click/type/navigate/getText` 四类命令。
4. 能稳定按 `seq` 收到并解析 response。
5. Rust 侧前置 `MAC Policy` 生效。
6. 与浏览器团队在同一测试页面上联调成功。

---

## 11. 联调日执行顺序

联调当天只按下面顺序走，避免双方并发改协议：

1. 先验证 `init -> init_ack`。
2. 再验证 `navigate`。
3. 再验证 `type`。
4. 再验证 `click`。
5. 最后验证 `getText`。
6. 再补失败场景：域名拒绝、非法 action、超时。

任何协议字段问题，一律以 `protocol.rs` 和本文件为准，不在联调现场临时改口。

---

## 12. 对浏览器团队的依赖

Rust 团队本周期只依赖浏览器团队提供以下冻结输入：

1. 浏览器能启动子进程。
2. 浏览器能收发 JSON Line。
3. 浏览器支持 4 个最小 action。
4. 浏览器返回结构化 `response`。

浏览器内部如何落到 `CommandRouter`，不属于 Rust 团队阻塞项。