# @naturali/sdk 中文文档

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

版本：0\.220\.3
npm 元数据更新时间：2026-11-01T23:09:21.288Z
中文译文更新时间：2026-11-01T23:36:16.800Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40naturali/sdk
原文对照：https://npmcn.com/package/%40naturali/sdk/?lang=original
项目主页：https://naturali.ai/docs/clients/sdk
源码仓库：https://github.com/TriangulosTecnologia/naturali.ai

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

- 包体积（解压后）：3.1 MB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-07-28T22:54:07.270Z
- 最新版本发布：2026-11-01T23:09:21.159Z
- 已发布版本数：420（近 12 个月 420 个）

## 中文简介

TypeScript SDK用于naturali。ai API，由OpenAPI规范生成

## 安装

```sh
npm install @naturali/sdk
```

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

## README

# @naturali / sdk

的TypeScript SDK [naturali.ai](https://naturali.ai/) API，从 它的 [OpenAPI规格](https://npmcn.com/package/api/openapi/).

```bash
pnpm add @naturali/sdk
```

## 使用

```ts
import { NaturaliClient } from '@naturali/sdk';

const naturali = new NaturaliClient({
  token: process.env.NATURALI_TOKEN, // nat_sk_… or a session access JWT
});

const { data, error } = await naturali.agents.listAgents({
  path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
  query: { limit: 10 },
});

if (error) {
  // The platform's error envelope, typed: { error: { code, message, details } }
  console.error(error);
} else {
  console.log(data.data);
}
```

方法永远不会抛出非2xx响应——它会解析为 `{ data, error }`， 所以是机器可读的 `code` （`approval_required`， `budget_exceeded`， `access_denied`)作为类型化数据可用。

## 选项

客户总是与 `https://api.naturali.ai` -唯一的自然。ai API 起源，不可配置。

| 选项 | 目的 |
| --- | --- |
| `token` | 发送 `Authorization: Bearer …`． 接受一个 `nat_sk_…` API密钥或会话访问JWT。 |
| `headers` | 最后合并，所以它可以覆盖上面的标题或添加您自己的。 |

没有 `project` 选项：项目范围内的操作需要 `project_id` 在 它的路径，这是API授权的唯一对象。

## 电话的形状

每个资源属性都镜像一个生成的服务类，并使用配置的 HTTP客户端已经绑定。参数遵循规范自己的结构和 **snake\_case** 字段名:

```ts
await naturali.sessions.addSessionMessage({
  path: { project_id, agent_id, session_id },
  body: { message: 'What is the capital of France?' },
});

await naturali.knowledge.queryKnowledgeCollection({
  path: { project_id, collection_id },
  body: { query: 'refund policy', limit: 5 },
});
```

资源: `agents`， `apiKeys`， `auth`， `channels`， `contacts`， `generations`， `knowledge`， `models`， `projects`， `providers`， `sessions`， `tools`， `traces`.

`naturali.http` 为拦截器或一次性公开底层客户端 请求(`naturali.http.get({ url: '/health' })`）。

## 类型

规范中的每个模式都被导出为一个类型：

```ts
import type { Agent, AgentCreate, ErrorResponse } from '@naturali/sdk';
```

`created_at` / `updated_at` 是递给来电者的 `Date` 对象;一切 Else与线的形状完全匹配。

## 一代

`src/generated/` 是构建输出——永远不要编辑它，也不要提交它。它是 重建的 `api/openapi/v1/*.yaml` 由 `pnpm generate`,这 `typecheck`， `test` 和 `build` 所有人先跑。看到 [`../README.md`](https://npmcn.com/package/%40naturali/README.md) 为 管道。

唯一的手写资料是 `src/naturaliClient.ts`.

## 版本控制

发布是自动的，版本是自动的 **与API共享 `@naturali/cli`** -一个号码，一个git标签，三个包。 `@naturali/sdk@0.28.0` 客户端是API 0.28.0，所以你安装的版本名称是你的合同 持有。

任何改变 `api/openapi/v1/*.yaml` 重新生成这个包并发布它， 因为规范就是它生成的东西 _从_ -所以一个新的版本可以意味着 API获得了资源，而不是手写的客户机发生了变化。

`fix:`/`chore:` 更改发布补丁和 `feat:` 从…中推断出的 压缩提交主题。每个案例都在合并时发布，打破更改 包括在内。请参阅存储库的 [`PIPELINE.md`](https://npmcn.com/package/PIPELINE.md#5-releasing) 和 [`CHANGELOG.md`](https://npmcn.com/package/CHANGELOG.md).

## 常见问题

### @naturali/sdk 是什么？

TypeScript SDK用于naturali。ai API，由OpenAPI规范生成

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

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

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

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

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

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

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

@naturali/sdk 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

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

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