# @celestoai/sdk 中文文档

规范地址：https://npmcn.com/package/%40celestoai/sdk/

版本：0\.1\.6
npm 元数据更新时间：2026-09-16T20:28:22.884Z
中文译文更新时间：2026-11-09T07:19:25.186Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：833 kB，39 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：1 个
- 首次发布：2026-01-13T12:31:55.940Z
- 最新版本发布：2026-09-16T20:28:22.522Z
- 近 30 天下载量：7845（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 7 个）

## 中文简介

Celesto SDK——Node.js的管理代理人、守门员和计算机客户

## 安装

```sh
npm install @celestoai/sdk
```

也可以使用：`pnpm add @celestoai/sdk`、`yarn add @celestoai/sdk`、`bun add @celestoai/sdk`

## README

# @ ceslestoai/ sdk

使用此软件包在 Celesto 从一个 Node.js app 运行工作 。 您的代码可以创建 云计算机,在其中运行命令,工作完成后删除.

AI代理是能够计划和运行任务的软件. 绳子是密码 启动、测试或监督代理人.

要使用此软件包时 :

-   在干净的电脑上运行一个人工智能代理或操纵器.
-   从 JavaScript 或 TypeScript 运行 shell 命令 .
-   保持代理工作与你的笔记本电脑、服务器或生产系统分开.
-   为每个用户运行一个代理,每个用户开支限额.
-   要求用户通过守门员批准Google Drive的访问权限.

守门员是塞莱斯多的出入口助手. 它让用户批准哪个外部 您的应用程序可以使用的文件或文件夹 .

## 所需资源

-   节点.js 18或更新.
-   来自 Celesto API 密钥 [Celesto 设置](https://celesto.ai/) 下级 **设置 > 警卫**。 。 。 .

## 安装

```bash
npm install @celestoai/sdk
```

签一次Celesto CLI:

```bash
pip install celesto
celesto auth login
```

这个 `Computer` API 检查明确通过的 `token` 或者说 `apiKey` 先说 `CELESTO_API_KEY` 在外壳中,当前工程的 `.env`,并保存证书 `celesto auth login`。您可以使用本地语言 `.env` 代替CLI:

```bash
CELESTO_API_KEY="your-api-key"
```

添加 `.env` 改为 `.gitignore`。 。 。 .

## 快速启动

创建名为的文件 `quickstart.mjs`数字 :

```js
import { Computer } from "@celestoai/sdk";

const computer = await Computer.create();
try {
  console.log(`Computer ready: ${computer.name}`);

  const result = await computer.run("uname -a");
  console.log(result.stdout);
} finally {
  await computer.delete();
}
```

运行它:

```bash
node quickstart.mjs
```

## 为您的用户运行代理

如果你在人工智能代理之上制造产品 每一次运行都会发生 联 合 国 __ 用户。 Celesto 把它们分开: 每个运行都记录在用户的名下 它的作用,所以你可以看到 那个人的代理人做了什么,花费 停止它花费超过你允许的.

您用您已有的字符串识别您的每个用户 —— 数据库ID, 电子邮件,任何东西。 塞莱斯托在你寄来的时候就储存起来 没有 Celesto 用户 要抬头看的身份证, 没有地图表可以保存 .

此示例创建代理, 为一个用户运行, 打印答案 到了,然后读了用户的支出.

```ts
import { ManagedAgentsClient } from "@celestoai/sdk";

const celesto = new ManagedAgentsClient({ apiKey: process.env.CELESTO_API_KEY });

const agent = await celesto.agents.create({
  name: "support-bot",
  model: "openai/gpt-5.4-mini",
  instructions: "Answer order questions in one short paragraph.",
});

for await (const event of celesto.runs.stream(agent.id, {
  input: "Where is my order?",
  endUserId: "usr_8837",
})) {
  if (event.name === "message.delta") process.stdout.write(event.data.text ?? "");
}

const { budget } = await celesto.endUsers.get("usr_8837");
console.log(`\nSpent ${budget.spentUsd} of ${budget.capUsd}`);
```

正在打开 `event.name` 缩小事件,所以 `event.data` 输入为 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}没有别的.

### 等待而不是流

`stream()` 给您答案,因为它是写. `create()` 等着给你 完成运行 :

```ts
import { ManagedAgentsClient } from "@celestoai/sdk";

const celesto = new ManagedAgentsClient({ apiKey: process.env.CELESTO_API_KEY });
const agentId = "agt_your_agent_id";

const run = await celesto.runs.create(agentId, {
  input: "Where is my order?",
  endUserId: "usr_8837",
});
console.log(run.output, run.usage.costUsd);
```

### 钱 是一个字符串

每一数额 -- `costUsd`, (中文(简体) ), `spentUsd`, (中文(简体) ), `capUsd` - 是小数字符串,例如 `"0.000450"`从来没有 `number`单一个答案可以花费几百万分之一 美元, JavaScript 数字不能准确持有。 显示和比较 字符串; 如果您需要算术, 请使用小数库而不是 `parseFloat`。 。 。 .

写作也是弦. `budgetCapUsd` 输入 `string`,因此数字失败 编译,通过一个反正扔,而不是寄出去—— `0.1 + 0.2` 字符串为 `"0.30000000000000004"`,唯一一个仍然可以 固定在离开程序之前.

### 设置支出限制

给一个用户一个盖子, 或者为每个人设置默认值 :

```ts
import { ManagedAgentsClient } from "@celestoai/sdk";

const celesto = new ManagedAgentsClient({ apiKey: process.env.CELESTO_API_KEY });

await celesto.endUsers.update("usr_8837", { budgetCapUsd: "5.00" });
await celesto.settings.update({ defaultEndUserBudgetUsd: "0.50" });
```

盖盖覆盖一个开始用户第一次运行的30天窗口 任何东西。 当它耗尽时, 下一跑抛出 `BudgetExceededError`运行 已经在飞行中停了下来 `run.failed` 活动.

### 安全重试

过 `idempotencyKey` 使重试安全:再次发送相同的密钥返回 已经发生的运行 而不是运行代理 - 并充电您 用户——两次.

```ts
import { ManagedAgentsClient } from "@celestoai/sdk";

const celesto = new ManagedAgentsClient({ apiKey: process.env.CELESTO_API_KEY });
const agentId = "agt_your_agent_id";

const run = await celesto.runs.create(agentId, {
  input: "Where is my order?",
  endUserId: "usr_8837",
  idempotencyKey: "order-status-42",
});
```

一次谈话一个代理。 如果第二次跑来的时候 先是继续,塞莱斯多扔 `SessionBusyError`。通过 `maxRetries: 2` 改为 等待并再次尝试; SDK 为您创建了一等键 .

### 继续对话

每次运行都属于一个会话,这就是用户的笔录. 离开 `sessionId` celesto开始一个; 传回去继续:

```ts
import { ManagedAgentsClient } from "@celestoai/sdk";

const celesto = new ManagedAgentsClient({ apiKey: process.env.CELESTO_API_KEY });
const agentId = "agt_your_agent_id";

const first = await celesto.runs.create(agentId, {
  input: "Hello",
  endUserId: "usr_8837",
});
const followUp = await celesto.runs.create(agentId, {
  input: "And the one before that?",
  endUserId: "usr_8837",
  sessionId: first.sessionId,
});
```

### 更改代理

更新代理保存新版本, 并让旧版本可以读取 。 运行 记住他们用过的版本,所以一个变化永远不会重写已经 发生了. `celesto.agents.activateVersion(agent.id, 1)` 回头看.

## 计算机

电脑是您的应用或代理的可支配云机。 默认, Celesto 创建 `scratch` 电脑,是一种最小的Ubuntu电脑.

### 用自定义资源创建

创建名为的文件 `create-computer.mjs`数字 :

```js
import { Computer } from "@celestoai/sdk";

const computer = await Computer.create({
  cpus: 2,
  memory: 2048,
  disk: "15gb",
});

try {
  console.log(computer.name, computer["name"]);
} finally {
  await computer.delete();
}
```

Omit CPU,内存,或磁盘字段可以使用默认大小. `disk` 接受 MB 为 整数或字符串,例如 `"2gb"`。 。 。 .

计算机默认为麻黄. 留着 `/home/ohm` 停止并恢复, 当创建计算机时, 启用一个持久家:

```js
import { Computer } from "@celestoai/sdk";

const computer = await Computer.create({ persistentHome: true });
```

此设置以后无法更改 .

### 控制互联网接入

互联网默认开通. 创建外部连接时禁用 计算机 :

```js
import { Computer } from "@celestoai/sdk";

const computer = await Computer.create({ networkPolicy: { mode: "off" } });
try {
  console.log((await computer.run("uname -a")).stdout);
} finally {
  await computer.delete();
}
```

命令和终端会话仍然无法上网。 政策 幸存的停止/ 启动和快照还原, 并且在 创建。 恒活家庭使用外部体积,所以不能结合 `networkPolicy: { mode: "off" }` 与 `persistentHome: true`域和 IP 允许列表不支持 .

### 模板

需要安装额外工具的计算机时使用模板. 譬如说, `coding-agent` 包括用于编码任务的通用工具.

列出可用的模板 :

创建名为的文件 `list-templates.mjs`数字 :

```js
import { Computer } from "@celestoai/sdk";

const templates = await Computer.listTemplates();
for (const template of templates) {
  console.log(template.id, template.defaultRamMb);
}
```

从模板创建计算机 :

```js
import { Computer } from "@celestoai/sdk";

const computer = await Computer.create({ templateId: "coding-agent" });
try {
  console.log(computer.name);
} finally {
  await computer.delete();
}
```

### 运行命令

创建名为的文件 `run-command.mjs`数字 :

```js
import { Computer } from "@celestoai/sdk";

const computer = await Computer.create();
try {
  const result = await computer.run("ls -la", {
    timeout: 60,
  });

  console.log(result.exitCode);
  console.log(result.stdout);
  console.error(result.stderr);
} finally {
  await computer.delete();
}
```

命令运行时流出输出 :

```js
import { Computer } from "@celestoai/sdk";

const computer = await Computer.get("curie");
const controller = new AbortController();

for await (const event of computer.runStream("npm test", {
  timeout: 300,
  signal: controller.signal,
})) {
  if (event.type === "stdout") process.stdout.write(event.data);
  if (event.type === "stderr") process.stderr.write(event.data);
  if (event.type === "exit") console.log(`Exit code: ${event.exitCode}`);
}
```

打电话 `controller.abort()` 以阻止溪流和远程命令.

### 管理计算机

`computerId` 可能会是 `computer.id` 从 `Computer.create()` 或计算机名称 由 Celesto 命令行工具显示 : `celesto computer list`。 。 。 .

| 方法 | 它会做什么 |
| --- | --- |
| `Computer.list()` | 在您的账户中列出计算机 |
| `Computer.get(computerId)` | 获得一个名称或身份的计算机 |
| `computer.listCommandHistory()` | 列出最近的命令及其状态 |
| `computer.createTerminalSession()` | 创建短寿命快终端连接 |
| `computer.createBrowserConnection()` | 创建一个短寿命 CDP 连接到浏览器代理 Chromium |
| `computer.createDisplayConnection({ mode: "read_only" })` | 创建短寿命的 RFB 显示连接 |
| `computer.stop()` | 停止电脑运行 |
| `computer.start()` | 启动停止的计算机 |
| `computer.delete()` | 删除计算机 |

### 发布端口

当计算机内部的服务需要公共 URL 时, 发布端口 :

```js
import { Computer } from "@celestoai/sdk";

const computer = await Computer.get("curie");
const url = await computer.publishPort(8000);
console.log(url);
```

列出并删除已公布的端口 :

```js
import { Computer } from "@celestoai/sdk";

const computer = await Computer.get("curie");
console.log(await computer.listPublishedPorts());
await computer.unpublishPort(8000);
```

### 终端连接

使用 `createTerminalSession()` 当您正在建立一个交互式终端时. Celesto 返回一个可以直接连接到快终端的短寿命 URL 网关而不是通过控制平面发送终端流量. 创建 a 终端会话需要写入计算机.

对于Node.js,首先安装了WebSocket客户端:

```bash
npm install ws
```

然后连接到认证的 URL :

```js
import { Computer } from "@celestoai/sdk";
import WebSocket from "ws";

const computer = await Computer.get("curie");
const connection = await computer.createTerminalSession();
const ws = new WebSocket(connection.url);

ws.on("message", (data) => process.stdout.write(data));
ws.on("open", () => ws.send("pwd\n"));
```

`connection.url` 包含一个短寿命的终端符号。 把它当作一个秘密 之后创建一个新的终端会话 `connection.expiresAt`。 。 。 .

### 浏览器自动化连接

使用 `browser-agent` 当应用程序需要已有时,模板 Chromium浏览器. `createBrowserConnection()` 返回短寿命的克罗姆 DevTools 协议(CDP) WebSocket URL,Playwright可以附加.

在运行此代码的应用程序中安装 Playwright Core :

```bash
npm install playwright-core
```

然后连接已经运行在 Celesto 计算机中的浏览器 :

```js
import { Computer } from "@celestoai/sdk";
import { chromium } from "playwright-core";

const computer = await Computer.create({ templateId: "browser-agent" });
try {
  const connection = await computer.createBrowserConnection();
  const browser = await chromium.connectOverCDP(connection.url);
  const context = browser.contexts()[0];
  if (!context) throw new Error("Celesto browser did not provide a context");
  const pages = context.pages();
  const page = pages[0] ?? await context.newPage();

  await page.goto("https://example.com");
  console.log(await page.title());
} finally {
  await computer.delete();
}
```

### 显示连接

使用 `createDisplayConnection()` 当远程帧缓冲( RFB) 客户端时, 例如 基于浏览器的 NoVNC 查看器,需要查看图形桌面. 连接默认只读 。 过 `{ mode: "read_write" }` 当查看器还需要指针和键盘控制时:

```js
import { Computer } from "@celestoai/sdk";

const computer = await Computer.get("curie");
const display = await computer.createDisplayConnection({ mode: "read_only" });
console.log(display.mode, display.expiresAt);
```

过 `display.url` 在 RFB 客户端到期前将其删除 。 浏览并显示 URL 包含短寿的秘密标志,所以不要记录、坚持或共享。 创建 断开或过期后的新连接。 浏览器自动化和 读写显示连接需要写入计算机.

## 守门员

当您的应用程序需要用户批准访问外部资源时使用门卫, 例如谷歌驱动器.

创建名为的文件 `gatekeeper-connect.mjs`数字 :

```js
import { GatekeeperClient } from "@celestoai/sdk/gatekeeper";

const client = new GatekeeperClient({ token: process.env.CELESTO_API_KEY });

const connect = await client.connect({
  subject: "customer_123",
  provider: "google_drive",
  projectName: "Default",
});

if (connect.status === "redirect") {
  console.log(connect.oauthUrl);
} else {
  console.log(connect.status);
}
```

如果响应打印出一个URL,打开后用户就可以批准访问.

完整守门员文件 : [https://docs.celesto.ai/celesto-sdk/守门员](https://docs.celesto.ai/celesto-sdk/gatekeeper)

## 配置

| 选项 | 它会做什么 |
| --- | --- |
| `token` | 塞莱斯多 API 键或 JWT |
| `apiKey` | 别名 `token` |
| `baseUrl` | 自定义 Celesto API URL |
| `organizationId` | 发送 `X-Current-Organization` 标题 |
| `timeoutMs` | 请求超时( 毫秒) |
| `headers` | 随请求一起发送的额外信头 |

将这些选项作为第二个参数传递给 `Computer.create()` 或者说 `Computer.get()`明确 `token` 或者说 `apiKey` 优于当地证书的发现。 守门员客户在其构建器中接受相同的选项,并需要明确标志.

JWT是一个签名的登录符. 大多数用户应该使用 Celesto API 键.

## 错误

SDK导出这些错误类别 :

| 错误 | 当使用时 |
| --- | --- |
| `CelestoApiError` | API 返回错误状态 |
| `CelestoNetworkError` | 网络请求失败 |
| `CelestoError` | 所有 SDK 错误的基准类 |

经理员会增加一个错误等级 每一个原因都可以拒绝操作,所以你 能够对特定的一个作出反应。 每个扩展 `ManagedAgentError`,扩展 `CelestoApiError`。 。 。 .

| 错误 | 当使用时 |
| --- | --- |
| `BudgetExceededError` | 此用户已经为窗口花费了预算 |
| `SessionBusyError` | 另一场比赛阻止了谈话 可重试; 检查 `retryAfter` |
| `IdempotencyConflictError` | 此密钥已经用过不同的请求 |
| `AgentArchivedError` | 代理不再运行 |
| `ProviderNotConnectedError` | 代理机型没有证书连接 |
| `SessionAgentMismatchError` | 那个谈话是属于另一个特工的 |
| `SessionEndUserMismatchError` | 那个对话属于另一个用户 |
| `ModelRequiresOwnKeyError` | 此模式只运行在您自己的提供者密钥上 |
| `ConfigKeyNotAllowedError` | 代理配置包含一个不支持的设置 。 被丢弃 `agents.create()`编号 :`agents.update()` 在发出任何请求之前,不是运行 |

## 本地开发

如果你有贡献 `npm` 运行这些命令 存储器 `ts` 目录 :

```bash
npm install
npm test
npm run lint
npm run build
```

## 许可证

阿帕奇2.0 (英语). SDK开源. Celesto平台的使用由以下规范: 《塞莱斯托服务条件》: [https://celesto.ai/legal/terms (法语)](https://celesto.ai/legal/terms)

## 常见问题

### @celestoai/sdk 是什么？

Celesto SDK——Node\.js的管理代理人、守门员和计算机客户

### 如何安装 @celestoai/sdk？

在项目目录运行 npm install @celestoai/sdk，或使用 pnpm add / yarn add / bun add。

### @celestoai/sdk 支持 TypeScript 吗？

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

### @celestoai/sdk 支持 ESM 还是 CommonJS？

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

### @celestoai/sdk 需要什么版本的 Node\.js？

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

### @celestoai/sdk 可以商用吗？

@celestoai/sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @celestoai/sdk 的下载量有多少？

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

### @celestoai/sdk 还在维护吗？

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