# @chaitin-ai/agent-compose-runtime-sdk 中文文档

规范地址：https://npmcn.com/package/%40chaitin-ai/agent-compose-runtime-sdk/

版本：0\.14\.0
npm 元数据更新时间：2026-11-06T08:10:09.920Z
中文译文更新时间：2026-11-09T09:45:53.589Z
软件包许可：LGPL-3\.0-only

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

原始 npm 页面：https://www.npmjs.com/package/%40chaitin-ai/agent-compose-runtime-sdk
原文对照：https://npmcn.com/package/%40chaitin-ai/agent-compose-runtime-sdk/?lang=original
项目主页：https://github.com/chaitin/agent-compose#readme
源码仓库：https://github.com/chaitin/agent-compose

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

- 包体积（解压后）：214 kB，64 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：1 个
- 首次发布：2026-07-10T15:16:25.436Z
- 最新版本发布：2026-11-06T08:10:09.475Z
- 近 30 天下载量：4868（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

节点Js SDK用于在代理编导的来宾运行时间内运行的脚本.

## 安装

```sh
npm install @chaitin-ai/agent-compose-runtime-sdk
```

也可以使用：`pnpm add @chaitin-ai/agent-compose-runtime-sdk`、`yarn add @chaitin-ai/agent-compose-runtime-sdk`、`bun add @chaitin-ai/agent-compose-runtime-sdk`

## README

# @chaitin-ai/代理编程时速

节点Js SDK用于在代理编导的来宾运行时间内运行的脚本.

软件包既提供命名导出, 也提供默认值 `runtime` 对象 :

```js
const { runtime } = require("@chaitin-ai/agent-compose-runtime-sdk");
```

```js
import runtime, { exec, shell, agent, llm, workflowFile, ssh } from "@chaitin-ai/agent-compose-runtime-sdk";
```

## 安装

从 npm 公共登记册安装 :

```bash
npm install @chaitin-ai/agent-compose-runtime-sdk
```

来宾图像也可以从离线柏油球上安装 SDK :

```bash
npm install --offline /opt/agent-compose/npm/agent-compose-runtime-sdk.tgz
```

## 快速启动

```js
const { runtime } = require("@chaitin-ai/agent-compose-runtime-sdk");

async function main() {
  const result = await runtime.shell("echo hello");
  runtime.log("command completed", { success: result.success });
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});
```

## 运行时路径

`runtime.paths` 曝光由环境变量解析的运行时路径 :

| 外地 | 环境变量 | 默认 |
| --- | --- | --- |
| `workspace` | `WORKSPACE` | `/workspace` |
| `stateRoot` | `STATE_ROOT` | `/data/state` |
| `runtimeRoot` | `RUNTIME_ROOT` | `/data/runtime` |
| `home` | `HOME` | `/root` |

`workspace`, (中文(简体) ), `stateRoot`,以及 `runtimeRoot` 也接受遗产的别名 `AGENT_COMPOSE_WORKSPACE`, (中文(简体) ), `AGENT_COMPOSE_STATE_ROOT`,以及 `AGENT_COMPOSE_RUNTIME_ROOT` 当主变量未设置时. `home` 没有别名.

## API 密码

### `runtime.exec(command, args?, options?)`

不扩展 shell 直接运行命令.

```js
const result = await runtime.exec("node", ["-e", "console.log(process.cwd())"]);
```

选项 :

| 选项 | 说明 |
| --- | --- |
| `cwd` | 工作目录. 默认为 `runtime.paths.workspace`。 。 。 . |
| `env` | 儿童过程环境所附的关键值对. |
| `timeoutMs` | 在此毫秒后终止命令 . |
| `maxOutputBytes` | 最大捕获字节 `stdout`, (中文(简体) ), `stderr`合并 `output`。默认为 1 MiB. |
| `rejectOnFailure` | 掷出 `CommandError` 当进程以非零状态代码退出时. |
| `streamOutput` | 儿童流程 `stdout` 财务报告和审定财务报表 `stderr` 用于当前进程。 默认为 `true`。 。 。 . |
| `forwardOutput` | 堕地. 使用 `streamOutput` 换句话说. |

返回值:

```ts
{
  stdout: string;
  stderr: string;
  output: string;
  exitCode: number;
  success: boolean;
  stdoutTruncated: boolean;
  stderrTruncated: boolean;
  outputTruncated: boolean;
}
```

默认, `runtime.exec()` 串流命令日志,这样代理编组可以在脚本仍在运行时显示活输出. 过 `{ streamOutput: false }` 静静地处决.

### `runtime.shell(script, options?)`

通过 shell 脚本运行 `bash -lc`。 。 。 .

```js
const result = await runtime.shell("echo shell:$AGENT_COMPOSE_TEST_VALUE", {
  env: { AGENT_COMPOSE_TEST_VALUE: "works" },
});
```

选项和返回值与 `runtime.exec()`启用 `runtime.shell()` 当您需要可变扩展、管道、方向调整或复合命令时.

### `runtime.agent(prompt, options?)`

在代理编导运行时间呼叫代理桥.

```js
const result = await runtime.agent("Inspect the workspace and summarize the project.");
```

过 `outputSchema` 当你需要结构化的JSON。 建议采用Zod schema:SDK将其转换为JSON Schema用于运行时代理桥并验证解析 `json` 以相同的 Zod 计划值.

```ts
import { z } from "zod";

const RiskSummary = z.object({
  summary: z.string(),
  risk: z.enum(["low", "high"]),
});

const result = await runtime.agent("Inspect the workspace and return risk.", {
  provider: "codex",
  outputSchema: RiskSummary,
});

console.log(result.json.summary);
```

当Zod计划通过时,类型 `result.json` 根据计划推断:

```ts
import { z } from "zod";

const RiskSummary = z.object({
  summary: z.string(),
  risk: z.enum(["low", "high"]),
});

const result = await runtime.agent("Inspect the workspace and return risk.", {
  provider: "claude",
  outputSchema: RiskSummary,
});

if (result.json) {
  console.log(result.json.risk);
}
```

您也可以通过一个平坦的 JSON Schema 对象,并以通则声明返回类型 :

```ts
type RiskSummary = {
  summary: string;
  risk: "low" | "high";
};

const result = await runtime.agent<RiskSummary>("Inspect the workspace and return risk.", {
  outputSchema: {
    type: "object",
    additionalProperties: false,
    properties: {
      summary: { type: "string" },
      risk: { type: "string", enum: ["low", "high"] },
    },
    required: ["summary", "risk"],
  },
});
```

选项 :

| 选项 | 说明 |
| --- | --- |
| `provider` | 代理供应商。 一个 `codex`, (中文(简体) ), `claude`, (中文(简体) ), `opencode`, (中文(简体) ), `pi`,或 `dsh`默认为 `codex`。 。 。 . |
| `stateRoot` | 代理状态根目录 。 默认为 `runtime.paths.stateRoot`。 。 。 . |
| `workspace` | 工作空间路径 。 默认为 `runtime.paths.workspace`。 。 。 . |
| `home` | 主目录. 默认为 `runtime.paths.home`。 。 。 . |
| `timeoutMs` | 在此数毫秒后终止代理桥. |
| `outputSchema` | Zod schema 或 JSON Schema 对象. 设定后返回 `json` 字段从 `finalText`。 Codex 和 Claude 支持此操作; OpenCode, Pi, 和 DSH 目前在无法使用基于chema的输出时会丢出一个不支持的错误 . |

返回值:

```ts
{
  provider: string;
  threadId: string;
  stopReason: string;
  finalText: string;
  json: unknown | null;
  transcript: string;
  stderr: string;
}
```

`finalText` 总是保存代理桥返回的原始文本。 何时 `outputSchema` 已经设定, `finalText` 一定是JSON的绳子 SDK运行 `JSON.parse(finalText)` 并存储结果 `json`如果 `outputSchema` sDK也用这个方法验证解析结果。 无 `outputSchema`, (中文(简体) ), `json` 实值 `null`。 。 。 .

错误行为 :

| 假设 | 行为 |
| --- | --- |
| `outputSchema` 不是一个简单的 JSON 对象 | `runtime.agent()` 在调用运行时间前扔出 . |
| 无法将 Zod 计划转换为 JSON Schema | `runtime.agent()` 在调用运行时间前扔出 . |
| 提供者不支持基于计划的产出 | 运行时间会丢出特定提供者的错误 。 Codex和Claude支持基于chema的输出;OpenCode,Pi,和DSH跑道报告不支持的输出. |
| 提供者返回 `finalText` 无效的 JSON | `runtime.agent()` 丢入解析错误. |
| 提供者返回不符合 Zod 计划的 JSON | `runtime.agent()` 扔出一个验证错误. |

### `runtime.workflow(script, options?)` 财务报告和审定财务报表 `runtime.workflowFile(path, options?)`

通过嘉宾运行时间CLI运行动态工作流程. `workflow()` 接受 源文本并管理一个临时脚本文件; `workflowFile()` 通过 直接调用文件 .

```js
const result = await runtime.workflowFile("workflows/inspect.js", {
  args: { area: "api" },
  provider: "codex",
  concurrency: 4,
  onUpdate(event) {
    if (event.type === "phase") {
      console.error(`phase: ${event.title}`)
    }
  },
})

console.log(result.result)
```

选项包括 `args`, (中文(简体) ), `provider`, (中文(简体) ), `model`, (中文(简体) ), `concurrency`, (中文(简体) ), `tokenBudget`, (中文(简体) ), `runId`, (中文(简体) ), `resumeRunId`, (中文(简体) ), `stateRoot`, (中文(简体) ), `workspace`, (中文(简体) ), `home`, (中文(简体) ), `timeoutMs`,以及 `onUpdate`。事件由 Stderr 逐渐解码,所以 `onUpdate` 运行 当工作流程活动时。 非事件 Stderr 返回为 `result.stderr`。 。 。 .

工作流程有效载荷抛出失败或中止 `RuntimeWorkflowError`; 其编号 `outcome` 字段保留运行的ID、代理、事件和 stderr。 无效的 CLI 协议抛出 `RuntimeWorkflowProtocolError`. SDK 超时抛出 `RuntimeWorkflowTimeoutError` 并保留部分事件和标准.

### `runtime.llm(prompt, options?)`

呼叫代理编组LLM服务. 守护进程通过 `LLM_API_PROTOCOL` (单位:千美元)`responses` 默认,或 `chat_completions` 页:1 OpenAI-兼容的聊天补全后端). 与 `outputSchema`, (中文(简体) ), `chat_completions` 使用即时指导 `response_format: json_object`没有 API严格JSON Schema反应.

```ts
const result = await runtime.llm("Summarize the workspace risk.", {
  model: "gpt-5.4",
});

console.log(result.text);
```

`runtime.llm()` 支持同样的 `outputSchema` 机制作为 `runtime.agent()`。建议使用 Zod schema : SDK 将其转换为 JSON Schema 进行 LLM 服务并验证解析 `json` 以相同的 Zod 计划值.

```ts
import { z } from "zod";

const RiskSummary = z.object({
  summary: z.string(),
  risk: z.enum(["low", "high"]),
});

const result = await runtime.llm("Inspect the workspace and return risk.", {
  model: "gpt-5.4",
  outputSchema: RiskSummary,
});

console.log(result.json.risk);
```

您也可以通过一个平坦的 JSON Schema 对象,并以通则声明返回类型 :

```ts
type RiskSummary = {
  summary: string;
  risk: "low" | "high";
};

const result = await runtime.llm<RiskSummary>("Inspect the workspace and return risk.", {
  outputSchema: {
    type: "object",
    additionalProperties: false,
    properties: {
      summary: { type: "string" },
      risk: { type: "string", enum: ["low", "high"] },
    },
    required: ["summary", "risk"],
  },
});
```

选项 :

| 选项 | 说明 |
| --- | --- |
| `model` | LLM模型名. 省略时,代理编译使用服务器侧配置. |
| `baseUrl` | 代理编译服务 URL. 默认为 `BASE_URL`,则 `HTTP_URL`,则 `AGENT_COMPOSE_BASE_URL`,则 `AGENT_COMPOSE_HTTP_URL`,则 `http://127.0.0.1:7410`。 。 。 . |
| `timeoutMs` | 在此毫秒后终止 LLM 服务请求 . |
| `outputSchema` | Zod schema 或 JSON Schema 对象. 设定后返回 `json` 字段从 `text`。 。 。 . |

返回值:

```ts
{
  text: string;
  model: string;
  responseId: string;
  finishReason: string;
  json: unknown | null;
}
```

`text` 总是保存 LLM 服务返回的原始文本。 何时 `outputSchema` 已经设定, `text` 一定是JSON的绳子 SDK运行 `JSON.parse(text)` 并存储结果 `json`如果 `outputSchema` sDK也用这个方法验证解析结果。 无 `outputSchema`, (中文(简体) ), `json` 实值 `null`。 。 。 .

### `runtime.env.get(name)`

读取环境变量。 回返 `undefined` 当变量未设定时.

```js
const value = runtime.env.get("WORKSPACE");
```

### `runtime.env.require(name)`

读取所需的环境变量。 缺少变量或空字符串时抛出.

```js
const token = runtime.env.require("API_TOKEN");
```

### `runtime.env.all()`

返回所有定义的环境变量为普通对象.

```js
const environment = runtime.env.all();
```

### `runtime.log(message, payload?)`

写入一个结构化的运行时日志行到 `stdout`。 。 。 .

```js
runtime.log("step completed", { step: "build", ok: true });
```

输出 JSON 形状 :

```ts
{
  type: "agent-compose.runtime.log";
  message: string;
  payload: unknown;
  createdAt: string;
}
```

### `runtime.report.writeMarkdown(name, content, options?)`

写入 Markdown 报告文件并返回创建的文件路径.

```js
const reportPath = await runtime.report.writeMarkdown("summary.md", "# Summary\n\nDone.");
```

选项 :

| 选项 | 说明 |
| --- | --- |
| `dir` | 输出目录. 默认为 `runtime.paths.workspace`。 。 。 . |

文件名称与 `path.basename()`,所以呼叫者应该通过一个文件名而不是一个嵌入路径.

### `runtime.ssh.prepareConfig(options)`

写入 SSH 客户端配置以达到主机并返回解析路径 。 它创建了 SSH 目录,可选地写出一个私钥,并维持一个标记块在 `~/.ssh/config` 指一个 `known_hosts` 文档.

```js
const sshConfig = await runtime.ssh.prepareConfig({
  hostAlias: "sandbox",
  hostName: "10.0.0.5",
  user: "root",
  privateKey: process.env.SANDBOX_SSH_KEY,
});

const command = runtime.ssh.command(sshConfig);
```

选项 :

| 选项 | 说明 |
| --- | --- |
| `hostAlias` | 需求 `Host` 将别名写入 `~/.ssh/config`。 。 。 . |
| `hostName` | 所需的主机名称或地址 . |
| `user` | SSH用户. 默认为 `root`。 。 。 . |
| `port` | SSH 端口. 默认为 `22`。 。 。 . |
| `proxyJump` | 可选 `ProxyJump` 目标. |
| `privateKey` | 要写的私人密钥内容 。 值必须包含 `PRIVATE KEY`; 逃脱 `\n` 序列实现正常化. |
| `privateKeyName` | 写入密钥的文件名 `~/.ssh`默认为 `id_rsa`。 。 。 . |
| `home` | 用于解析的主目录 `~/.ssh`默认为 `runtime.paths.home`。 。 。 . |
| `blockName` | 管理配置块的标记名称 。 默认为 `agent-compose-runtime-sdk`。 。 。 . |
| `strictHostKeyChecking` | 一个 `accept-new`, (中文(简体) ), `yes`,或 `no`默认为 `accept-new`。 。 。 . |

返回值:

```ts
{
  hostAlias: string;
  hostName: string;
  user: string;
  port: string;
  proxyJump?: string;
  privateKeyPath?: string;
  configPath: string;
  knownHostsPath: string;
  blockName: string;
  strictHostKeyChecking: "accept-new" | "yes" | "no";
}
```

返回的配置可转换为 shell 命令 `runtime.ssh.command(config)` (单位:千美元)`ssh …`, (中文(简体) ), `runtime.ssh.scpCommand(config)` (单位:千美元)`scp …`),以及 `runtime.ssh.options(config)` (共享资源) `-F`, (中文(简体) ), `UserKnownHostsFile`,以及 `StrictHostKeyChecking` 旗帜).

## 自定义脚本中的 OctoBus 能力

`runtime.capabilities` 允许使用已有的脚本或 Codex 兼容的运行程序 沙盒宣布的OctoBus能力没有应用侧接器. 它读取了守护进程生成的 `RUNTIME_ROOT/mpi/capabilities.json` 简介和 使用来宾图像 `grpcurl` 可执行文件通过 `CAP_GRPC_TARGET`。 。 。 .

```js
import { runtime } from "@chaitin-ai/agent-compose-runtime-sdk";

const tools = await runtime.capabilities.list();
// Select an explicitly intended tool; identical methods on different
// instances/capsets have different IDs.
const selected = tools.find((tool) => tool.id === requestedToolID);
if (!selected) throw new Error("Requested tool is unavailable");
const definition = await runtime.capabilities.describe(selected.id);
// definition.method/request/response contain reflected Protobuf text.
const result = await runtime.capabilities.call(selected.id, params, {
  timeoutMs: 30_000,
  maxOutputBytes: 256 * 1024,
  signal: abortController.signal,
});
```

`list()` 返回时 `id`, (中文(简体) ), `capset`, (中文(简体) ), `instance`, (中文(简体) ), `method`, (中文(简体) ), `request_type` 财务报告和审定财务报表 `response_type`它拒绝失踪、畸形、外出或不完整 示意图. 当守护进程准备能力时, 快照会被刷新 指南;它不是活的目录或赠款。 重新准备运行,或创建 新建沙盒,在恢复一个没有可用的目录后.

`describe()` 返回无用的 RPC,顶级请求/应答 Protobuf 文本, 财务报告和审定财务报表 `descriptorSetBase64`: 标准二进制 `google.protobuf.FileDescriptorSet` 被编码为 Base64,包括被导入的信件/enum定义. 消费者可能 用他们自己的Protobuf 库装入;它不是 JSON Schema 或被钉住的图案 核准。 临时描述文件在成败时被删除. `call()` 接受Protobuf JSON并返回 解码的JSON反应; `grpcurl` 进行反射和标准线编码. 熟知消息可能使用scalar、数组或无效的JSON格式;输入包含 未定义,非无限数字或其他非JSON值在引用前失败. 在援引商业理由之前,拒绝采用流动方法。 没有发现 或SDK验证取代近似/OctoBus授权或业务核准. 从方法名称中不推断出只读分类.

每个选项 `grpcurl` 操作. `describe()` 进行三次反省 操作; `call()` 检查一下方法,并引用一次。 使用 `signal` (单位:千美元) 共享端到端截止日期 。 电话没有被重审。 JSON请求仅限于 256 KiB;输出默认为256 KiB并可能设置为1个米B. 超过 限制失败, 而不是返回已截断的 JSON 。 相同的产出限制适用 到Base64编码前设置的二进制描述符。 上游诊断不是 已转发或附上错误。 CAP 证书使用信头环境 请求JSON被发送到Stdin, 避免两者在argv之外.

现有的 Codex 事件输出和业务路由可能被保留. 这个API 不执行模式/工具循环。 脚本仍然拥有自己的商业决定权 和预测.

守护进程发布完整的目录和带有原子的Markdown快照 重命名仅限于沙盒目录 。 来宾创建的符号链接无法重定向 这些主机在目录外写。 来源 URL 保留其默认端口 当转换为 grpcurl 地址时.

## 错误

何时 `rejectOnFailure` 启用,从 `runtime.exec()` 或者说 `runtime.shell()` 掷出 `CommandError`。错误对象包含:

| 外地 | 说明 |
| --- | --- |
| `command` | 执行的命令 . |
| `args` | 辩相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相. |
| `result` | 命令结果对象,形状相同,由 `runtime.exec()` 或者说 `runtime.shell()`。 。 。 . |

```js
const { runtime, CommandError } = require("@chaitin-ai/agent-compose-runtime-sdk");

try {
  await runtime.shell("exit 1", { rejectOnFailure: true });
} catch (error) {
  if (error instanceof CommandError) {
    runtime.log("command failed", { exitCode: error.result.exitCode });
  }
}
```

## 常见问题

### @chaitin-ai/agent-compose-runtime-sdk 是什么？

节点Js SDK用于在代理编导的来宾运行时间内运行的脚本\.

### 如何安装 @chaitin-ai/agent-compose-runtime-sdk？

在项目目录运行 npm install @chaitin-ai/agent-compose-runtime-sdk，或使用 pnpm add / yarn add / bun add。

### @chaitin-ai/agent-compose-runtime-sdk 支持 TypeScript 吗？

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

### @chaitin-ai/agent-compose-runtime-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @chaitin-ai/agent-compose-runtime-sdk 需要什么版本的 Node\.js？

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

### @chaitin-ai/agent-compose-runtime-sdk 可以商用吗？

@chaitin-ai/agent-compose-runtime-sdk 使用 LGPL-3\.0-only 许可。弱 Copyleft：作为库被调用时通常不要求开源你自己的代码，但修改库本身需以 LGPL 开源；前端打包合并后的适用边界存在不同理解。以上为概括，不构成法律意见，请以许可原文为准。

### @chaitin-ai/agent-compose-runtime-sdk 的下载量有多少？

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

### @chaitin-ai/agent-compose-runtime-sdk 还在维护吗？

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