# @execution-associates/isb 中文文档

规范地址：https://npmcn.com/package/%40execution-associates/isb/

版本：4\.1\.2
npm 元数据更新时间：2026-11-09T13:02:20.213Z
中文译文更新时间：2026-11-14T03:29:49.690Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40execution-associates/isb
原文对照：https://npmcn.com/package/%40execution-associates/isb/?lang=original
项目主页：https://github.com/execution-associates/isb/tree/main/sdk/typescript#readme
源码仓库：https://github.com/execution-associates/isb

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

- 包体积（解压后）：193 kB，30 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-09-29T03:30:57.034Z
- 最新版本发布：2026-11-09T13:02:19.854Z
- 近 30 天下载量：3138（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：64（近 12 个月 64 个）

## 中文简介

SDK 类型SDK for isb: 声明式墨盒 (容器和 VMs)

## 安装

```sh
npm install @execution-associates/isb
```

也可以使用：`pnpm add @execution-associates/isb`、`yarn add @execution-associates/isb`、`bun add @execution-associates/isb`

## README

# @ execution- assisters/ isb( 执行- 联系)

类型脚本 SDK [义b](https://github.com/execution-associates/isb)数字 : 声明式沙盒(容器和VM)。 这是一个瘦客户 `isb rpc`,一个线性限定的 JSON 协议, 覆盖 isb 二进制的 stdin 和 静态( t)[参考文件/参考文件/](https://npmcn.com/package/docs/reference/rpc.md). isb 工作; SDK 开始 它,发送请求和输入结果.

-   邦先;节点20或后起也行. 仅限无害环境管理.
-   没有运行时间依赖 .
-   光谱对象精确使用作曲 YAML 的字段名 (单位:千美元)[文件/参考资料/汇编](https://npmcn.com/package/docs/reference/compose.md)),因此可以在YAML之间复制一个 spec 密码 SDK选项为骆驼Case.

## 安装

```sh
bun add @execution-associates/isb
```

软件包有可选的依赖性 `@execution-associates/isb-linux-x64` 财务报告和审定财务报表 `@execution-associates/isb-linux-arm64`,每个携带释放的 该平台的签名是 b 二进制, 对照发布签名检查 当软件包用 npm 出处构建和发布时。 用来使用Isb 您安装了安装器, 设置 `ISB_BIN=$(command -v isb)`编辑 二进制在此顺序中 :

1.  `new Client({ isbBin })`
2.  `$ISB_BIN`
3.  平台软件包`bin/isb` 在里面) ("内地")
4.  `isb` 打开 `PATH`

isb 需要访问插件套接字, 这在主机上相当于根 .

## 快速启动

```ts
import { PortBinding, Sandbox, Volume } from "@execution-associates/isb";

const sb = await Sandbox.connectOrCreate({
  container_name: "dev-web",
  image: "dev-base",
  cpus: 4,
  mem_limit: "8g",
  labels: { app: "web" },
  environment: { NODE_ENV: "development" },
  volumes: [
    Volume.bind("/srv/src", "/home/dev/src", { device: "src" }),
    Volume.named("dev-cache", "/home/dev/.cache", { owner: "dev" }),
    "/srv/ref:/home/dev/ref:ro", // the short form works too
  ],
  ports: [
    PortBinding.publish("5173-5193", 5173, { name: "vite" }), // first free port
    "127.0.0.1:8080:80",
  ],
  ready: ["running", "default_route", { user_exists: "dev" }],
  user: "dev",
  working_dir: "/home/dev/src",
});
console.log(sb.lastReport?.ports); // device name -> listen address in use

// Captured output. argv is never joined into a shell string.
const out = await sb.exec("printf", ["[%s]", "a b"]);
console.log(out.exitCode, out.stdoutText); // 0 "[a b]"

// Streaming output, piped stdin, signals.
const proc = await sb.execStream(["sh", "-c", "cat; echo done >&2"], {
  stdin: "piped",
});
await proc.write("hello\n");
await proc.closeStdin();

const decoder = new TextDecoder();
for await (const event of proc) {
  process.stdout.write(`${event.kind}: ${decoder.decode(event.data)}`);
}
console.log("exit code:", await proc.wait());

await sb.remove({ force: true });
```

作曲文件 :

```ts
import { Project } from "@execution-associates/isb";

const project = await Project.load({
  files: ["isb.yaml"],
  vars: { WORKTREE: process.cwd() },
});
console.log(project.name, project.services);

for (const plan of await project.plan()) {
  console.log(plan.name, plan.actions);
}

// Like `isb up -d`: resolves once the sandboxes are ready. A service's
// `command` is for the foreground CLI `isb up` and is not run here.
const reports = await project.up({
  onProgress: (line) => console.error(line),
});

// A sandbox from the project carries its service's exec defaults.
const web = project.sandbox("web");
await web.exec(["bun", "install"]);

await project.down();
```

## API 密码

### 客户端

`new Client({ isbBin?, socket?, project?, createTimeout?, cwd?, env?, spawner? })` 拥有一个长寿 `isb rpc` 子进程, 始于第一个请求. `socket`, (中文(简体) ), `project` 财务报告和审定财务报表 `createTimeout` 成为全球旗帜 `--socket`, (中文(简体) ), `--project` 财务报告和审定财务报表 `--create-timeout`。客户端检查服务器的问候和 拒绝1以外的协议。 请求同时运行并匹配 编号.

每个调用都使用可选对象选项 `client`如果没有一个 共享 `defaultClient()` 已使用(`setDefaultClient()` 改为:.

-   `await client.close()` 关闭服务器的 stdin 并等待它退出 . `await using client = new Client()` 在范围结束时也这样做.
-   闲置的客户端不能让进程活着,所以脚本从不调用 `close()` 仍然离开。 与 `spawner: "bun"` (Bun. spawn 代替: `node:child_process`,它会一直到 `close()`。 。 。 .
-   如果子进程已终止, 待决请求以 `ProcessExitedError` (带有退出状态并结束其 stderr)和下一个请求开始 一个新的.
-   `client.request(method, params, onEvent?)` 直接发送任何 rpc 方法 .

### 沙盒

静态 :

| 方法 | 已经 |
| --- | --- |
| `Sandbox.create(spec, { baseDir?, volumes?, waitReady?, onProgress? })` | 创建; `AlreadyExistsError` 如果它存在的话 |
| `Sandbox.connectOrCreate(spec, { ..., pruneDevices? })` | 创建或调节( e)`isb up` 一个沙盒; 报告 `sb.lastReport` |
| `Sandbox.plan(spec, { baseDir?, volumes?, pruneDevices? })` | 什麽 `connectOrCreate` 将更改: `Plan` |
| `Sandbox.resolve(spec, ...)` | 针对此主机的 spec 解析 |
| `Sandbox.get(name)` | 现有沙盒; `NotFoundError` 如果缺少 |
| `Sandbox.listWith({ labels })`, (中文(简体) ), `Sandbox.list()` | `SandboxInfo[]`标签为 `{ key: "value", other: null }` 或者说 `["key=value", "other"]` |
| `Sandbox.remove(name, { force? })` | 删除; 运行中需要 `force` |

`spec` 是一个 `SandboxSpec` (单位:千美元) `services.<service>` 作曲对象 格式)与 `container_name` (实例名称)和 `image` 所需经费. `baseDir` 锁定相对绑定路径( 默认: 子进程正在工作) 目录). `volumes` 持有名量定义, 如作曲文件 顶级 `volumes:`: 一个山上 `source` 名称定义的密钥,以及 该定义是 `name`,否则键本身(一个没有 定义使用 `source` 作为主音量名称. `onProgress` 接收 线条例如 `web: creating from dev-base`。 。 。 .

实例 : `info()`, (中文(简体) ), `labels()`, (中文(简体) ), `start()`, (中文(简体) ), `stop({ force?, timeout? })`, (中文(简体) ), `restart()`, (中文(简体) ), `waitReady({ ready?, readyTimeout? })`, (中文(简体) ), `remove({ force? })`, (中文(简体) ), `addPort(port)` 联合国 `ports` 条目; 返回正在使用的收听地址 , `removeDevice(name)` (返回它是否在那里), `exec(...)`, (中文(简体) ), `execStream(...)`。 。 。 .

一个沙盒由 `create`, (中文(简体) ), `connectOrCreate` 或者说 `project.sandbox()` 记得 spec的执行默认, `user`, (中文(简体) ), `working_dir`, (中文(简体) ), `exec.env` 财务报告和审定财务报表 `exec.login` (同意每个执行官,作为 `sb.execDefaults`页:1 `ready` 财务报告和审定财务报表 `ready_timeout` (使用时间: `waitReady()` . . . . . . 一个来自 `get` 没有. `execDefaultsOf(spec)` 计算相同的默认值.

### 执行

```ts
sb.exec(cmd, args?, {
  cwd?,
  user?,
  env?,
  login?,
  timeout?,
  stdin?,
  tty?,
  width?,
  height?,
})
```

`cmd` 程序为 `args` 作为其参数,或整个 argv 数组. `timeout` 是秒或持续时间字符串(`"90s"`, (中文(简体) ), `"5m"`;通过命令 被杀死,电话被拒绝 `IsbTimeoutError` (单位:千美元)`code: "exec_timeout"`) (中文(简体) ). `stdin` 是一个字符串或字节。 单调选项覆盖沙盒的执行 默认值.

它决定一个 `ExecOutput`数字 : `exitCode`, (中文(简体) ), `stdout` 财务报告和审定财务报表 `stderr` (字节),和 获取器 `stdoutText`, (中文(简体) ), `stderrText` 页:1 `success` (出站码为0). A 类 非零退出代码不是一个错误.

`sb.execStream(cmd, args?, opts)` 选择相同的选项 `stdin` (单位:千美元) 接受 `"piped"`,并决心 `ExecProcess` 只要请求是 发送时间 :

-   `for await (const ev of proc)`数字 : `{ kind: "stdout" | "stderr", data: Uint8Array }` 按每条溪流顺序排列。 一个消费者。 输出被缓冲直到读取 .
-   `write(data)`, (中文(简体) ), `closeStdin()`: 与 `stdin: "piped"`。 。 。 .
-   `signal(15)` 或者说 `signal("SIGTERM")`, (中文(简体) ), `resize(width, height)` (仅限).
-   `wait()`:出站代码. `output()`:读完其余内容,然后返回 `ExecOutput`。 。 。 .

与 `tty: true` 所有输出都以stdout的形式到达.

### 构建器

他们把服务品的普通条目还给我 `volumes` 财务报告和审定财务报表 `ports` 列表,列在 长窗体; 短字符串 (`"./src:/home/dev/src:ro"`, (中文(简体) ), `"8080:80"`可能会是 自由混杂.

-   `Volume.bind(hostPath, target, { readOnly?, device?, options? })`数字 : `{type: "bind", source, target, ...}`。 。 。 .
-   `Volume.named(name, target, { external?, owner?, readOnly?, pool?, device?, options? })`数字 : `{type: "volume", source, target, ...}`,如果缺少则创建,除非 `external: true` (音量必须存在).
-   `PortBinding.publish(published, target, { hostIp?, protocol?, name?, options? })`数字 : 多克的长端口形式. `hostIp` 默认为 127.0.0.1.A `published` 范围 (单位:千美元)`"5173-5223"`单人 `target` 取其中的第一个自由端口.
-   `PortBinding.host(listen, connect, { name?, search?, options? })`: 线索 代理在主机上监听,并在嘉宾中连接,并加注 地址(`5173`, (中文(简体) ), `"0.0.0.0:5173"`, (中文(简体) ), `"5353/udp"`, (中文(简体) ), `"tcp:HOST:PORT"`) (中文(简体) ). `search: N` 返回 a `publish` 输入范围 `listen`.`listen+N` 转而投出 `TypeError` 当地址无法写入时 方式(一个端口范围,一个unix socket,一个连接主机而不是默认).
-   `PortBinding.guest(listen, connect, { name?, options? })`: 倾听在 宾客,在主机上连接.

### 项目(组成)

`Project.load({ files?, envFiles?, projectName?, vars?, client? })` 负载, 插入并合并不触碰主控的文件。 无 `files` 写着 `isb.yaml` (或 `isb.yml`)在子进程的工作目录中,加 `isb.override.yaml` (或 `.yml`旁边;无 `envFiles`, (中文(简体) ), `.env` 旁边 第一个文件如果存在. `vars` 胜过isb的环境 子进程和 env 文件。 该项目已经 `name`, (中文(简体) ), `baseDir`, (中文(简体) ), `files`, (中文(简体) ), `file` (决 议 `ComposeFile`和 `services`。 。 。 .

-   `up({ services?, pruneDevices?, waitReady?, onProgress? })`数字 : `[{ service, report }]`
-   `plan({ services?, pruneDevices? })`数字 : `Plan[]`
-   `down({ services?, volumes?, onProgress? })`
-   `spec(service)`, (中文(简体) ), `sandbox(service)`

### 音量和音量

-   `volumes.list({ pool? })`, (中文(简体) ), `volumes.get(name, { pool? })`, (中文(简体) ), `volumes.create(name, { pool?, config? })` (单位:千美元)`{ created, pool }`, (中文(简体) ), `volumes.remove(name, { pool? })`
-   `prune(label, { dryRun? })`: 砂盒,其 `label` 值是一个主机路径 已经不复存在。 干燥,除非 `dryRun: false`。 。 。 .

### 类型

类别`SandboxSpec`, (中文(简体) ), `VolumeSpec` =字符串 === `VolumeMount`, (中文(简体) ), `PortSpec` =字符串 === `PortMapping` | `ProxyPort`, (中文(简体) ), `MapOrList`, (中文(简体) ), `Command`, (中文(简体) ), `ExecSpec`, (中文(简体) ), `ReadyCheck`, (中文(简体) ), `IdmapSpec`, (中文(简体) ), `NamedVolumeSpec`, (中文(简体) ), `ComposeFile`, (...) (中文(简体) ) 从 `isb schema` 输入 `src/spec.ts`。结果如下: `SandboxInfo`, (中文(简体) ), `ApplyReport`, (中文(简体) ), `Plan` (与 `Action` 工会,由 `action`, (中文(简体) ), `VolumeInfo`, (中文(简体) ), `PruneItem`· ; `ExecDefaults` 是执行- 默认形状 rpc 方法选择。 结果的字段名称是 Isb 发送它们 (snake case) (英语).

## 错误

每一个失败都是以 `IsbError` 携带 `code`, (中文(简体) ), `message` 财务报告和审定财务报表 `data` (文件/参考资料/rpc.md列出它们)。 按代码划分的子类 :

| 类 | 代码 |
| --- | --- |
| `NotFoundError` | `not_found` |
| `AlreadyExistsError` | `already_exists` |
| `NotReadyError` | `not_ready` |
| `IsbTimeoutError` | `request_timeout`, (中文(简体) ), `operation_timeout`, (中文(简体) ), `exec_timeout` |
| `InvalidError` | `invalid`, (中文(简体) ), `interpolation`, (中文(简体) ), `parse` |
| `ConnectError` | `connect` (责任无法到达; `data.socket`(中文(简体) ) |
| `ProtocolError` | `protocol` (也是一种未知的方法), `bad_request`, (中文(简体) ), `websocket`一个糟糕的你好 |
| `ProcessExitedError` | `process_exited`: 无法启动或死亡子进程 |
| `ClientClosedError` | `closed`: 客户端已关闭 |
| `IsbError` | 其它东西`api`, (中文(简体) ), `operation_failed`, (中文(简体) ), `io`, (中文(简体) ), `json`(中文(简体) ) |

## 发展

类型由isb 二进制的系统生成 :

```sh
ISB_BIN=/path/to/isb bun run gen-types    # rewrites src/spec.ts
```

Dev 依赖性(TypeScript, Biome, json-schema- to-typescript)仅用于 字型检查、林入、类型生成和建筑。 测试导入自 `src/` 只有,所以他们跑没有 `bun install`数字 :

```sh
ISB_BIN=/path/to/isb bun test                                  # unit tests, no incus
ISB_INTEGRATION=1 ISB_BIN=/path/to/isb bun test                # plus integration tests
bun install && bun run typecheck && bun run lint && bun run build
```

单位测试运行真实 `isb rpc` 对不存在的套接字,加 小假服务器. 一体化测试需要加强,当地形象需要 `dev` 用户在 uid 1000(`ISB_TEST_IMAGE`默认值 `dev-base`) (中文(简体) ). 所有他们 创建名称 `isb-test-ts-<pid>-...` 并被清除后,通过或失败.

## 许可证

SDK是麻省理工学院的.

其安装的平台包( :`@execution-associates/isb-linux-x64`, (中文(简体) ), `@execution-associates/isb-linux-arm64`(b) 承接在 [执行助理 来源 许可证 1.0](https://github.com/execution-associates/isb/blob/main/LICENSE) (EXA-SL-1.0) (中文(简体) ).

## 常见问题

### @execution-associates/isb 是什么？

SDK 类型SDK for isb: 声明式墨盒 \(容器和 VMs\)

### 如何安装 @execution-associates/isb？

在项目目录运行 npm install @execution-associates/isb，或使用 pnpm add / yarn add / bun add。

### @execution-associates/isb 支持 TypeScript 吗？

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

### @execution-associates/isb 支持 ESM 还是 CommonJS？

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

### @execution-associates/isb 需要什么版本的 Node\.js？

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

### @execution-associates/isb 可以商用吗？

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

### @execution-associates/isb 的下载量有多少？

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

### @execution-associates/isb 还在维护吗？

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