# @bike4mind/sdk 中文文档

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

版本：2\.2\.0
npm 元数据更新时间：2026-11-16T04:56:36.584Z
中文译文更新时间：2026-11-16T04:57:48.717Z
软件包许可：BUSL-1\.1

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

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

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

- 包体积（解压后）：3.1 MB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：1 个
- 首次发布：2026-10-20T06:56:01.793Z
- 最新版本发布：2026-11-16T04:56:36.215Z
- 近 30 天下载量：327503（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：1540（近 12 个月 1540 个）

## 中文简介

Bike4Mind HTTP API的类型化客户端，从其OpenAPI规范生成

## 安装

```sh
npm install @bike4mind/sdk
```

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

## README

# @ bike4mind/ sdk (英语)

一个Bike4Mind HTTP API的小型打字客户端. 其类型由API的OpenAPI spec生成,因此该光谱中的每个操作都可以被打出路径参数,查询,正文和响应,每个端点没有手写代码.

-   全局运行的任何地方 `fetch`: Node 18+, Bun, Deno, 浏览器.
-   一次运行中的依赖性(`eventsource-parser`,用于流出).
-   答复是打字的,未经证实.

API的全部参考文献,包括范围、费率限制和同步工作,由每个部署地点提供 `/api/v1/docs` (原始谱系为 `/api/v1/openapi.json`) (中文(简体) ).

## 安装

```sh
npm install @bike4mind/sdk
```

## 创建客户端

```ts
import { createClient } from '@bike4mind/sdk';

const b4m = createClient({
  baseUrl: 'https://app.example.com', // your deployment; there is no default
  apiKey: process.env.B4M_API_KEY, // sent as `Authorization: Bearer b4m_live_...`
});
```

其他选项:

-   `getAuthToken: () => string | undefined | Promise<...>` 在每次请求之前运行, 它的标志胜过 `apiKey`用在JWT上 你刷新自己.
-   `fetch` 是用于超时、复试、代理或测试的自定义获取.
-   `headers` 每一个请求都发出.

## 调用任何操作

`call(operationId, args)` 使用光标 `operationId`。 。 。 . `params` (路径), `query` 财务报告和审定财务报表 `body` 每次操作都输入,以及 `params`编号 :`body` 在行动需要他们时需要他们.

```ts
const me = await b4m.call('getMe');
const models = await b4m.call('listModels', { query: { limit: 20 } });
const project = await b4m.call('getProject', { params: { id: projectId } });
await b4m.call('deleteProject', { params: { id: projectId } }); // 204: resolves undefined
```

`call` 返回已解析的 JSON 天体。 非JSON 2xx 体( 例如默认的二进制音频从 `synthesizeSpeech`投掷;使用 `raw`, (中文(简体) ), `completions` 或 `tts`编号 :`music`编号 :`soundEffects` 帮手 对于二进制或流出的身体, `raw(operationId, args)` 返回 2xx 键 `Response` 自己来. `operations` 将每个 id 映射到它的 `{ method, path }`。 。 。 .

## 使工作顺利完成

```ts
for await (const event of b4m.completions({
  model: 'claude-sonnet-5-5',
  messages: [{ role: 'user', content: 'Hi' }],
})) {
  if (event.type === 'content') process.stdout.write(event.text);
  if (event.type === 'error') throw new Error(event.message);
}
```

端点在验证、认证或速率限制前打开流出,所以一个无效的正体、一个被否决的密钥或速率限制作为结果到达 `{ type: 'error' }` 事件,而不是抛出的错误。 只有从未变成流的响应( 错误的 JSON 机构, 错误的方法, 代理错误) 扔出 `B4mApiError`。通过 `{ signal }` 取消,或 `{ url }` 从不同的端点流出; 相对 `url` 合并到 `baseUrl`绝对值 `url` 接收相同的 `Authorization` 信头,只通过一个你信任的来源 结束的溪流 `[DONE]` 而不发生错误事件.

## 聊天和图像工作

聊天回合和图像生成和编辑被排队. 每个帮助者返回一个手柄 `poll()` 等待任务完成 :

```ts
const turn = await b4m.chat({ message: 'Summarize my last notebook' });
const quest = await turn.poll({ timeoutMs: 120_000 });
console.log(quest.reply);

const image = await b4m.generateImage({ prompt: 'a red bicycle', model: 'gpt-image-1' });
const { images } = await image.poll();
```

`poll` 背从 `intervalMs` (默认为 1000 ms) 至 `maxIntervalMs` (默认5000毫秒). 它会扔 `B4mQuestError` 当任务结束时 `type: "error"` (单位:千美元)`reason: 'error'`),结束 `stopped` (单位:千美元)`'stopped'`),或过期 `timeoutMs` (单位:千美元)`'timeout'`) (中文(简体) ). `error.quest` 拥有最后一个州。 要恢复投票 已知的寻觅身份,使用 `pollQuest(id)`。 。 。 .

其他同步任务(代理处决、视频生成、文件上传)是简单的 `call`s: 开始工作,然后调查它 `get*` 操作.

## 音频

`tts`, (中文(简体) ), `music` 财务报告和审定财务报表 `soundEffects` 总是请求 `encoding: 'base64'`,所以一个结果太大 对于反应回来作为 `delivery: 'url'` 变体而不是重定向。 早于此日期的服务器 `encoding` 流生字节; SDK 从这些字节和 `X-B4M-Audio-*` 头.

```ts
const result = await b4m.tts({ text: 'Hello', voice: 'alloy' });
if (result.kind === 'audio' && result.data.delivery === 'inline') {
  const bytes = Buffer.from(result.data.audio, 'base64');
}
```

`tts` ưμ㼯a `{ kind: 'saved-too-large', data }` 当一个更古老的服务器拒绝带有413的超大小音频但保存了保存的拷贝时(`data.fabFileId`) (中文(简体) ). 要直接获得二进制音频, 请使用 `raw('synthesizeSpeech', { body: { text, encoding: 'binary' } })`。 。 。 .

## 向注册用户计费

`exchangeIdToken` 交易用户的 B4M 标识符,以换取一个短命的 API 密钥,该密钥可以支付用户的信用。 没错 **只有服务器**\- 它会给你的客户保密.

```ts
import { createClient, exchangeIdToken } from '@bike4mind/sdk';

const baseUrl = 'https://your-b4m-host';
const { apiKey, expiresAt } = await exchangeIdToken({
  baseUrl,
  clientId,
  clientSecret,
  idToken,
  signal: AbortSignal.timeout(10_000),
});
const b4m = createClient({ baseUrl, apiKey });
```

投出失败 `B4mApiError` 与 `errorCode` 设置到 OAuth `error` (单位:千美元)`invalid_request`, (中文(简体) ), `invalid_client`, (中文(简体) ), `invalid_grant`, (中文(简体) ), `access_denied`, (中文(简体) ), `invalid_scope`, (中文(简体) ), `subscription_required`, (中文(简体) ), `temporarily_unavailable`和 `message` 设定为 `error_description`在429号机上等待 `retryAfterSeconds`。 。 。 .

缓存是您的:每个用户和应用程序有一个活键(每个交换取消前一个),所以在不久之前,每个用户保留一个键并重新点火 `expiresAt`。见 [打给用户,不是你自己](https://docs.bike4mind.com/developers/building-on-b4m#5-bill-the-user-not-yourself) 整个合同.

## 错误

任何非-2xx响应投出 `B4mApiError`. OAuth 风格的天体(一个蛇外壳) `error` 代码和 `error_description`() 地图 `error` 改为 `errorCode` 财务报告和审定财务报表 `error_description` 改为 `message`数字 :

```ts
import { B4mApiError } from '@bike4mind/sdk';

try {
  await b4m.call('getMe');
} catch (error) {
  if (error instanceof B4mApiError) {
    error.status; // HTTP status
    error.errorCode; // e.g. 'insufficient_credits'; branch on this, not on the message
    error.requestId; // body request_id or the X-Request-ID header
    error.retryAfterSeconds; // from Retry-After on a 429
    error.body; // the parsed body
  }
}
```

## 类型

生成类型会导出为您自己的代码 : `paths`, (中文(简体) ), `components`, (中文(简体) ), `Operations`快捷键 `Schemas` (例如 `Schemas['ErrorResponse']`) (中文(简体) ). 行动助手 `JsonBody<'createProject'>`, (中文(简体) ), `JsonResponse<'getQuest'>`, (中文(简体) ), `PathParams<...>` 财务报告和审定财务报表 `QueryParams<...>`。 。 。 .

这些名称直接出自于 spec (OperationIds, schema names 如: `getQuestResponse200`,状态代码),所以它们是这个软件包的公用API的一部分:在光谱中重命名一个是导入它的代码的破解更改.

## 重新生成类型(贡献者)

`src/generated/` 从 `apps/client/public/openapi.json` 并登记了进来。 从回波根:

```sh
pnpm turbo:openapi:generate   # regenerates the spec, then the SDK types
```

`pnpm --filter @bike4mind/sdk generate` 仅从当前光谱再生 SDK 类型 。 当CI僵化时就失败了.

## 出版

通过 npm 信任的出版(OIDC)从 CI 中释放到 npm;没有 npm 令牌被存储 .

## 常见问题

### @bike4mind/sdk 是什么？

Bike4Mind HTTP API的类型化客户端，从其OpenAPI规范生成

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

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

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

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

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

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

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

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

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

@bike4mind/sdk 使用 BUSL-1\.1 许可。声明的许可为 BUSL-1\.1，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @bike4mind/sdk 的下载量有多少？

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

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

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

