admin/skill-lib
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4d9b17f975369c39afb928818842a3e6040f6590
skill-lib/docs/L1-系统架构与安全模型层.md
zyl 4e32b3193f first commit
2026-03-06 03:36:12 +08:00

58 KiB
Raw Blame History

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）：

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

{
  "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，主动推送）：

{
  "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 代码完全一致：

// 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 依赖

构建命令：

# 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（实现规范） 将在此基础上展开。

Reference in New Issue View Git Blame Copy Permalink