# @flop-labs/client 中文文档

规范地址：https://npmcn.com/package/%40flop-labs/client/

版本：0\.2\.2
npm 元数据更新时间：2026-11-08T14:59:41.047Z
中文译文更新时间：2026-11-15T00:48:23.191Z
软件包许可：MIT OR Apache-2\.0

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

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

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

- 包体积（解压后）：82.7 kB，20 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：1 个
- 首次发布：2026-10-29T04:00:48.967Z
- 最新版本发布：2026-11-08T14:59:40.835Z
- 近 30 天下载量：3008（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

为 FLOP 公共模式发现获取客户端并网关聊天完成

## 安装

```sh
npm install @flop-labs/client
```

也可以使用：`pnpm add @flop-labs/client`、`yarn add @flop-labs/client`、`bun add @flop-labs/client`

## README

# @flop-labs/客户端

一个用于FLOP的公用网关,浏览器和节点.js 22或以后的小型ESM获取客户端. 它唯一的运行时间依赖是 `@flop-labs/contracts`。 。 。 .

```sh
pnpm add @flop-labs/client
```

```ts
import { FlopClient, FlopHTTPError } from "@flop-labs/client";

const client = new FlopClient({ apiKey: "your-flop-api-key" });
const models = await client.listModels();
const model = await client.getModel(models.data[0].id);

try {
  const completion = await client.createChatCompletion({
    model: model.data.id,
    messages: [{ role: "user", content: "Hello" }],
    stream: false,
  }, { signal: AbortSignal.timeout(30_000) });
  console.log(completion.choices);
} catch (error) {
  if (error instanceof FlopHTTPError) {
    console.log(error.status, error.retryAfter);
    // error.body retains the gateway's structured error, or non-JSON text.
  }
  throw error;
}
```

默认 `baseURL` 实值 `https://api.flop.network/v1`公众别名 [`services/rest-gateway/README.md`](https://github.com/flop-labs/flop-core/blob/main/services/rest-gateway/README.md)。只获得来源的 URL `/v1` 附录。 明确的 API 路径必须结束于 `/v1` (包括 `/api/v1`);后行鞭打被去除. HTTP(S) URL 包含证书,查询或片段被拒绝. 重新定向从未被跟踪;浏览器可能暴露为状态为0的不透明HTTP错误.

模型发现不需要 API 密钥, 也不发送无记名证书 。 聊天完成和收件检查要求 `apiKey` 并只将其发送到已配置的网关。 在服务器上保留特权证书 . `fetch` 可以注射用于测试或兼容的运输. 每个方法都接受一个可选的呼叫器 `signal`请求使用 `credentials: "omit"` 财务报告和审定财务报表 `redirect: "manual"`。 。 。 .

请求在网络接入前经过验证;利用共享合同在结构上检查JSON成功的答复。 供应商扩展和接收字段不变地返回。 这些是 **网关所报告数据**:客户不核实收据,证明书,付款,连锁包容,或最终性.

客户端支持 `listModels()`, (中文(简体) ), `getModel(id)`, (中文(简体) ), `createChatCompletion(request)` (杰森语), `streamChatCompletion(request)` (SSE),和 `getCredentialReceipt(requestId)`钱包业务、x402资金和赠款薄荷在外。 已付款的请求一经发出:没有自动复试,包括429次,取消或运输故障。 暂停不能确定网关没有起作用;在人工重复付费电话之前解决这一结果.

`listModels` 还接受 `offset` (非负整数), `limit` (1-1000) (中文(简体) ), `output_modalities` 财务报告和审定财务报表 `supported_parameters` (名称阵列),与 `signal`。这些序列化为公共模型种子的查询参数;模型细节 ID 被编码为一个路径段.

`FlopHTTPError` 保留 `status`, (中文(简体) ), `body`,原始的则 `retryAfter` 头曰. 它的信息不包括请求的证书和网关机构内容. `FlopValidationError` 报告配置、输入或成功反应不当. `FlopTransportError` 将潜在的运输故障保留为: `cause`;呼叫取消会宣传信号的理由. 避免登录错误机构或原因,而不应用您的应用程序的数据政策.

## 正在流出聊天完成

`streamChatCompletion` 返回一个同步生成器。 它第一次发送一个POST 激起 力量 `stream: true`并拒绝明白的、 `stream: false`。其产量 结构验证 `ChatCompletionChunk` 对象返回 a `ChatCompletionStreamResult` 成功终止。 使用 `next()` 保留 终端返回值( o)`for await` 消耗块但丢弃返回值 :

```ts
const stream = client.streamChatCompletion({
  model: "flop/model",
  messages: [{ role: "user", content: "Hello" }],
}, { signal: AbortSignal.timeout(30_000) });

while (true) {
  const next = await stream.next();
  if (next.done) {
    console.log(next.value.finishReason, next.value.usage, next.value.receipt);
    console.log(next.value.toolCalls); // Complete calls assembled by index.
    break;
  }
  console.log(next.value.choices[0]?.delta.content ?? "");
}
```

执行人执行角色/内容/工具/完成/使用/`[DONE]` 生命周期. 只有一个有效的成功 完成、使用/接收框架, `[DONE]`,而被关闭的机体则产生终端结果. 提前执行关闭时不返回结果;关闭则取消身体 读者。 客户端通过 EOF 读取拒绝数据框架 `[DONE]`。 。 。 .

在溪流打开前, 未成功 HTTP 状态丢弃 `FlopHTTPError`,保留 尸体和 `Retry-After`HTTP 200 要求 `text/event-stream`; JSON 重放 对流出请求的回复被拒绝。 投出带内故障 `FlopStreamError` 与 `body`, (中文(简体) ), `usageSource` (单位:千美元)`"estimated"` (一) 供应时, `retryAfter` (秒),和 `outputStreamed`8\. 收款使用情况和估计出错使用情况仍然不同. 框架或命令抛出错误 `FlopValidationError`缺少 `[DONE]` 或一个 运输失败抛出 `FlopStreamInterruptionError`与已知的事业.

以信号的确切原因中止拒绝并取消阅读器. 取消 停止阅读;它不会取消接受的工作或付款。 无出错或中断 触发重试。 和解和任何重播都是打电话者的决定.

## 呼叫者拥有的重放身份

两种付费方法都接受 `{ idempotencyKey }` 并行 `signal`键作为 `Idempotency-Key`,必须包含1-128可打印的 ASCII 字符,没有白空格, 发现后就会被拒绝 客户端从不为您创建密钥或重试. 持久恢复用途 `createChatCompletion` 与 `stream: false`: 网关 存储完成的 JSON 响应用于重放,而不是重放的 SSE 正文.

## 追回含糊不清的请求

坚持请求 ID, 原始相关性 ID, 确切的请求正文和网关 URL 在第一个支付POST之前. `Idempotency-Key` 是请求的ID,除非呼叫者 用品 `X-Request-ID`,优先进行。 失去反应后,使用 `getCredentialReceipt` 在考虑重放前使用同一ID:

```ts
import { FlopClient, FlopHTTPError } from "@flop-labs/client";

// Loaded from the application's durable job record; no new ID is generated here.
async function observeLostResponse(client: FlopClient, originalRequestId: string) {
  try {
    const receipt = await client.getCredentialReceipt(originalRequestId, {
      signal: AbortSignal.timeout(10_000),
    });
    if (receipt.state === "reserved" || receipt.state === "estimated") {
      return { action: "wait-or-reconcile" as const, receipt };
    }
    return { action: "review-terminal-observation" as const, receipt };
  } catch (error) {
    if (error instanceof FlopHTTPError && error.status === 404) {
      return { action: "investigate-missing-record" as const };
    }
    // 401: obtain authorized parent access; timeout/transport failure: outcome unknown.
    throw error;
  }
}
```

此示例不提交推论,也不记录证书、提示或产出. 既无缺行也无超时证明没有发生有偿工作。 他们必须 不启动自动替换的带薪工作。 如果操作员随后选择 JSON重放,使用原始证书,ID,相关ID,身体和路由; 3; 积极的父母可以检查孩子的分类账,但不能作为孩子重放.

检索用途 `GET /keys/me/receipts/{request_id}` 并读到一个准确的,对案件敏感的 ID独立于最新20榜单. 身份证跟随客户端的1-128可打印的 ASCII 符号规则; `.` 财务报告和审定财务报表 `..` 路径段无效。 客户端 URL 编码 ID 和 将回复描述为 `CredentialReceipt`。错误的ID 本地失败 `FlopValidationError` (HTTP呼叫者收到400 `invalid_request_id`; 401 否认 失踪/无效/失效/撤销权力; 404 `receipt_not_found` 包括两个缺席 和范围外的记录 而不透露另一个证书的要求.

积极的家长会看到自己和所有孩子的要求。 一个孩子只看到自己的 即使其用途已用尽或 演示文稿窗口关闭。 查找既未显示新会话, 也未扩展会话 . 儿童期满或被吊销,拒绝与该儿童一起获得康复;使用其授权, 替换为活动父 。 父母期满或撤销均否认。 过期子女补助金 在未解决的请求完成后, 元数据会被刷新, 而保留分类账行 仍然可以被活动父母读取.

`reserved` 持有未设完成检查站的配额; `estimated` 保留 完成后保留,实际开支尚未解决. `settled` 核对记录 支出和 `released` 记录还原了保留配额。 释放行不 发明零结算证据. `response_status` 描述缓存的 HTTP 检查点 与定居无关。 重新找找就可以在原作开始的时候解决 缓存的 JSON 完成情况仍有待报告; 重放未改变的检查点返回 . 检查时不返回快取、输出或缓存的完成正文.

`reserved_spend` 财务报告和审定财务报表 `settled_spend` fLOP 配额值. `settled_spend_raw`当可用时,是作为小数整数的精确分配 原始 FLOP 基单元中的字符串 : **10^18 生 = 1 FLOP**。未知数量、频道标识符 而终极事件仍然是无效的. `terminal_event` 识别可用的终端 频道证据; 集合请求共享频道事件和分配, 不分开 要求矿工付款或烧掉交易。 这些观测数据是网关数据, 或承诺立即解决.

回收只覆盖已配置的网关所保留的 SQLite 分类账 。 没有 今天的自动分类账 TTL,但没有存档或跨出道保证:数据库 丢失、 操作员删除或切换网关可以使记录无法使用。 保护 根据您申请的留用政策,您拥有自己的工作身份和证据.

## 任务关联

网关组代理任务转弯 `X-Correlation-ID`调用 `client.task()` 一次 每个任务并通过返回的手柄进行付费呼叫: 相同的随机 id, 和下一个 `task()` 呼叫开始一个新的.

```ts
const task = client.task(); // or client.task("job-42") to supply your own id
await task.createChatCompletion({ model: "qwen/qwen3-8b", messages });
await task.createChatCompletion({ model: "qwen/qwen3-8b", messages: [...messages, reply, toolResult] });
```

两种方法都接受 `{ correlationId }` 直接说 值跟随 一分之能 - 键符号规则 并在发现时被拒绝。 不重复使用一个标识 任务,因为网关将将它们合并为一个会话。 在一个 一能键必须发送其原始相关性 id.

## 常见问题

### @flop-labs/client 是什么？

为 FLOP 公共模式发现获取客户端并网关聊天完成

### 如何安装 @flop-labs/client？

在项目目录运行 npm install @flop-labs/client，或使用 pnpm add / yarn add / bun add。

### @flop-labs/client 支持 TypeScript 吗？

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

### @flop-labs/client 支持 ESM 还是 CommonJS？

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

### @flop-labs/client 需要什么版本的 Node\.js？

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

### @flop-labs/client 可以商用吗？

@flop-labs/client 使用 MIT OR Apache-2\.0 许可。可在 MIT、Apache-2\.0 中任选其一遵守。选择 MIT 时，宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @flop-labs/client 的下载量有多少？

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

### @flop-labs/client 还在维护吗？

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