# L1 — 系统架构与安全模型层

**文档版本**: 1.0
**适用项目**: sgClaw (业数融合一平台 AI Agent 底座)
**编制日期**: 2026-03-03

---

## 1. 全局架构拓扑

### 1.1 完整架构图

以下是 sgClaw 系统的完整进程与组件拓扑。图中标注了新增组件(New)与已有组件(Existing)，
以便评估改造范围。

```
superrpa-chromium.sh (wrapper, 启动入口)
  │
  ├─ watchdog (background) ─────────────────────────── [Existing, 不变]
  │   └─ node local_service                            [Existing, 不变]
  │        ├─ 本地 HTTP API (端口 9527)
  │        └─ 文件上传 / 下载辅助
  │
  └─ chrome (main process, foreground) ─────────────── [Existing, 不变]
       │
       ├─ SgClawProcessHost ────────────────────────── [New, Singleton in Browser Process]
       │    │
       │    ├── STDIO Pipe (stdin/stdout) ──────────→ sgclaw (Rust child process)
       │    │                                           │
       │    │                                           ├─ Agent Runtime ──────── ZeroClaw ReAct Loop
       │    │                                           │    └─ think → act → observe → repeat
       │    │                                           │
       │    │                                           ├─ LLM Provider ──────── Claude / GPT / 本地模型
       │    │                                           │    ├─ streaming 支持
       │    │                                           │    └─ token 用量统计
       │    │                                           │
       │    │                                           ├─ BrowserPipeTool ──── 自定义 Tool trait 实现
       │    │                                           │    └─ 将 Agent action 序列化为 pipe command
       │    │                                           │
       │    │                                           ├─ SkillLoader ──────── 加载 JS 业务技能脚本
       │    │                                           │    ├─ 技能签名校验
       │    │                                           │    └─ 沙箱执行环境
       │    │                                           │
       │    │                                           ├─ MAC Policy ──────── 域 / Action 白名单
       │    │                                           │    └─ rules.json 配合浏览器侧双重校验
       │    │                                           │
       │    │                                           ├─ Critic ─────────── 输出质量评估
       │    │                                           │    └─ Circuit Breaker (熔断器)
       │    │                                           │
       │    │                                           ├─ Memory ─────────── SQLite + Vector 向量存储
       │    │                                           │    ├─ 短期对话记忆
       │    │                                           │    └─ 长期任务知识库
       │    │                                           │
       │    │                                           └─ MCP Client ─────── rmcp (Rust MCP SDK)
       │    │                                                └─ 连接外部 MCP Server 获取工具
       │    │
       │    ├─ PipeListener (async read loop)
       │    │    └─ 解析 JSON Line，分发到 MAC 校验
       │    │
       │    ├─ MAC Whitelist Check ──────────────────── [New, ~100 lines C++]
       │    │    ├─ 校验 action 是否在 pipe 允许列表
       │    │    └─ 校验 expected_domain 是否匹配当前页
       │    │
       │    └─→ CommandRouter ──────────────────────── [Existing, 40+ actions, 不变]
       │         ├─ CdpCommandExecutor → 页面操作
       │         ├─ ZombiePageManager → 后台会话池
       │         └─ SessionManager → 会话状态机
       │
       ├─ CdpBridgeManager ────────────────────────── [Existing, 页内 JS SDK, 不变]
       │    └─ 页面 JS → CDP binding → CommandRouter
       │
       ├─ ZombiePageManager ───────────────────────── [Existing, 后台会话池, 不变]
       │    └─ 最多 5 个 zombie page，自动回收
       │
       ├─ SessionManager ──────────────────────────── [Existing, 会话状态机, 不变]
       │    └─ login → active → expired → re-login
       │
       └─ RpaGlobalStorage ────────────────────────── [Existing, 跨页存储, 不变]
            └─ key-value 存储，持久化到磁盘
```

### 1.2 简化四组件视图

从系统集成的角度，sgClaw 的架构可简化为四个核心组件的交互：

```
┌─────────────────────┐         STDIO Pipe          ┌─────────────────────┐
│                     │ ◄──────────────────────────► │                     │
│  SuperRPA Browser   │    JSON Line Protocol        │  sgClaw (Rust)      │
│  (C++ Chromium)     │    单连接、进程私有           │  基于 ZeroClaw       │
│                     │                              │                     │
│  • CommandRouter    │                              │  • Agent Runtime    │
│  • CdpBridgeManager│                              │  • BrowserPipeTool  │
│  • ZombiePageMgr   │                              │  • SkillLoader      │
│  • SessionManager   │                              │  • Memory           │
│  • SgClawProcessHost│                              │  • MAC Policy       │
│    (New)            │                              │  • Critic           │
└─────────┬───────────┘                              └──────┬──┬──────────┘
          │                                                 │  │
          │ 页面渲染                                  API 调用 │  │ 加载技能
          │ 用户交互                                         │  │
          ▼                                                 ▼  ▼
┌─────────────────────┐                    ┌────────────────────────────┐
│                     │                    │                            │
│   用户 (前台浏览器)   │                    │  LLM Cloud / Local         │
│                     │                    │  ├─ Claude API             │
│   • Side Panel UI   │                    │  ├─ GPT API               │
│   • 启动/停止按钮    │                    │  └─ 本地模型 (Ollama 等)    │
│   • 任务输入框       │                    │                            │
│   • 执行日志         │                    ├────────────────────────────┤
│                     │                    │                            │
└─────────────────────┘                    │  Skill Repository          │
                                           │  ├─ 内置技能 (OA 审批等)    │
                                           │  ├─ 用户自定义技能          │
                                           │  └─ 签名校验 + 版本管理     │
                                           │                            │
                                           └────────────────────────────┘
```

---

## 2. 技术选型决策记录

### 2.1 基底框架选型: ZeroClaw

在确定 sgClaw 的 Agent Runtime 底座时，团队对 Rust 生态中主流 Agent 框架进行了系统评估。
评估维度包括：社区活跃度、内存占用、可嵌入性（是否支持替换浏览器控制层）、以及与我们
STDIO Pipe 架构的兼容性。

| Framework  | Language | Stars | Runtime Memory | Embeddability        | Browser Layer Replaceable | 备注                      |
|------------|----------|-------|----------------|----------------------|---------------------------|---------------------------|
| **ZeroClaw** | Rust   | 17K   | ~5 MB          | High (trait-driven)  | **Best**                  | 活跃社区，trait 抽象完善    |
| Rig        | Rust     | 6.2K  | Minimal        | Best (cargo add)     | Full custom               | 轻量但 Agent loop 需自建   |
| Moltis     | Rust     | -     | ~40 MB         | Medium               | Via MCP only              | 内存偏高，嵌入需改造       |
| OpenFang   | Rust     | New   | ~40 MB         | Low (API only)       | Difficult                 | API Server 架构，不适合嵌入 |
| MicroClaw  | Rust     | 152   | -              | Low (fork needed)    | Via MCP only              | 社区不活跃，需 fork 维护    |

**决策：ZeroClaw**

核心理由：

1. **trait-driven 架构**：ZeroClaw 将 Tool、Provider、Memory、Security 全部定义为 trait，
   允许我们用自定义的 `BrowserPipeTool` 替换默认的浏览器控制层（如 Playwright/Puppeteer），
   同时复用其 Agent Runtime、Provider 抽象、Memory 系统和安全模块。

2. **内存优势**：~5 MB 的运行时内存占用，在 8 GB 总内存预算内几乎可以忽略不计。
   相比 Moltis/OpenFang 的 ~40 MB，差异显著。

3. **ReAct Loop 成熟**：ZeroClaw 内置 think → act → observe 循环，支持 streaming、
   multi-turn、tool-use，无需从零构建。

4. **MCP 生态兼容**：内置 rmcp client，可在需要时连接外部 MCP Server 扩展工具集。

### 2.2 通信协议选型: STDIO Pipe

sgClaw (Rust) 与 SuperRPA Browser (C++) 之间的 IPC 通道是整个架构的关键路径。
团队评估了四种 IPC 机制：

| 方式             | Linux 支持   | Windows 支持         | 安全性                          | 多连接支持 | 延迟      |
|------------------|-------------|---------------------|---------------------------------|-----------|----------|
| **STDIO Pipe**   | fd inherit  | HANDLE inherit      | **最高** (进程私有，无法外部连接) | 否        | ~0.1 ms  |
| Unix Domain Socket| /tmp/sock  | 不支持              | 高 (文件权限控制)                | 是        | ~0.2 ms  |
| Named Pipe       | 不支持      | \\\\.\pipe\          | 高 (DACL)                       | 是        | ~0.2 ms  |
| TCP localhost    | 支持        | 支持                | **低** (任意进程可连)            | 是        | ~0.5 ms  |

**决策：STDIO Pipe**

核心理由：

1. **安全性最高**：STDIO Pipe 是进程私有的文件描述符（Linux）或句柄（Windows），
   只有父子进程间可以访问。本机其他进程无法连接、监听或注入命令。
   这从物理层面杜绝了 Pipe Hijack 攻击。

2. **跨平台统一**：Chromium 的 `base::LaunchProcess` 已经抽象了跨平台的管道创建，
   Linux 使用 `pipe()` + `fork()`/`exec()`，Windows 使用 `CreatePipe()` + `CreateProcess()`。
   我们不需要编写任何平台特定代码。

3. **单连接足够**：sgClaw 是 Browser 的唯一 Rust 子进程，一条 STDIO Pipe 即可满足
   全部双向通信需求。不需要多客户端并发连接的能力。

4. **延迟最低**：内核态 pipe buffer（Linux 默认 64 KB）的读写延迟约 0.1 ms，
   远低于 socket 方案。

### 2.3 Why Rust

为什么 sgClaw 选择 Rust 而非 C++/Python/Node.js：

1. **内存安全无 GC**：在 8 GB 总内存限制下，GC 语言的内存开销和暂停不可接受。
   Rust 的零成本抽象确保 ~5 MB 运行时内存，无 GC 停顿。

2. **跨平台编译**：目标平台包括 Linux 银河麒麟 V10 SP1 (x86_64) 和 Windows 10/11。
   Rust 的 cross-compilation 工具链 (`cross`, `cargo-zigbuild`) 可直接生成两个平台的二进制。

3. **极小二进制体积**：release 构建约 8.8 MB（含 LLM provider、memory、MCP client 全部功能），
   Windows 约 9 MB。无需额外运行时依赖。

4. **冷启动极快**：< 10 ms 内完成进程初始化和 pipe handshake，用户点击"启动"后几乎无感。

5. **ZeroClaw 生态**：ZeroClaw 本身及其核心依赖（rmcp、tokenizers 等）均为 Rust 实现，
   选择 Rust 可直接复用，无需 FFI 桥接。

---

## 3. 进程模型与生命周期

### 3.1 进程层次结构

sgClaw 嵌入 SuperRPA 浏览器的既有进程树中，作为 Chrome 主进程的子进程存在。

```
superrpa-chromium.sh (wrapper, PID 1001)
  │
  ├─ watchdog (PID 1002, background, 守护进程)
  │   └─ node local_service (PID 1003, HTTP API)
  │       ├─ 监听 127.0.0.1:9527
  │       ├─ 文件上传/下载
  │       └─ 与浏览器通过 HTTP 通信
  │
  └─ chrome (PID 1004, foreground, 用户交互主进程)
       │
       │  当用户在 Side Panel 点击 [启动] 按钮时：
       │  SgClawProcessHost::Start() 被调用
       │
       └─ sgclaw (PID 1005, child of chrome)
            │
            ├─ stdin  ← chrome stdout (接收命令响应/事件)
            ├─ stdout → chrome stdin  (发送命令请求)
            │
            ├─ Agent Runtime (ReAct loop)
            ├─ LLM Provider (网络出口)
            └─ Memory (SQLite 文件 I/O)
```

关键特征：

- sgclaw 是 chrome 的**直接子进程**，继承 chrome 的 UID/GID 权限
- STDIO Pipe 的文件描述符在 `fork()`/`exec()` 时自动继承，无需额外传递
- 当 chrome 进程退出时，sgclaw 会收到 SIGPIPE/EOF，自行退出
- watchdog 和 local_service 与 sgclaw **无直接通信**，完全独立

### 3.2 生命周期状态机

```
                    ┌──────────────────────────────────┐
                    │    Side Panel UI: [启动] 按钮     │
                    └──────────────┬───────────────────┘
                                   │ 用户点击
                                   ▼
                    ┌──────────────────────────────────┐
                    │  SgClawProcessHost::Start()       │
                    │                                   │
                    │  1. Check: sgclaw 二进制存在?      │
                    │     → 不存在: 报错，终止           │
                    │                                   │
                    │  2. Check: 是否已有实例运行?       │
                    │     → 已运行: 直接返回             │
                    │                                   │
                    │  3. 创建 pipe pair (读端+写端)     │
                    │                                   │
                    │  4. base::LaunchProcess(           │
                    │       "sgclaw", pipe_opts)         │
                    │                                   │
                    │  5. 启动 PipeReader async loop     │
                    │                                   │
                    │  6. 发送 handshake:                │
                    │     {"type":"init","version":"1.0"}│
                    │                                   │
                    │  7. 等待 sgClaw ack (超时 5s)      │
                    │     → 超时: Kill + 报错            │
                    │                                   │
                    │  8. Notify UI: Running             │
                    └──────────────┬───────────────────┘
                                   │
                    ┌──────────────┴───────────────────┐
                    │         Running (正常运行)         │
                    │                                   │
                    │  • PipeReader 持续监听响应         │
                    │  • Agent Runtime 接受用户任务      │
                    │  • 命令经 pipe 发往 Browser        │
                    └──────┬──────────┬──────────┬─────┘
                           │          │          │
                     用户点击       浏览器      sgClaw
                     [停止]        正常退出     异常崩溃
                           │          │          │
                           ▼          ▼          ▼
                    ┌──────────┐ ┌─────────┐ ┌──────────────────┐
                    │ Stop()   │ │Shutdown()│ │ OnProcessCrash() │
                    │          │ │          │ │                  │
                    │ 发送     │ │ 发送     │ │ 1. 记录崩溃日志   │
                    │ shutdown │ │ SIGTERM  │ │ 2. 收集 stderr   │
                    │ 命令     │ │ + 等待   │ │ 3. 通知 UI 异常   │
                    │ 等待退出  │ │ 2s 超时  │ │ 4. 关闭 pipe     │
                    │ Kill     │ │ SIGKILL  │ │                  │
                    └────┬─────┘ └────┬────┘ │ *** 不自动重启 ***│
                         │            │      └────────┬─────────┘
                         ▼            ▼               ▼
                    ┌──────────────────────────────────┐
                    │         Stopped (已停止)          │
                    │                                   │
                    │  • Pipe 已关闭                    │
                    │  • 子进程已退出                    │
                    │  • UI 显示 [启动] 按钮            │
                    │  • 用户可再次点击启动              │
                    └──────────────────────────────────┘
```

**关键决策：崩溃不自动重启**

当 sgclaw 进程崩溃时（如 panic、OOM、非零退出码），系统**不会**自动重启。
用户必须显式点击 [启动] 按钮才能再次启动。理由：

- 防止恶意 prompt injection 导致的无限崩溃重启循环
- 防止异常状态下的资源耗尽（内存泄漏累积、日志磁盘写满）
- 给用户明确的故障感知，而非静默恢复后行为异常

### 3.3 内存预算 (8 GB 约束)

目标部署环境为 8 GB 内存的银河麒麟工作站。以下是各组件的内存分配：

```
┌───────────────────────────────────┬────────────┬──────────┐
│ 组件                              │ 内存占用    │ 备注      │
├───────────────────────────────────┼────────────┼──────────┤
│ OS + Desktop (银河麒麟 V10)        │ ~2.0 GB    │ 固定开销  │
│ Browser Process (主进程)           │ ~0.2 GB    │ 已有      │
│ Foreground Tabs (1-3 tabs)        │ ~0.3-0.9 GB│ 用户页面  │
│ Side Panel (Agent UI)             │ ~0.05 GB   │ Vue SPA   │
│ Zombie Page Pool (max 5)          │ ~0.15-0.25 GB│ 后台会话 │
│ local_service (Node.js)           │ ~0.1 GB    │ 已有      │
│ sgClaw (Rust binary)              │ ~0.005 GB  │ 5 MB      │
│ LLM context cache (对话历史)       │ ~0.05 GB   │ 内存缓存  │
│ SQLite + vector memory            │ ~0.02 GB   │ 磁盘为主  │
├───────────────────────────────────┼────────────┼──────────┤
│ **Total**                         │ **~3.0-3.6 GB** │        │
│ **Headroom**                      │ **~4.4-5.0 GB** │ >50%  │
└───────────────────────────────────┴────────────┴──────────┘
```

sgClaw 的 ~5 MB 内存占用仅为总预算的 0.06%，对系统几乎零负担。
即使在极端场景下（3 个前台标签 + 5 个 zombie page + LLM 长对话），
总内存使用也不超过 4 GB，保留超过 50% 的余量供操作系统和突发需求使用。

---

## 4. 安全架构

### 4.1 三层纵深防御模型

sgClaw 的安全架构采用纵深防御（Defense in Depth）策略，从内到外设置三道独立的安全层。
任何单一层被突破时，上层仍能有效阻止攻击。

```
┌─────────────────────────────────────────────────────────────────────────┐
│                                                                         │
│    Layer 3: 浏览器内核层 (C++ Browser Process)                           │
│    最后一道防线 —— 不信任外部一切输入                                      │
│                                                                         │
│    ┌─ MAC 强制访问控制 ───────────────────────────────────────────┐      │
│    │                                                              │      │
│    │  • 域白名单: 仅 rules.json 中配置的域允许特权操作             │      │
│    │    → 未知域的 click/type 等操作直接拒绝                       │      │
│    │                                                              │      │
│    │  • Action 白名单: pipe 来源命令受限于安全子集                 │      │
│    │    → eval、executeJsInPage 等危险操作禁止通过 pipe 调用       │      │
│    │                                                              │      │
│    │  • 凭证隔离: credential_store 数据永不通过 pipe 暴露          │      │
│    │    → 登录操作由 SessionManager 内部完成                       │      │
│    │                                                              │      │
│    │  • 速率限制: 单域每秒最多 N 次特权操作 (可配置，默认 10)      │      │
│    │    → 超限后暂停该域操作 30 秒                                 │      │
│    │                                                              │      │
│    └──────────────────────────────────────────────────────────────┘      │
│                                                                         │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│    Layer 2: Rust 中枢层 (sgClaw Agent)                                  │
│    核心原则 —— 不信任 LLM 输出                                           │
│                                                                         │
│    ┌─ 命令校验沙箱 ──────────────────────────────────────────────┐      │
│    │                                                              │      │
│    │  • JSON Schema 严格校验: LLM 输出必须符合预定义的命令格式     │      │
│    │    → 非法字段、类型错误、缺失必要参数均被拒绝                  │      │
│    │                                                              │      │
│    │  • 禁止危险命令: LLM 不可生成 eval / executeJsInPage 类命令  │      │
│    │    → BrowserPipeTool 的 action 枚举中不包含这些操作           │      │
│    │                                                              │      │
│    │  • Human-in-the-loop: 敏感操作弹窗确认                       │      │
│    │    → sessionLogin / sessionLogout / 大批量操作               │      │
│    │                                                              │      │
│    │  • 序列号 + HMAC: 每条 pipe 消息携带递增 sequence_id          │      │
│    │    → 防止消息重放和篡改                                       │      │
│    │                                                              │      │
│    │  • 熔断器 (Circuit Breaker): 连续失败 N 次自动停止 Agent     │      │
│    │    → 默认阈值 10 次，指数退避冷却                             │      │
│    │                                                              │      │
│    └──────────────────────────────────────────────────────────────┘      │
│                                                                         │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│    Layer 1: 管道传输层 (STDIO Pipe)                                     │
│    物理隔离 —— 传输通道本身不可被第三方访问                               │
│                                                                         │
│    ┌─ 安全通道 ──────────────────────────────────────────────────┐      │
│    │                                                              │      │
│    │  • STDIO Pipe: 进程私有 fd/HANDLE，无法被外部进程连接        │      │
│    │    → 不经过文件系统、不绑定端口、不暴露地址                    │      │
│    │                                                              │      │
│    │  • Handshake 校验: 启动时双向版本握手                        │      │
│    │    → 版本不匹配则立即断开                                     │      │
│    │                                                              │      │
│    │  • 递增 sequence_id: 所有消息附带全局递增序列号               │      │
│    │    → 检测到乱序或重复即报警并断开                              │      │
│    │                                                              │      │
│    │  • 格式约束: JSON Line 格式，单消息最大 1 MB                 │      │
│    │    → 超大消息直接丢弃，防止内存 DoS                           │      │
│    │                                                              │      │
│    └──────────────────────────────────────────────────────────────┘      │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

### 4.2 各层防御详解

**Layer 1 — 管道传输层**

本层的设计目标是确保 sgClaw 与 Browser 之间的通信通道从物理层面不可被第三方窃听或注入。

防御对象：
- 本机恶意进程尝试连接或嗅探 IPC 通道
- 中间人攻击（消息篡改、注入伪造命令）
- 消息重放（录制合法命令序列后重新发送）

实现机制：
- STDIO Pipe 使用操作系统内核的匿名管道，文件描述符仅在父子进程间继承，
  `/proc/[pid]/fd/` 对其他用户不可见（取决于 procfs 挂载选项，银河麒麟默认安全）
- 启动时的 handshake 消息包含协议版本号，防止二进制版本不匹配导致的解析错误
- 每条消息的 `sequence_id` 全局递增，接收方校验连续性，检测到跳号或重复立即断开 pipe

**Layer 2 — Rust 中枢层**

本层的核心假设是 **LLM 的输出不可信**。无论是 prompt injection 还是 hallucination，
LLM 可能生成任何格式、任何内容的输出。sgClaw 必须在将命令发往 Browser 之前进行严格校验。

防御对象：
- Prompt injection：恶意网页内容被 LLM 读取后，诱导其生成危险操作
- Hallucination：LLM 生成不存在的 action 或格式错误的参数
- 无限循环：LLM 陷入 retry 死循环，持续消耗资源

实现机制：
- `BrowserPipeTool` 定义了一个封闭的 action 枚举（enum），LLM 只能选择预定义的安全操作
- 每个 action 都有对应的 JSON Schema，参数类型、范围、必填项均有严格约束
- Critic 模块在 Agent 每步 observe 后评估输出质量，异常时触发终止
- Circuit Breaker 在连续 10 次操作失败后自动停止 Agent loop，需用户手动恢复
- 敏感操作（涉及登录、批量删除等）通过 Side Panel UI 弹窗请求用户确认

**Layer 3 — 浏览器内核层**

本层是安全架构的最后防线。即使 sgClaw 的 Rust 层被完全绕过（理论上几乎不可能），
Browser 的 C++ 代码仍会独立执行 MAC 检查。

防御对象：
- 已突破 Layer 2 的命令（假设 sgClaw 被完全控制）
- 未授权域上的操作（sgClaw 试图操作不在白名单中的网站）
- 凭证窃取（任何试图通过 pipe 读取存储密码的操作）

实现机制：
- `rules.json` 白名单由管理员配置，列出允许 Agent 操作的域名（如 `oa.example.com`）
- 每条 pipe 命令到达 Browser 后，先校验 `expected_domain` 是否与当前页面的实际域名一致
- `credential_store`（Linux Keyring / Windows Credential Manager）的 API 在 pipe handler 中
  没有任何暴露点——登录凭证只能由 SessionManager 在 Browser 内部使用
- 速率限制器独立于 sgClaw 的 Circuit Breaker，即使后者被禁用，Browser 侧的限速仍然生效

---

## 5. 威胁模型与对抗策略

### 5.1 威胁分类总表

| #  | 威胁名称                 | 描述                                           | 影响                        | 防御层          | 对抗策略                                                |
|----|------------------------|------------------------------------------------|----------------------------|-----------------|---------------------------------------------------------|
| T1 | Pipe Hijack            | 本机攻击者劫持 STDIO Pipe                        | 完全控制浏览器操作           | Layer 1         | STDIO 进程私有；fd 不经过文件系统；procfs 受限            |
| T2 | LLM Prompt Injection   | 恶意页面内容注入 LLM prompt                      | 执行未授权操作              | Layer 2         | JSON Schema 校验；Action 枚举白名单；禁止 eval           |
| T3 | Skill Poisoning        | 注入恶意 Skill 脚本                              | 持久化后门                  | Layer 2 + 3     | Skill 签名校验；沙箱执行；MAC 域名限制                    |
| T4 | Credential Leakage     | 通过 pipe 读取浏览器存储的密码                    | 账户泄露                    | Layer 3         | credential_store API 不暴露给 pipe；凭证仅内部使用        |
| T5 | Replay Attack          | 录制合法命令后重放                                | 重复执行敏感操作            | Layer 2         | sequence_id 递增校验 + HMAC 签名                         |
| T6 | Retry Storm            | LLM 无限重试导致资源耗尽                          | CPU/内存/网络耗尽            | Layer 2         | Circuit Breaker (阈值 10)；指数退避；最大重试限制         |

### 5.2 各威胁详细分析

**T1: Pipe Hijack（管道劫持）**

攻击路径：同一台机器上的恶意进程尝试读取/写入 sgClaw 与 Browser 之间的 STDIO Pipe。

分析：STDIO Pipe 基于操作系统匿名管道实现，没有文件系统路径，没有网络端口。
攻击者需要获取目标进程的 fd（Linux）或 HANDLE（Windows），这在标准安全配置下
需要 root 权限或 `ptrace` 能力。银河麒麟 V10 默认启用 `kernel.yama.ptrace_scope=1`，
非父进程无法 ptrace。

残余风险：root 用户可以访问任何进程的 fd。但在本部署场景中，root 被视为可信实体。

**T2: LLM Prompt Injection（提示注入）**

攻击路径：用户访问的恶意网页中包含精心构造的文本，当 sgClaw 读取页面内容并发送给 LLM 时，
这些文本被 LLM 误解为指令，导致 Agent 执行非预期操作。

分析：这是 AI Agent 面临的最常见威胁。sgClaw 的防御不依赖于 LLM 本身的抗注入能力
（这是不可靠的），而是在 Rust 层进行硬编码限制：
- LLM 只能输出预定义的 action 枚举值，任何不在枚举中的操作被直接拒绝
- 最危险的 `eval`、`executeJsInPage` 不在枚举中，从根本上不可能被 LLM 触发
- `expected_domain` 字段要求 LLM 明确声明目标域名，Browser 侧校验实际域名是否匹配

**T3: Skill Poisoning（技能投毒）**

攻击路径：攻击者将恶意 JavaScript Skill 注入到 Skill Repository 中，
当 sgClaw 加载该 Skill 时执行恶意代码。

分析：Skill 文件在加载前经过以下校验链：
1. 签名校验：每个 Skill 文件必须附带由构建系统生成的数字签名
2. 沙箱执行：Skill 代码在受限的 JavaScript 沙箱中运行，无法访问文件系统或网络
3. MAC 限制：即使 Skill 生成了恶意命令，Browser 侧的域白名单仍会阻止未授权操作

**T4: Credential Leakage（凭证泄漏）**

攻击路径：通过 pipe 发送特制命令，尝试读取 Browser 中存储的登录密码。

分析：`credential_store` 使用 Linux Keyring（银河麒麟）或 Windows Credential Manager
存储加密凭证。其 C++ API 仅在 `SessionManager::DoLogin()` 内部调用，
没有任何 CommandRouter action 会暴露凭证数据。pipe handler 的代码路径中
完全不存在读取凭证的逻辑。

**T5: Replay Attack（重放攻击）**

攻击路径：攻击者（假设已突破 Layer 1）录制合法的 pipe 命令序列，稍后重放。

分析：每条消息携带递增的 `sequence_id` 和基于共享密钥的 HMAC。
接收方维护已处理的最大 sequence_id，拒绝任何小于或等于该值的消息。
HMAC 密钥在每次 sgclaw 启动时通过 handshake 动态协商，重启后旧命令的 HMAC 无效。

**T6: Retry Storm（重试风暴）**

攻击路径：LLM 因 hallucination 或 prompt injection 陷入无限循环，
持续生成失败命令并重试。

分析：sgClaw 内置两级防护：
1. Agent Runtime 层：单次任务最大步数限制（默认 50 步），超出自动终止
2. Circuit Breaker：连续 10 次操作失败后，断路器打开，停止所有 pipe 通信，
   需要用户手动恢复。冷却期间采用指数退避（1s → 2s → 4s → ... → 30s max）

---

## 6. 通信架构

### 6.1 Pipe 协议概览

sgClaw 与 Browser 之间使用 JSON Line 格式通过 STDIO Pipe 通信。
每条消息占一行（以 `\n` 结尾），单消息最大 1 MB。

**消息类型一览：**

```
sgClaw → Browser:
  ├─ command  (请求执行浏览器操作)
  └─ ack      (确认收到事件)

Browser → sgClaw:
  ├─ response (命令执行结果)
  ├─ event    (主动推送的页面事件)
  └─ init_ack (handshake 响应)
```

**Request 格式（sgClaw → Browser）：**

```json
{
  "seq": 1,
  "type": "command",
  "action": "click",
  "params": {
    "selector": "#submit-btn",
    "wait_after": 1000
  },
  "security": {
    "expected_domain": "oa.example.com",
    "hmac": "a3f8c2..."
  }
}
```

字段说明：
- `seq`: 递增序列号，全局唯一，用于匹配 response 和防重放
- `type`: 消息类型，`command` 表示操作请求
- `action`: 操作名称，必须在允许列表中
- `params`: 操作参数，每个 action 有独立的 JSON Schema
- `security.expected_domain`: 期望的目标域名，Browser 侧校验
- `security.hmac`: 消息完整性签名

**Response 格式（Browser → sgClaw）：**

```json
{
  "seq": 1,
  "type": "response",
  "success": true,
  "data": {
    "clicked": true,
    "element_text": "提交"
  },
  "aom_snapshot": [
    {"role": "button", "name": "提交", "bounds": [100, 200, 80, 30]}
  ],
  "timing": {
    "queue_ms": 2,
    "exec_ms": 45
  }
}
```

字段说明：
- `seq`: 与请求对应的序列号
- `success`: 操作是否成功
- `data`: 操作结果数据，格式因 action 而异
- `aom_snapshot`: 操作后的 AOM（Accessibility Object Model）快照，
  供 Agent 的 observe 阶段使用，理解页面当前状态
- `timing`: 性能计时信息

**Event 格式（Browser → sgClaw，主动推送）：**

```json
{
  "type": "event",
  "event": "page_navigated",
  "data": {
    "url": "https://oa.example.com/approval/list",
    "title": "审批列表 - OA系统",
    "domain": "oa.example.com"
  },
  "timestamp": 1709452800000
}
```

支持的事件类型：
- `page_navigated`: 页面导航完成
- `page_loaded`: 页面 DOMContentLoaded
- `dialog_appeared`: 浏览器对话框弹出（alert/confirm/prompt）
- `session_expired`: SessionManager 检测到会话过期
- `zombie_ready`: Zombie page 初始化完成

### 6.2 与 CommandRouter 的对接

sgClaw 的命令最终汇入 SuperRPA 已有的 CommandRouter，这是一个统一的命令分发器，
支持 40+ 种浏览器操作。sgClaw 作为新增的命令来源，与已有的 JS SDK 并行存在。

**sgClaw Pipe 路径（新增）：**

```
sgClaw (Rust)
  │
  │  JSON Line over STDIO Pipe
  │
  ▼
SgClawProcessHost (C++, Browser Process)
  │
  ▼
PipeListener (async read, parse JSON)
  │
  ├─── MAC Whitelist Check ─────────────────────────────┐
  │     │                                                │
  │     ├─ action in allowed_pipe_actions?               │
  │     │   → No: reject with error response             │
  │     │                                                │
  │     ├─ expected_domain matches current page?         │
  │     │   → No: reject with domain_mismatch error      │
  │     │                                                │
  │     └─ rate limit not exceeded?                      │
  │         → Exceeded: reject with rate_limit error     │
  │                                                      │
  ▼                                                      │
CommandRouter (Existing, 40+ actions) ◄──────────────────┘
  │
  ├───────────┬──────────────┬──────────────┐
  ▼           ▼              ▼              ▼
CdpCommand  ZombiePage    Session      RpaGlobal
Executor    Manager       Manager      Storage
  │
  ▼
Page DOM Operations (click, type, getText, etc.)
```

**已有 JS SDK 路径（不变）：**

```
页面内 JavaScript
  │
  │  CDP binding (chrome.runtime.sendMessage)
  │
  ▼
CdpBridgeManager (C++, Renderer → Browser IPC)
  │
  ▼
CommandRouter (Same instance!) ◄── 同一个 CommandRouter
  │
  ├───────────┬──────────────┬──────────────┐
  ▼           ▼              ▼              ▼
CdpCommand  ZombiePage    Session      RpaGlobal
Executor    Manager       Manager      Storage
```

两条路径汇聚于同一个 CommandRouter 实例。sgClaw 只是新增了一个命令来源，
不改变 CommandRouter 的任何现有逻辑。区别仅在于：

- JS SDK 路径：无 MAC whitelist check（页面 JS 已通过 CSP 和 rules.json 限制）
- Pipe 路径：增加 MAC whitelist check（因为 sgClaw 被视为外部进程，需额外校验）

### 6.3 Pipe 允许的 Action 子集

并非所有 CommandRouter 支持的 40+ 个 action 都允许通过 pipe 调用。
出于安全考虑，pipe 来源的命令被限制在以下安全子集中：

**允许通过 Pipe 调用（无需确认）：**

| Action           | 描述                | 备注                           |
|------------------|--------------------|---------------------------------|
| click            | 点击元素            | 需 expected_domain 匹配         |
| type             | 输入文本            | 需 expected_domain 匹配         |
| navigate         | 导航到 URL          | URL 必须在域白名单内             |
| getText          | 获取元素文本        | 只读操作，安全                   |
| getHtml          | 获取元素 HTML       | 只读操作，安全                   |
| waitForSelector  | 等待元素出现        | 只读操作，安全                   |
| pageScreenshot   | 页面截图            | 返回 base64，用于 Agent observe  |
| storageSet       | 写 RpaGlobalStorage | key 前缀限制为 sgclaw.*          |
| storageGet       | 读 RpaGlobalStorage | key 前缀限制为 sgclaw.*          |
| zombieSpawn      | 创建 zombie page    | 受池大小限制（max 5）            |
| zombieKill       | 销毁 zombie page    | 只能销毁自己创建的 zombie        |
| select           | 下拉框选择          | 需 expected_domain 匹配         |
| scrollTo         | 滚动页面            | 需 expected_domain 匹配         |
| getAomSnapshot   | 获取 AOM 快照       | 只读操作，核心 observe 能力      |

**禁止通过 Pipe 调用（硬编码拒绝）：**

| Action             | 描述                | 禁止原因                                     |
|--------------------|--------------------|--------------------------------------------|
| eval               | 执行任意 JS         | 最高危操作，可绕过一切安全限制                 |
| executeJsInPage    | 在页面执行 JS       | 等同于 eval，prompt injection 核心攻击面       |
| registerJsFunction | 注册 JS 回调        | 可植入持久化代码                              |
| setRequestInterceptor | 拦截网络请求    | 可窃取请求中的 token/cookie                   |
| exportCookies      | 导出所有 cookie     | 可窃取会话凭证                                |

**需要用户确认的操作（Human-in-the-loop）：**

| Action           | 描述                | 确认原因                         |
|------------------|--------------------|---------------------------------|
| sessionLogin     | 执行登录流程        | 涉及凭证使用，需用户知情          |
| sessionLogout    | 登出会话            | 可能中断用户正在进行的工作        |
| clearStorage     | 清空存储            | 不可逆操作                       |

---

## 7. 跨平台策略

### 7.1 STDIO Pipe 跨平台实现

STDIO Pipe 的跨平台实现依赖 Chromium 已有的 `base::LaunchProcess` 抽象层，
sgClaw 团队无需编写平台特定的管道代码。

**Linux 实现路径：**

```
Browser Process (C++)                        sgClaw (Rust)
─────────────────────                        ─────────────
1. pipe(fds)  → fds[0](读), fds[1](写)
2. pipe(fds2) → fds2[0](读), fds2[1](写)
3. fork()
4. 子进程:
   dup2(fds[0], STDIN_FILENO)
   dup2(fds2[1], STDOUT_FILENO)
   exec("sgclaw")  ──────────────────→       main()
5. 父进程:                                     std::io::stdin()  → 读取命令
   write(fds[1], ...)  ──────────────→         std::io::stdout() → 写回响应
   read(fds2[0], ...)  ◄────────────           BufReader + BufWriter
```

Chromium 的 `base::LaunchProcess` 封装了上述 `pipe()` + `fork()` + `exec()` 流程，
通过 `LaunchOptions::fds_to_remap` 配置 fd 映射。

**Windows 实现路径：**

```
Browser Process (C++)                        sgClaw (Rust)
─────────────────────                        ─────────────
1. CreatePipe(&hRead1, &hWrite1, ...)
2. CreatePipe(&hRead2, &hWrite2, ...)
3. SetHandleInformation(hRead1, INHERIT)
4. SetHandleInformation(hWrite2, INHERIT)
5. CreateProcess("sgclaw.exe",
     STARTUPINFO {
       hStdInput  = hRead1,                  main()
       hStdOutput = hWrite2                    std::io::stdin()  → ReadFile
     })                                        std::io::stdout() → WriteFile
6. WriteFile(hWrite1, ...) ──────────→
   ReadFile(hRead2, ...)   ◄────────
```

Chromium 的 `base::LaunchProcess` 在 Windows 下使用 `CreateProcess` + `STARTUPINFO`
实现句柄继承，与 Linux 的 fd 继承语义一致。

**Rust 侧统一代码：**

无论 Linux 还是 Windows，sgclaw 的 Rust 代码完全一致：

```rust
// sgclaw 端无需区分平台
let reader = BufReader::new(std::io::stdin());
let writer = BufWriter::new(std::io::stdout());

for line in reader.lines() {
    let msg: PipeMessage = serde_json::from_str(&line?)?;
    let response = handle_message(msg).await?;
    writeln!(writer, "{}", serde_json::to_string(&response)?)?;
    writer.flush()?;
}
```

### 7.2 目标平台

| 平台      | 操作系统                  | CPU 架构  | 状态             | 备注                         |
|-----------|--------------------------|----------|------------------|-----------------------------|
| Primary   | 银河麒麟 V10 SP1          | x86_64   | 目标部署环境      | 政企客户主要使用平台           |
| Secondary | Windows 10 / 11          | x86_64   | 开发 + 部分部署   | 开发团队日常使用 + 部分客户    |
| Future    | 银河麒麟 V10 SP1          | aarch64  | 规划中           | 国产 ARM 服务器/终端          |

**银河麒麟 V10 SP1 特殊注意事项：**

- 基于 Ubuntu 内核，但定制了安全策略（SELinux/AppArmor 变体）
- `procfs` 默认配置限制跨进程 fd 访问，有利于 Pipe Hijack 防御
- `kernel.yama.ptrace_scope=1`，非父进程无法 ptrace，增强安全性
- glibc 版本需确认兼容（通常 >= 2.31），Rust musl 静态链接可规避

### 7.3 sgClaw 二进制分发

sgClaw 编译为单一静态链接的 Rust 二进制，无外部运行时依赖。

```
sgclaw 二进制产物
├─ Linux:   sgclaw      (~8.8 MB, musl 静态链接, strip)
│           target: x86_64-unknown-linux-musl
│           无 glibc 依赖，银河麒麟直接运行
│
└─ Windows: sgclaw.exe  (~9.0 MB, MSVC 链接, strip)
            target: x86_64-pc-windows-msvc
            无额外 DLL 依赖
```

构建命令：

```bash
# Linux (musl 静态链接，确保银河麒麟兼容)
cargo build --release --target x86_64-unknown-linux-musl
strip target/x86_64-unknown-linux-musl/release/sgclaw

# Windows (交叉编译)
cargo build --release --target x86_64-pc-windows-msvc
```

部署方式：将 `sgclaw` / `sgclaw.exe` 放置在 SuperRPA 浏览器安装目录下：

```
superrpa-browser/
├─ chrome                    (浏览器主程序)
├─ superrpa-chromium.sh      (启动脚本)
├─ sgclaw                    (AI Agent, 新增)
├─ sgclaw-skills/            (技能目录, 新增)
│   ├─ oa-approval.js
│   └─ ...
└─ resources/
    └─ rules.json            (域白名单, 已有)
```

---

## 8. 与 SuperRPA 已有子系统的关系

### 8.1 复用与新增总览

sgClaw 的核心设计原则之一是**最小侵入**——最大限度复用 SuperRPA 浏览器的已有基础设施，
将新增代码量控制在最低水平。

```
┌─────────────────────────────────────────────────────────────────────┐
│                    SuperRPA Browser 已有子系统                       │
│                    (全部保持不变，零修改)                              │
│                                                                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                 │
│  │ Command     │  │ CdpBridge   │  │ ZombiePage  │                 │
│  │ Router      │  │ Manager     │  │ Manager     │                 │
│  │ (40+ acts)  │  │ (JS SDK)    │  │ (5 pools)   │                 │
│  └──────┬──────┘  └─────────────┘  └─────────────┘                 │
│         │                                                           │
│  ┌──────┴──────┐  ┌─────────────┐  ┌─────────────┐                 │
│  │ CdpCommand  │  │ Session     │  │ RpaGlobal   │                 │
│  │ Executor    │  │ Manager     │  │ Storage     │                 │
│  │             │  │ (状态机)     │  │ (KV store)  │                 │
│  └─────────────┘  └─────────────┘  └─────────────┘                 │
│                                                                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                 │
│  │ credential  │  │ rules.json  │  │ BrowserAction│                 │
│  │ _store      │  │ (URL白名单) │  │ API         │                 │
│  │ (Keyring)   │  │             │  │ (JS 调度)    │                 │
│  └─────────────┘  └─────────────┘  └─────────────┘                 │
│                                                                     │
├─────────────────────────────────────────────────────────────────────┤
│                    sgClaw 新增组件                                   │
│                    (~500 lines C++ in Browser + Rust binary)        │
│                                                                     │
│  ┌─────────────────────────────────────────────────────┐            │
│  │ SgClawProcessHost (C++, ~200-300 lines)             │            │
│  │ ├─ 进程生命周期管理 (Start / Stop / OnCrash)        │            │
│  │ ├─ PipeListener (~150 lines, async read loop)       │            │
│  │ ├─ MAC Whitelist Check (~100 lines)                 │            │
│  │ └─ FunctionsUI handlers for start/stop (~50 lines)  │            │
│  └─────────────────────────────────────────────────────┘            │
│                                                                     │
│  ┌─────────────────────────────────────────────────────┐            │
│  │ Side Panel UI Controls (Vue, ~100 lines)            │            │
│  │ ├─ [启动] / [停止] 按钮                              │            │
│  │ ├─ 状态指示 (Running / Stopped / Error)             │            │
│  │ ├─ 任务输入框                                       │            │
│  │ └─ 执行日志 (streaming output)                      │            │
│  └─────────────────────────────────────────────────────┘            │
│                                                                     │
│  ┌─────────────────────────────────────────────────────┐            │
│  │ sgclaw Binary (Rust, based on ZeroClaw)             │            │
│  │ ├─ Agent Runtime (ReAct loop)                       │            │
│  │ ├─ BrowserPipeTool (custom Tool trait impl)         │            │
│  │ ├─ SkillLoader (JS business skills)                 │            │
│  │ ├─ LLM Provider (Claude / GPT / local)              │            │
│  │ ├─ Memory (SQLite + vector)                         │            │
│  │ ├─ MAC Policy (domain / action whitelist)           │            │
│  │ ├─ Critic + Circuit Breaker                         │            │
│  │ └─ MCP Client (rmcp)                               │            │
│  └─────────────────────────────────────────────────────┘            │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

### 8.2 复用子系统详细说明

| 子系统              | 代码位置              | sgClaw 如何复用                                    | 是否修改 |
|---------------------|----------------------|---------------------------------------------------|---------|
| CommandRouter       | browser/rpa/command/ | sgClaw 通过 pipe → PipeListener → CommandRouter    | 不修改   |
| CdpBridgeManager    | browser/rpa/cdp/     | 独立运行，JS SDK 路径不受影响                        | 不修改   |
| ZombiePageManager   | browser/rpa/zombie/  | sgClaw 通过 zombieSpawn/zombieKill action 使用     | 不修改   |
| SessionManager      | browser/rpa/session/ | sgClaw 可触发 sessionLogin (需确认)                 | 不修改   |
| RpaGlobalStorage    | browser/rpa/storage/ | sgClaw 通过 storageSet/storageGet 读写              | 不修改   |
| BrowserAction API   | browser/rpa/action/  | 已有 JS SDK 继续使用，与 sgClaw 独立                 | 不修改   |
| credential_store    | browser/rpa/cred/    | 仅 SessionManager 内部使用，sgClaw 无法访问          | 不修改   |
| rules.json          | resources/           | sgClaw 的 MAC Policy 也读取此文件进行域校验           | 不修改   |

### 8.3 新增代码量估算

| 组件                        | 语言   | 估计行数     | 位置                          |
|-----------------------------|--------|-------------|-------------------------------|
| SgClawProcessHost           | C++    | ~200-300    | browser/rpa/sgclaw/           |
| PipeListener                | C++    | ~150        | browser/rpa/sgclaw/           |
| MAC Whitelist Check (Pipe)  | C++    | ~100        | browser/rpa/sgclaw/           |
| FunctionsUI handlers        | C++    | ~50         | browser/rpa/functions_ui/     |
| Side Panel UI controls      | Vue    | ~100        | resources/side_panel/         |
| **Browser 侧合计**         |        | **~500-600**|                               |
| sgclaw binary               | Rust   | ~3000-5000  | 独立仓库 sgclaw/              |

### 8.4 影响评估

**对已有功能的影响：零。**

具体论证：

1. **CommandRouter 不变**：sgClaw 只是新增了一个命令来源（pipe），CommandRouter 本身的
   dispatch 逻辑、action 处理函数、错误处理均不修改。

2. **JS SDK 不变**：CdpBridgeManager 独立于 SgClawProcessHost，两者通过不同的 IPC 路径
   到达同一个 CommandRouter。JS SDK 的用户不会感知到 sgClaw 的存在。

3. **会话管理不变**：SessionManager 的状态机（login → active → expired → re-login）
   完全不变。sgClaw 只能通过 CommandRouter 触发 sessionLogin action（需用户确认），
   不直接操作 SessionManager 内部状态。

4. **存储隔离**：sgClaw 通过 RpaGlobalStorage 的 key 被限制在 `sgclaw.*` 命名空间下，
   不会与已有的 JS SDK 存储的 key 冲突。

5. **二进制独立**：sgclaw 是独立二进制，不链接 Chromium 的任何库。
   即使 sgclaw 构建失败或缺失，浏览器仍然正常工作——只是 Side Panel 的 [启动] 按钮
   会报错"sgclaw binary not found"。

---

*文档结束。本文档为 sgClaw L1 层架构设计参考，后续 L2（详细设计）、L3（实现规范）
将在此基础上展开。*