# @alvera-ai/platform-sdk 中文文档

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

版本：0\.22\.0
npm 元数据更新时间：2026-11-11T17:38:38.836Z
中文译文更新时间：2026-11-13T06:28:48.181Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：3.4 MB，59 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-04-13T10:18:30.069Z
- 最新版本发布：2026-11-11T17:38:38.634Z
- 近 30 天下载量：2150（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：154（近 12 个月 154 个）

## 中文简介

为Alvera平台API打入了SDK——管理数据源,工具,通用表格,AI代理,以及动作状态更新器.

## 安装

```sh
npm install @alvera-ai/platform-sdk
```

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

## README

# `@alvera-ai/platform-sdk`

为 Alvera 平台 API 所打入的 TypeScript SDK ——管理数据湖,数据 源,工具,AI代理,互操作性合同,数据激活客户端, 工作流程,以及更多,都来自一个单一的打字客户端.

## 安装

```sh
npm install @alvera-ai/platform-sdk
# or: pnpm add / bun add / yarn add @alvera-ai/platform-sdk
```

## 快开始

认证是两个步骤——薄荷会话,然后构建一个打入的客户端:

```ts
import {
  createSession,
  createIsolatedPlatformApi,
  type PlatformApi,
} from '@alvera-ai/platform-sdk'

// 1. mint a session (pass tenantSlug to scope it to a tenant)
const session = await createSession({
  baseUrl: 'https://api.alvera.ai',
  email,
  password,
  tenantSlug,
})

// 2. build a typed client
const api: PlatformApi = createIsolatedPlatformApi({
  baseUrl: 'https://api.alvera.ai',
  sessionToken: session.sessionToken,
})

// 3. call resources — every nested resource is tenant + datalake scoped
const { data: datalake } = await api.datalakes.create(tenantSlug, {
  name: 'Production Lake',
  type: 'raw',
  // …db_reader_* / db_writer_* + cloud_storage credentials…
})

const { data, meta } = await api.tools.list(tenantSlug, datalake.slug)
```

### 会议范围

`createSession` 薄荷是三种范围之一:

-   **根号** – Alvera root admin(用户签名+确认).
-   **无租户** ——认证用户尚未租户;曾用于创建 租户,或接受邀请。 奥米 `tenantSlug`。 。 。 .
-   **租户范围** ——承担租户业务的犬人. 过 `tenantSlug`。 。 。 .

在同一进程中拥有多个客户端(例如测试或应用程序服务) 多用户)? 使用 `createIsolatedPlatformApi` 它造就了一个新鲜的私人 客户端. `createPlatformApi` 变异一个共享的单子 并且只对一个 单人持枪.

### 有些事情要知道

-   **`update()` 替换整个资源** — 没有部分更新;发送 整个身体.
-   **列表终点返回 `{ data, meta }`** ——去结构化,不要去结构化 直接反应.
-   **垃圾是服务器生成的** - 读取 `slug` 关闭 a `create()` 响应; 永远 预计算.
-   **SDK 验证不了客户端** - 身体变糟了 `422 AlveraApiError` 带有 `source.pointer` 到违法的地方.

## 类型脚本配置

SDK使用过 [`@hey-api/client-fetch`](https://heyapi.dev/openapi-ts/clients/fetch), (中文(简体) ), 其生成的代码参考 WhatWG 获取类型 - `BodyInit`, (中文(简体) ), `RequestInit`, (中文(简体) ), `Headers`, (中文(简体) ), `FormData`等 (中文(简体) ). 这些名字住在 `lib.dom.d.ts`没有 `@types/node`因此,一个节点消费者与 `"lib": ["ES2022"]` 联合国 `tsconfig.json` 将看到错误,如 `Cannot find name 'BodyInit'` 何时 类型检查.

修补的是 `DOM` 财务报告和审定财务报表 `DOM.Iterable` 给您的 `lib`数字 :

```jsonc
// tsconfig.json
{
  "compilerOptions": {
    "lib": ["ES2022", "DOM", "DOM.Iterable"]
    //               ^^^^^^^^^^^^^^^^^^^^^^^
    // Required by @hey-api/client-fetch — see hey-api/openapi-ts#2539.
    // Type-only: adds NOTHING to the runtime — Node 18+ provides real
    // fetch independently of these declarations.
  }
}
```

这是Hey -api公开发行的作品 [#2539号](https://github.com/hey-api/openapi-ts/issues/2539); 放弃 `DOM` 条目再次显示自定义类型。 浏览器 消费者( React, Vue, Next, Nuxt, Remix) 已启用 `DOM` 编号 : `DOM.Iterable` 默认情况——不需要更改.

## 环境

带软件包的 Base URL 船, 构建时从 `servers[]` 框中的 OpenAPI 光谱,导出为 `ENVIRONMENTS`数字 :

```ts
import { ENVIRONMENTS, DEFAULT_ENVIRONMENT } from '@alvera-ai/platform-sdk'

ENVIRONMENTS.local.base_url // http://localhost:4000
ENVIRONMENTS.demo.base_url  // https://demo.alvera.ai
ENVIRONMENTS.prod.base_url  // https://app.alvera.ai

DEFAULT_ENVIRONMENT // 'prod'
```

通过选中的 `base_url` 输入 `createSession` 财务报告和审定财务报表 `createIsolatedPlatformApi`。 。 。 .

## 资源

每个资源都是客户端上输入的命名空间( E)`api.<resource>.<verb>`:

| 资源 | 业务 |
| --- | --- |
| `ping` | 健康检查 |
| `sessions` | `verify` |
| `auth` | `signUp` |
| `admin` | `confirmUser` |
| `tenants` | `list`, (中文(简体) ), `create` |
| `invitations` | `list`, (中文(简体) ), `create`, (中文(简体) ), `accept` |
| `datasets` | `search`, (中文(简体) ), `metadata`, (中文(简体) ), `createUserSearch` |
| `datalakes` | `list`, (中文(简体) ), `get`, (中文(简体) ), `create`, (中文(简体) ), `metadata`, (中文(简体) ), `migrate`, (中文(简体) ), `createUploadLink`, (中文(简体) ), `createDownloadLink`, (中文(简体) ), `textToSql`, (中文(简体) ), `executeSql` |
| `dataSources` | `list`, (中文(简体) ), `create`, (中文(简体) ), `update` |
| `tools` | `list`, (中文(简体) ), `get`, (中文(简体) ), `create`, (中文(简体) ), `update`, (中文(简体) ), `delete`, (中文(简体) ), `testInvocation` |
| `genericTables` | `list`, (中文(简体) ), `create` |
| `actionStatusUpdaters` | `list`, (中文(简体) ), `create`, (中文(简体) ), `update` |
| `aiAgents` | `list`, (中文(简体) ), `get`, (中文(简体) ), `create`, (中文(简体) ), `update`, (中文(简体) ), `delete`, (中文(简体) ), `invoke` |
| `authenticatedLinks` | `exchange`, (中文(简体) ), `updateMessageTracking` |
| `dataActivationClients` | `list`, (中文(简体) ), `get`, (中文(简体) ), `create`, (中文(简体) ), `update`, (中文(简体) ), `delete`, (中文(简体) ), `metadata`, (中文(简体) ), `runManually`, (中文(简体) ), `ingest`, (中文(简体) ), `ingestFile`, (中文(简体) ), `logs.list`, (中文(简体) ), `logs.get` |
| `interoperabilityContracts` | `list`, (中文(简体) ), `get`, (中文(简体) ), `create`, (中文(简体) ), `update`, (中文(简体) ), `delete`, (中文(简体) ), `metadata`, (中文(简体) ), `run` |
| `mdm` | `verify` |
| `workflows` | `list`, (中文(简体) ), `get`, (中文(简体) ), `create`, (中文(简体) ), `update`, (中文(简体) ), `delete`, (中文(简体) ), `metadata`, (中文(简体) ), `execute`, (中文(简体) ), `run`, (中文(简体) ), `workflowLogs.list/get/download`, (中文(简体) ), `batchLogs.list/get/start/stop/refresh` |

租户和数据湖的提供由Alvera 管理员负责——联系您 代表登上新租户.

## 编码代理

这个包裹载着一个 **代理文件目录** 下级 `.agent/` 它降落在... 它降落在.. `node_modules/@alvera-ai/platform-sdk/.agent/` 安装后, 以及一个代理 走开 `node_modules` 自动发现它。 这是自给自足的 建立针对 SDK 的应用程序或测试套件 :

-   [`.agent/AGENTS.md`](https://npmcn.com/package/%40alvera-ai/platform-sdk/.agent/AGENTS.md) ——指数+资源参考.
-   [`.agent/cookbook/`](https://npmcn.com/package/%40alvera-ai/platform-sdk/.agent/cookbook/) 有效、可操作的食谱: 商业烹饪手册(每个结果一个)和能力文件(一个能力) 每个,例如:. `bulk-ingest`, (中文(简体) ), `ai-agent-invoke`, (中文(简体) ), `custom-tables`, (中文(简体) ), `invite-team`) (中文(简体) ).

把指针接入你自己的项目 `AGENTS.md` (和a) `@AGENTS.md` 导入到 `CLAUDE.md`),运行——不需要全局安装:

```sh
npx @alvera-ai/platform-sdk llm-export
```

它写着一个同位素管理块;重跑只替换了那个块.

## 文档

-   [`.agent/`](https://npmcn.com/package/%40alvera-ai/platform-sdk/.agent/AGENTS.md) ——消费者参考书+厨用书(套装货船)
-   [`docs/sdk-architecture.md`](https://npmcn.com/package/docs/sdk-architecture.md) - SDK的设计

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/%40alvera-ai/platform-sdk/LICENSE)。 。 。 .

## 常见问题

### @alvera-ai/platform-sdk 是什么？

为Alvera平台API打入了SDK——管理数据源,工具,通用表格,AI代理,以及动作状态更新器\.

### 如何安装 @alvera-ai/platform-sdk？

在项目目录运行 npm install @alvera-ai/platform-sdk，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 platform-sdk，可以用 npx platform-sdk 直接运行。

### @alvera-ai/platform-sdk 支持 TypeScript 吗？

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

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

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

### @alvera-ai/platform-sdk 需要什么版本的 Node\.js？

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

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

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

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

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

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

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