# @byok-sdk/cloud 中文文档

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

版本：0\.40\.0
npm 元数据更新时间：2026-11-08T07:03:36.323Z
中文译文更新时间：2026-11-08T21:31:11.344Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.7 MB，103 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.22\.1
- 运行依赖：4 个
- 首次发布：2026-08-09T14:38:25.422Z
- 最新版本发布：2026-11-08T07:03:36.125Z
- 近 30 天下载量：5036（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：61（近 12 个月 61 个）

## 中文简介

BYOK SDK 主机设备表面: 无国籍的冷冻-v1 HTTP 处理器在租户先行@byok-sdk/ core ports

## 安装

```sh
npm install @byok-sdk/cloud
```

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

## README

# @ byok- sdk/ 云

无国籍的 BYOK HTTP 处理器和内存的参考成分 租户第一 `@byok-sdk/core` 端口。 拥有设备配置协议/自动/政策 逻辑但是没有持久的数据库或对象存储驱动程序 .

说对了 `@byok-sdk/cloud-dataplane` 用于Postgres+R2生产存储.

`authenticateHostedDeviceAssertion()` 是主机连接器绑定的认证 组成。 它可以适应当前 `DeviceDirectory` 页:1 `CloudCrypto` 改为 核心的单用途验证器; 调用者必须注入重播权限和 信任的部署约束 。 仅在此之后创建持久连接器状态 返回本金。 OAuth 刷新令牌及由此而来的长期配置 仍为主机所有,从未被此API所存储.

```ts
const authenticated = await authenticateHostedDeviceAssertion(assertion, {
  devices,
  crypto,
  replay,
  clock,
  expected: { issuer, productId, audience: 'connector-binding' },
});
if (authenticated === undefined) throw new Error('unauthorized');
await connectorProfiles.bind(authenticated.device, providerLogin);
```

主机组件在 Agent 提议中命名工具, 设备必须使用 承认 `toolset-selection`数字 :

```ts
await cloud.enqueueAgentOffer(tenantId, deviceId, {
  taskId,
  payload: {
    instruction: 'Research the account and prepare the next sales action.',
    runtime: 'claude',
    agentRef,
    sessionRef,
    requiredToolsets: ['salesko.prospecting'],
  },
});
```

不同于现场的自办协调员, 这个无国籍的排队API不能 推断当前设备的能力; 主机必须路径到已知的设备 广告 `toolset-selection`。 。 。 . `listPresence(tenant)` 包含可选 `configuredToolsets` 每个直播守护进程报告,所以主机可以缩小 排队前的候选设备 。 这是TTL的发现,不是执行 权限: 守护进程仍然在本地解决每个需要的ID并降低 如果配置改变,则关闭失败.

阅读一个任务的结果会经历两次相同的第一个终端事实: `readTerminalReceipt(tenant, taskId)` 返回存储的信封生( 之后) `redactTasks` 它抛出 `task_content_redacted`),以及 `readTaskResult(tenant, taskId)` 将同一收据解码为输入 `TerminalResult` - 国家,加 `summary`编号 :`sessionRef`编号 :`artifactRefs`编号 : `document` 完成时或 `reason`编号 :`retryable` 失败——预测 无再验证的逐字记录:

```ts
const result = await cloud.readTaskResult(tenantId, taskId);
if (result === undefined) {
  // No terminal fact and no Host cancellation yet. A decline is a terminal:
  // it reads back as `failed` with its `code`.
} else if (result.state === 'failed' && result.retryable) {
  // re-offer
}
```

`document` 当守护进程没有发出任何信号时,它就不存在了 存储的身体不是终端信封扔出 `ByokCloudError` 而不是说 返回最佳形状.

麻省理工学院有执照 节点.js 24.22.1或更新.

## 不可移动的回转报价

`readTaskOffer(tenant, taskId)` 使用 任务尝试目标与稳定消息身份. 它能验证协议 有效载荷、目标/代理装订和交付标记。 坏账; 缺少尝试或缺少报盘接收返回未定义。 回来的 记录At是接收时间,而不是运输时间;没有发明邮箱序列. 发送=假读不是附件从未发生的证据. 仅限主机 消息上下文是一个单独的权威,而不是此要约投影的一部分. API的持久性是被注入的收条店:内存重启 和 Postgres 通用收件保留不采用此读取方法升级.

## 邮箱提醒组件

`createByokCloud` 财务报告和审定财务报表 `tenantStoresFor` 需要一个 `mailboxWake` 端口 。 这是一个 丢失提示 : 邮箱读取仍然是唯一的事件/ursor权限 。 民意调查 在它第一次读取之前订阅, 在提示或后退间隔之后重新读取, ,并在回复、错误或请求中止时关闭订阅。 每一个活 空回覆在最后读取之后,包括倒放底盘检查.

`createInMemoryByokCloud` 默认为 `createInProcessMailboxWake()` 并揭露 同一实例 `mailboxWake` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}对东道主来说 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}租户的外表很直接. 注入的直接成分 `createInProcessMailboxWake({ fallbackMs: 5_000 })`, (中文(简体) ), 或来自节点/邮政的收听器 `@byok-sdk/cloud-dataplane`默认值 倒计时 `DEFAULT_MAILBOX_WAKE_FALLBACK_MS` (5秒钟). 没有间隔 选择或替代投票。 发布附加和取消提示 直接写到裸体店靠倒.

## 东道方合同

云花岗工人的地貌H主机 [主机合同](https://npmcn.com/package/docs/hosted-host-contract.md)。它映射每个任务 状态为主机动作。 也让重新扫描 唤醒 信息消耗 闲置 成本和留存规则.

运行时间依赖性和规模预算: [入职扶养合同](https://npmcn.com/package/README.md#entry-dependencies)。 。 。 .

## 常见问题

### @byok-sdk/cloud 是什么？

BYOK SDK 主机设备表面: 无国籍的冷冻-v1 HTTP 处理器在租户先行@byok-sdk/ core ports

### 如何安装 @byok-sdk/cloud？

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

### @byok-sdk/cloud 支持 TypeScript 吗？

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

### @byok-sdk/cloud 支持 ESM 还是 CommonJS？

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

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

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

### @byok-sdk/cloud 可以商用吗？

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

### @byok-sdk/cloud 的下载量有多少？

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

### @byok-sdk/cloud 还在维护吗？

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