Cerevox

> TypeScript SDK for browser automation and secure command execution in highly available and scalable cloud environments


🎯 项目概述

Cerevox 是一个基于 TypeScript 的浏览器自动化和安全命令执行 SDK，专为高可用和可扩展的云浏览器环境设计。它提供了完整的沙箱环境管理、浏览器控制、文件系统操作和终端命令执行功能。

$3

- 🚀 云浏览器自动化 - 基于 E2B 和 Playwright 的高性能浏览器控制
- 🔒 安全沙箱环境 - 隔离的命令执行环境，确保安全性
- 📁 文件系统操作 - 完整的文件上传、下载、读写功能
- 💻 终端命令执行 - 实时流式输出的命令执行
- 🤖 AI 功能集成 - 图像生成、视频制作、背景音乐生成等 AI 能力
- 📝 多语言代码执行 - 支持 TypeScript、JavaScript、Python、Shell 脚本执行
- 📊 高性能日志 - 基于 Pino 的结构化日志系统
- 🎨 TypeScript 严格模式 - 完整的类型安全保障
- 🔧 模块化设计 - 高内聚低耦合的架构设计

📦 安装

``bash


使用 pnpm (推荐)

pnpm add cerevox

使用 npm

npm install cerevox

使用 yarn

yarn add cerevox
`

🚀 快速开始

$3

`typescript
import { Cerevox } from 'cerevox';
import { chromium } from 'playwright';

async function main() {
// 初始化 Cerevox 实例
const cerevox = new Cerevox({
apiKey: 'your-api-key', // 或通过环境变量 CEREVOX_API_KEY
debug: true
});

// 启动云浏览器会话
const session = await cerevox.launch({
browser: {
type: 'chrome-stable',
headless: false,
liveview: true
}
});

// 连接到浏览器
const browser = await chromium.connectOverCDP(session.browser.endpoint);
const page = await browser.newPage();

// 执行浏览器操作
await page.goto('https://example.com');
await page.screenshot({ path: './screenshot.png' });

// 清理资源
await page.close();
await browser.close();
await session.close();
}

main().catch(console.error);
`

$3

`typescript
import { Cerevox } from 'cerevox';

async function fileOperations() {
const cerevox = new Cerevox();
const session = await cerevox.launch();

// 写入文件
await session.files.write('/home/user/test.txt', 'Hello World!');

// 读取文件
const content = await session.files.read('/home/user/test.txt');
console.log(content); // "Hello World!"

// 上传本地文件
await session.files.upload('./local-file.txt', '/home/user/remote-file.txt');

// 下载远程文件
await session.files.download('/home/user/remote-file.txt', './downloaded-file.txt');

// 列出目录内容
const files = await session.files.listFiles('/home/user');
console.log(files);

await session.close();
}
`

$3

`typescript
import { Cerevox } from 'cerevox';

async function runCommands() {
const cerevox = new Cerevox();
const session = await cerevox.launch();

// 执行命令并获取结果
const result = await session.terminal.run('ls -la');
console.log(await result.json());

// 流式输出
const process = await session.terminal.run('npm install');
process.stdout.pipe(process.stdout);
process.stderr.pipe(process.stderr);
await process.end();

await session.close();
}
`

$3

`typescript
import { Cerevox } from 'cerevox';

async function runCode() {
const cerevox = new Cerevox();
const session = await cerevox.launch();

// 执行 Python 代码
const pythonCode =
print("Hello from Python!")
import requests
response = requests.get("https://api.github.com")
print(f"Status: {response.status_code}")
;
const pythonResult = await session.codeRunner.run(pythonCode);
console.log(await pythonResult);

// 执行 Shell 脚本
const shellCode = #!/bin/bash
echo "Hello from Shell!"
ls -la
pwd
;
const shellResult = await session.codeRunner.run(shellCode);
console.log(await shellResult);

// 执行 TypeScript 代码
const tsCode =
import { chromium } from 'playwright';

async function main() {
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
const title = await page.title();
console.log('Page title:', title);
await browser.close();
}

main();
;
const tsResult = await session.codeRunner.run(tsCode, { inject: true });
console.log(await tsResult);

await session.close();
}
`

$3

`typescript
import { Cerevox } from 'cerevox';

async function useAI() {
const cerevox = new Cerevox();
const session = await cerevox.launch();

// 获取可用的 AI 模型
const models = await session.ai.getModels();
console.log('Available models:', models);

// 生成图像
const imageResult = await session.ai.generateImage({
prompt: '一只可爱的橘猫在阳光下睡觉',
size: '1024x1024'
});
console.log('Generated image:', imageResult);

// 帧到视频转换
const videoResult = await session.ai.framesToVideo({
prompt: '让这只猫动起来',
start_frame: '/path/to/start_frame.jpg',
end_frame: '/path/to/end_frame.jpg',
duration: 5,
resolution: '720p'
});
console.log('Generated video:', videoResult);

// 生成背景音乐
const bgmResult = await session.ai.generateBGM({
Text: '轻松愉快的背景音乐',
Duration: 30
});
console.log('Generated BGM:', bgmResult);

await session.close();
}
`

🏗️ 架构设计

$3

- Cerevox - 主入口类，负责会话管理和配置
- Session - 会话管理，提供统一的资源访问接口
- Browser - 浏览器控制，基于 Playwright 的浏览器操作
- FileSystem - 文件系统操作，支持本地和远程文件管理
- Terminal - 终端命令执行，支持实时流式输出
- CodeRunner - 代码执行引擎，支持 TypeScript、JavaScript、Python、Shell 脚本
- AI - AI 功能集成，提供图像生成、视频制作、背景音乐生成等能力
- Logger - 高性能日志系统，基于 Pino 实现

$3

- 语言: TypeScript 5.8+ (严格模式)
- 运行时: Node.js 18+
- 模块系统: CommonJS
- 包管理: pnpm
- 浏览器引擎: Playwright Core
- 沙箱环境: E2B
- 日志系统: Pino
- 构建工具: TypeScript Compiler + esbuild

📚 API 文档

$3

#### 构造函数

`typescript
const cerevox = new Cerevox({
apiKey?: string; // API 密钥，默认从环境变量读取
debug?: boolean; // 调试模式，默认 false
logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'fatal'; // 日志级别
});
`

#### 方法

- launch(config?: ILaunchConfig): Promise - 启动新的浏览器会话
- connect(sandboxId: string): Promise - 连接到现有沙箱

$3

#### 属性

- browser: Browser - 浏览器控制实例
- files: FileSystem - 文件系统操作实例
- terminal: Terminal - 终端操作实例
- codeRunner: CodeRunner - 代码执行引擎实例
- ai: AI - AI 功能实例

#### 方法

- getHost(): string - 获取会话主机地址
- close(force?: boolean): Promise - 关闭会话

$3

#### 方法

- run(code: string, options?: RunOptions): Promise - 执行代码
- code - 要执行的代码字符串
- options.inject? - 是否注入浏览器启动参数（仅 TypeScript/JavaScript）
- options.timeout? - 执行超时时间（毫秒）

#### 支持的代码类型

- TypeScript - 自动检测 ES 模块语法
- JavaScript - 支持 CommonJS 和 ES 模块
- Python - 自动检测 Python 语法特征
- Shell - 检测 #!/bin/bash 开头的脚本

$3

#### 方法

- getModels(): Promise - 获取可用的 AI 模型列表
- generateImage(params: ImageGenerationParams): Promise - 生成图像
- framesToVideo(params: VideoGenerationParams): Promise - 帧到视频转换
- generateBGM(params: BGMGenerationParams): Promise - 生成背景音乐

#### 接口定义

`typescript
interface ImageGenerationParams {
prompt: string;
size?: string;
quality?: string;
style?: string;
}

interface VideoGenerationParams {
prompt: string;
start_frame: string;
end_frame: string;
duration: number;
resolution?: string;
}

interface BGMGenerationParams {
Text: string;
Duration: number;
Style?: string;
}
`

$3

`typescript
interface IBrowserConfig {
type?: 'chromium' | 'chrome-stable'; // 浏览器类型
args?: string[]; // 浏览器启动参数
headless?: boolean; // 无头模式
liveview?: boolean; // 实时预览
adblock?: boolean; // 广告拦截
webgl?: boolean; // WebGL 支持
}

interface ILaunchConfig {
browser?: IBrowserConfig; // 浏览器配置
timeoutMS?: number; // 超时时间
keepAliveMS?: number; // 保活时间
metadata?: Record; // 元数据
}

interface RunOptions {
inject?: boolean;
timeout?: number;
}
`

🔧 开发指南

$3

- Node.js 18+
- pnpm 8+
- TypeScript 5.8+

$3

`bash


克隆项目

git clone https://github.com/liubei-ai/cerevox.git
cd cerevox

安装依赖

pnpm install

构建项目

pnpm build

运行示例

pnpm dev

代码检查

pnpm lint

代码格式化

pnpm format
`

$3

`
cerevox/
├── src/ # 核心源码
│ ├── index.ts # 主入口文件
│ ├── core/ # 核心模块
│ │ ├── cerevox.ts # 主类
│ │ ├── session.ts # 会话管理
│ │ ├── browser.ts # 浏览器控制
│ │ ├── file-system.ts # 文件系统
│ │ ├── terminal.ts # 终端操作
│ │ ├── code-runner.ts # 代码执行引擎
│ │ └── ai.ts # AI 功能集成
│ └── utils/ # 工具函数
│ ├── logger.ts # 日志系统
│ ├── detect-code.ts # 代码类型检测
│ └── volc-signv4.ts # 火山引擎签名工具
├── sandbox/ # 沙箱环境代码
├── examples/ # 使用示例
├── scripts/ # 构建脚本
└── dist/ # 编译输出
`

🧪 测试

`bash


运行测试

pnpm test

运行测试并生成覆盖率报告

pnpm test:coverage
`

🛠️ Template 构建

Cerevox 支持构建自定义的 E2B 沙盒模板，提供预配置的浏览器环境：

$3

`bash


构建 Chromium 模板


pnpm run deploy:chromium
`

这将创建一个名为 cerevox-chromium 的模板，包含：
- Chromium 浏览器
- 4GB 内存，4核 CPU
- 预配置的沙盒环境

$3

`bash


构建 Chrome Stable 模板


pnpm run deploy:chrome
`

这将创建一个名为 cerevox-chrome-stable 的模板，包含：
- Chrome 稳定版浏览器
- 4GB 内存，4核 CPU
- 预配置的沙盒环境

$3

模板配置文件位于：
- chromium.toml - Chromium 模板配置
- chrome-stable.toml - Chrome Stable 模板配置

🖥️ CLI 工具 - cerevox-run

Cerevox 提供了一个强大的 CLI 工具，可以直接运行 TypeScript/JavaScript 文件在沙盒环境中：

$3

`bash


通过 npx 直接运行（推荐）

npx cerevox-run your-script.ts

或者全局安装

npm install -g cerevox
cerevox-run your-script.ts
`

$3

`bash
cerevox-run [options]

参数:
file 要运行的 JavaScript 或 TypeScript 文件

选项:
-V, --version 显示版本号
-k, --key Cerevox API 密钥（可选，如果设置了 CEREVOX_API_KEY 环境变量）
-l, --listen 监听端口号
-h, --help 显示帮助信息
`

$3

`bash


基础使用

npx cerevox-run script.ts

指定 API 密钥

npx cerevox-run -k your-api-key script.ts

指定监听端口

npx cerevox-run -l 3000 web-server.ts
`

$3

创建 .env.cerevox 文件：

`bash
CEREVOX_API_KEY=your-api-key-here
`

$3

- 自动代码转换：自动将 Playwright 的 launch() 方法替换为 connectOverCDP()
- TypeScript 支持：原生支持 TypeScript 文件
- 实时预览：非 headless 模式下自动打开浏览器预览
- 智能打包：使用 esbuild 进行代码打包和优化
- 环境管理：自动创建和管理 API 密钥配置文件
- 代码执行：支持 TypeScript、JavaScript、Python、Shell 脚本执行
- AI 功能：集成图像生成、视频制作、背景音乐生成等 AI 能力
- 文件管理：支持文件上传下载和目录操作
- 命令执行：实时执行终端命令

📄 许可证

ISC License - 详见 LICENSE 文件

🤝 贡献

欢迎提交 Issue 和 Pull Request！

$3

- 遵循 TypeScript 严格模式
- 使用 ESLint + Prettier 代码规范
- 所有函数必须包含类型注解
- 提交前运行 pnpm lint` 检查代码

📞 支持

- 📧 Email: support@cerevox.io
- 🐛 Issues: GitHub Issues
- 📖 文档: 官方文档

🔗 相关链接

- E2B Platform - 云沙箱环境
- Playwright - 浏览器自动化
- Pino - 高性能日志

---

Cerevox - 让浏览器自动化更简单、更安全、更高效 🚀