# @21st-sdk/node 中文文档

规范地址：https://npmcn.com/package/%4021st-sdk/node/

版本：0\.1\.1
npm 元数据更新时间：2026-04-28T17:58:37.765Z
中文译文更新时间：2026-11-06T05:22:28.456Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%4021st-sdk/node
原文对照：https://npmcn.com/package/%4021st-sdk/node/?lang=original
项目主页：https://21st.dev/agents

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

- 包体积（解压后）：85.2 kB，18 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-03-06T02:34:29.583Z
- 最新版本发布：2026-04-28T17:58:37.589Z
- 近 30 天下载量：4841（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

用于第21代理的服务器端节点.js SDK

## 安装

```sh
npm install @21st-sdk/node
```

也可以使用：`pnpm add @21st-sdk/node`、`yarn add @21st-sdk/node`、`bun add @21st-sdk/node`

## README

# @21st-sdk/节点

服务器侧节点.js SDK [21号特工](https://21st.dev/agents)。在程序上管理沙盒、线条和符号.

## 安装

```bash
npm install @21st-sdk/node
```

## 快速启动

```ts
import { AgentClient } from "@21st-sdk/node"

const client = new AgentClient({
  apiKey: process.env.API_KEY_21ST!, // 21st_sk_...
})

// Create a sandbox for your agent
const sandbox = await client.sandboxes.create({ agent: "my-agent" })

// Create a thread
const thread = await client.threads.create({
  sandboxId: sandbox.sandboxId,
  name: "Review PR #42",
})

// Generate a short-lived token for browser clients
const { token, expiresAt } = await client.tokens.create({
  agent: "my-agent",
  expiresIn: "1h",
})
```

## API 密码

### `new AgentClient(config)`

```ts
new AgentClient({
  apiKey: string     // Your 21st_sk_ API key
  baseUrl?: string   // Default: "https://relay.an.dev"
})
```

### `client.sandboxes`

| 方法 | 说明 |
| --- | --- |
| `create({ agent })` | 为代理创建新沙盒 |
| `get(sandboxId)` | 获取沙盒细节( 状态、 线程、 代理信息) |
| `delete(sandboxId)` | 删除一个沙盒 |
| `exec({ sandboxId, command, cwd?, envs?, timeoutMs? })` | 在沙盒内运行命令 |
| `git.clone({ sandboxId, url, path?, token?, depth? })` | 将仓库切入沙盒 |

### `client.sandboxes.files`

| 方法 | 说明 |
| --- | --- |
| `write({ sandboxId, files })` | 将一个或多个文本文件写入沙盒 |
| `read({ sandboxId, path })` | 从沙盒读取一个文件 |
| `list({ sandboxId, path, depth? })` | 在路径下列出文件和目录 |
| `getInfo({ sandboxId, path })` | 获取一个文件或目录的元数据 |
| `exists({ sandboxId, path })` | 检查文件或目录是否存在 |
| `makeDir({ sandboxId, path })` | 创建目录路径, 返回是否新创建 |
| `rename({ sandboxId, oldPath, newPath })` | 重命名或移动文件或目录 |
| `remove({ sandboxId, path })` | 删除文件或目录 |

### `client.threads`

| 方法 | 说明 |
| --- | --- |
| `list({ sandboxId })` | 在沙盒中列出所有线索 |
| `create({ sandboxId, name? })` | 创建新线索 |
| `get({ sandboxId, threadId })` | 用信件获取线程 |
| `delete({ sandboxId, threadId })` | 删除线索 |

### `client.tokens`

| 方法 | 说明 |
| --- | --- |
| `create({ agent?, userId?, expiresIn? })` | 创建短寿命 JWT( 默认:1h) |

## 许可证

麻省理工学院

## 常见问题

### @21st-sdk/node 是什么？

用于第21代理的服务器端节点\.js SDK

### 如何安装 @21st-sdk/node？

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

### @21st-sdk/node 支持 TypeScript 吗？

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

### @21st-sdk/node 支持 ESM 还是 CommonJS？

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

### @21st-sdk/node 可以商用吗？

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

### @21st-sdk/node 的下载量有多少？

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

### @21st-sdk/node 还在维护吗？

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