first commit

docs/浏览器对接标准.md

@@ -0,0 +1,77 @@
+# sgClaw 浏览器对接标准（Chromium ↔ sgClaw）
+
+> 适用范围：P1a（Rust）与 P2（Chromium C++）联调开发。
+> 目标：双方只要严格按本文档实现，即可稳定联调。
+
+## 1. 协议边界与责任
+
+- 单一事实来源：`docs/L2-核心模块与接口契约层.md` 第 5 章（5.1~5.4）。
+- 协议版本冻结：`1.0`；字段、action、错误码变更均视为协议变更。
+- P1a 负责：`seq` 生成、command 组包、HMAC 计算、response 关联。
+- P2 负责：message 解析、Schema 校验、MAC 检查、CommandRouter 执行、结构化回包。
+
+## 2. Wire Contract（双方 MUST）
+
+| 项目 | 强约束 | 违规错误码 |
+|---|---|---|
+| 传输层 | STDIO + JSON Line（每行一条完整 JSON） | `PIPE_INVALID_JSON` |
+| 编码 | UTF-8 | `PIPE_INVALID_JSON` |
+| 消息大小 | 单条消息 `<= 1MB` | `PIPE_MESSAGE_TOO_LARGE` |
+| 序列号 | `seq` 从 1 开始、严格递增、不可重复 | `PIPE_SEQ_DUPLICATE` / `PIPE_SEQ_OUT_OF_ORDER` |
+| 安全字段 | command 必含 `security.expected_domain` 与 `security.hmac` | `PIPE_HMAC_INVALID` / `MAC_*` |
+| 一问一答 | 一个 `seq` 必须且只能对应一个 response | `INTERNAL_UNKNOWN` |
+
+## 3. 握手协议（启动门禁）
+
+1. Browser 启动 sgClaw 子进程。
+2. Browser 发送：`{"type":"init","version":"1.0","hmac_seed":"<hex>"}`。
+3. sgClaw 返回：`{"type":"init_ack","version":"1.0","agent_id":"<uuid-v4>","supported_actions":[...]}`。
+4. Browser 超时 `5000ms` 未收到 `init_ack`：Kill 子进程并置状态 `Crashed`。
+5. 任一方 `version` 不一致：立即失败，不进入 Running。
+
+## 4. 命令/响应字段标准
+
+- command 必填：`seq`、`type=command`、`action`、`params`、`security`。
+- response 必填：`seq`、`type=response`、`success`。
+- 失败 response 必填：`error.code`、`error.message`（禁止纯文本错误）。
+- `action` 与 `params` 必须通过 L2 的枚举和 Schema 校验。
+
+**标准 command 示例**：
+
+```json
+{"seq":12,"type":"command","action":"click","params":{"selector":"#submit"},"security":{"expected_domain":"erp.example.com","hmac":"<hex>"}}
+```
+
+## 5. HMAC 统一规则（避免两端实现不一致）
+
+- 算法：`HMAC-SHA256`，输出小写 hex。
+- 密钥：由 `hmac_seed` 派生后在会话内固定。
+- 签名原文（canonical string）：
+
+```text
+<seq>\n<action>\n<stable_json(params)>\n<expected_domain>
+```
+
+- `stable_json(params)`：键名按字典序、无多余空格、UTF-8 编码。
+
+## 6. 错误处理与重试矩阵
+
+| 错误类型 | 重试策略 |
+|---|---|
+| `PIPE_*` | 不重试，直接失败 |
+| `MAC_*` | 不重试，等待配置/人工确认 |
+| `CMD_SELECTOR_TIMEOUT` | 最多重试 2 次（500ms、1000ms） |
+| `CMD_NAVIGATION_FAILED` | 最多重试 1 次（1000ms） |
+| `INTERNAL_*` | 最多重试 1 次，仍失败则熔断 |
+
+- 同一 action 连续失败 `>10` 次：触发熔断并通知 UI。
+
+## 7. 联调验收（全部通过才算完成）
+
+- [ ] `init -> init_ack` 连续 100 次成功率 100%。
+- [ ] 版本不匹配时稳定失败并返回可读日志。
+- [ ] `seq` 重复/乱序场景可复现并返回标准错误码。
+- [ ] >1MB 消息可稳定被拒绝。
+- [ ] 核心 action（click/type/navigate/getText）成功率 `>=99%`。
+- [ ] 所有失败场景均返回结构化 `error.code` + `error.message`。
+- [ ] 日志可按 `seq` 贯通请求、执行、响应。