feat: refactor sgclaw around zeroclaw compat runtime

2026-03-26 16:23:31 +08:00
parent bca5b75801
commit ff0771a83f
1059 changed files with 409460 additions and 23 deletions
--- a/third_party/zeroclaw/docs/i18n/zh-CN/security/frictionless-security.zh-CN.md
+++ b/third_party/zeroclaw/docs/i18n/zh-CN/security/frictionless-security.zh-CN.md
@@ -0,0 +1,312 @@
+# 无摩擦安全：对安装向导零影响
+
+> ⚠️ **状态：提案 / 路线图**
+>
+> 本文档描述提议的实现方法，可能包含假设的命令或配置。
+> 如需了解当前运行时行为，请参见 [config-reference.zh-CN.md](../reference/api/config-reference.zh-CN.md)、[operations-runbook.zh-CN.md](../ops/operations-runbook.zh-CN.md) 和 [troubleshooting.zh-CN.md](../ops/troubleshooting.zh-CN.md)。
+
+## 核心原则
+
+> **"安全功能应该像安全气囊 — 存在、有保护作用，且在需要之前不可见。"**
+
+## 设计：静默自动检测
+
+### 1. 无新的向导步骤（保持 9 步，< 60 秒）
+
+```rust
+// 向导保持不变
+// 安全功能在后台自动检测
+
+pub fn run_wizard() -> Result<Config> {
+    // ... 现有 9 步，无更改 ...
+
+    let config = Config {
+        // ... 现有字段 ...
+
+        // 新增：自动检测的安全（不在向导中显示）
+        security: SecurityConfig::autodetect(),  // 静默！
+    };
+
+    config.save().await?;
+    Ok(config)
+}
+```
+
+### 2. 自动检测逻辑（首次启动时运行一次）
+
+```rust
+// src/security/detect.rs
+
+impl SecurityConfig {
+    /// 检测可用的沙箱并自动启用
+    /// 基于平台 + 可用工具返回智能默认值
+    pub fn autodetect() -> Self {
+        Self {
+            // 沙箱：优先 Landlock（原生），然后 Firejail，然后无
+            sandbox: SandboxConfig::autodetect(),
+
+            // 资源限制：始终启用监控
+            resources: ResourceLimits::default(),
+
+            // 审计：默认启用，记录到配置目录
+            audit: AuditConfig::default(),
+
+            // 其他所有项：安全默认值
+            ..SecurityConfig::default()
+        }
+    }
+}
+
+impl SandboxConfig {
+    pub fn autodetect() -> Self {
+        #[cfg(target_os = \"linux\")]
+        {
+            // 优先 Landlock（原生，无依赖）
+            if Self::probe_landlock() {
+                return Self {
+                    enabled: true,
+                    backend: SandboxBackend::Landlock,
+                    ..Self::default()
+                };
+            }
+
+            // 回退：如果安装了 Firejail 则使用
+            if Self::probe_firejail() {
+                return Self {
+                    enabled: true,
+                    backend: SandboxBackend::Firejail,
+                    ..Self::default()
+                };
+            }
+        }
+
+        #[cfg(target_os = \"macos\")]
+        {
+            // 在 macOS 上尝试 Bubblewrap
+            if Self::probe_bubblewrap() {
+                return Self {
+                    enabled: true,
+                    backend: SandboxBackend::Bubblewrap,
+                    ..Self::default()
+                };
+            }
+        }
+
+        // 回退：禁用（但仍有应用层安全）
+        Self {
+            enabled: false,
+            backend: SandboxBackend::None,
+            ..Self::default()
+        }
+    }
+
+    #[cfg(target_os = \"linux\")]
+    fn probe_landlock() -> bool {
+        // 尝试创建最小 Landlock 规则集
+        // 如果成功，内核支持 Landlock
+        landlock::Ruleset::new()
+            .set_access_fs(landlock::AccessFS::read_file)
+            .add_path(Path::new(\"/tmp\"), landlock::AccessFS::read_file)
+            .map(|ruleset| ruleset.restrict_self().is_ok())
+            .unwrap_or(false)
+    }
+
+    fn probe_firejail() -> bool {
+        // 检查 firejail 命令是否存在
+        std::process::Command::new(\"firejail\")
+            .arg(\"--version\")
+            .output()
+            .map(|o| o.status.success())
+            .unwrap_or(false)
+    }
+}
+```
+
+### 3. 首次运行：静默日志
+
+```bash
+$ zeroclaw agent -m \"hello\"
+
+# 首次运行：静默检测
+[INFO] Detecting security features...
+[INFO] ✓ Landlock sandbox enabled (kernel 6.2+)
+[INFO] ✓ Memory monitoring active (512MB limit)
+[INFO] ✓ Audit logging enabled (~/.config/zeroclaw/audit.log)
+
+# 后续运行：安静
+$ zeroclaw agent -m \"hello\"
+[agent] Thinking...
+```
+
+### 4. 配置文件：所有默认值隐藏
+
+```toml
+# ~/.config/zeroclaw/config.toml
+
+# 这些部分不会被写入，除非用户自定义
+# [security.sandbox]
+# enabled = true  # （默认，自动检测）
+# backend = \"landlock\"  # （默认，自动检测）
+
+# [security.resources]
+# max_memory_mb = 512  # （默认）
+
+# [security.audit]
+# enabled = true  # （默认）
+```
+
+仅当用户更改某些内容时：
+```toml
+[security.sandbox]
+enabled = false  # 用户显式禁用
+
+[security.resources]
+max_memory_mb = 1024  # 用户提高了限制
+```
+
+### 5. 高级用户：显式控制
+
+```bash
+# 检查哪些功能处于活动状态
+$ zeroclaw security --status
+Security Status:
+  ✓ Sandbox: Landlock (Linux kernel 6.2)
+  ✓ Memory monitoring: 512MB limit
+  ✓ Audit logging: ~/.config/zeroclaw/audit.log
+  → 今日已记录 47 个事件
+
+# 显式禁用沙箱（写入配置）
+$ zeroclaw config set security.sandbox.enabled false
+
+# 启用特定后端
+$ zeroclaw config set security.sandbox.backend firejail
+
+# 调整限制
+$ zeroclaw config set security.resources.max_memory_mb 2048
+```
+
+### 6. 优雅降级
+
+| 平台 | 最佳可用 | 回退 | 最坏情况 |
+|----------|---------------|----------|------------|
+| **Linux 5.13+** | Landlock | 无 | 仅应用层 |
+| **Linux（任意版本）** | Firejail | Landlock | 仅应用层 |
+| **macOS** | Bubblewrap | 无 | 仅应用层 |
+| **Windows** | 无 | - | 仅应用层 |
+
+**应用层安全始终存在** — 这是现有的白名单/路径阻止/注入保护，已经很全面。
+
+---
+
+## 配置模式扩展
+
+```rust
+// src/config/schema.rs
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SecurityConfig {
+    /// 沙箱配置（未设置则自动检测）
+    #[serde(default)]
+    pub sandbox: SandboxConfig,
+
+    /// 资源限制（未设置则应用默认值）
+    #[serde(default)]
+    pub resources: ResourceLimits,
+
+    /// 审计日志（默认启用）
+    #[serde(default)]
+    pub audit: AuditConfig,
+}
+
+impl Default for SecurityConfig {
+    fn default() -> Self {
+        Self {
+            sandbox: SandboxConfig::autodetect(),  // 静默检测！
+            resources: ResourceLimits::default(),
+            audit: AuditConfig::default(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SandboxConfig {
+    /// 启用沙箱（默认：自动检测）
+    #[serde(default)]
+    pub enabled: Option<bool>,  // None = 自动检测
+
+    /// 沙箱后端（默认：自动检测）
+    #[serde(default)]
+    pub backend: SandboxBackend,
+
+    /// 自定义 Firejail 参数（可选）
+    #[serde(default)]
+    pub firejail_args: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(rename_all = \"lowercase\")]
+pub enum SandboxBackend {
+    Auto,       // 自动检测（默认）
+    Landlock,   // Linux 内核 LSM
+    Firejail,   // 用户空间沙箱
+    Bubblewrap, // 用户命名空间
+    Docker,     // 容器（重量级）
+    None,       // 禁用
+}
+
+impl Default for SandboxBackend {
+    fn default() -> Self {
+        Self::Auto  // 默认始终自动检测
+    }
+}
+```
+
+---
+
+## 用户体验对比
+
+### 之前（当前）
+
+```bash
+$ zeroclaw onboard
+[1/9] Workspace Setup...
+[2/9] AI Provider...
+...
+[9/9] Workspace Files...
+✓ Security: Supervised | workspace-scoped
+```
+
+### 之后（带无摩擦安全）
+
+```bash
+$ zeroclaw onboard
+[1/9] Workspace Setup...
+[2/9] AI Provider...
+...
+[9/9] Workspace Files...
+✓ Security: Supervised | workspace-scoped | Landlock sandbox ✓
+# ↑ 仅多了一个词，静默自动检测！
+```
+
+---
+
+## 向后兼容性
+
+| 场景 | 行为 |
+|----------|----------|
+| **现有配置** | 工作不变，新功能选择加入 |
+| **新安装** | 自动检测并启用可用的安全功能 |
+| **无可用沙箱** | 回退到应用层（仍然安全） |
+| **用户禁用** | 一个配置标志：`sandbox.enabled = false` |
+
+---
+
+## 总结
+
+✅ **对向导零影响** — 保持 9 步，< 60 秒
+✅ **无新提示** — 静默自动检测
+✅ **无破坏性变更** — 向后兼容
+✅ **可选择退出** — 显式配置标志
+✅ **状态可见性** — `zeroclaw security --status`
+
+向导仍然是「通用应用快速安装」 — 安全只是**默默地更好了**。