# @agent-infra/sandbox 中文文档 规范地址：https://npmcn.com/package/%40agent-infra/sandbox/ 版本：1\.0\.17 npm 元数据更新时间：2026-05-28T07:31:50.908Z 中文译文更新时间：2026-11-06T05:22:58.160Z 软件包许可：ISC 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40agent-infra/sandbox 原文对照：https://npmcn.com/package/%40agent-infra/sandbox/?lang=original 项目主页：https://github.com/agent-infra/sandbox-sdk#readme 源码仓库：https://github.com/agent-infra/sandbox-sdk ## 关键信息（来自 npm 元数据） - 包体积（解压后）：5.2 MB，3096 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=18\.0\.0 - 运行依赖：0 个 - 首次发布：2025-08-14T15:11:02.263Z - 最新版本发布：2026-05-28T07:31:50.751Z - 近 30 天下载量：4826（2026-10-05 至 2026-11-03，npm 官方下载统计） - 已发布版本数：46（近 12 个月 23 个） ## 中文简介 为AIO Sandbox集成提供工具和接口的节点.js SDK ## 安装 ```sh npm install @agent-infra/sandbox ``` 也可以使用：`pnpm add @agent-infra/sandbox`、`yarn add @agent-infra/sandbox`、`bun add @agent-infra/sandbox` ## README # @ agent-infra/ sandbox 节点.js/TypeScript SDK用于AIO沙盒集成,提供沙盒管理和云提供商集成的工具和接口. ## 安装 ```bash npm install @agent-infra/sandbox ``` 或带线: ```bash yarn add @agent-infra/sandbox ``` 或带pnm: ```bash pnpm add @agent-infra/sandbox ``` ## 快速启动 ### 基本用途 ```typescript import { SandboxApiClient } from '@agent-infra/sandbox'; // Initialize the client const client = new SandboxApiClient({ environment: 'https://your-sandbox-api.com', // Add authentication if required }); // Use the API const result = await client.file.read({ path: '/path/to/file', }); console.log(result); ``` ### 使用云提供商 SDK包括不同云平台上管理沙盒的供应商执行. #### Volcengine 供应商 ```typescript import { providers } from '@agent-infra/sandbox'; // Initialize Volcengine provider const volcengineProvider = new providers.VolcengineProvider({ accessKey: process.env.VOLCENGINE_ACCESS_KEY, secretKey: process.env.VOLCENGINE_SECRET_KEY, region: 'cn-beijing', // Optional, defaults to 'cn-beijing' }); // Create a sandbox const sandboxId = await volcengineProvider.createSandbox( 'your-function-id', 30 // timeout in minutes ); console.log('Created sandbox:', sandboxId); // Get sandbox details with APIG domains const sandbox = await volcengineProvider.getSandbox( 'your-function-id', sandboxId ); console.log('Sandbox domains:', sandbox.domains); // List all sandboxes for a function const sandboxes = await volcengineProvider.listSandboxes('your-function-id'); console.log('Total sandboxes:', sandboxes.length); // Delete a sandbox await volcengineProvider.deleteSandbox('your-function-id', sandboxId); console.log('Sandbox deleted'); ``` #### 应用程序管理 ```typescript // Create an application const appId = await volcengineProvider.createApplication( 'my-app', 'my-gateway' ); // Check application readiness const [isReady, functionId] = await volcengineProvider.getApplicationReadiness(appId); if (isReady) { console.log('Application is ready, function ID:', functionId); } // Get APIG domains for a function const domains = await volcengineProvider.getApigDomains('your-function-id'); console.log('Available domains:', domains); ``` ## 特征 ### Sandbox API 客户端 - **文件操作**: 读取、写入、搜索和管理文件 - **执行壳牌**: 执行 shell 命令并管理会话 - **浏览器自动化**: 控制浏览器动作并检索信息 - **代码执行**: 执行各种语言的代码(Python, Node.js, Jupyter) - **MCP 一体化**: 执行MCP(模式上下文协议)工具 ### 云提供商 #### Volcengine 供应商 - QQ 沙盒生命周期管理( 创建、 删除、 获取、 列表) - \* 应用程序部署和监测 - APIG( API Gateway) 域管理 - 与 HMAC-SHA256 自动签署请求 - 支持临时全权证书 #### 可扩展提供者系统 通过扩展 `BaseProvider` 类 : ```typescript import { providers } from '@agent-infra/sandbox'; class MyCustomProvider extends providers.BaseProvider { async createSandbox(functionId: string, ...kwargs: any[]): Promise { // Your implementation } async deleteSandbox(functionId: string, sandboxId: string, ...kwargs: any[]): Promise { // Your implementation } async getSandbox(functionId: string, sandboxId: string, ...kwargs: any[]): Promise { // Your implementation } async listSandboxes(functionId: string, ...kwargs: any[]): Promise { // Your implementation } } ``` ## API 参考 ### 沙盒Api客户端 与 Sandbox API 互动的主要客户端. ```typescript const client = new SandboxApiClient({ environment: string, // API base URL timeout?: number, // Request timeout in milliseconds headers?: Record, // Custom headers }); ``` #### 可用模块 - `client.file` - 文件操作 - `client.shell` - 壳牌命令执行 - `client.browser` - 浏览器自动化 - `client.code` - 代码执行 - `client.jupyter` - Jupyter笔记本操作 - `client.nodejs` - 节点作业 - `client.mcp` - MCP工具执行 ### 供应商 #### 碱基提供器( Abstract) 所有云提供方实施的基础类. **方法:** - `createSandbox(functionId: string, ...kwargs: any[]): Promise` - `deleteSandbox(functionId: string, sandboxId: string, ...kwargs: any[]): Promise` - `getSandbox(functionId: string, sandboxId: string, ...kwargs: any[]): Promise` - `listSandboxes(functionId: string, ...kwargs: any[]): Promise` #### 伏尔肯宁 Volcengine VEFAAS实施. **构造器选项 :** ```typescript { accessKey: string; // Volcengine access key ID secretKey: string; // Volcengine secret access key region?: string; // Region (default: 'cn-beijing') clientSideValidation?: boolean; // Enable validation (default: true) } ``` **补充方法:** - `createApplication(name: string, gatewayName: string): Promise` - `getApplicationReadiness(id: string): Promise<[boolean, string | null]>` - `getApigDomains(functionId: string): Promise` ## 环境变量 使用环境变量配置 Volcengine 证书 : ```bash # Volcengine credentials (option 1) VOLCENGINE_ACCESS_KEY=your-access-key VOLCENGINE_SECRET_KEY=your-secret-key # Volcengine credentials (option 2) VOLC_ACCESSKEY=your-access-key VOLC_SECRETKEY=your-secret-key ``` ## 类型脚本支持 此软件包以 TypeScript 写成,包含完整类型定义. 建议采用5.0+型. ```typescript import type { SandboxApi, BaseClientOptions, BaseRequestOptions } from '@agent-infra/sandbox'; ``` ## 实例 ### 执行 Shell 命令 ```typescript const result = await client.shell.exec({ command: 'ls -la', timeout: 5000, }); console.log(result.stdout); ``` ### 读取文件 ```typescript const fileContent = await client.file.read({ path: '/path/to/file.txt', }); console.log(fileContent.content); ``` ### 浏览器自动化 ```typescript const browserInfo = await client.browser.info(); console.log('Browser:', browserInfo); await client.browser.config({ action: { type: 'click', selector: '#button', }, }); ``` ### 执行 Python 代码 ```typescript const result = await client.code.execute({ code: 'print("Hello from sandbox!")', language: 'python', }); console.log(result.output); ``` ## 处理错误 ```typescript import { SandboxApiError, SandboxApiTimeoutError } from '@agent-infra/sandbox'; try { const result = await client.file.read({ path: '/nonexistent' }); } catch (error) { if (error instanceof SandboxApiTimeoutError) { console.error('Request timed out'); } else if (error instanceof SandboxApiError) { console.error('API error:', error.statusCode, error.message); } else { console.error('Unexpected error:', error); } } ``` ## 发展 ### 项目结构 ``` sdk/js/ ├── src/ # TypeScript source code │ ├── api/ # Generated API modules │ ├── core/ # Core utilities │ ├── errors/ # Error classes │ ├── providers/ # Cloud provider implementations (custom code) │ │ ├── base.ts # Base provider interface │ │ ├── volcengine.ts # Volcengine implementation │ │ ├── sign.ts # Request signing utilities │ │ └── README.md # Provider documentation │ ├── BaseClient.ts # Base client implementation │ ├── Client.ts # Main API client │ └── index.ts # Package entry point ├── dist/ # Compiled JavaScript output (generated by build) ├── package.json # Package configuration └── tsconfig.json # TypeScript configuration ``` ### 大楼 SDK 使用 TypeScript 并编译源代码 `src/` 改为 `dist/`数字 : ```bash npm run build ``` 这将: 1. 编译类型脚本文件 `src/` 到 Java 脚本在 `dist/` 2. 生成 `.d.ts` 类型定义文件 3. 生成用于调试的源地图 ### 测试 ```bash npm test # With coverage npm run test:coverage # With UI npm run test:ui ``` ### 发展模式 ```bash npm run dev # Watch mode with auto-rebuild ``` ### 正在生成 SDK 基 SDK 代码使用 [费恩](https://buildwithfern.com/)数字 : ```bash cd sdk/fern fern generate --group nodejs-sdk --local ``` 从 OpenAPI 规格生成类型脚本代码 `src/`。 。 。 . 自定义提供者在 `src/providers/` 保存通过 `.fernignore`。 。 。 . ## 捐款 欢迎捐款! 请随意提交拉力请求. ### 添加自定义提供者 见 [供应商/README.md](https://npmcn.com/package/%40agent-infra/sandbox/providers/README.md) 关于实施自定义云提供者的详细信息. ## 许可证 公务员制度委员会 ## 链接 - [仓库](https://github.com/agent-infra/sandbox-sdk) - [问题](https://github.com/agent-infra/sandbox-sdk/issues) - [Volcengine 文档](https://www.volcengine.com/docs/) ## 支助 询问和支持请在GitHub上打开一个问题. * * * **版本**: 1.0.0 (中文(简体) ) **节点.js**页:1 **类型脚本**页:1 ## 常见问题 ### @agent-infra/sandbox 是什么？ 为AIO Sandbox集成提供工具和接口的节点\.js SDK ### 如何安装 @agent-infra/sandbox？ 在项目目录运行 npm install @agent-infra/sandbox，或使用 pnpm add / yarn add / bun add。 ### @agent-infra/sandbox 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @agent-infra/sandbox 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @agent-infra/sandbox 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @agent-infra/sandbox 可以商用吗？ @agent-infra/sandbox 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @agent-infra/sandbox 的下载量有多少？ 根据 npm 官方下载统计，@agent-infra/sandbox 在 2026/10/05 – 2026/11/03 这 30 天内被下载 4,826 次，日均约 161 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @agent-infra/sandbox 还在维护吗？ 最新版本 1\.0\.17 发布于 2026/05/28（5 个月前）；至今共发布 46 个版本，其中过去 12 个月发布了 23 个；首次发布于 2025/08/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。