byy/qiming

Fork 0

Files

Codex bfd67a0f2c chore: initialize qiming workspace repository

2026-05-29 14:22:48 +08:00

9.6 KiB

Raw Permalink Blame History

QimingClaw Sandbox API 文档

版本: 1.0.0 更新日期: 2026-03-27

1. 概述

QimingClaw Sandbox API 提供统一的沙箱执行接口，支持 macOS、Linux 和 Windows 平台。

2. TypeScript API

2.1 QimingSandbox 类

import { QimingSandbox, SandboxConfig, ExecuteResult } from '@qiming/sandbox-native';

const sandbox = new QimingSandbox();

2.1.1 构造函数

constructor()

创建沙箱实例。

示例:

const sandbox = new QimingSandbox();

2.1.2 execute 方法

async execute(
  command: string,
  cwd: string,
  config?: Partial<SandboxConfig>
): Promise<ExecuteResult>

在沙箱中执行命令。

参数:

参数	类型	必需	说明
`command`	string	✅	要执行的命令
`cwd`	string	✅	工作目录
`config`	SandboxConfig	❌	沙箱配置

返回值:

interface ExecuteResult {
  exitCode: number;      // 退出码
  stdout: string;        // 标准输出
  stderr: string;        // 标准错误
}

示例:

const result = await sandbox.execute(
  'npm install',
  '/Users/user/project',
  {
    networkEnabled: true,
    memoryLimit: '2g',
    timeout: 300,
  }
);

console.log(result.exitCode);  // 0
console.log(result.stdout);    // "added 100 packages..."

2.1.3 isAvailable 方法

isAvailable(): boolean

检查沙箱是否可用。

返回值: true 表示可用

示例:

if (sandbox.isAvailable()) {
  console.log('Sandbox is available');
}

2.2 配置类型

SandboxConfig

interface SandboxConfig {
  // 网络配置
  networkEnabled?: boolean;              // 是否启用网络
  allowedDomains?: string[];             // 允许的域名
  deniedDomains?: string[];              // 禁止的域名
  
  // 资源限制
  memoryLimit?: string;                  // 内存限制 (e.g., "2g")
  cpuLimit?: number;                     // CPU 核心数限制
  timeout?: number;                      // 超时时间（秒）
  
  // 文件系统
  allowRead?: string[];                  // 允许读取的路径
  denyRead?: string[];                   // 禁止读取的路径
  allowWrite?: string[];                 // 允许写入的路径
  denyWrite?: string[];                  // 禁止写入的路径
}

默认值:

const DEFAULT_CONFIG: SandboxConfig = {
  networkEnabled: false,
  memoryLimit: '2g',
  cpuLimit: 2,
  timeout: 300,
  
  allowRead: ['.'],
  denyRead: ['~/.ssh', '~/.aws', '~/.gnupg'],
  allowWrite: ['.', '/tmp'],
  denyWrite: ['.env', '*.pem', '*.key'],
};

3. 配置管理 API

3.1 SandboxConfigManager

import { SandboxConfigManager } from '@main/services/sandbox/SandboxConfigManager';

const configManager = new SandboxConfigManager();

3.1.1 getConfig

getConfig(): SandboxConfig

获取当前沙箱配置。

示例:

const config = configManager.getConfig();
console.log(config.mode);  // "non-main"

3.1.2 updateConfig

updateConfig(updates: Partial<SandboxConfig>): void

更新沙箱配置。

示例:

configManager.updateConfig({
  mode: 'all',
  network: {
    enabled: true,
    allowedDomains: ['github.com'],
  },
});

3.1.3 setMode

setMode(mode: SandboxMode): void

设置沙箱模式。

参数:

mode: "off" | "on-demand" | "non-main" | "all"

示例:

configManager.setMode('non-main');

3.1.4 isEnabled

isEnabled(sessionId?: string): boolean

检查沙箱是否启用。

参数:

sessionId: 会话 ID（可选）

返回值:

true 表示启用

示例:

// 检查全局是否启用
const globalEnabled = configManager.isEnabled();

// 检查特定会话是否启用
const sessionEnabled = configManager.isEnabled('session-123');

4. IPC API

4.1 渲染进程调用

4.1.1 获取配置

const config = await window.electron.invoke('sandbox:get-config');

4.1.2 设置模式

await window.electron.invoke('sandbox:set-mode', 'non-main');

4.1.3 更新配置

await window.electron.invoke('sandbox:update-config', {
  network: {
    enabled: true,
  },
});

4.1.4 重置配置

await window.electron.invoke('sandbox:reset-config');

4.1.5 获取状态

const status = await window.electron.invoke('sandbox:get-status');
// {
//   enabled: true,
//   mode: 'non-main',
//   platform: 'darwin',
//   available: true,
//   type: 'seatbelt'
// }

5. Rust API (内部使用)

5.1 SandboxInterface

pub trait SandboxInterface {
    /// 初始化沙箱
    fn initialize(&mut self, config: SandboxConfig) -> Result<(), SandboxError>;
    
    /// 执行命令
    fn execute(&self, command: &str, cwd: &str, config: &SandboxConfig) -> Result<ExecuteResult, SandboxError>;
    
    /// 读取文件
    fn read_file(&self, session_id: &str, path: &str) -> Result<String, SandboxError>;
    
    /// 写入文件
    fn write_file(&self, session_id: &str, path: &str, content: &str) -> Result<(), SandboxError>;
    
    /// 检查是否可用
    fn is_available(&self) -> bool;
    
    /// 获取状态
    fn get_status(&self) -> SandboxStatus;
    
    /// 清理资源
    fn cleanup(&mut self) -> Result<(), SandboxError>;
}

5.2 配置结构

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SandboxConfig {
    pub network_enabled: Option<bool>,
    pub memory_limit: Option<String>,
    pub cpu_limit: Option<i32>,
    pub timeout: Option<i32>,
    
    pub allowed_domains: Option<Vec<String>>,
    pub denied_domains: Option<Vec<String>>,
    
    pub allow_read: Option<Vec<String>>,
    pub deny_read: Option<Vec<String>>,
    pub allow_write: Option<Vec<String>>,
    pub deny_write: Option<Vec<String>>,
}

5.3 执行结果

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ExecuteResult {
    pub exit_code: i32,
    pub stdout: String,
    pub stderr: String,
}

6. 错误处理

6.1 错误类型

enum SandboxErrorCode {
  SANDBOX_UNAVAILABLE = 'SANDBOX_UNAVAILABLE',
  EXECUTION_FAILED = 'EXECUTION_FAILED',
  TIMEOUT = 'TIMEOUT',
  PERMISSION_DENIED = 'PERMISSION_DENIED',
  RESOURCE_LIMIT = 'RESOURCE_LIMIT',
}

6.2 错误示例

try {
  const result = await sandbox.execute('rm -rf /', '/tmp');
} catch (error) {
  if (error.code === 'PERMISSION_DENIED') {
    console.error('Permission denied');
  }
}

7. 使用示例

7.1 基本使用

import { QimingSandbox } from '@qiming/sandbox-native';

const sandbox = new QimingSandbox();

// 执行简单命令
const result = await sandbox.execute('ls -la', '/Users/user');
console.log(result.stdout);

7.2 网络访问

// 允许网络访问
const result = await sandbox.execute(
  'npm install',
  '/Users/user/project',
  {
    networkEnabled: true,
    allowedDomains: ['registry.npmjs.org'],
  }
);

7.3 资源限制

// 限制资源使用
const result = await sandbox.execute(
  'cargo build --release',
  '/Users/user/rust-project',
  {
    memoryLimit: '4g',
    cpuLimit: 4,
    timeout: 600,  // 10 分钟
  }
);

7.4 文件系统隔离

// 限制文件访问
const result = await sandbox.execute(
  'python script.py',
  '/Users/user/project',
  {
    allowRead: ['/Users/user/project', '/usr/local/lib'],
    denyRead: ['~/.ssh', '~/.aws'],
    allowWrite: ['/Users/user/project', '/tmp'],
    denyWrite: ['.env'],
  }
);

8. 平台特定行为

8.1 macOS (sandbox-exec)

// macOS 使用 Seatbelt 配置文件
// 自动生成 .sb 配置文件
// 示例配置:
(version 1)
(allow default)
(allow file-read* (subpath "/Users/user/project"))
(deny file-read* (subpath "~/.ssh"))

8.2 Linux (bubblewrap)

# Linux 使用 bubblewrap 命令
bwrap \
  --ro-bind /usr /usr \
  --bind /workspace /workspace \
  --unshare-all \
  --die-with-parent \
  bash -c "command"

8.3 Windows (Codex Sandbox)

// Windows 使用 Codex 实现
// 基于 Windows Job Objects 和 Restricted Tokens
// 自动处理进程隔离和权限限制

9. 性能指标

操作	macOS	Linux	Windows
启动时间	<50ms	<100ms	<200ms
命令执行	原生	原生	轻微开销
内存占用	~10MB	~20MB	~50MB
网络过滤	系统	iptables	WinAPI
文件隔离	系统	命名空间	Job Objects

10. 最佳实践

10.1 始终检查可用性

if (!sandbox.isAvailable()) {
  console.warn('Sandbox not available, running unsandboxed');
}

10.2 设置合理的超时

const result = await sandbox.execute(command, cwd, {
  timeout: 300,  // 5 分钟
});

10.3 限制网络访问

// 仅允许必要的域名
const result = await sandbox.execute(command, cwd, {
  networkEnabled: true,
  allowedDomains: ['github.com', 'registry.npmjs.org'],
});

10.4 处理错误

try {
  const result = await sandbox.execute(command, cwd, config);
  
  if (result.exitCode !== 0) {
    console.error('Command failed:', result.stderr);
  }
} catch (error) {
  console.error('Sandbox error:', error);
}

文档版本: 1.0.0 最后更新: 2026-03-27

9.6 KiB Raw Permalink Blame History Unescape Escape