# @arbol-ai/sdk 中文文档

规范地址：https://npmcn.com/package/%40arbol-ai/sdk/

版本：5\.42\.0
npm 元数据更新时间：2026-11-06T19:31:00.563Z
中文译文更新时间：2026-11-06T13:48:35.645Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：1.6 MB，891 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-10-18T20:12:30.712Z
- 最新版本发布：2026-11-06T19:31:00.392Z
- 近 30 天下载量：12477（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：69（近 12 个月 69 个）

## 中文简介

TypeScript和JavaScript的Arbol API由Cloudflare Forge从平台的公开OpenAPI中生成.

## 安装

```sh
npm install @arbol-ai/sdk
```

也可以使用：`pnpm add @arbol-ai/sdk`、`yarn add @arbol-ai/sdk`、`bun add @arbol-ai/sdk`

## README

# @ arbol-ai/ sdk

TypeScript 和 JavaScript 的 arbol API , 由 [云浮堡垒](https://github.com/cloudflare/forge) 从平台的公开OpenAPI, [`https://api.getarbol.com/openapi.json`](https://api.getarbol.com/openapi.json)。所有内容 `src/` 是Forge的 TypeScript 输出,未经编辑。 每个版本都记录了OpenAPI 生成来源: `npm view @arbol-ai/sdk@<version> arbol.openapi` 打印其 `release` (单位:千美元)`info.version`(中文(简体) ) 和内容散列`sha256`) (中文(简体) ).

```sh
npm install @arbol-ai/sdk
```

```ts
import { ApiError, createClient } from '@arbol-ai/sdk';

const arbol = createClient({ baseUrl: 'https://api.getarbol.com', token });

const { data } = await arbol.agenda.appointments.get({ appointmentId: 'eng_…' });
data.startsAt; // Temporal.Instant
```

每一次行动都是 `client.<service>.<resource>.<verb>(request, options?)`,经其请求 其旁边的反应类型(`agenda/appointments`数字 : `GetRequest`, (中文(简体) ), `GetResponse`(中文(简体) ).

### 只有你的客户

每种服务及其资源也是自己的入口,有自己的 `createClient`这样 一个应用程序只捆绑它所谓的,而不是每个服务的:

```ts
import { createClient } from '@arbol-ai/sdk/account/organization';
import type { AccountCurrentOrganization } from '@arbol-ai/sdk/account/organization';

const organization = createClient({ baseUrl: 'https://api.getarbol.com', token });

const { data } = await organization.get();
```

`@arbol-ai/sdk/<service>` 是一个服务( o)`client.<resource>.<verb>`和 `@arbol-ai/sdk/<service>/<resource>` 一个资源(`client.<verb>`),名称为 `src/` (单位:千美元)`account/members`, (中文(简体) ), `agenda/appointments`, (中文(简体) ), `nuevaEps/…`);每个出口其类型和 `ApiError`。 。 。 .

## 全权证书

`token` 以 `Authorization: Bearer <token>`它是:

-   a Arbol API 密钥,在 Arbol 账户中创建。 藏在秘密经理那里 永远不要送去 浏览器;
-   给观众的进入标志 `https://api.getarbol.com`,来自 OAuth 客户端,例如 个人在您的应用程序中的会话.

SDK不持有 OAuth 逻辑: 无论您的应用程序如何在其中签名, 并创建客户端 你拥有的象征.

## 答复和错误

用API声明的响应解决的方法: `{ success: true, data, error: null, metadata }`。 。 。 . 任何其它状态 `ApiError`,与 `status`,则 `response`,及其宣布的遗体在 `details` (单位:千美元)`{ success: false, error: { code, message, retryable, data }, metadata }`) (中文(简体) ).

每通电话都会发出一个请求,并且从未被重审. 过 `fetch` 通过您自己发送请求 函数, `headers` 或者说 `query` 增加每项请求,以及 `signal` 以中止一个电话.

服务器授权每通电话:客户端中的一种方法不是赠款.

## 所需资源

`date-time` 字段为 `Temporal.Instant` 财务报告和审定财务报表 `date` 字段 `Temporal.PlainDate`因此运行时间需要 `fetch` 财务报告和审定财务报表 `Temporal` (节点.js 26, Bun 1. 4, 当前浏览器), 和 TypeScript 需要 `"lib": ["ESNext"]`。 。 。 .

## 发展

```sh
bun install
bun run forge       # build the pinned Cloudflare Forge with cargo into .forge/ (once; needs Rust)
bun run openapi     # download https://api.getarbol.com/openapi.json
bun run generate    # src/ from openapi.json with `forge --target ts`; its release and hash in arbol.openapi
bun run hash        # the OpenAPI's content hash (see Releases)
bun run verify      # typecheck and build dist/
```

`openapi.json` 是在生成时下载的,没有承诺. `package.json`是因为 `arbol.openapi` 记录 OpenAPI `src/` 产生源源 `info.version` 作为 `release` 及其内容散列为 `sha256`· ; `version` 财务报告和审定财务报表 `arbol` 正在发布工作流程设置的元数据。 福尔吉是罪魁祸首 `7f86447210b7bea3779bfdab3cd5655eade0eadb` (0.1.0) 中标 `forge` 剧本.

## 释放

版本是成品,独立于OpenAPI的发行号. 1.x版本 (中文(简体) )`1.YYYYMMDD.n`(中文(简体) ) 是OpenAPI的日期发布; 2.x开始于 2.1.0.

新的 OpenAPI 的发布是自动的, 从 API 到 CLI :

1.  **网关.** 当Arbol API 发送 OpenAPI 发布时,网关会发送此寄存器 a `repository_dispatch` `openapi-release` 与 `{ "version": "<release>" }`。 。 。 .
2.  **SDK(这个仓库).** [生成](https://npmcn.com/package/%40arbol-ai/sdk/.github/workflows/generate.yml) 运行的调度,每一个 六个小时,用手 它下载了OpenAPI(等待API为宣布的发布服务) 并把它的内容。 当异于 `arbol.openapi.sha256` 内 `package.json`,这个 重新生成 `src/` ,将 OpenAPI 记录在 `arbol.openapi`,并取最高版本 在npm上与小起子和补丁在0 (2.1.0, 2.2.0, 2.3.0....). 它能证实结果, 承诺 `Release <version>` 改为 `main` 作为Arbol,并出版 `@arbol-ai/sdk` 到 npm 时为 [发布](https://npmcn.com/package/%40arbol-ai/sdk/.github/workflows/publish.yml)。当源寄存器存在时,软件包访问仍然公开 私处. Npm不支持私有源寄存器, 从而禁用证明.
3.  **CLI(英语:CLI).** 发布后, 发布发送 [项目-arbol-cli](https://github.com/getarbol/project-arbol-cli) (单位:千美元) `repository_dispatch` `sdk-release` 与 `{ "version": "<published version>", "openapi": { "release": "…", "sha256": "…" } }`, (中文(简体) ), 已发表 `version` 财务报告和审定财务报表 `arbol.openapi`,而CLI 释放自己在上面.

散列( A)[`scripts/release.ts`](https://npmcn.com/package/%40arbol-ai/sdk/scripts/release.ts))是OpenAPI克纳克的SHA-256六克 JSON( 对象密钥按递归排序, 数组顺序排列, 无白空格 ) `info.version` 已删除。 一个新的 相同的API散列的发布编号相同,因此生成承诺、发布和宣布 没什么 一个版本在 `main` 还没有在 npm 上发布, 例如一个失败的运行 由下一个运行.

对SDK本身的更改,如新的Forge 指针,用手释放: 承诺 `main` (以 `bun run generate` 当它们改变时 `src/`,然后在 `main` 与 `bump` `patch` (默认), `minor` 或者说 `major`数字 :

```sh
gh workflow run publish.yml --repo getarbol/project-arbol-sdk-js --ref main -f bump=patch
```

它提出了npm上最高版本的部分(虽然没有发表 2.x 版本,结果却是 2.1.0 不论撞到什么地步,都要承担 `Release <version>` 改为 `main`并公布给 CLI就像创造。 它拒绝当 `main`'版本还没有在npm上(运行生成,发布它), 当没有东西进入包裹时`src/`, (中文(简体) ), `package.json`, (中文(简体) ), `tsconfig.json`, (中文(简体) ), `bun.lock`, (中文(简体) ), `README.md`, (中文(简体) ), `LICENSE`)自释放的承诺以来有所改变 `main`版本,所以同样的SDK是 从来没有出版过两次。 手工放出并生成等相.

生成并发布推动和发送 作为Arbol Bot GitHub App,所以他们承诺 `main` 运行 [校验](https://npmcn.com/package/%40arbol-ai/sdk/.github/workflows/verify.yml)他们需要组织变量 `ARBOL_BOT_APP_ID`,则 组织秘密 `ARBOL_BOT_PRIVATE_KEY`,并安装了内容的 App 写入此选项 npm的出版使用组织的秘密 `NPM_TOKEN`。 。 。 .

## 迁移到 SDK 5

SDK 5遵循目前跨平台的公共所有者合同. 更新 从SDK 3中继承的账号:

| SDK 3 (英语) | SDK 5 (韩语) |
| --- | --- |
| `account.organizations.current` | `account.organization.get` |
| `account.organizations.configure` | `account.organization.update` |
| `account.billing.overview` | `account.billing.get` |
| `account.usage.breakdown` | `account.usage.get` |
| `account.usage.summary` | `account.usageSummary.get` |
| `account.invoices.document` | `account.invoiceDocuments.get` |

议程预定发现现在使用 `bookingLocations.list`, (中文(简体) ), `bookingOfferings.list`, (中文(简体) ), `bookingRequirements.get`, (中文(简体) ), `bookingSlots.list` 财务报告和审定财务报表 `nearestBookingSlots.list`。 。 。 . `bookings.lookup` 替换 `bookings.list`· ; `firstAvailability.get` 替换 `availability.first`· ; `resourceSchedules.update` 替换 `scheduleRules.replace`。 。 。 . 附表规则单独使用 `create` 财务报告和审定财务报表 `update` 方法代替 `upsert`。 。 。 .

SURA 用途 `appointments.lookup`, (中文(简体) ), `bookingOptions.lookup`, (中文(简体) ), `availability.lookup` 财务报告和审定财务报表 `copays.lookup` 替换 `appointments.list`, (中文(简体) ), `appointments.prepare`, (中文(简体) ), `availability.list` 财务报告和审定财务报表 `copays.list`。包含个人数据的查询使用 拥有者现在的JSON请求体. 医疗也暴露 `patients.lookup`。 。 。 .

现在使用的账户资源标识符 `apiKeyId`, (中文(简体) ), `billingProfileId`, (中文(简体) ), `invitationId`, (中文(简体) ), `invoiceId` 财务报告和审定财务报表 `memberId` 替换 `id`,如生成的请求类型声明. 连接创建、更新和删除是公众以外的工作人员用户操作 SDK(英语:SDK). 授权工作人员使用私人运营商CLI;具有证书的业务 留在MCP之外。 账户仍然拥有和执行这些权限.

共享生成的模型出口也沿用了目前的计划名称. 更新 使用编译器的诊断器进行明确的模型导入。 客户端构建者, 答复信封, `ApiError` 和时间价值 保持他们现有的行为.

## 许可证

[Apache 许可证 2.0](https://npmcn.com/package/%40arbol-ai/sdk/LICENSE)

### 公布已准备好的来源承诺

出版工作流程接受现有的主分支 `ref` 在不创建的情况下发布 释放承诺。 设定 `announce` 在单独协调 CLI 发布时为假. 生成应用 `scripts/forge-path-segments.patch` 至被钉住的 Forge 传输中,所以路径标识符 `.` 或者说 `..` 在请求到达不同的路径之前失败 。 如果未来的Forge版本更改了补丁代码,则生成步骤会失败.

出版进行同类型检查,SDK单元测试并按拉取请求构建. 运行 `bun test ./tests` 独立行使生成的公共客户.

## 常见问题

### @arbol-ai/sdk 是什么？

TypeScript和JavaScript的Arbol API由Cloudflare Forge从平台的公开OpenAPI中生成\.

### 如何安装 @arbol-ai/sdk？

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

### @arbol-ai/sdk 支持 TypeScript 吗？

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

### @arbol-ai/sdk 支持 ESM 还是 CommonJS？

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

### @arbol-ai/sdk 可以商用吗？

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

### @arbol-ai/sdk 的下载量有多少？

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

### @arbol-ai/sdk 还在维护吗？

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