# @blaxel/eve-sandbox 中文文档

规范地址：https://npmcn.com/package/%40blaxel/eve-sandbox/

版本：0\.3\.37
npm 元数据更新时间：2026-11-11T04:21:07.979Z
中文译文更新时间：2026-11-11T04:44:54.405Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40blaxel/eve-sandbox
原文对照：https://npmcn.com/package/%40blaxel/eve-sandbox/?lang=original
项目主页：https://blaxel.ai/
源码仓库：https://github.com/blaxel-ai/sdk-typescript

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：37.3 kB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：1 个
- peer 依赖：ai ^7\.0\.38，eve ^0\.31\.3
- 首次发布：2026-08-10T21:46:57.894Z
- 最新版本发布：2026-11-11T04:21:07.805Z
- 近 30 天下载量：3926（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：93（近 12 个月 93 个）

## 中文简介

持续为夜行代理提供银河沙盒后端

## 安装

```sh
npm install @blaxel/eve-sandbox
```

也可以使用：`pnpm add @blaxel/eve-sandbox`、`yarn add @blaxel/eve-sandbox`、`bun add @blaxel/eve-sandbox`

## README

# @ blaxel/ eve- sandbox (英语)

[银河](https://blaxel.ai/) 沙盒后端 [夜 间](https://eve.dev/)。 。 。 .

运行前夕的内置外壳和文件工具 安全,耐用 Blaxel 沙盒。 每个耐久的前夕会话在应用程序重启后重新连接到同一个沙盒上,而不依赖于仅预览的Blaxel API.

## 快开始

你需要节点24或晚点 和一个现有的 [前夕的项目](https://eve.dev/docs/installation)。 。 。 .

### 1\. 安装后端

```bash
npm install @blaxel/eve-sandbox
```

包裹预计 `eve` 财务报告和审定财务报表 `ai` 版本已经由您的 even 工程安装 .

### 2\. Blaxel认证

就当地发展而言,请与 [布莱克塞尔CLI](https://docs.blaxel.ai/cli-reference/overview)数字 :

```bash
bl login YOUR-WORKSPACE
```

在CI和制作中,提供 `BL_WORKSPACE` 财务报告和审定财务报表 `BL_API_KEY` 到应用程序运行时间。 不要把这些证书复制到沙盒里.

### 3\. 在前夕选择Blaxel

```ts
// agent/sandbox.ts
import { blaxel } from "@blaxel/eve-sandbox";
import { defineSandbox } from "eve/sandbox";

export default defineSandbox({
  backend: blaxel({
    image: "blaxel/ts-app:latest",
    lifecycle: {
      expirationPolicies: [{ type: "ttl-idle", value: "1d", action: "delete" }],
    },
    memory: 4096,
  }),
  async onSession({ use }) {
    const sandbox = await use({
      networkPolicy: { allow: ["github.com", "*.npmjs.org"] },
    });
    await sandbox.run({ command: "mkdir -p /workspace/project" });
  },
});
```

照常开始前夕 :

```bash
npm run dev
```

内置 `bash`, (中文(简体) ), `read_file`, (中文(简体) ), `write_file`, (中文(简体) ), `glob`,以及 `grep` 工具现在运行在Brlaxel沙盒内。 要在夕阳的终端UI中抽取测试设置,请代理创建 `/workspace/hello.txt` 然后读回来.

可在 [`examples/agent/sandbox.ts`](https://npmcn.com/package/%40blaxel/eve-sandbox/examples/agent/sandbox.ts)。 。 。 .

## 何谓有效

-   所有五个内置的夜之沙盒工具
-   屏蔽命令和流出背景进程
-   文本、 二进制和流文件操作
-   持久文件系统和程序状态跨回合和应用程序重新启动
-   自定义银河图像、区域、资源、数量、环境变量和生命周期政策
-   通过届会设置 `onSession()`
-   域外政策和暗后页眉转换
-   通过 Eight 抓取的会话元数据决定重联

## 现有一般能力范围

后端有意只使用一般可用的Brlaxel sandbox API. 它不叫Blaxel快照或叉式API.

节日 `bootstrap()` 钩子和下面的文件 `agent/sandbox/workspace` 需要一个后端来复制一个构建时间模板。 此后端不执行模板预热 。 如果配置了任一特性,则在为流量服务前会以可操作的引导失败.

将可重复使用的系统依赖性和基础文件放入 a [自定义 Blaxel 图像](https://docs.blaxel.ai/Sandboxes/Templates)设置每个持久前夕必须运行一次 `onSession()`。 。 。 .

## 生命周期

-   `create()` 用名称重新连接所保存的沙盒或从所配置的图像创建新的沙盒.
-   `onSession()` 为新的持久前夕会议进行一次性设置.
-   会话名称包括后端配置身份,因此被更改的沙盒定义会得到一个新的沙盒.
-   `captureState()` 将Blaxel沙盒的名字 持续在持续会话状态.
-   `shutdown()` 关闭活动日志流。 然后将闲置的沙盒移动到备用状态,同时保存内存,过程,和文件.

会话发现使用Blaxel资源,并不依赖于进程内注册.

## 网络政策

后端支持:

-   `"allow-all"`
-   `"deny-all"`
-   域允许列表
-   夕发头通过Blaxel的秘密后卫Egress代理进行转换

后端拒绝子网规则,请求匹配条件,以及 `forwardURL`它不会默默地削弱得不到支持的政策.

默认是 `"allow-all"`。对于生产或不可信的工作量,选择 `"deny-all"` 或第一个命令运行前的明确允许列表.

## 选项

`blaxel()` 接受标准 `SandboxCreateConfiguration` 字段,例如 `image`, (中文(简体) ), `memory`, (中文(简体) ), `region`, (中文(简体) ), `ports`, (中文(简体) ), `envs`, (中文(简体) ), `volumes`, (中文(简体) ), `ttl`, (中文(简体) ), `lifecycle`,以及 `labels`。 。 。 .

| 选项 | 目的 | 默认 |
| --- | --- | --- |
| `backendName` | 稳定后端标识符 | `blaxel` |
| `namePrefix` | 确定性Blaxel资源前缀 | `eve` |
| `networkPolicy` | 创建会话沙盒时应用的 Egress 策略 | `"allow-all"` |
| `processOutputBufferBytes` | 每个进程流的最大未读 stdout 或 stderr | 1个小米B |
| `startupTimeoutMs` | 最大冷象准备等待 | 60秒钟 |

## 兼容性

| 软件包 | 夜 间 | AI SDK 软件 | 节点.js | 默认图像 |
| --- | --- | --- | --- | --- |
| `@blaxel/eve-sandbox` 0.2.x (中文(简体) ) | 0.31.3至0.32以下 | 7.0.38至8岁以下 | 24岁或以后 | `blaxel/ts-app:latest` |

每次发布都必须通过适配器合同套件,以及一次针对其申报范围的直播前夕代理评估. 新前夕的未成年人需要经过测试的对等距离更新.

## 清理

Blaxel沙盒在它们配置的生命周期被移除之前,一直保持耐用. 设定 `lifecycle` 或者说 `ttl` 当应用程序需要自动删除不活动会话时.

## 常见问题

### @blaxel/eve-sandbox 是什么？

持续为夜行代理提供银河沙盒后端

### 如何安装 @blaxel/eve-sandbox？

在项目目录运行 npm install @blaxel/eve-sandbox，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：ai（^7\.0\.38）、eve（^0\.31\.3）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @blaxel/eve-sandbox 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @blaxel/eve-sandbox 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @blaxel/eve-sandbox 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @blaxel/eve-sandbox 可以商用吗？

@blaxel/eve-sandbox 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @blaxel/eve-sandbox 的下载量有多少？

根据 npm 官方下载统计，@blaxel/eve-sandbox 在 2026/10/09 – 2026/11/07 这 30 天内被下载 3,926 次，日均约 131 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @blaxel/eve-sandbox 还在维护吗？

最新版本 0\.3\.37 发布于 2026/11/11（今天）；至今共发布 93 个版本，其中过去 12 个月发布了 93 个；首次发布于 2026/08/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。