# @e2b/convex 中文文档

规范地址：https://npmcn.com/package/%40e2b/convex/

版本：0\.1\.1
npm 元数据更新时间：2026-09-14T13:03:56.822Z
中文译文更新时间：2026-11-13T03:13:38.440Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40e2b/convex
原文对照：https://npmcn.com/package/%40e2b/convex/?lang=original
项目主页：https://github.com/e2b-dev/e2b-convex#readme
源码仓库：https://github.com/e2b-dev/e2b-convex

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

- 包体积（解压后）：328 kB，119 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：3 个
- peer 依赖：ai ^7\.0\.0，convex ^1\.45\.0，@convex-dev/agent ^0\.7\.1
- 首次发布：2026-09-14T10:25:28.052Z
- 最新版本发布：2026-09-14T13:03:56.169Z
- 近 30 天下载量：16406（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

Convex 代理应用的 E2B 沙盒

## 安装

```sh
npm install @e2b/convex
```

也可以使用：`pnpm add @e2b/convex`、`yarn add @e2b/convex`、`bun add @e2b/convex`

## README

# @ e2b/ convex

持久性 [E2B 软件](https://e2b.dev/) 用于Convex应用程序和AI代理的沙盒.

`@e2b/convex` 是一个有小V8兼容的 E2B 客户端的无表 Convex 组件。 它赋予了Convex动作沙盒生命周期,命令,被捆绑的文件操作,预览主机,Convex Agent工具,以及平版AI SDK工具而无需将全节点导向的E2B SDK运入Convex运行时间.

> 前1.0:在生产使用前根据您的 E2B 模板和网络政策验证软件包.

## 安装

```sh
npm install @e2b/convex
npx convex env set E2B_API_KEY e2b_your_key
```

在您的 Convex 应用程序中注册组件并绑定该秘密 :

```ts
// convex/convex.config.ts
import e2b from "@e2b/convex/convex.config.js";
import { defineApp } from "convex/server";
import { v } from "convex/values";

const app = defineApp({ env: { E2B_API_KEY: v.string() } });
app.use(e2b, { env: { E2B_API_KEY: app.env.E2B_API_KEY } });

export default app;
```

## 运行命令

在 Convex 动作中创建客户端, 并用应用程序拥有的识别沙盒 `scope` 财务报告和审定财务报表 `key`数字 :

```ts
// convex/sandbox.ts
import { E2B } from "@e2b/convex";
import { v } from "convex/values";
import { components } from "./_generated/api";
import { action } from "./_generated/server";

const sandboxes = new E2B(components.e2b, {
  template: "base",
  timeoutMs: 10 * 60_000,
});

export const run = action({
  args: { userId: v.string(), sessionId: v.string(), command: v.string() },
  handler: async (ctx, args) => {
    const identity = { scope: args.userId, key: args.sessionId };
    const sandbox = await sandboxes.getOrCreate(ctx, identity);

    return sandboxes.runCommand(ctx, {
      ...identity,
      sandboxId: sandbox.sandboxId,
      command: args.command,
    });
  },
});
```

使用相同的范围与密钥重复使用相同的运行或暂停的沙盒。 在平行工作之前解决一次,然后通过 `sandboxId` 之后的行动.

## 一体化

-   **最小 API :** 生命周期、 shell 命令、文件、目录和预览主机.
-   **顶层代理 :** `createAgentTools(sandboxes, ...)` 从 `@e2b/convex/agent` 创建有可选审批规则的线性意识工具。 要求数 `@convex-dev/agent` 财务报告和审定财务报表 `ai`。 。 。 .
-   **AI SDK: (英语)** `createAiSdkTools(sandboxes, ctx, ...)` 从 `@e2b/convex/ai` 在任何 Convex 动作中创建标准的 AI SDK 工具. 要求数 `ai`。 。 。 .

核心软件包对两者都没有运行时间依赖性;只为您使用的集成安装.

开始于 [正在启动指南](https://npmcn.com/package/%40e2b/convex/docs/getting-started.md),然后使用复制页 [烹饪本](https://npmcn.com/package/%40e2b/convex/docs/cookbook.md)。完整的本地应用程序 [`example`](https://npmcn.com/package/%40e2b/convex/example/README.md) 包括一个xterm.js终端和一个带有可见工具呼叫的实时代理聊天.

## 默认和限制

-   沙盒在超时暂停,通过命名空间的 E2B 元数据被重新发现. 暂停的沙盒上的任何操作都会恢复它,从而重新开始计费.
-   每个操作先解决沙盒(`getInfo` + 键 `connect`,或元数据列表 `sandboxId` 大约每通电话增加一次.
-   范围和关键值在输入E2B元数据之前被散列.
-   指令输出默认为每流32 KiB.
-   命令输出和单个文件读取被封为 1 MiB.
-   文件读取默认为64 KiB;写作被封为4 MiB.
-   文件工具仅限 `/home/user` 财务报告和审定财务报表 `/tmp` 除非另有配置.
-   `getHost` 除非明确允许,否则不接触代理人.
-   每个E2B请求都有标记 `e2b-convex/<version>` 用于整合归属.

见 [警卫](https://npmcn.com/package/%40e2b/convex/docs/security.md), (中文(简体) ), [业务](https://npmcn.com/package/%40e2b/convex/docs/operations.md),以及 [结构](https://npmcn.com/package/%40e2b/convex/docs/architecture.md) 在部署执行不可信指令的代理人之前.

## 状态

该套件使用E2B的公用API,并仅包括组件需要的Process和Filesystem协议描述符. 被钉住 `e2b` 软件包是一个只开发的协议源。 CI 拒绝在已发射的 Convex 运行时间中输入节点内置或全SDK 和用于协议漂移的预定实时测试表 .

麻省理工学院

## 常见问题

### @e2b/convex 是什么？

Convex 代理应用的 E2B 沙盒

### 如何安装 @e2b/convex？

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

### @e2b/convex 支持 TypeScript 吗？

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

### @e2b/convex 支持 ESM 还是 CommonJS？

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

### @e2b/convex 需要什么版本的 Node\.js？

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

### @e2b/convex 可以商用吗？

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

### @e2b/convex 的下载量有多少？

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

### @e2b/convex 还在维护吗？

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