# L2 — 核心模块与接口契约层

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

**读者**: 各组组长（Rust 组、浏览器 C++ 组、前端组）—— 需要理解模块边界、接口契约、依赖关系，指导各组并行开发。

---

## 1. 模块总览与依赖拓扑

### 1.1 全局模块图

sgClaw 系统由三个独立的代码域组成：Rust 端（sgclaw binary）、C++ 端（Browser Process 新增模块）、前端（Side Panel Vue 组件）。以下拓扑展示了所有模块及其依赖关系。

```
┌──────────────────────────────────────────────────────────────────────────┐
│                          sgClaw Rust Binary                              │
│                                                                          │
│  ┌──────────┐   ┌──────────────┐   ┌───────────┐   ┌────────────────┐  │
│  │  main.rs  │──→│ Agent Runtime│──→│  Critic   │   │  Config/       │  │
│  │  (入口)   │   │  (ReAct)     │   │  (评估器) │   │  Settings      │  │
│  └────┬─────┘   └──────┬───────┘   └─────┬─────┘   └────────────────┘  │
│       │                │                  │                              │
│       │         ┌──────┴───────┐   ┌──────┴──────┐                      │
│       │         │ BrowserPipe  │   │  Circuit    │                      │
│       │         │ Tool         │   │  Breaker    │                      │
│       │         │ (Tool trait) │   └─────────────┘                      │
│       │         └──────┬───────┘                                        │
│       │                │                                                │
│  ┌────┴─────┐   ┌──────┴───────┐   ┌───────────┐   ┌────────────────┐  │
│  │  Pipe    │   │  MAC Policy  │   │  Memory   │   │  LLM Provider  │  │
│  │ Protocol │   │  (安全策略)   │   │ (记忆层)  │   │  (模型适配)     │  │
│  └──────────┘   └──────────────┘   └───────────┘   └────────────────┘  │
│                                                                          │
│  ┌──────────────┐   ┌──────────────┐                                    │
│  │  SkillLoader │   │  MCP Client  │                                    │
│  │  (技能加载)   │   │  (rmcp)      │                                    │
│  └──────────────┘   └──────────────┘                                    │
│                                                                          │
└───────────────────────────────┬──────────────────────────────────────────┘
                                │ STDIO Pipe (JSON Line)
                                │
┌───────────────────────────────┴──────────────────────────────────────────┐
│                    SuperRPA Browser Process (C++ 新增)                    │
│                                                                          │
│  ┌─────────────────────────┐                                            │
│  │  SgClawProcessHost      │ Singleton, 进程生命周期管理                  │
│  │  ├─ PipeListener        │ 异步读取循环, 解析 JSON Line                │
│  │  ├─ MAC Whitelist Check │ action + domain 白名单校验                   │
│  │  └─→ CommandRouter      │ [Existing] 40+ actions, 零修改              │
│  └─────────────────────────┘                                            │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘
                                │ FunctionsUI IPC
                                │
┌───────────────────────────────┴──────────────────────────────────────────┐
│                    Side Panel (Vue 前端)                                  │
│                                                                          │
│  ┌─────────────────────────┐                                            │
│  │  AgentControlPanel.vue  │ 启停按钮 + 指令输入 + 状态显示 + 执行日志    │
│  └─────────────────────────┘                                            │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘
```

### 1.2 模块依赖矩阵

以下矩阵展示 Rust 端各模块之间的依赖关系（行依赖列）：

```
               Runtime  BrowserPipe  Protocol  MAC    Memory  LLM    Skill  Critic  MCP    Config
Runtime          -         ✓           -       -       ✓      ✓       ✓      ✓      ✓       ✓
BrowserPipe      -         -           ✓       ✓       -      -       -      -      -       -
Protocol         -         -           -       -       -      -       -      -      -       ✓
MAC Policy       -         -           -       -       -      -       -      -      -       ✓
Memory           -         -           -       -       -      -       -      -      -       ✓
LLM Provider     -         -           -       -       -      -       -      -      -       ✓
SkillLoader      -         -           -       -       -      -       -      -      -       ✓
Critic           -         -           -       -       ✓      -       -      -      -       ✓
MCP Client       -         -           -       -       -      -       -      -      -       ✓
Config           -         -           -       -       -      -       -      -      -       -
```

设计原则：
- **Config 是叶节点**：所有模块依赖 Config，Config 不依赖任何业务模块
- **Runtime 是根节点**：Agent Runtime 协调所有模块，是唯一的"上帝模块"
- **BrowserPipeTool 仅依赖 Protocol 和 MAC**：确保 Tool 实现的纯粹性
- **无循环依赖**：依赖图是 DAG（有向无环图）

### 1.3 并行开发分工

基于模块依赖关系，三个组可以并行开发：

| 组别 | 负责模块 | 依赖条件 | 可并行阶段 |
|------|---------|---------|-----------|
| **Rust 组** | Agent Runtime, BrowserPipeTool, Protocol, MAC Policy, Memory, LLM Provider, SkillLoader, Critic, MCP Client, Config | 无外部依赖，可先行 | 第一阶段即可开始 |
| **C++ 组** | SgClawProcessHost, PipeListener, MAC Whitelist Check | 需与 Rust 组对齐 Pipe 协议格式 | 协议 JSON Schema 确定后开始 |
| **前端组** | AgentControlPanel.vue | 需 C++ 组提供 FunctionsUI handler | C++ 组 handler 就绪后开始 |

---

## 2. sgClaw Rust 端模块详细设计

### 2.1 main.rs — 进程入口

**职责**：初始化 Pipe I/O、配置加载、tokio 异步运行时启动、模块组装、handshake 握手。

**启动序列**：

```
main()
  │
  ├── 1. 初始化 tracing (日志)
  │     └── 日志输出到 stderr (stdout 保留给 pipe)
  │
  ├── 2. 加载 Config
  │     ├── 默认值 (编译时内嵌)
  │     ├── 配置文件 (sgclaw.toml, 可选)
  │     └── 环境变量覆盖 (SGCLAW_*)
  │
  ├── 3. 初始化 tokio runtime
  │     └── multi_thread, worker_threads = 2
  │
  ├── 4. 创建 Pipe I/O
  │     ├── stdin  → BufReader (接收 Browser 消息)
  │     └── stdout → BufWriter (发送消息到 Browser)
  │
  ├── 5. Handshake
  │     ├── 等待 Browser 的 init 消息 (超时 5s)
  │     ├── 校验协议版本
  │     ├── 交换 HMAC 密钥种子
  │     └── 发送 init_ack 确认
  │
  ├── 6. 组装模块
  │     ├── MAC Policy  ← Config (rules 路径)
  │     ├── Protocol    ← Config (max_message_size)
  │     ├── BrowserPipeTool ← Protocol + MAC
  │     ├── LLM Provider ← Config (model, api_key)
  │     ├── Memory       ← Config (db_path)
  │     ├── SkillLoader  ← Config (skills_dir)
  │     ├── MCP Client   ← Config (mcp_servers)
  │     ├── Critic       ← Config (thresholds) + Memory
  │     └── Agent Runtime ← 以上全部
  │
  ├── 7. 启动 Agent 消息循环
  │     └── 监听 pipe 输入，分发到 Runtime
  │
  └── 8. 优雅退出
        ├── 收到 shutdown 命令 / EOF / SIGTERM
        ├── 停止 Agent loop
        ├── flush Memory 到磁盘
        └── 退出进程 (exit code 0)
```

**关键设计决策**：

- **stdout 专用于 pipe**：所有日志、调试信息通过 `tracing` 输出到 stderr。stdout 严格保留给 JSON Line 协议，防止日志混入 pipe 流导致解析失败。
- **tokio worker_threads = 2**：在 8 GB 内存约束下，2 个 worker 线程足以处理 pipe I/O + LLM HTTP 请求。不需要更多并发。
- **模块组装使用依赖注入**：所有模块通过构造函数接收依赖，便于测试时替换为 mock 实现。

### 2.2 Agent Runtime — ReAct 循环

**职责**：实现 think → act → observe 循环，协调 LLM、Tool、Memory、Critic 完成用户任务。

**模块接口**：

```rust
/// Agent Runtime 核心结构
pub struct AgentRuntime {
    provider: Box<dyn LlmProvider>,
    tools: Vec<Box<dyn Tool>>,          // 包含 BrowserPipeTool + MCP tools
    memory: Arc<dyn Memory>,
    critic: Critic,
    config: RuntimeConfig,
}

/// Runtime 配置
pub struct RuntimeConfig {
    pub max_steps: u32,                  // 单次任务最大步数 (默认 50)
    pub max_thinking_tokens: u32,        // 单步 thinking 最大 token (默认 4096)
    pub system_prompt_template: String,  // 系统提示模板路径
    pub human_confirm_actions: Vec<String>, // 需人工确认的 action 列表
}

impl AgentRuntime {
    /// 创建 Runtime 实例
    pub fn new(
        provider: Box<dyn LlmProvider>,
        tools: Vec<Box<dyn Tool>>,
        memory: Arc<dyn Memory>,
        critic: Critic,
        config: RuntimeConfig,
    ) -> Self;

    /// 执行用户任务 (核心入口)
    /// 返回任务执行结果或错误
    pub async fn execute_task(&mut self, task: &str) -> Result<TaskResult, AgentError>;

    /// 停止当前任务 (由外部 shutdown 信号触发)
    pub fn abort(&self);
}

/// 任务执行结果
pub struct TaskResult {
    pub success: bool,
    pub summary: String,           // LLM 生成的任务完成摘要
    pub steps: Vec<StepRecord>,    // 所有执行步骤记录
    pub token_usage: TokenUsage,   // token 消耗统计
}

/// 单步执行记录
pub struct StepRecord {
    pub step_num: u32,
    pub thinking: String,          // LLM 的推理内容
    pub action: Option<Action>,    // 选择的操作 (None = 任务完成)
    pub observation: String,       // 操作结果观察
    pub duration_ms: u64,
}
```

**ReAct 循环伪码**：

```
execute_task(user_instruction):
    context = memory.load_context(user_instruction)
    system_prompt = render_template(config.system_prompt_template, {
        available_tools: tools.descriptions(),
        skills: skill_loader.list_skills(),
        context: context,
    })

    for step in 1..=config.max_steps:
        // === THINK ===
        llm_response = provider.chat(system_prompt, messages, tools)

        if llm_response.is_final_answer():
            return TaskResult { success: true, summary: llm_response.text }

        // === ACT ===
        action = llm_response.tool_call
        if action.name in config.human_confirm_actions:
            confirmation = request_human_confirm(action)  // 通过 pipe 发送确认请求
            if not confirmation:
                messages.push(observation: "用户拒绝了此操作")
                continue

        result = tools.execute(action)

        // === OBSERVE ===
        observation = format_observation(result)
        messages.push(observation)

        // === CRITIC ===
        critic_verdict = critic.evaluate(step, action, result)
        if critic_verdict.should_abort:
            return TaskResult { success: false, summary: critic_verdict.reason }

        memory.record_step(step, action, result)

    return TaskResult { success: false, summary: "达到最大步数限制" }
```

### 2.3 BrowserPipeTool — 自定义 Tool trait 实现

**职责**：将 Agent 的 action 请求序列化为 Pipe JSON 命令，发送到 Browser 并等待响应。这是 sgClaw 与 ZeroClaw 框架的核心对接点。

**模块接口**：

```rust
/// ZeroClaw 的 Tool trait (框架定义)
#[async_trait]
pub trait Tool: Send + Sync {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn parameters_schema(&self) -> serde_json::Value;
    async fn execute(&self, params: serde_json::Value) -> Result<ToolOutput, ToolError>;
}

/// sgClaw 的浏览器操作工具实现
pub struct BrowserPipeTool {
    pipe_writer: Arc<Mutex<PipeWriter>>,
    pipe_reader: Arc<PipeResponseReceiver>,
    mac_policy: Arc<MacPolicy>,
    seq_counter: AtomicU64,
    hmac_key: [u8; 32],
}

impl BrowserPipeTool {
    pub fn new(
        pipe_writer: Arc<Mutex<PipeWriter>>,
        pipe_reader: Arc<PipeResponseReceiver>,
        mac_policy: Arc<MacPolicy>,
        hmac_key: [u8; 32],
    ) -> Self;
}

#[async_trait]
impl Tool for BrowserPipeTool {
    fn name(&self) -> &str { "browser_action" }

    fn description(&self) -> &str {
        "在浏览器中执行操作。支持的操作包括：click, type, navigate, \
         getText, getHtml, waitForSelector, pageScreenshot, select, \
         scrollTo, getAomSnapshot, storageSet, storageGet, \
         zombieSpawn, zombieKill"
    }

    fn parameters_schema(&self) -> serde_json::Value {
        // 返回所有 action 的 JSON Schema (oneOf 结构)
        // 详见 §5 接口契约
    }

    async fn execute(&self, params: serde_json::Value) -> Result<ToolOutput, ToolError> {
        // 1. 解析 action + params
        let action: Action = serde_json::from_value(params)?;

        // 2. MAC 策略校验
        self.mac_policy.check(&action)?;

        // 3. 构造 pipe message
        let seq = self.seq_counter.fetch_add(1, Ordering::SeqCst);
        let msg = PipeMessage::command(seq, &action, &self.hmac_key);

        // 4. 发送到 Browser
        self.pipe_writer.lock().await.send(&msg)?;

        // 5. 等待对应 seq 的 response (超时 30s)
        let response = self.pipe_reader.recv(seq, Duration::from_secs(30)).await?;

        // 6. 转换为 ToolOutput
        Ok(ToolOutput::from_pipe_response(response))
    }
}
```

**Action 枚举（白名单）**：

```rust
/// 允许通过 pipe 的操作类型 (封闭枚举)
#[derive(Debug, Serialize, Deserialize)]
#[serde(tag = "action", content = "params")]
pub enum Action {
    #[serde(rename = "click")]
    Click { selector: String, wait_after: Option<u64> },

    #[serde(rename = "type")]
    Type { selector: String, text: String, clear_first: Option<bool> },

    #[serde(rename = "navigate")]
    Navigate { url: String },

    #[serde(rename = "getText")]
    GetText { selector: String },

    #[serde(rename = "getHtml")]
    GetHtml { selector: String, outer: Option<bool> },

    #[serde(rename = "waitForSelector")]
    WaitForSelector { selector: String, timeout_ms: Option<u64> },

    #[serde(rename = "pageScreenshot")]
    PageScreenshot { full_page: Option<bool> },

    #[serde(rename = "select")]
    Select { selector: String, value: String },

    #[serde(rename = "scrollTo")]
    ScrollTo { selector: Option<String>, x: Option<i32>, y: Option<i32> },

    #[serde(rename = "getAomSnapshot")]
    GetAomSnapshot { root_selector: Option<String> },

    #[serde(rename = "storageSet")]
    StorageSet { key: String, value: String },

    #[serde(rename = "storageGet")]
    StorageGet { key: String },

    #[serde(rename = "zombieSpawn")]
    ZombieSpawn { url: String },

    #[serde(rename = "zombieKill")]
    ZombieKill { page_id: String },
}
```

### 2.4 SkillLoader — 技能加载器

**职责**：发现、校验、加载 JavaScript 业务技能脚本，将其注册到 Agent 的工具集中。

**模块接口**：

```rust
/// 技能加载器
pub struct SkillLoader {
    skills_dir: PathBuf,
    registry: HashMap<String, Skill>,
    signature_verifier: SignatureVerifier,
}

/// 技能定义
pub struct Skill {
    pub name: String,               // 技能名称 (如 "oa-approval")
    pub version: String,            // 语义版本 (如 "1.2.0")
    pub description: String,        // 自然语言描述 (供 LLM 选择)
    pub target_domains: Vec<String>,// 适用域名列表
    pub parameters: JsonSchema,     // 输入参数 schema
    pub script: String,             // JS 脚本内容
    pub signature: String,          // 数字签名 (Ed25519)
}

/// 技能清单文件 (registry.json)
pub struct SkillRegistry {
    pub version: String,
    pub skills: Vec<SkillManifestEntry>,
}

pub struct SkillManifestEntry {
    pub name: String,
    pub file: String,              // 相对路径 (如 "builtin/oa-approval.js")
    pub hash: String,              // SHA-256 文件哈希
    pub signature: String,         // Ed25519 签名
}

impl SkillLoader {
    /// 创建加载器并扫描技能目录
    pub fn new(skills_dir: PathBuf, public_key: &[u8]) -> Result<Self, SkillError>;

    /// 获取所有已加载技能的描述 (供 LLM system prompt)
    pub fn list_skills(&self) -> Vec<SkillDescription>;

    /// 获取指定技能的 JS 脚本
    pub fn get_script(&self, name: &str) -> Option<&str>;

    /// 运行时重新加载技能 (热更新)
    pub fn reload(&mut self) -> Result<(), SkillError>;
}
```

**技能加载流程**：

```
SkillLoader::new(skills_dir)
  │
  ├── 1. 读取 skills/registry.json
  │     └── 解析技能清单
  │
  ├── 2. 遍历每个 SkillManifestEntry
  │     │
  │     ├── 2a. 读取技能文件
  │     │
  │     ├── 2b. 计算文件 SHA-256
  │     │     └── 与 registry.json 中的 hash 比对
  │     │     └── 不匹配 → 跳过 + 警告日志
  │     │
  │     ├── 2c. 验证 Ed25519 签名
  │     │     └── 使用编译时内嵌的公钥
  │     │     └── 签名无效 → 跳过 + 警告日志
  │     │
  │     └── 2d. 解析技能元数据 (JS 文件头部注释)
  │           └── 注册到 registry HashMap
  │
  └── 3. 日志: "Loaded N skills, skipped M (signature failed)"
```

**技能文件格式** (JS 文件头部)：

```javascript
/**
 * @skill oa-approval
 * @version 1.2.0
 * @description OA系统审批单自动处理：查询待审批列表、批量审批、添加审批意见
 * @domains oa.example.com, oa-test.example.com
 * @params {
 *   "type": "object",
 *   "properties": {
 *     "action": { "enum": ["list", "approve", "reject"] },
 *     "opinion": { "type": "string" }
 *   }
 * }
 */
async function execute(params, browserAction) {
    // browserAction 是 BrowserAction 函数的引用
    // 技能代码使用 browserAction 调用浏览器操作

    if (params.action === 'list') {
        await browserAction('navigate', 'https://oa.example.com/approval/pending');
        await browserAction('waitForSelector', '.approval-list');
        const items = await browserAction('getText', '.approval-list');
        return { success: true, data: items };
    }
    // ...
}
```

### 2.5 MAC Policy — 强制访问控制策略

**职责**：在 Rust 端实施域名白名单和 Action 白名单校验，作为安全架构 Layer 2 的核心组件。

**模块接口**：

```rust
/// MAC 策略引擎
pub struct MacPolicy {
    allowed_domains: HashSet<String>,     // 允许操作的域名集合
    allowed_actions: HashSet<String>,     // 允许的 action 名称集合
    blocked_actions: HashSet<String>,     // 硬性禁止的 action 集合
    confirm_actions: HashSet<String>,     // 需人工确认的 action 集合
    storage_key_prefix: String,           // 存储 key 前缀限制 (默认 "sgclaw.")
    rate_limits: HashMap<String, RateLimit>, // 每域速率限制
}

/// 速率限制配置
pub struct RateLimit {
    pub max_per_second: u32,            // 每秒最大操作数
    pub cooldown_seconds: u32,          // 超限后冷却时间
}

/// MAC 校验结果
pub enum MacVerdict {
    Allow,                              // 允许执行
    NeedConfirm(String),                // 需要用户确认 (附确认提示)
    Deny(MacDenyReason),                // 拒绝执行
}

/// 拒绝原因
pub enum MacDenyReason {
    ActionNotAllowed(String),           // action 不在白名单
    ActionBlocked(String),              // action 在黑名单 (eval 等)
    DomainNotAllowed(String),           // 域名不在白名单
    StorageKeyViolation(String),        // storage key 前缀不合规
    RateLimitExceeded(String, u32),     // 超过速率限制 (域名, 当前速率)
}

impl MacPolicy {
    /// 从 rules.json 加载策略
    pub fn from_rules_file(path: &Path) -> Result<Self, PolicyError>;

    /// 校验 action 是否允许
    pub fn check(&self, action: &Action) -> MacVerdict;

    /// 校验域名是否在白名单
    pub fn check_domain(&self, domain: &str) -> bool;

    /// 记录一次操作 (用于速率统计)
    pub fn record_access(&self, domain: &str);
}
```

**rules.json 策略文件格式**：

```json
{
  "version": "1.0",
  "domains": {
    "allowed": [
      "oa.example.com",
      "erp.example.com",
      "hr.example.com",
      "finance.example.com"
    ]
  },
  "pipe_actions": {
    "allowed": [
      "click", "type", "navigate", "getText", "getHtml",
      "waitForSelector", "pageScreenshot", "select", "scrollTo",
      "getAomSnapshot", "storageSet", "storageGet",
      "zombieSpawn", "zombieKill"
    ],
    "blocked": [
      "eval", "executeJsInPage", "registerJsFunction",
      "setRequestInterceptor", "exportCookies"
    ],
    "need_confirm": [
      "sessionLogin", "sessionLogout", "clearStorage"
    ]
  },
  "storage": {
    "key_prefix": "sgclaw."
  },
  "rate_limits": {
    "default": { "max_per_second": 10, "cooldown_seconds": 30 },
    "overrides": {
      "finance.example.com": { "max_per_second": 5, "cooldown_seconds": 60 }
    }
  }
}
```

### 2.6 Critic — 输出质量评估器

**职责**：在 Agent 每步 observe 后评估操作结果质量，检测异常模式，触发熔断保护。

**模块接口**：

```rust
/// 输出质量评估器
pub struct Critic {
    circuit_breaker: CircuitBreaker,
    memory: Arc<dyn Memory>,
    config: CriticConfig,
}

pub struct CriticConfig {
    pub consecutive_failure_threshold: u32,  // 连续失败熔断阈值 (默认 10)
    pub same_action_repeat_limit: u32,       // 同一 action 重复上限 (默认 5)
    pub max_task_duration_secs: u64,         // 单任务最大时长 (默认 600)
}

/// 评估结果
pub struct CriticVerdict {
    pub should_abort: bool,             // 是否应终止任务
    pub reason: Option<String>,         // 终止原因
    pub warning: Option<String>,        // 警告 (不终止但需记录)
}

/// 熔断器
pub struct CircuitBreaker {
    state: CircuitState,
    consecutive_failures: AtomicU32,
    last_failure_time: Mutex<Option<Instant>>,
    config: CircuitBreakerConfig,
}

pub enum CircuitState {
    Closed,         // 正常 — 允许操作
    Open,           // 断开 — 拒绝所有操作
    HalfOpen,       // 半开 — 允许一次试探
}

pub struct CircuitBreakerConfig {
    pub failure_threshold: u32,          // 失败次数阈值 (默认 10)
    pub cooldown_base_secs: u64,         // 基础冷却时间 (默认 1)
    pub cooldown_max_secs: u64,          // 最大冷却时间 (默认 30)
    pub reset_on_success: bool,          // 成功后是否重置计数 (默认 true)
}

impl Critic {
    pub fn new(memory: Arc<dyn Memory>, config: CriticConfig) -> Self;

    /// 评估单步结果
    pub fn evaluate(
        &self,
        step: u32,
        action: &Action,
        result: &ToolOutput,
        elapsed: Duration,
    ) -> CriticVerdict;

    /// 重置熔断器 (用户手动恢复时调用)
    pub fn reset(&self);
}
```

**评估逻辑**：

```
evaluate(step, action, result, elapsed):
    // 1. 检查操作是否失败
    if result.is_error():
        circuit_breaker.record_failure()
        if circuit_breaker.state == Open:
            return Verdict { should_abort: true, reason: "连续失败次数达到熔断阈值" }

    // 2. 检查是否在重复同一操作
    recent_actions = memory.get_recent_actions(config.same_action_repeat_limit)
    if all_same(recent_actions, action):
        return Verdict { should_abort: true, reason: "检测到死循环：连续重复相同操作" }

    // 3. 检查任务时长
    if elapsed > config.max_task_duration_secs:
        return Verdict { should_abort: true, reason: "任务执行超时" }

    // 4. 成功时重置计数
    if result.is_success() && config.reset_on_success:
        circuit_breaker.reset_failures()

    return Verdict { should_abort: false }
```

### 2.7 Memory — 记忆系统

**职责**：管理 Agent 的短期对话记忆和长期任务知识库，支持上下文检索和经验沉淀。

**模块接口**：

```rust
/// Memory trait (ZeroClaw 框架定义)
#[async_trait]
pub trait Memory: Send + Sync {
    /// 存储对话消息
    async fn store_message(&self, msg: &Message) -> Result<(), MemoryError>;

    /// 检索相关上下文 (语义搜索)
    async fn retrieve(&self, query: &str, limit: usize) -> Result<Vec<MemoryEntry>, MemoryError>;

    /// 清除当前会话记忆
    async fn clear_session(&self) -> Result<(), MemoryError>;
}

/// sgClaw 的复合记忆实现
pub struct CompositeMemory {
    short_term: ShortTermMemory,       // Ring Buffer 短期记忆
    long_term: LongTermMemory,         // SQLite 长期记忆
}

/// 短期记忆 (Ring Buffer)
pub struct ShortTermMemory {
    buffer: VecDeque<Message>,
    max_size: usize,                   // 默认 50 条消息
    max_tokens: usize,                 // 默认 8000 tokens
}

/// 长期记忆 (SQLite + 简单向量)
pub struct LongTermMemory {
    db: SqlitePool,                    // SQLite 连接池
    embedding_dim: usize,              // 向量维度 (默认 384)
}

/// 记忆条目
pub struct MemoryEntry {
    pub id: String,
    pub content: String,
    pub entry_type: MemoryType,
    pub relevance_score: f32,          // 与查询的相关度 (0.0 ~ 1.0)
    pub created_at: DateTime<Utc>,
}

pub enum MemoryType {
    Conversation,                       // 对话历史
    TaskResult,                         // 任务执行结果
    SkillExperience,                    // 技能执行经验
    UserPreference,                     // 用户偏好
}

impl CompositeMemory {
    pub fn new(config: MemoryConfig) -> Result<Self, MemoryError>;

    /// 获取最近 N 步的 action 记录 (供 Critic 查重)
    pub fn get_recent_actions(&self, n: usize) -> Vec<Action>;

    /// 保存任务执行经验 (供自进化学习)
    pub async fn save_task_experience(
        &self,
        task: &str,
        result: &TaskResult,
    ) -> Result<(), MemoryError>;
}
```

**存储 Schema** (SQLite):

```sql
-- 长期记忆表
CREATE TABLE memory_entries (
    id          TEXT PRIMARY KEY,
    content     TEXT NOT NULL,
    entry_type  TEXT NOT NULL,           -- 'conversation' | 'task_result' | 'skill_exp' | 'user_pref'
    embedding   BLOB,                    -- f32 向量 (384 维 = 1536 bytes)
    metadata    TEXT,                    -- JSON 附加信息
    created_at  TEXT NOT NULL,
    session_id  TEXT                     -- 关联的 trace_id
);

-- 向量索引 (简单线性扫描，数据量小时足够)
CREATE INDEX idx_memory_type ON memory_entries(entry_type);
CREATE INDEX idx_memory_session ON memory_entries(session_id);

-- 技能执行记录表
CREATE TABLE skill_executions (
    id          TEXT PRIMARY KEY,
    skill_name  TEXT NOT NULL,
    input_hash  TEXT NOT NULL,           -- 输入参数 hash (用于精确匹配)
    success     INTEGER NOT NULL,
    duration_ms INTEGER,
    created_at  TEXT NOT NULL
);
```

### 2.8 LLM Provider — 模型适配层

**职责**：统一封装不同 LLM 服务的调用接口，支持 streaming、tool-use、token 计量。

**模块接口**：

```rust
/// LLM Provider trait (ZeroClaw 框架定义)
#[async_trait]
pub trait LlmProvider: Send + Sync {
    /// 发送聊天请求
    async fn chat(
        &self,
        messages: &[Message],
        tools: &[ToolDefinition],
        config: &ChatConfig,
    ) -> Result<LlmResponse, LlmError>;

    /// 发送 streaming 请求
    async fn chat_stream(
        &self,
        messages: &[Message],
        tools: &[ToolDefinition],
        config: &ChatConfig,
    ) -> Result<Pin<Box<dyn Stream<Item = Result<StreamChunk, LlmError>>>>, LlmError>;

    /// 获取 provider 信息
    fn info(&self) -> ProviderInfo;
}

/// 聊天配置
pub struct ChatConfig {
    pub max_tokens: u32,              // 最大生成 token 数
    pub temperature: f32,             // 温度 (默认 0.1, Agent 场景偏低)
    pub stop_sequences: Vec<String>,  // 停止序列
}

/// LLM 响应
pub struct LlmResponse {
    pub content: Option<String>,       // 文本回复
    pub tool_calls: Vec<ToolCall>,     // 工具调用请求
    pub usage: TokenUsage,             // token 使用量
    pub finish_reason: FinishReason,
}

/// Token 使用统计
pub struct TokenUsage {
    pub prompt_tokens: u32,
    pub completion_tokens: u32,
    pub total_tokens: u32,
}

/// Provider 信息
pub struct ProviderInfo {
    pub name: String,                  // "claude" | "openai" | "ollama"
    pub model: String,                 // 如 "claude-sonnet-4-20250514"
    pub max_context_tokens: u32,       // 最大上下文窗口
    pub supports_tools: bool,
    pub supports_streaming: bool,
}
```

**已实现的 Provider**：

| Provider | 模块 | 支持功能 | 适用场景 |
|----------|------|---------|---------|
| **Claude** | `llm/claude.rs` | streaming + tool-use + vision | 默认推荐，综合能力最强 |
| **OpenAI** | `llm/openai.rs` | streaming + tool-use | 兼容 GPT-4 及 API 兼容服务 |
| **Ollama** | `llm/ollama.rs` | streaming + tool-use (部分模型) | 本地部署，离线场景 |

**Provider 选择逻辑**：

```rust
/// 根据配置创建 Provider 实例
pub fn create_provider(config: &LlmConfig) -> Result<Box<dyn LlmProvider>, LlmError> {
    match config.provider.as_str() {
        "claude" => Ok(Box::new(ClaudeProvider::new(
            &config.api_key,
            &config.model,   // 如 "claude-sonnet-4-20250514"
            config.base_url.as_deref(),
        )?)),
        "openai" => Ok(Box::new(OpenAiProvider::new(
            &config.api_key,
            &config.model,   // 如 "gpt-4o"
            config.base_url.as_deref(),
        )?)),
        "ollama" => Ok(Box::new(OllamaProvider::new(
            &config.model,   // 如 "qwen2.5:32b"
            config.base_url.as_deref().unwrap_or("http://localhost:11434"),
        )?)),
        other => Err(LlmError::UnknownProvider(other.to_string())),
    }
}
```

### 2.9 MCP Client — 外部工具扩展

**职责**：通过 rmcp（Rust MCP SDK）连接外部 MCP Server，动态获取额外工具供 Agent 使用。

**模块接口**：

```rust
/// MCP 客户端管理器
pub struct McpClientManager {
    clients: HashMap<String, McpClient>,    // server_name → client
    config: McpConfig,
}

pub struct McpConfig {
    pub servers: Vec<McpServerConfig>,
}

pub struct McpServerConfig {
    pub name: String,                       // 服务器标识名
    pub command: String,                    // 启动命令
    pub args: Vec<String>,                  // 命令参数
    pub env: HashMap<String, String>,       // 环境变量
}

impl McpClientManager {
    /// 创建并连接所有配置的 MCP Server
    pub async fn new(config: McpConfig) -> Result<Self, McpError>;

    /// 获取所有 MCP Server 提供的工具列表
    pub fn list_tools(&self) -> Vec<ToolDefinition>;

    /// 调用 MCP 工具
    pub async fn call_tool(
        &self,
        server: &str,
        tool: &str,
        params: serde_json::Value,
    ) -> Result<serde_json::Value, McpError>;

    /// 关闭所有连接
    pub async fn shutdown(&mut self);
}
```

---

## 3. 浏览器 C++ 端模块详细设计

### 3.1 SgClawProcessHost — 进程宿主

**职责**：Singleton，管理 sgclaw 子进程的完整生命周期（Start / Stop / OnCrash），创建和持有 STDIO Pipe。

**接口声明**：

```cpp
// sg_claw_process_host.h

#ifndef CHROME_BROWSER_SUPERRPA_SGCLAW_SG_CLAW_PROCESS_HOST_H_
#define CHROME_BROWSER_SUPERRPA_SGCLAW_SG_CLAW_PROCESS_HOST_H_

#include <memory>
#include <string>
#include "base/process/launch.h"
#include "base/process/process.h"

namespace superrpa {
namespace sgclaw {

class PipeListener;

// sgClaw 进程状态
enum class ProcessState {
  kStopped,      // 初始状态 / 已停止
  kStarting,     // 正在启动 (等待 handshake)
  kRunning,      // 正常运行
  kStopping,     // 正在停止
  kCrashed,      // 异常退出
};

// 进程事件观察者
class ProcessObserver {
 public:
  virtual ~ProcessObserver() = default;
  virtual void OnStateChanged(ProcessState new_state) = 0;
  virtual void OnPipeMessage(const std::string& json_line) = 0;
  virtual void OnProcessCrash(int exit_code, const std::string& stderr_output) = 0;
};

// sgClaw 进程宿主 (Singleton)
class SgClawProcessHost {
 public:
  static SgClawProcessHost* GetInstance();

  // 启动 sgClaw 子进程
  // 成功返回 true，失败返回 false 并通过 observer 通知
  bool Start();

  // 优雅停止 sgClaw
  void Stop();

  // 发送消息到 sgClaw
  bool SendMessage(const std::string& json_line);

  // 获取当前状态
  ProcessState GetState() const;

  // 注册/移除观察者
  void AddObserver(ProcessObserver* observer);
  void RemoveObserver(ProcessObserver* observer);

 private:
  SgClawProcessHost();
  ~SgClawProcessHost();

  // 禁止拷贝
  SgClawProcessHost(const SgClawProcessHost&) = delete;
  SgClawProcessHost& operator=(const SgClawProcessHost&) = delete;

  // 内部方法
  base::FilePath GetSgClawBinaryPath() const;
  void OnChildProcessExited(int exit_code);
  void DoHandshake();

  // 成员
  ProcessState state_ = ProcessState::kStopped;
  base::Process child_process_;
  std::unique_ptr<PipeListener> pipe_listener_;

  // Pipe 文件描述符 (Linux: fd, Windows: HANDLE)
  base::ScopedFD pipe_write_fd_;    // Browser → sgClaw
  base::ScopedFD pipe_read_fd_;     // sgClaw → Browser

  std::vector<ProcessObserver*> observers_;
};

}  // namespace sgclaw
}  // namespace superrpa

#endif
```

**关键实现说明**：

- **Singleton**：使用 `base::NoDestructor<SgClawProcessHost>` 实现进程全局唯一实例
- **Start() 流程**：检查二进制存在 → 创建 pipe pair → `base::LaunchProcess` → 启动 PipeListener → 发送 handshake → 等待 ack (5s 超时) → 状态切换到 Running
- **Stop() 流程**：发送 `{"type":"shutdown"}` → 等待进程退出 (2s 超时) → SIGTERM → 再等 2s → SIGKILL
- **OnChildProcessExited()**：检查退出码，非零且非主动 Stop → 视为 Crash → 通知 observers → 不自动重启
- **线程安全**：所有方法在 Browser UI 线程调用，Pipe 读取在 IO 线程

### 3.2 PipeListener — 异步读取循环

**职责**：在 IO 线程上异步读取 sgClaw 的 stdout 输出，按行解析 JSON，分发到 MAC 校验和 CommandRouter。

**接口声明**：

```cpp
// pipe_listener.h

#ifndef CHROME_BROWSER_SUPERRPA_SGCLAW_PIPE_LISTENER_H_
#define CHROME_BROWSER_SUPERRPA_SGCLAW_PIPE_LISTENER_H_

#include <string>
#include <functional>
#include "base/files/file_descriptor_watcher_posix.h"  // Linux
// Windows: base/win/object_watcher.h

namespace superrpa {
namespace sgclaw {

class PipeListener {
 public:
  using MessageCallback = std::function<void(const std::string& json_line)>;
  using ErrorCallback = std::function<void(const std::string& error)>;

  PipeListener(base::ScopedFD read_fd,
               MessageCallback on_message,
               ErrorCallback on_error);
  ~PipeListener();

  // 开始异步监听
  void StartListening();

  // 停止监听
  void StopListening();

 private:
  void OnReadable();                   // fd 可读回调
  void ProcessBuffer();                // 从 buffer 中提取完整行
  bool ValidateMessageSize(const std::string& line);  // 检查消息大小 (<=1MB)

  base::ScopedFD read_fd_;
  std::string read_buffer_;            // 累积读取缓冲
  MessageCallback on_message_;
  ErrorCallback on_error_;

  // Linux: FileDescriptorWatcher
  std::unique_ptr<base::FileDescriptorWatcher::Controller> fd_watcher_;
};

}  // namespace sgclaw
}  // namespace superrpa

#endif
```

**读取流程**：

```
StartListening()
  │
  └── 注册 fd_watcher_ 监听 read_fd_ 可读事件
        │
        ▼
OnReadable()  [IO 线程回调]
  │
  ├── read(read_fd_, temp_buffer, 4096)
  │     → 返回 0: EOF → 通知 process exited
  │     → 返回 -1: EAGAIN → 忽略 (非阻塞 I/O)
  │     → 返回 N: 追加到 read_buffer_
  │
  └── ProcessBuffer()
        │
        ├── 在 read_buffer_ 中查找 '\n'
        │     → 找到: 提取该行作为 json_line
        │     → 未找到: 等待下次 OnReadable()
        │
        ├── ValidateMessageSize(json_line)
        │     → > 1MB: 丢弃 + 日志警告
        │
        └── on_message_(json_line)
              │
              └── [UI 线程] MAC 校验 → CommandRouter
```

### 3.3 MAC Whitelist Check — Pipe 来源 MAC 校验

**职责**：对通过 Pipe 收到的命令进行强制访问控制校验，作为安全架构 Layer 3 的实现。

**接口声明**：

```cpp
// mac_whitelist_check.h

#ifndef CHROME_BROWSER_SUPERRPA_SGCLAW_MAC_WHITELIST_CHECK_H_
#define CHROME_BROWSER_SUPERRPA_SGCLAW_MAC_WHITELIST_CHECK_H_

#include <string>
#include <set>
#include "base/values.h"

namespace superrpa {
namespace sgclaw {

// MAC 校验结果
enum class MacResult {
  kAllow,                // 允许
  kDeny,                 // 拒绝
  kNeedConfirm,          // 需用户确认
};

struct MacCheckResult {
  MacResult result;
  std::string reason;    // 拒绝/确认原因
};

class MacWhitelistCheck {
 public:
  // 从 rules.json 加载策略
  static std::unique_ptr<MacWhitelistCheck> CreateFromRules(
      const base::FilePath& rules_path);

  // 校验 pipe 命令
  MacCheckResult Check(const std::string& action,
                       const std::string& expected_domain,
                       const std::string& current_page_domain) const;

 private:
  MacWhitelistCheck();

  std::set<std::string> allowed_actions_;
  std::set<std::string> blocked_actions_;
  std::set<std::string> confirm_actions_;
  std::set<std::string> allowed_domains_;
};

}  // namespace sgclaw
}  // namespace superrpa

#endif
```

**校验流程**：

```
Check(action, expected_domain, current_page_domain):
  │
  ├── 1. action 在 blocked_actions_ 中?
  │     → 是: return Deny("Action is blocked: " + action)
  │
  ├── 2. action 不在 allowed_actions_ 中?
  │     → 是: return Deny("Action not in pipe whitelist: " + action)
  │
  ├── 3. expected_domain 不在 allowed_domains_ 中?
  │     → 是: return Deny("Domain not in whitelist: " + expected_domain)
  │
  ├── 4. expected_domain != current_page_domain?
  │     → 是: return Deny("Domain mismatch: expected " + expected_domain
  │                         + " but current is " + current_page_domain)
  │
  ├── 5. action 在 confirm_actions_ 中?
  │     → 是: return NeedConfirm("操作需要用户确认: " + action)
  │
  └── 6. return Allow
```

---

## 4. 前端 Side Panel 新增 UI

### 4.1 AgentControlPanel.vue

**职责**：在 Side Panel 中提供 Agent 控制面板，包括启停按钮、指令输入、状态显示、执行日志流。

**组件接口**：

```
AgentControlPanel.vue
│
├── Props: 无 (独立组件)
│
├── State:
│   ├── agentState: 'stopped' | 'starting' | 'running' | 'error'
│   ├── taskInput: string          // 用户输入的自然语言指令
│   ├── logs: LogEntry[]           // 执行日志条目
│   ├── currentTask: string        // 当前执行的任务描述
│   └── errorMessage: string       // 错误信息
│
├── Methods:
│   ├── startAgent()               // 调用 FunctionsUI → SgClawProcessHost::Start()
│   ├── stopAgent()                // 调用 FunctionsUI → SgClawProcessHost::Stop()
│   ├── submitTask(instruction)    // 发送任务到 Agent
│   ├── confirmAction(actionId)    // 用户确认 human-in-the-loop 操作
│   └── rejectAction(actionId)     // 用户拒绝操作
│
└── Events (from C++ via FunctionsUI):
    ├── onStateChanged(state)      // Agent 状态变更
    ├── onLogEntry(entry)          // 新日志条目
    ├── onConfirmRequired(action)  // 需要用户确认的操作
    └── onTaskCompleted(result)    // 任务完成
```

**UI 布局**：

```
┌─────────────────────────────────────┐
│  sgClaw Agent                       │
├─────────────────────────────────────┤
│                                     │
│  状态: ● 运行中                      │
│                                     │
│  ┌─────────────────────────────┐    │
│  │ 请输入业务指令...             │    │
│  │                             │    │
│  └─────────────────────────────┘    │
│  [ 发送 ]                           │
│                                     │
│  ─── 执行日志 ───────────────────   │
│                                     │
│  ▸ [10:23:01] 正在分析指令...       │
│  ▸ [10:23:03] 导航至 ERP 系统       │
│  ▸ [10:23:05] 点击"财务报表"菜单    │
│  ▸ [10:23:08] 设置时间范围: 本月     │
│  ▸ [10:23:10] 正在导出数据...       │
│                                     │
│  ─── 确认请求 ───────────────────   │
│                                     │
│  ⚠ Agent 请求执行登录操作            │
│  目标系统: erp.example.com          │
│  [ 允许 ]  [ 拒绝 ]                 │
│                                     │
├─────────────────────────────────────┤
│  [ 启动 Agent ]  [ 停止 Agent ]     │
└─────────────────────────────────────┘
```

**与 C++ 层的通信**：

前端通过 FunctionsUI 机制（SuperRPA 已有的 JS → C++ IPC）与 SgClawProcessHost 交互。

```javascript
// 启动 Agent
window.sgFunctionsUI('sgclaw_start', {}, (response) => {
    // response: { success: true } 或 { success: false, error: "..." }
});

// 停止 Agent
window.sgFunctionsUI('sgclaw_stop', {}, (response) => { ... });

// 发送任务
window.sgFunctionsUI('sgclaw_submit_task', {
    instruction: "导出本月合规报表"
}, (response) => { ... });

// 确认/拒绝操作
window.sgFunctionsUI('sgclaw_confirm', {
    action_id: "abc123",
    approved: true
}, (response) => { ... });
```

**事件接收**（C++ → JS 推送）：

```javascript
// C++ 通过 ExecuteJavaScript 推送事件到 Side Panel
// 前端注册全局事件处理器
window.sgClawEvents = {
    onStateChanged: function(state) {
        // state: 'stopped' | 'starting' | 'running' | 'error'
        vm.agentState = state;
    },
    onLogEntry: function(entry) {
        // entry: { time: "10:23:01", message: "正在分析指令...", level: "info" }
        vm.logs.push(entry);
    },
    onConfirmRequired: function(action) {
        // action: { id: "abc123", type: "sessionLogin", domain: "erp.example.com" }
        vm.pendingConfirm = action;
    },
    onTaskCompleted: function(result) {
        // result: { success: true, summary: "已成功导出3份报表" }
        vm.currentTask = null;
    }
};
```

---

## 5. 接口契约

### 5.1 Pipe JSON 协议完整 Schema

以下定义了 sgClaw 与 Browser 之间所有 Pipe 消息的完整 JSON Schema。

**Handshake — Browser → sgClaw**：

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "PipeInitMessage",
  "type": "object",
  "required": ["type", "version", "hmac_seed"],
  "properties": {
    "type": { "const": "init" },
    "version": {
      "type": "string",
      "pattern": "^\\d+\\.\\d+$",
      "description": "协议版本号 (如 1.0)"
    },
    "hmac_seed": {
      "type": "string",
      "minLength": 32,
      "maxLength": 64,
      "description": "HMAC 密钥种子 (hex 编码)"
    },
    "capabilities": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Browser 支持的扩展能力列表"
    }
  }
}
```

**Handshake — sgClaw → Browser**：

```json
{
  "title": "PipeInitAckMessage",
  "type": "object",
  "required": ["type", "version", "agent_id"],
  "properties": {
    "type": { "const": "init_ack" },
    "version": {
      "type": "string",
      "description": "sgClaw 协议版本 (必须与 init.version 一致)"
    },
    "agent_id": {
      "type": "string",
      "description": "Agent 实例唯一标识 (UUID v4)"
    },
    "supported_actions": {
      "type": "array",
      "items": { "type": "string" },
      "description": "sgClaw 可使用的 action 列表"
    }
  }
}
```

**Command — sgClaw → Browser**：

```json
{
  "title": "PipeCommandMessage",
  "type": "object",
  "required": ["seq", "type", "action", "params", "security"],
  "properties": {
    "seq": {
      "type": "integer",
      "minimum": 1,
      "description": "全局递增序列号"
    },
    "type": { "const": "command" },
    "action": {
      "type": "string",
      "enum": [
        "click", "type", "navigate", "getText", "getHtml",
        "waitForSelector", "pageScreenshot", "select", "scrollTo",
        "getAomSnapshot", "storageSet", "storageGet",
        "zombieSpawn", "zombieKill"
      ]
    },
    "params": {
      "type": "object",
      "description": "操作参数，格式取决于 action (见 §5.2)"
    },
    "security": {
      "type": "object",
      "required": ["expected_domain", "hmac"],
      "properties": {
        "expected_domain": {
          "type": "string",
          "description": "期望操作的目标域名"
        },
        "hmac": {
          "type": "string",
          "description": "HMAC-SHA256 签名 (hex)"
        }
      }
    }
  }
}
```

**Response — Browser → sgClaw**：

```json
{
  "title": "PipeResponseMessage",
  "type": "object",
  "required": ["seq", "type", "success"],
  "properties": {
    "seq": {
      "type": "integer",
      "description": "对应 command 的序列号"
    },
    "type": { "const": "response" },
    "success": { "type": "boolean" },
    "data": {
      "type": "object",
      "description": "操作结果数据 (成功时)"
    },
    "error": {
      "type": "object",
      "properties": {
        "code": { "type": "string" },
        "message": { "type": "string" }
      },
      "description": "错误信息 (失败时)"
    },
    "aom_snapshot": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "role": { "type": "string" },
          "name": { "type": "string" },
          "bounds": {
            "type": "array",
            "items": { "type": "integer" },
            "minItems": 4,
            "maxItems": 4,
            "description": "[x, y, width, height]"
          },
          "value": { "type": "string" },
          "children": { "type": "array" }
        }
      },
      "description": "操作后的 AOM 快照"
    },
    "timing": {
      "type": "object",
      "properties": {
        "queue_ms": { "type": "integer" },
        "exec_ms": { "type": "integer" }
      }
    }
  }
}
```

### 5.2 各 Action 参数 Schema

**click**：

```json
{
  "type": "object",
  "required": ["selector"],
  "properties": {
    "selector": {
      "type": "string",
      "description": "CSS 选择器"
    },
    "wait_after": {
      "type": "integer",
      "minimum": 0,
      "maximum": 30000,
      "default": 1000,
      "description": "点击后等待时间 (ms)"
    }
  }
}
```

**type**：

```json
{
  "type": "object",
  "required": ["selector", "text"],
  "properties": {
    "selector": {
      "type": "string",
      "description": "CSS 选择器"
    },
    "text": {
      "type": "string",
      "maxLength": 10000,
      "description": "要输入的文本"
    },
    "clear_first": {
      "type": "boolean",
      "default": true,
      "description": "输入前是否清空已有内容"
    }
  }
}
```

**navigate**：

```json
{
  "type": "object",
  "required": ["url"],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "description": "目标 URL (必须在域白名单内)"
    }
  }
}
```

**getText**：

```json
{
  "type": "object",
  "required": ["selector"],
  "properties": {
    "selector": {
      "type": "string",
      "description": "CSS 选择器"
    }
  }
}
```

**getHtml**：

```json
{
  "type": "object",
  "required": ["selector"],
  "properties": {
    "selector": {
      "type": "string"
    },
    "outer": {
      "type": "boolean",
      "default": false,
      "description": "true 返回 outerHTML, false 返回 innerHTML"
    }
  }
}
```

**waitForSelector**：

```json
{
  "type": "object",
  "required": ["selector"],
  "properties": {
    "selector": {
      "type": "string"
    },
    "timeout_ms": {
      "type": "integer",
      "minimum": 100,
      "maximum": 30000,
      "default": 5000,
      "description": "等待超时 (ms)"
    }
  }
}
```

**pageScreenshot**：

```json
{
  "type": "object",
  "properties": {
    "full_page": {
      "type": "boolean",
      "default": false,
      "description": "是否截取整页 (true) 或仅可视区域 (false)"
    }
  }
}
```

**select**：

```json
{
  "type": "object",
  "required": ["selector", "value"],
  "properties": {
    "selector": {
      "type": "string",
      "description": "select 元素的 CSS 选择器"
    },
    "value": {
      "type": "string",
      "description": "要选择的 option 的 value 值"
    }
  }
}
```

**scrollTo**：

```json
{
  "type": "object",
  "properties": {
    "selector": {
      "type": "string",
      "description": "滚动到指定元素 (优先于 x/y)"
    },
    "x": {
      "type": "integer",
      "description": "水平滚动位置 (px)"
    },
    "y": {
      "type": "integer",
      "description": "垂直滚动位置 (px)"
    }
  }
}
```

**getAomSnapshot**：

```json
{
  "type": "object",
  "properties": {
    "root_selector": {
      "type": "string",
      "description": "从指定元素开始获取 AOM 子树 (默认整页)"
    }
  }
}
```

**storageSet**：

```json
{
  "type": "object",
  "required": ["key", "value"],
  "properties": {
    "key": {
      "type": "string",
      "pattern": "^sgclaw\\.",
      "description": "存储键名 (必须以 sgclaw. 开头)"
    },
    "value": {
      "type": "string",
      "maxLength": 65536,
      "description": "存储值"
    }
  }
}
```

**storageGet**：

```json
{
  "type": "object",
  "required": ["key"],
  "properties": {
    "key": {
      "type": "string",
      "pattern": "^sgclaw\\.",
      "description": "存储键名 (必须以 sgclaw. 开头)"
    }
  }
}
```

**zombieSpawn**：

```json
{
  "type": "object",
  "required": ["url"],
  "properties": {
    "url": {
      "type": "string",
      "format": "uri",
      "description": "Zombie page 加载的 URL (必须在域白名单内)"
    }
  }
}
```

**zombieKill**：

```json
{
  "type": "object",
  "required": ["page_id"],
  "properties": {
    "page_id": {
      "type": "string",
      "description": "要销毁的 zombie page ID"
    }
  }
}
```

### 5.3 错误码体系

所有错误响应使用统一的错误码格式：

```json
{
  "seq": 5,
  "type": "response",
  "success": false,
  "error": {
    "code": "MAC_DOMAIN_MISMATCH",
    "message": "Expected domain erp.example.com but current page is oa.example.com"
  }
}
```

**错误码分类**：

| 错误码前缀 | 来源 | 描述 |
|-----------|------|------|
| `PIPE_*` | PipeListener | Pipe 传输层错误 |
| `MAC_*` | MAC Whitelist Check | 安全策略拒绝 |
| `CMD_*` | CommandRouter | 命令执行错误 |
| `SESSION_*` | SessionManager | 会话相关错误 |
| `INTERNAL_*` | 内部 | 系统内部错误 |

**完整错误码列表**：

| 错误码 | 描述 | 建议处理 |
|--------|------|---------|
| `PIPE_INVALID_JSON` | JSON 解析失败 | 检查消息格式 |
| `PIPE_MESSAGE_TOO_LARGE` | 消息超过 1MB 限制 | 减小消息体积 |
| `PIPE_SEQ_DUPLICATE` | 序列号重复 | 检查 seq 生成逻辑 |
| `PIPE_SEQ_OUT_OF_ORDER` | 序列号乱序 | 检查消息发送顺序 |
| `PIPE_HMAC_INVALID` | HMAC 签名校验失败 | 检查密钥和签名算法 |
| `MAC_ACTION_BLOCKED` | Action 在黑名单中 | 使用允许的 action |
| `MAC_ACTION_NOT_ALLOWED` | Action 不在白名单中 | 检查 action 名称 |
| `MAC_DOMAIN_NOT_ALLOWED` | 域名不在白名单中 | 联系管理员添加域名 |
| `MAC_DOMAIN_MISMATCH` | 期望域名与实际不匹配 | 确认当前页面域名 |
| `MAC_RATE_LIMIT` | 超过速率限制 | 降低操作频率 |
| `MAC_NEED_CONFIRM` | 操作需要用户确认 | 等待用户确认 |
| `CMD_SELECTOR_NOT_FOUND` | 选择器未匹配到元素 | 检查选择器或等待元素 |
| `CMD_SELECTOR_TIMEOUT` | 等待元素超时 | 增加超时时间 |
| `CMD_NAVIGATION_FAILED` | 页面导航失败 | 检查 URL 可达性 |
| `CMD_ZOMBIE_POOL_FULL` | Zombie 池已满 (max 5) | 先销毁不需要的 zombie |
| `CMD_ZOMBIE_NOT_FOUND` | 指定的 zombie page 不存在 | 检查 page_id |
| `SESSION_EXPIRED` | 会话已过期 | 触发重新登录 |
| `SESSION_LOGIN_FAILED` | 登录失败 | 检查凭证或网络 |
| `INTERNAL_UNKNOWN` | 未知内部错误 | 查看日志 |

### 5.4 Handshake 协议流程

```
Browser                                sgClaw
   │                                      │
   │  (1) Start child process             │
   │  ──────────────────────────────────→  │
   │                                      │
   │  (2) init message                    │
   │  {"type":"init",                     │
   │   "version":"1.0",                   │
   │   "hmac_seed":"a1b2c3..."}           │
   │  ──────────────────────────────────→  │
   │                                      │  校验版本号
   │                                      │  派生 HMAC 密钥
   │  (3) init_ack                        │
   │  {"type":"init_ack",                 │
   │   "version":"1.0",                   │
   │   "agent_id":"uuid-v4",             │
   │   "supported_actions":[...]}         │
   │  ◄──────────────────────────────────  │
   │                                      │
   │  校验版本号                           │
   │  记录 agent_id (审计)                 │
   │  状态 → Running                      │
   │                                      │
   │  (4) 正常通信开始                     │
   │  ◄═══════════════════════════════════►│
   │                                      │
```

**超时处理**：
- Browser 发送 init 后等待 5 秒
- 超时未收到 init_ack → Kill 子进程 → 状态切换到 Crashed → 通知 UI

**版本不匹配处理**：
- sgClaw 收到的 version 与自身版本不一致 → 发送 error ack → 主动退出
- Browser 收到的 version 与自身不一致 → Kill 子进程 → 报错

---

## 6. 跨模块交互时序

### 6.1 用户启动 Agent 完整时序

```
用户                Side Panel           C++ (Browser)           Rust (sgClaw)
 │                    │                      │                       │
 │  点击 [启动]       │                      │                       │
 │ ──────────────→   │                      │                       │
 │                    │  sgclaw_start        │                       │
 │                    │ ────────────────→    │                       │
 │                    │                      │  Start()              │
 │                    │                      │  ├ 检查二进制          │
 │                    │                      │  ├ 创建 pipe pair     │
 │                    │                      │  ├ LaunchProcess      │
 │                    │                      │  │ ─────────────────→ │ main()
 │                    │                      │  │                    │ ├ 初始化
 │                    │                      │  │  init message      │ ├ 等待 init
 │                    │                      │  │ ─────────────────→ │
 │                    │                      │  │                    │ ├ 校验版本
 │                    │                      │  │  init_ack          │ ├ 派生 HMAC
 │                    │                      │  │ ◄───────────────── │
 │                    │                      │  ├ 状态 → Running     │
 │                    │  { success: true }   │                       │
 │                    │ ◄────────────────    │                       │
 │  状态: ● 运行中    │                      │                       │
 │ ◄──────────────   │                      │                       │
```

### 6.2 用户提交任务完整时序

```
用户              Side Panel           C++ (Browser)           Rust (sgClaw)         LLM
 │                  │                      │                       │                  │
 │ "导出合规报表"   │                      │                       │                  │
 │ ───────────→    │                      │                       │                  │
 │                  │ sgclaw_submit_task   │                       │                  │
 │                  │ ──────────────────→  │                       │                  │
 │                  │                      │  Pipe: submit_task    │                  │
 │                  │                      │ ──────────────────→   │                  │
 │                  │                      │                       │ execute_task()    │
 │                  │                      │                       │                  │
 │                  │                      │                       │ ┌─ ReAct Loop ───┤
 │                  │                      │                       │ │                │
 │                  │                      │                       │ │ THINK          │
 │                  │                      │                       │ │ ──────────────→│
 │                  │                      │                       │ │ LLM response   │
 │                  │                      │                       │ │ ◄──────────────│
 │                  │                      │                       │ │                │
 │                  │                      │                       │ │ ACT            │
 │                  │                      │  Pipe: click          │ │                │
 │                  │                      │ ◄──────────────────   │ │                │
 │                  │                      │  MAC Check → Allow    │ │                │
 │                  │                      │  CommandRouter.exec   │ │                │
 │                  │                      │  Pipe: response       │ │                │
 │                  │                      │ ──────────────────→   │ │                │
 │                  │                      │                       │ │ OBSERVE        │
 │                  │                      │                       │ │ CRITIC         │
 │                  │                      │                       │ │                │
 │                  │                      │                       │ │ (repeat...)    │
 │                  │                      │                       │ └────────────────┤
 │                  │                      │                       │                  │
 │                  │                      │  Pipe: task_complete  │                  │
 │                  │                      │ ◄──────────────────   │                  │
 │                  │ onTaskCompleted      │                       │                  │
 │                  │ ◄──────────────────  │                       │                  │
 │ "已导出3份报表"  │                      │                       │                  │
 │ ◄───────────    │                      │                       │                  │
```

### 6.3 Human-in-the-loop 确认时序

```
Rust (sgClaw)         C++ (Browser)           Side Panel            用户
     │                      │                      │                  │
     │ Pipe: command        │                      │                  │
     │ action=sessionLogin  │                      │                  │
     │ ──────────────────→  │                      │                  │
     │                      │  MAC: NeedConfirm    │                  │
     │                      │  push onConfirmReq   │                  │
     │                      │ ──────────────────→  │                  │
     │                      │                      │  显示确认对话框    │
     │                      │                      │ ───────────────→ │
     │                      │                      │                  │
     │                      │                      │  用户点击 [允许]  │
     │                      │                      │ ◄─────────────── │
     │                      │  sgclaw_confirm      │                  │
     │                      │ ◄──────────────────  │                  │
     │                      │                      │                  │
     │                      │  CommandRouter.exec  │                  │
     │                      │  (sessionLogin)      │                  │
     │  Pipe: response      │                      │                  │
     │ ◄──────────────────  │                      │                  │
     │                      │                      │                  │
```

---

## 7. 配置体系

### 7.1 sgclaw.toml 配置文件

```toml
# sgClaw 配置文件
# 路径: 与 sgclaw 二进制同目录, 或 $SGCLAW_CONFIG 指定

[general]
# Agent 日志级别: trace | debug | info | warn | error
log_level = "info"

[llm]
# LLM Provider: claude | openai | ollama
provider = "claude"
model = "claude-sonnet-4-20250514"
# API Key (建议通过环境变量 SGCLAW_LLM_API_KEY 设置)
# api_key = "sk-..."
# 自定义 API 端点 (可选)
# base_url = "https://api.example.com/v1"

[llm.config]
max_tokens = 4096
temperature = 0.1

[agent]
# 单次任务最大步数
max_steps = 50
# 系统提示模板路径 (相对于 sgclaw 二进制)
system_prompt_template = "prompts/system.txt"

[memory]
# SQLite 数据库路径
db_path = "data/memory.db"
# 短期记忆最大条数
short_term_max_messages = 50
# 短期记忆最大 token 数
short_term_max_tokens = 8000

[security]
# rules.json 路径 (域白名单 + action 白名单)
rules_path = "rules.json"
# Skill 公钥路径 (Ed25519)
skill_public_key_path = "keys/skill_verify.pub"

[skills]
# 技能目录路径
skills_dir = "sgclaw-skills"

[circuit_breaker]
# 连续失败熔断阈值
failure_threshold = 10
# 基础冷却时间 (秒)
cooldown_base_secs = 1
# 最大冷却时间 (秒)
cooldown_max_secs = 30

[mcp]
# MCP Server 配置 (可选)
# [[mcp.servers]]
# name = "filesystem"
# command = "npx"
# args = ["-y", "@anthropic/mcp-server-filesystem", "/tmp"]
```

### 7.2 环境变量覆盖

所有配置均可通过 `SGCLAW_` 前缀的环境变量覆盖：

| 环境变量 | 覆盖配置项 | 示例 |
|---------|-----------|------|
| `SGCLAW_LOG_LEVEL` | `general.log_level` | `debug` |
| `SGCLAW_LLM_PROVIDER` | `llm.provider` | `ollama` |
| `SGCLAW_LLM_MODEL` | `llm.model` | `qwen2.5:32b` |
| `SGCLAW_LLM_API_KEY` | `llm.api_key` | `sk-...` |
| `SGCLAW_LLM_BASE_URL` | `llm.base_url` | `http://localhost:11434` |
| `SGCLAW_MAX_STEPS` | `agent.max_steps` | `100` |
| `SGCLAW_RULES_PATH` | `security.rules_path` | `/etc/sgclaw/rules.json` |

优先级：环境变量 > 配置文件 > 编译时默认值。

---

*文档结束。本文档为 sgClaw L2 层模块设计与接口契约参考，各组应基于此文档中的接口定义
进行并行开发。接口变更需经三方组长会审后更新本文档。*