# sgClaw 浏览器团队开发启动文档

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

---

## 1. 开发目标

浏览器团队本周期只负责浏览器侧 Pipe 接入，不负责 LLM、Skill、Memory、Agent 推理。

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

1. 能从浏览器主进程启动 `sgclaw` Rust 子进程。
2. 能通过 `stdin/stdout` 与 `sgclaw` 进行双向 `JSON Line` 通信。
3. 能解析 sgClaw 发来的 `command` 消息，并路由到现有 `CommandRouter`。
4. 能执行最小可联调动作：`click`、`type`、`navigate`、`getText`。
5. 能返回结构化 `response` 消息。
6. 能在浏览器侧执行域名和 action 白名单校验。

本周期不做：

1. 不改现有 `CommandRouter` 的核心接口。
2. 不新造一套浏览器操作 API。
3. 不改为 HTTP、WebSocket、Named Pipe。
4. 不实现 Rust 侧逻辑。

---

## 2. 架构边界

浏览器侧是父进程，`sgclaw` 是子进程。浏览器侧新增三个模块：

1. `SgClawProcessHost`
   负责子进程启动、停止、状态管理、异常退出处理。
2. `PipeListener`
   负责异步读取 `sgclaw stdout`，按行解析 JSON 并分发。
3. `MacWhitelistCheck`
   负责浏览器侧二次安全校验，防止越权 action 落到 `CommandRouter`。

浏览器侧数据流固定如下：

`Side Panel / UI -> SgClawProcessHost -> STDIO Pipe -> sgclaw`

`sgclaw -> STDIO Pipe -> PipeListener -> MacWhitelistCheck -> CommandRouter -> response`

---

## 3. 浏览器团队负责的交付物

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

1. `sgclaw_process_host.h`
2. `sgclaw_process_host.cc`
3. `pipe_listener.h`
4. `pipe_listener.cc`
5. `mac_whitelist_check.h`
6. `mac_whitelist_check.cc`
7. `rules.json`
8. `sgclaw_unittests` 中对应单元测试

建议目录：

```text
chrome/browser/superrpa/sgclaw/
  sgclaw_process_host.h
  sgclaw_process_host.cc
  pipe_listener.h
  pipe_listener.cc
  mac_whitelist_check.h
  mac_whitelist_check.cc
  test/
    sgclaw_process_host_unittest.cc
    pipe_listener_unittest.cc
    mac_whitelist_check_unittest.cc
  resources/
    rules.json
```

---

## 4. 冻结接口

### 4.1 传输协议

1. 传输层固定为 `STDIO Pipe`。
2. 编码固定为 `UTF-8`。
3. 消息边界固定为 `JSON Line`，每行一条完整 JSON。
4. 单条消息最大 `1 MB`。
5. `stdout` 只允许输出协议消息，日志必须走 `stderr`。

### 4.2 握手协议

浏览器发送：

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

sgClaw 返回：

```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"]}
```

约束：

1. 浏览器必须在子进程启动后 `5s` 内发送 `init`。
2. `5s` 内收不到 `init_ack`，判定启动失败。
3. `version` 不一致，必须立即终止会话。

### 4.3 command 消息格式

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

字段要求：

1. `seq` 为正整数，必须唯一。
2. `action` 必须在白名单内。
3. `params` 必须是对象。
4. `security.expected_domain` 和 `security.hmac` 必须存在。

### 4.4 response 消息格式

成功：

```json
{
  "type":"response",
  "seq":12,
  "success":true,
  "data":{"text":"提交成功"},
  "aom_snapshot":[],
  "timing":{"queue_ms":2,"exec_ms":38}
}
```

失败：

```json
{
  "type":"response",
  "seq":12,
  "success":false,
  "data":{
    "error":{
      "code":"CMD_SELECTOR_NOT_FOUND",
      "message":"selector '#submit' not found"
    }
  },
  "aom_snapshot":[],
  "timing":{"queue_ms":1,"exec_ms":10}
}
```

约束：

1. 一个 `command.seq` 只能对应一个 `response.seq`。
2. 失败必须返回结构化错误，不允许只返回字符串。
3. `timing` 必须始终带上。

---

## 5. 本周期最小 Action 集

联调周期只强制四个动作：

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

动作语义：

1. `click`
   调用现有点击能力，支持可选 `wait_after`。
2. `type`
   在目标输入框输入文本，支持 `clear_first`。
3. `navigate`
   导航到目标 URL。
4. `getText`
   获取目标节点文本。

其余 action 可保留接口但不进入本周期强制验收。

---

## 6. 浏览器侧实现要求

### 6.1 SgClawProcessHost

必须实现：

1. 单例，避免重复创建多个 `sgclaw` 子进程。
2. `Start()` 创建匿名管道并启动子进程。
3. `Stop()` 正常关闭并在超时后强制结束。
4. `OnProcessCrash()` 记录错误并更新状态。
5. 状态机至少包含 `Idle -> Starting -> Running -> Stopped / Crashed`。

建议接口：

```cpp
class SgClawProcessHost {
 public:
  bool Start();
  void Stop();
  bool IsRunning() const;
  bool SendLine(std::string json_line);
};
```

### 6.2 PipeListener

必须实现：

1. 持续读取 `stdout`。
2. 以换行符切分 `JSON Line`。
3. 拒绝空行、非 JSON、超过 1MB 的消息。
4. 能按 `seq` 追踪一次请求的完整生命周期。
5. 管道断开时通知 `SgClawProcessHost`。

### 6.3 CommandRouter 对接

必须实现：

1. `command.action` 到现有浏览器命令的映射表。
2. 尽量复用现有 `CommandRouter`。
3. 不允许在 Pipe 层直接写新的页面控制逻辑。
4. response 必须从实际执行结果构造，不允许伪造成功。

建议映射：

1. `click -> CommandRouter.click`
2. `type -> CommandRouter.type`
3. `navigate -> CommandRouter.navigate`
4. `getText -> CommandRouter.getText`

### 6.4 MacWhitelistCheck

必须实现：

1. action 白名单校验。
2. expected_domain 与当前页面域名比对。
3. `rules.json` 加载失败时默认拒绝。
4. 拒绝时返回统一错误码。

建议错误码：

1. `MAC_ACTION_NOT_ALLOWED`
2. `MAC_DOMAIN_NOT_ALLOWED`
3. `MAC_RULES_LOAD_FAILED`
4. `PIPE_INVALID_JSON`
5. `PIPE_MESSAGE_TOO_LARGE`

---

## 7. 浏览器团队开发顺序

### Day 1-2

1. 完成 `SgClawProcessHost` 骨架。
2. 用 dummy 子进程验证启动和退出。
3. 打通 `stdin/stdout` 读写通道。

验收：

1. 能启动 `echo` 或测试进程。
2. 能发送一行字符串并收到回写。

### Day 3-4

1. 完成 `PipeListener`。
2. 完成 `init -> init_ack` 握手。
3. 建立 `command` / `response` 解析结构。

验收：

1. 能与 Rust 侧互发 JSON Line。
2. 能处理 `seq` 对应关系。

### Day 5-6

1. 接入 `CommandRouter`。
2. 完成 4 个最小 action。
3. 完成 `MacWhitelistCheck`。

验收：

1. Rust 发起 `click/type/navigate/getText` 时浏览器真实执行。
2. 非白名单域名被拒绝。

### Day 7

1. 完成浏览器侧单元测试。
2. 提供联调分支和运行说明。
3. 预留半天与项目团队联调。

---

## 8. 浏览器团队自测清单

- [ ] `Start()` 成功启动真实 `sgclaw` 二进制。
- [ ] `Start()` 重复调用不会启动多个实例。
- [ ] `Stop()` 能正常关闭进程。
- [ ] `init -> init_ack` 成功。
- [ ] 超过 1MB 的 JSON 消息会被拒绝。
- [ ] 非 JSON 行会被拒绝。
- [ ] `click/type/navigate/getText` 能成功返回。
- [ ] 域名不匹配时返回 `MAC_DOMAIN_NOT_ALLOWED`。
- [ ] `rules.json` 缺失时默认拒绝。
- [ ] 日志中能按 `seq` 查到请求和响应。

---

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

### 9.1 手动握手

浏览器发：

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

期待 Rust 回：

```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"]}
```

### 9.2 最小 click 联调

Rust 发：

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

浏览器回：

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

---

## 10. 联调日必须提供的东西

浏览器团队在联调前必须准备：

1. 可运行的浏览器分支。
2. `sgclaw` 子进程启动入口。
3. `rules.json` 默认测试配置。
4. 最小测试页面，至少包含一个输入框、一个按钮、一个文本节点。
5. 一份 action 到 `CommandRouter` 的映射表。
6. 一份错误码表。

---

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

以下全部满足，浏览器团队本周期完成：

1. 能在浏览器中稳定启动和停止 `sgclaw`。
2. `init -> init_ack` 成功率 100%。
3. `click/type/navigate/getText` 联调通过。
4. 所有失败场景均返回结构化错误。
5. 域名和 action 白名单生效。
6. 与项目团队在同一测试页完成一次端到端演示。

---

## 12. 依赖与协作方式

浏览器团队只依赖以下冻结输入：

1. Pipe 协议版本：`1.0`
2. 消息结构：`init / init_ack / command / response`
3. 最小 action：`click/type/navigate/getText`
4. 安全字段：`expected_domain`、`hmac`

除以上四项外，本周期内其他细节不应阻塞浏览器侧开发。