# @alter-ai/alter-sdk 中文文档

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

版本：0\.31\.0
npm 元数据更新时间：2026-11-03T20:12:41.644Z
中文译文更新时间：2026-11-06T20:48:24.357Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40alter-ai/alter-sdk
原文对照：https://npmcn.com/package/%40alter-ai/alter-sdk/?lang=original

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

- 包体积（解压后）：2 MB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：2 个
- peer 依赖：@opentelemetry/api ^1\.0\.0
- 首次发布：2026-02-18T21:28:57.220Z
- 最新版本发布：2026-11-03T20:12:41.483Z
- 近 30 天下载量：2367（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：35（近 12 个月 35 个）

## 中文简介

用于 Alter Vault 的官方 TypeScript SDK —— AI 代理商的特权访问:金库证书,默认拒绝政策,批准政策,以及通过 Alter 调用的每一通电话的审计线索

## 安装

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

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

## README

# 用于 TypeScript / Node.js 的更改 SDK

正式类型SDK [换行](https://alterauth.com/) ——AI代理的特权准入管理:金库证书,默认拒绝政策下至参数,对风险电话的审批政策,以及每一次通过Alter通话的审计线索.

提供商通过 Alter 代理执行呼叫 。 全权证书留在Alter,在那里执行政策和批准要求.

## 安装

```bash
npm install @alter-ai/alter-sdk
```

在Node.js 20+上运行,用于服务器侧环境. 关于浏览器侧面 OAuth 弹出流量,请参见 [`@alter-ai/connect`](https://www.npmjs.com/package/@alter-ai/connect)。 。 。 .

## 快速实例

制作一个经过认证的API呼叫——任何符号都不会触碰应用程序代码.

```typescript
import { App, HttpMethod } from "@alter-ai/alter-sdk";

const app = new App({ apiKey: "<api-key>" });
try {
  let response = await app.proxyRequest({ method: HttpMethod.POST, url: "https://api.example.com/resource", grantId: "<grant-id>",
      json: { example: "payload" }, });
  if ("status" in response) {
    for (const gate of response.gates) {
      console.log("Approval required:", gate.approvalUrl);
    }
    response = await app.awaitApproval(response.approvalId);
  }
  console.log(response.statusCode, await response.bodyJson());
} finally {
  await app.close();
}
```

需要全面走过——注册、密钥薄荷、奥奥特——请参看 [快速启动](https://docs.alterauth.com/quickstart)。 。 。 .

## 供应商电话

使用 `app.proxy_request(...)` (毕 `app.proxyRequest({...})` (TypeScript)用于提供商呼叫. 后端持有证书,执行请求,并返回提供者的结果.

-   `app.proxyUploadRequest(...)` ——大型请求机体的代理模式:机体由大小和SHA-256宣布,每条政策运行,然后发送一次,没有Alter持有. `app.deliverApprovedUpload(...)` 发送一个需要批准.
-   `app.proxyStreamRequest(...)` ——下载和服务器-恒星事件代理模式:提供方字节流通过后压. 二进制请求机构最多为5个米B. 也不能等待批准.

代理模式返回一个 `ApprovalResult` 与 `statusCode`,反应头/体, `bodyTruncated`,以及 `durationMs` (提供方往返毫秒; `null` 页:1 老年工人创造的成果)。 管理机密的副主管/村长 注射和AWS SigV4——包括查询参数、原始/JSON体和 临时会话符号——由后端注入.

见 [服务商呼叫](https://docs.alterauth.com/concepts/identity#provider-calls-execute-through-alter) 用于执行边界.

## 政策规则助手

`contentMatchRule(...)` 建立操作意识请求规则 `withConstraints({ rule })` 在第一次API呼叫前进行本地验证。 它接受操作ids(一个编目提供者的认证ids,或者IDs一个自定义集成开发者映射)和/或操作家族,可选参数条件,以及三种效果之一: `deny`, (中文(简体) ), `redact`,或 `step_up`。自定义集成的操作项目中,只有请求的查询字符串参数,与文本相比较,所以任何其他参数条件(正文、标题或路径参数,或数字比较)都否认匹配请求;a `redact` 规定只拒绝自定义操作,通过一个家庭到达的编辑拒绝请求。 已命名的外出请求- 机构字段; 需要升级 `maxSessionAgeSeconds` 作为整数从 `1` 结束 `86400`参数条件与 `equals`,光标运算符 `any_in` 编号 : `not_subset_of` (何处) `*`, (中文(简体) ), `?` 财务报告和审定财务报表 `[...]` 他们的双胞胎 `in` 编号 : `not_all_in` (与字面上比较的相同的数组,对大小写不敏感—— `in` 当任何成员被列入名单时, `not_all_in` 当并非所有成员都是成员时; 将它们用于文字声明、 ids 和通道时, 存在运算符 `exists` (布尔: `true` 当请求带有参数时起火, `false` 当它没有的时候,数字 `gt` 编号 : `gte` 编号 : `lt` 编号 : `lte`,以及 `outside_windows`。 。 。 .

`operationAllowlistRule(...)` 是积极的对应:它构建一个 `operation_allowlist` 请求规则,根据规则,只可运行列出的操作ID和/或操作家族。 每个其它的分类操作都被拒绝,任何请求目录都不能分类. 一个链上有几个允许列表相互交叉,因此每个请求允许列表只能缩小访问范围. 至少其中一个 `operations` 编号 : `families` 需要时间.

```typescript
import { operationAllowlistRule } from "@alter-ai/alter-sdk";

const readOnly = app.withConstraints({
  rule: operationAllowlistRule({ operations: ["query", "generalledger/query_a_report"] }),
});
```

## 追回遗失赠款错误

当请求因用户尚未授权提供商而失败时,SDK会从打出的错误上暴露恢复上下文,这样您就可以在不从呼叫站点重新找到任何东西的情况下驱动重新同意的流量:

```typescript
import { Agent, HttpMethod, NoDelegatedGrantError } from "@alter-ai/alter-sdk";

const agent = new Agent({ apiKey: "<agent-api-key>" });
try {
  try {
    await agent.proxyRequest({ method: HttpMethod.GET, url: "https://api.example.com/v1/resources", provider: "<provider-id>",
      userToken: jwt, });
  } catch (e) {
    if (e instanceof NoDelegatedGrantError) {
      const session = await agent.createConnectSessionForError(e, {
        allowedOrigin: "https://app.example.com",
      });
      // Surface session.connectUrl to the user, then wait for consent.
      const results = await agent.pollConnectSession(session.sessionToken);
      let response = await agent.proxyRequest({ method: HttpMethod.GET, url: "https://api.example.com/v1/resources", grantId: results[0].grantId, userToken: jwt });
      if ("status" in response) {
        for (const gate of response.gates) {
          console.log("Approval required:", gate.approvalUrl);
        }
        response = await agent.awaitApproval(response.approvalId);
      }
      console.log(response.statusCode);
    } else {
      // Re-throw every other error class so network errors and
      // programming bugs aren't silently swallowed.
      throw e;
    }
  }
} finally {
  await agent.close();
}
```

`createConnectSessionForError` 财务报告和审定财务报表 `pollConnectSession` 两者均可查阅 `App` 财务报告和审定财务报表 `Agent` 这样渔获区块就可以从任何客户中恢复. 对于 `CredentialRevokedError`,帮助将会话绑定到错误的精确度 赠款。 成功的修复报告 `operation === "reauth"` 和同样的 `grantId` ——与返回已连接的赠款的完成一样: `"reauth"` 也就是说,现在的一笔赠款 带着它保存的id回来了,而不是 一定是断了 给目标取名是一种优化,而不是要求: 错误不包含 赠款 id(一个较老的后端), 补助金 调用者无法地址(通过) `userToken` )或不再使用的赠款 活动全部返回到报告正常会话 `operation === "creation"` 带有新的 `grantId`读取结果的ID.

如果 Alter 观察会话待决, 但不会在本地之前收到回话 截止或服务器过期,投票投放 `ConnectTimeoutError`检查 `error.details.reason` (单位:千美元)`poll_deadline_elapsed` 或者说 `session_expired`) (中文(简体) ). 一个提供者 可能将授权错误保留在自己的页面上,并且永远不重定向,所以 例外列表 : 而不是声称一个确切的提供者错误 Alter 没有收到.

如果新的供应商授权无法启动, `pollConnectSession` 掷出 `ConnectConfigError`。这包括输入 `provider_configuration_unavailable` 财务报告和审定财务报表 `shared_dev_credential_unavailable` 终端; 显示错误的安全消息到 调用并请求应用程序管理员纠正提供者可用性 在创建新会话之前。 现有的赠款仍然可以使用.

`ConnectConfigError` 还有第三个航站楼, `managed_oauth_scope_approval_required`,抛出 `createConnectSession` (HTTP 409号文件) `pollConnectSession`: 申请的范围 请求超过 Alter 管理的 OAuth 客户端的核准。 应用程序 管理员不能扩大范围——联系Alter以便批准范围,或 将应用程序的配置范围缩小到已核准的套件, 并且只有那时 创建新会话。 反应是 `retryable: false`所以每个新鲜的 在批准更改之前,会话同样失败。 打开 `createConnectSession` 路径错误 `details` 是全反应机构,所以 `details.details.unapproved_scopes` 确切的哪些范围需要批准.

第四个终端, `agent_allowlist_exceeded` (HTTP 422) 拒绝连接 (b) 向代理人代表的届会`agent`键,或 代理用户自己的密钥 ),当代理机的能力允许列表不能使用用户将使用什么 赠款. `createConnectSession` (和 `connect()`,创建会话 在用户发送到提供者之前扔出,支票在 `details.details.detail_reason` (单位:千美元)`provider_not_allowlisted`, (中文(简体) ), `scopes_not_allowlisted` 或者说 `grant_scopes_malformed`和 每个被拒绝的提供者在 `details.details.uncovered_providers`。 。 。 . `pollConnectSession` 在用户之前缩小许可列表时丢出 完成; 仅带失败 `details.error_code`管理员 扩大代理许可列表,或者应用程序缩小其范围 请求或通过一个封面 `scopeConstraint`在新的会议之前。 A 类 既不提供会话名称 `allowedProviders` 也没有 `requiredScopes` 当代理设备无法使用时,则将其删除,并列入 `ConnectSession.droppedProviders` (单位:千美元)`providerId`, (中文(简体) ), `check`) (中文(简体) ). 继续 `delegate()` 掷出 `BackendError` 同一个代码.

`NoDelegatedGrantError` 财务报告和审定财务报表 `GrantNotFoundError` 携带 `providerId` 编号 : `agentId` 编号 : `appUserId` 原始搜索为身份模式时的恢复上下文; `CredentialRevokedError` 携带 `providerId` 编号 : `appUserId`见 [引用错误](https://docs.alterauth.com/reference/errors) 为整个地表.

打开 **代理人** 路径, a `grant_not_found` 明确 `grantId` 表面为 `AgentDelegationMissingError` - 一个子类 `GrantNotFoundError`基地级的渔获物仍然在燃烧 这意味着赠款没有下放给该代理人,或者在需要代理人自己授权身份时,通过用户/基地赠款ID(从 `agent.listGrants`) (中文(简体) ). 通过Connect( 连接) 授权代理恢复`agent.createConnectSession`),或由提供者解决而不是通过 `grantId`。 。 。 .

## 管理机密连接:用户自己的密钥,或代表团

一个连接会话名称为管理下的秘密提供者( O)`provider`,提供商的"涕")和用户. shall是每个app独有的:几个提供者可以共享一个模板或显示名称,因此shall而不是模板名称选择一个. 当用户对提供者不持有赠款时,主机页面会询问自己的API密钥;当他们这样做时,会让他们批准其使用. 与 `agent`,用户的访问也授权给该代理人:

```typescript
import { App } from "@alter-ai/alter-sdk";

const app = new App({ apiKey: "<app-api-key>" });

const session = await app.createManagedSecretConnectSession({
  provider: "<provider-slug>",
  userToken: "<user-jwt>",
  agent: "<agent-id-or-name>", // optional: omit for the application's own use
  requestedGrant: { label: "<label>" }, // optional: names the key's grant
});
// Open session.connectUrl in the user's browser (a popup, the system browser
// or the @alter-ai/connect widget). session.path is "key_entry" when the user
// will enter a key, "fast_path" when they already hold a grant.
```

用户签入,输入密钥(或取出赠出),可自行设定使用限额并进行确认. 关键是用户自己的授权:应用程序可以撤销但不能编辑. 通过赠款,将它作为OAuth赠款使用: `grantId`,或 `provider` 与用户的代号,解决一次赠与。 几笔相应的赠款 `AmbiguousGrantError` (HTTP 409电话) `ambiguous_grant`); 以 `label` 或者说 `account`,或通过 `grantId`。一旦用户设定了限制,则使用 `proxyRequest()` (单位:千美元)`request()` 掷出 `RestrictedGrantRequiresProxyError`) (中文(简体) ). `repairGrantId` 让用户替换其密钥到位( 相同 ) `grantId`) (中文(简体) ).

一个特工自求多福 `agent.createManagedSecretConnectSession`,不需要目标:

```typescript
import { Agent } from "@alter-ai/alter-sdk";

const agent = new Agent({ apiKey: "<agent-api-key>" });

const session = await agent.createManagedSecretConnectSession({
  provider: "<provider-slug>",
  userToken: "<user-jwt>",
  delegable: true, // optional: ask that this agent may share the access onward
});
// On approval the page delivers the delegation id this agent passes as
// grantId to agent.proxyRequest() (a delegation is proxy-only).
```

用户决定是否可以继续分享代表团:对于代理商自己的请求,页面的复选框会从一个新的代表团开始,所以用户会选择代理人进入;对于现有的代表团,它会从存储的设置开始. `session.delegableRequested` 呼应所请.

`ConnectConfigError` 系指管理员或应用程序必须先更改某事; `error.details.error` 说吧`secret_not_found`, (中文(简体) ), `secret_template_mismatch`, (中文(简体) ), `idp_signin_not_configured`, (中文(简体) ), `binding_hosts_required`, (中文(简体) ), `provider_contract_repair_required`, (中文(简体) ), `no_eligible_grants`) (中文(简体) ). 相对于一个在调用之前的替代后端, SDK 投出 `ServerFeatureUnsupportedError`。 。 。 . `templateSlug` 财务报告和审定财务报表 `delegatedAgentId` 已贬值的化名 `provider` 财务报告和审定财务报表 `agent`:他们仍然工作并发射 `DeprecationWarning`。 。 。 .

## 进一步授权(代理人)

持有赠款的代理人可以向另一代理人转交一份范围缩小的复制件——而不要求证书所有人再次表示同意。 使用 `agent.delegate()` 向第二名代理人发放儿童补助金:

```typescript
import { Agent, GrantNotDelegableError } from "@alter-ai/alter-sdk";

const agent = new Agent({ apiKey: "<agent-api-key>" });

try {
  const result = await agent.delegate(
    "<grant-id>",                // a grant this agent already holds
    "<other-agent-id>",          // the agent that should receive access
    {
      scopeConstraint: ["resource:write"], // optional: narrow to fewer scopes
      ttlSeconds: 3600,                // optional: shorten the lifetime
    },
  );
  console.log(result.grantId, result.depth, result.expiresAt);
} catch (e) {
  if (e instanceof GrantNotDelegableError) {
    // e.detailReason says why: "holder_not_delegable" (the user did not allow
    // onward sharing), "ceiling_off" (the operator ceiling is off), ...
    console.warn("cannot share onward:", e.detailReason);
  } else {
    throw e;
  }
} finally {
  await agent.close();
}
```

持有的赠款必须是作为 **可删除**:用户在批准时允许继续共享(与 `delegable: true` —— 管理下的秘密提供者授权政策或OAuth提供者的代理人共享设置—— 仍然必须允许每次通话。 儿童只能缩小范围——缩小范围,缩短寿命——永远不会扩大。 赠款数额减少 `scopeConstraint` 仅使用代理服务器 : `agent.proxyRequest(...)`。每跳一次就选择代表团:通过 `delegable: true` 只有在应允许受援方进一步授权的情况下。 奥米 `delegable` (a) 保持现有代表团的设置,然后,新的代表团就成为一席之地,而再次将权力交给同一机构则保持目前的设置不变 `delegable: false` 使代表团关闭.

`delegate()` 还要 `rules`, (中文(简体) ), `tags` 财务报告和审定财务报表 `label`: 规则是与孩子一起创建的,并且只能缩小,标记从父母的开始,接受者通过 `label` 打开 `proxyRequest()` 财务报告和审定财务报表 `listGrants()`。结果 `approverWarnings` 名称 `require_approval` 规定其批准人未对照目录进行核查。 应用程序标记现有赠款 `app.updateGrantTags(grantId, tags)`,将整个地图替换,并将新地图标记为 `tags` 打开 `createConnectSession()`, (中文(简体) ), `createManagedSecretConnectSession()` 或者说 `mintGrant()`。 。 。 .

`agent.listGrants()` 返回每笔赠款 `parentGrantId` (赠款是根据该赠款计算的,或 `null` 用于根)和 `depth` (它与根相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去相去.

## OpenTeleometry 微量传播

当应用程序运行 OpenTeleometry SDK 时, Alter 请求自动携带活动跨度的 W3C `traceparent`因此,审计线索——以及任何跨越组织流到自己的OTLP收集器的线索——加入了应用程序的痕迹. 不需要配置 : `@opentelemetry/api` 是一个 _选项_ sDK从未安装或要求的对等依赖性——当应用程序拥有它时,SDK使用它(包括在pnpm的孤立模式下和Yarn PnP下);没有它(或没有活动跨度),SDK的行为与以前完全一样.

```typescript
import { trace } from "@opentelemetry/api";
import { App, HttpMethod } from "@alter-ai/alter-sdk";

const tracer = trace.getTracer("the-application");

const tracedApp = new App({ apiKey: "<api-key>" });
try {
  await tracer.startActiveSpan("handle-user-request", async (span) => {
    try {
      // This call's audit events share the surrounding trace's ids.
      let response = await tracedApp.proxyRequest({ method: HttpMethod.GET, url: "https://api.example.com/v1/resources", grantId: "<grant-id>" });
      if ("status" in response) {
        for (const gate of response.gates) {
          console.log("Approval required:", gate.approvalUrl);
        }
        response = await tracedApp.awaitApproval(response.approvalId);
      }
      console.log(response.statusCode);
    } finally {
      span.end();
    }
  });
} finally {
  await tracedApp.close();
}
```

## 文档

完整文件已经 **[https://docs.alterauth.com (中文(简体) )](https://docs.alterauth.com/)**。 。 。 .

| 专题 | 页次 |
| --- | --- |
| 开始端到端 | [快速启动](https://docs.alterauth.com/quickstart) |
| 心理模式 | [变化如何运作](https://docs.alterauth.com/how-it-works) |
| 代表用户调用API( OAuth + JWT) | [指南](https://docs.alterauth.com/guides/call-apis-on-behalf-of-users) |
| 身份提供者设置 | [指南](https://docs.alterauth.com/admin/identity-provider) |
| 提供后端机密 | [指南](https://docs.alterauth.com/guides/provision-secrets-for-backend-services) |
| 人工智能代理人的范围证书 | [指南](https://docs.alterauth.com/guides/give-an-agent-scoped-access) |
| 嵌入连接部件 | [指南](https://docs.alterauth.com/guides/embed-the-connect-widget) |
| 人与人之间的核准 | [指南](https://docs.alterauth.com/guides/add-human-in-the-loop-approvals) |
| OpenTeleometry 微量传播 | [调用 API](https://docs.alterauth.com/reference/typescript-sdk/calling-apis#opentelemetry-trace-propagation) |
| 提供者通过 Alter 呼叫 | [概念](https://docs.alterauth.com/concepts/identity) |
| 每方法 API 参考 | [类型脚本 SDK 引用](https://docs.alterauth.com/reference/typescript-sdk) |
| 浏览器弹出 SDK | [`@alter-ai/connect`](https://docs.alterauth.com/reference/connect-sdk) |
| 错误 | [引用错误](https://docs.alterauth.com/reference/errors) |

## 许可证

麻省理工学院. 见 `LICENSE`。 。 。 .

## 支助

电子邮件 **[创建者@ alterauth.com](mailto:founders@alterauth.com)** 或打开一个问题在 [https://github.com/alter-ai/alter-vault 页面存档备份,存于互联网档案馆](https://github.com/alter-ai/alter-vault)。 。 。 .

## 常见问题

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

用于 Alter Vault 的官方 TypeScript SDK —— AI 代理商的特权访问:金库证书,默认拒绝政策,批准政策,以及通过 Alter 调用的每一通电话的审计线索

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

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

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

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

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

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

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

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

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

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

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

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

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

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