claw/docs/sgclaw_project_team_kickoff.md

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

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

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

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

response

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

4.2 sgClaw -> Browser

init_ack

{"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

{
  "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 建议格式：

{
  "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 手动运行握手

输入：

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

期望输出：

{"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 最小命令样例

输出给浏览器：

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

浏览器回：

{"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 团队阻塞项。