# @flovialabs/sdk 中文文档

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

版本：0\.1\.23
npm 元数据更新时间：2026-11-11T11:26:32.493Z
中文译文更新时间：2026-11-15T00:29:19.219Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40flovialabs/sdk
原文对照：https://npmcn.com/package/%40flovialabs/sdk/?lang=original
项目主页：https://api.flovia.dev/
源码仓库：https://github.com/flovia/groupbuy

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

- 包体积（解压后）：227 kB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-10-12T16:53:07.844Z
- 最新版本发布：2026-11-11T11:26:31.801Z
- 近 30 天下载量：3191（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 25 个）

## 中文简介

TypeScript客户端和CLI for Flovia:在HTTP和OpenAI相容生成上使用MCP工具. 零从属.

## 安装

```sh
npm install @flovialabs/sdk
```

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

## README

# @flovialabs/sdk (英语)

TypeScript 客户端和命令行工具 [弗洛维亚](https://api.flovia.dev/). 它称弗洛维亚的工具凌驾于MCP(HTTP)及其可兼容的OpenAI文本生成上.

> **Flovia在α;API可能会有变化.** 打开您使用的版本 .

-   具有类型申报的无害环境管理,无运行时间依赖(使用) `fetch` 页:1.
-   节点.js 20或后,或 Bun.

## 安装

```sh
npm install --save-exact @flovialabs/sdk@0.1.23
```

## 0.1.23 发布说明

`flovia resets` 同步读取已保存的重排和自由窗口状态,并显示一个等待指标。 两者都读取即使一个失败也开始;如果两者都失败,第一个拒绝决定错误. TTY 等待反馈更新一行 stderr 并在请求完成后清除. 成功输出和 JSON 保持其已存在的形状; 有管的 Stderr 和 `--json` 没有等待反馈。 这份解约预计同一份合同 `2026-10-07.208` 并且不改变公共客户的方法、类型或运行时间依赖.

## 0.1.22 释放说明

这份解约合同 `2026-10-07.208` 包含 `team_feature_off` 在打入的公开拒绝代码。 它没有增加客户方法或运行时间依赖。 Per-Team sandbox 选入仍以部署为主。 安装 SDK 无法启用该门或更改 Team 所有人设置 .

## 0.1.21 发布说明

这份解约合同 `2026-10-07.207`。它为代码运行、保存结果、时间表和团队工作空间添加了输入方法和CLI命令。 代码运行和Team任务仍受中继器的可用性和同意性检查;安装SDK不能允许. 在发送前保存原始操作ID并请求 。 丢失的答复或 `executed: "unknown"` 并不是没有运行的证据, 所以永远不要创建 替换操作回收它.

## 0.1.20 发布说明

这份解约合同 `2026-10-07.198`它添加 `client.spendMode()` 编号 : `flovia spend-mode` 仅限自由模式和 `client.keyCaps()` 编号 : `client.setKeyCaps()` 编号 : `flovia key-caps` 每日和月支出上限。 中继回复 `.182` 添加 `flovia_quote` 工具,双子座 `status` 编号 : `incomplete_details`,全输入快节点日志结果,用法崩溃的生成行,Firecrawl和上下文。 dev 读取没有 `operation_id`,则 `elevenlabs_terms_required` 拒绝。 CLI 现在拒绝错误的操作代号,一个缺失的选项值,以及一个带查询或片段的基站URL,然后发送任何东西. 提供者的可用性遵循中继器目前的配置.

## 0.19 发布说明

这份解约合同 `2026-10-07.182`,其中继回复包括上下文。 Dev 输入-反驳细节,MiniMax搜索ID和冲突恢复指导,南森连锁退休通知,以及fal工作计数与已结算的购买-余额支出. SDK还拒绝在发送请求前超过节点计时器的超时值. 提供者的可用性遵循中继器目前的配置.

## 0.18 发布说明

这份解约合同 `2026-10-07.178`它添加 `flovia install --client` 和只读 `flovia doctor` 命令,列出最多30天的使用历史,并导出可选 `ForUser` 编号 : `ReplyCharge` 包括收费信息的答复类型。 缺少的电荷不是零。 不得增加重播和工作快照作为新调用. 以前的释放情况保持不变.

## 0.17 释放说明

此版本引入 `client.consent()`, (中文(简体) ), `client.acceptConsent(version)` 编辑 `flovia consent` 命令,这些命令不在已发布的0.1.16包中。 它期望合同 `2026-10-07.172`当当前通知是 `relay-consent-19`, CLI 显示其12月 3日的新记录规则。 你之前的"是"一直在工作, 和CLI从来没有为你回答.

符合资格的南森回答和生成的文本/音频只能由所有者在18号通知下重新开放,最长30天,从原始记录的创建开始. 检索可用性遵循Relay推出程序,以及每个原始记录上的通知。 早期的记录保留了原来的时期. 其他查询答复和Fal.ai URL副本的这一段时间只能用于新的通知19记录,从2026-12-03年,或者在您重新明确同意通知19之后。 旧的18号通知和较早的检索副本保留了约15分钟;后来的协议从不延长。 重新打开不会延长最后期限、获取新数据或恢复缺失的副本。 一个fal.ai图像 URL在大约一个小时后仍然会过期;一个被保存的URL不会延长图像的寿命.

## 钥匙

1.  登记地点: [https://console.flovia.dev/auth/register 页面存档备份,存于互联网档案馆](https://console.flovia.dev/auth/register) 还有电子邮件和密码.
2.  单位 [弗洛维亚控制台](https://console.flovia.dev/groupbuy/)键。 给出CLI或Cursor等应用名称. 控制台显示一次;保存在私人的地方.
3.  设置密钥( E)`flv_...`在环境中,然后检查它:

```sh
export FLOVIA_KEY=flv_...
npx flovia status
```

无 `FLOVIA_KEY` 或者说 `--key-file`,CLI读取 `~/.config/flovia/key`,文件控制台的 Claude 代码设置保存.

Claude 代码插件QQ `~/.config/flovia/relay-key` CLI 插图 克洛德码 `/flovia:setup` を再実行してください(保存先の基点) `28e5cbeee1d7bca5c68c18d765e576445e452997`. 2026-10-25-X\] (中文(简体) )。

`status` 显示您使用过多少免费津贴,以及您购买的余额。 购买的零美元余额是罚款,而免费的津贴仍存.

试验期的钥匙不再起作用。 这个 [快速启动](https://docs.flovia.dev/get-started/quickstart/) 有完整的步骤,和 [免费有偿使用](https://docs.flovia.dev/usage/) 解释出限制。 您可以在一个账户中保存最多5个活的 API 密钥; 全部分享其备抵、 余额和限制 。 如果一个密钥丢失或被曝光, 请在 API 密钥标签中为该密钥选择 Revoke [弗洛维亚控制台](https://console.flovia.dev/groupbuy/),然后创建 API 密钥并更新所使用的应用程序。 其他密钥和OAuth连接继续工作. 见 [管理 API 密钥](https://docs.flovia.dev/connect/check/#manage-api-keys)。安装此软件包不会创建账户或启动免费的备抵.

在代码中,客户端读取 `FLOVIA_KEY`或者你可以通过它作为 `new FloviaClient({ apiKey })`。客户端保留密钥的私密性:它不出现在日志、错误消息或 `console.log(client)`SDK没有发出遥测信号.

`baseUrl` 需要 HTTPS。 Plain HTTP 只能用于回路开发(`localhost`, (中文(简体) ), `127.0.0.1`, (中文(简体) ), `[::1]`) (中文(简体) ). 原始运输诊断不附在错误上,因为它们可能包含请求头.

## 快开始

```ts
import { FloviaClient, newOperationId } from "@flovialabs/sdk";

const flovia = new FloviaClient(); // reads FLOVIA_KEY; base URL https://api.flovia.dev

// Your free allowance windows, services and the contract version
const status = await flovia.status();
console.log(status.five_hour.used_pct, status.week.used_pct);

// Your lookups today (or the last N days, up to 30)
const usage = await flovia.usageToday(); // today, UTC

// Any tool: list them, then call one
const tools = await flovia.listTools();
const reply = await flovia.call("flovia_status");

// A text generation (uses your free allowance first, then your purchased balance). Save the operation id before sending.
const op = newOperationId();
const request = { model: "gpt-6-luna" as const, input: "Explain a DEX aggregator in one sentence.", reasoning: { effort: "low" as const } };
// Persist { op, request } in your application's private storage before the next line.
const g = await flovia.generate(request, { operationId: op });
console.log(g.response.status, g.response.incomplete_details, g.outputText);
```

### 第一次数据查询

`listTools()` 返回提供给您的账户及其工具 `inputSchema`。目录调用不会给数据提供者带来任何信息。 例如, 列出 CoinGecko 路径, 然后进行一个价格查询 :

```ts
await flovia.call("flovia_coingecko", {
  path: "list", request_text: "Which prices can I read?", purpose: "choose a supported path",
});
const priceRequest = {
  path: "/simple/price", query: { ids: "bitcoin", vs_currencies: "usd", include_last_updated_at: true },
  request_text: "What is Bitcoin's USD price?", purpose: "check a price with its update time",
  conversation_id: "sdk-price-example", operation_id: newOperationId(),
};
// Save priceRequest before sending; this lookup uses your free allowance or purchased balance.
const price = await flovia.call("flovia_coingecko", priceRequest);
```

如果打电话要求通知或同意,请停止并跟踪下面的人的回答。 读取返回的源时间, 覆盖和缺失值说明; 成功的查找并不能保证它能回答您的问题 。 Flovia曝出所选的只读路径,方法和公开的HTML主机,而不是上游计划中的每一个特性. 使用支持子集的活目录 。 OpenAI 支持文本生成方式 `gpt-6-luna`;它不获取其他提供者或提供图像/音频生成.

### 运行道图像和视频

何时 `listTools()` 提议 `flovia_runway`,使用同样的 `call()` 方法和你的克洛维亚键。 跑道需要当事人的单独同意: 显示返回的通知, 只询问何时 `next_step` 请求它。 永远不要为这个人提供同意 跑道可就投入和产出进行培训;不发送私人资料或证书.

```ts
const catalog = await flovia.call("flovia_runway", { action: "list" });
// After the person's actual consent has been recorded, save this request before sending.
const imageRequest = {
  action: "image", prompt: "A blue paper circle on a white background",
  operation_id: newOperationId(),
};
const accepted = await flovia.call("flovia_runway", imageRequest);
// Accepted is not completed. Later, explicitly read the same job's status:
const result = await flovia.call("flovia_runway", {
  action: "status", operation_id: imageRequest.operation_id,
});
// Only when output.state is ready, using the generation_id returned by Flovia:
const output = await flovia.downloadRunwayOutput(String(result["generation_id"]));
// output.data is Uint8Array; output.contentType is the checked media type.
```

图像为 1 720p `gen4_image` 结果。 视频使用 `action: "video"` 与 `duration: 2` 结束 `5`,并返回 MP4。 运行道任务不会自动再发送, 即使使用 `retryRateLimited: true`,在断开或未知结果后保留原始操作ID;从不生成替换以恢复. 失败/ 缓和的一代仍可能被充电 。 状态将计费状态与产出交付区分开来.

Flovia在18号通知(早期记录保留24小时)下,自创建起最多30天的私人产出,并有经过认证的下载; 跑道本身的保留是独立的. SDK的下载是一个被绑定的(32 MiB),一个请求Get to Flovia,从不提供URL. 下载不会再次生成或充电 。 只使用 OAuth 的 MCP 用户可以使用返回的 `console_download_url` 在他们自己的控制台上签字.

```bash
flovia call flovia_runway '{"action":"list"}'
# Create through call only after actual consent; save your JSON request first.
flovia call flovia_runway - < image-request.json
flovia call flovia_runway '{"action":"status","operation_id":"<saved-operation-id>"}'
flovia runway-output <generation_id> --out image.png
```

`runway-output` 用模式创建新文件 `0600`它永远不会覆盖。 一个失败的写入可能会留下一个私有的部分文件,因此在选择另一个输出路径之前检查它. 显示 **由跑道供电** 链接到 [运行路径](https://runwayml.com/) 显示生成的介质时; SDK 消费者必须将这种归属带入自己的界面.

### 运行一个结果, 显示它, 然后重新打开它

此完整示例另存为 `first-price.mjs` 在你身边 `node_modules`放在服务器侧或自己的机器上.

```js
// Run on your own machine. Never bundle this file, FLOVIA_KEY or private usage into a browser app.
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { pathToFileURL } from "node:url";
import { FloviaClient, FloviaError, newOperationId } from "@flovialabs/sdk";

const mode = process.argv[2];
if (!["--new", "--replay", "--saved"].includes(mode)) {
  console.error("Use --new once, --replay with the saved request, or --saved (no network).");
  process.exit(1);
}
const directory = new URL("./.flovia-price/", pathToFileURL(process.cwd() + "/"));
const requestFile = new URL("request.json", directory);
const answerFile = new URL("answer.json", directory);

try {
  let reply;
  if (mode === "--saved") {
    reply = JSON.parse(await readFile(answerFile, "utf8"));
  } else {
    const client = new FloviaClient();
    if (mode === "--new") {
      await mkdir(directory, { mode: 0o700 });
      const request = {
        path: "/simple/price",
        query: { ids: "bitcoin", vs_currencies: "usd", include_last_updated_at: true },
        request_text: "What is Bitcoin's USD price?",
        purpose: "display one price with its source update time",
        conversation_id: "sdk-first-price",
        operation_id: newOperationId(),
      };
      // Exclusive creation: rerunning --new cannot silently replace the operation that might have run.
      await writeFile(requestFile, JSON.stringify(request), { mode: 0o600, flag: "wx" });
      await client.status(); // Account/allowance read only; stop on authentication errors.
    }
    const request = JSON.parse(await readFile(requestFile, "utf8"));
    reply = await client.call("flovia_coingecko", request);
    await writeFile(answerFile, JSON.stringify(reply), { mode: 0o600 });
  }
  const price = JSON.parse(reply.response).bitcoin;
  const updated = price?.last_updated_at;
  console.log(JSON.stringify({
    display: mode === "--saved" ? "Saved locally; not a live update" : reply.stored_answer ? "Earlier answer; not a live update" : "Fetched once; not auto-updating",
    btc_usd: price?.usd ?? null,
    provider_updated_at: Number.isFinite(updated) ? new Date(updated * 1000).toISOString() : null,
    flovia_received_at: reply.created_at ?? null,
    lookup_id: reply.lookup_id ?? null,
    charge_guidance: mode === "--saved" ? "Nothing: this display is offline; see the original lookup in private usage"
      : reply.for_user?.charged_to_you ?? "Unavailable; do not assume zero",
    attribution: "Data provided by CoinGecko",
  }, null, 2));
} catch (error) {
  if (error instanceof FloviaError) {
    console.error(JSON.stringify({ code: error.code, executed: error.executed, operation_id: error.operationId, next_step: error.nextStep }));
  } else {
    console.error("Could not read, save or display the example. Keep .flovia-price unchanged; do not start a new operation to recover it.");
  }
  // No automatic resend, consent answer or replacement operation, including on pending/unknown or an expired saved answer.
  process.exitCode = 1;
}
```

在安装此 SDK 和设置后 `FLOVIA_KEY` 私人,运行:

```sh
# One new CoinGecko lookup; uses your free allowance or purchased balance.
node first-price.mjs --new
# Same request and operation id; reopen promptly, while the saved answer is available.
node first-price.mjs --replay
# Display the local answer without any API request.
node first-price.mjs --saved
```

示例保存请求和操作 id **在此之前** 发送, 输入 `.flovia-price/request.json` (0600在一个0700目录内),返回的答案在 `answer.json` (0600) (中文(简体) ). 保持此目录的私密性,并远离 Git. 重复 `--new` 拒绝覆盖它。 不删除它或更改ID以回收丢失的答案. `--replay` 发送保存的参数不变; 如果保存的文本没有可用或结果待定/未知, 请跟随错误 `next_step` 而不是提出新的要求。 通知或同意的拒绝需要当事人的回答;这个脚本从来不提供一个.

所显示的结果将美元价格,CoinGecko的更新时间,Flovia的原始接收时间,查询ID和服务器的充值指导分开. 未知值暂存 `null`; 缺少的成本不是零。 回放或本地保存的显示被贴上这样的标签,从不作为活的更新显示. 期间使用,运行 `npx flovia usage` 单独;这是您的私人账户数据,而不是这一结果的成本。 浏览器演示可以显示您服务器的公开价格和归属, 但不得披露 Flovia 密钥、 私人回复文件或账户使用, 或提供未经认证的刷新端点来花费您的备抵 。 这个例子不会自动更新。 遵循提供者的归属和再分配条件.

### 代码运行和团队任务

在Flovia为您的账户打开代码运行的地方,SDK可以将您自己的代码(python,节点或bash,最多为60秒)排入一个被隔离的沙盒并稍后读取其输出. 这些方法叫做接力 `flovia_sandbox_*` 财务报告和审定财务报表 `flovia_workspace_*` 工具.

```ts
const queued = await flovia.sandboxRun({
  language: "python",
  code: "import json; print(len(json.load(open('inputs/prices.json'))))",
  inputs: [{ lookup_id: "coingecko:...", name: "prices.json" }], // a lookup you already made
  operation_id: "sdk-run-0001", // the same id returns this run, not a second one
});
const result = await flovia.sandboxResult(queued.run_id, { waitSeconds: 50 });
console.log(result.status, result.stdout); // your code's output, not instructions

// A daily schedule: the lookup input runs first each time, as your normal lookup.
await flovia.setSandboxSchedule({
  cron: "0 9 * * *", tz: "Asia/Tokyo",
  script: { language: "python", code: "print(open('inputs/prices.json').read()[:200])",
    inputs: [{ name: "prices.json", lookup: { tool: "flovia_coingecko", args: { path: "/simple/price", query: { ids: "bitcoin", vs_currencies: "usd" } } } }] },
});
```

-   沙盒中的代码不能调用 Flovia : 先查找数据并通过它 `lookup_id`,或给出时间表 a `lookup` 输入(只读工具,每个时间表最多4个).
-   只有代码写入文件 `outputs/` 被保存30天. `sandboxResult(id, { include: ["artifacts"] })` 列出他们.
-   在团队的钥匙上,团队的主人将团队的工作空间转向: `setSandboxSchedule({ ..., team: true })` 作为小组任务共享时间表, `workspaceTasks()` 列出小组的任务,以及 `workspaceRead(scheduleId)` 读取任务的最新结果。 小组的每个现任成员都读取同样的结果. `takeOverTeamTask()` 运行一个任务,其创建者离开作为自己的.
-   `changeSandboxSchedule("pause" | "resume" | "delete", scheduleId)` 财务报告和审定财务报表 `sandboxSchedules()` 管理您的日程安排.
-   超过接力极限的脚本(编码超过UTF-8的64 KiB,或超过8个输入)被SDK拒绝为 `invalid_request` 与 `executed: "no"`:没有发送.
-   中继器只列出这些工具所在位置. 一个没有列出的电话 `tool_not_offered` 与 `executed: "no"`。其他拒绝保留中继器的代码,例如 `sandbox_disabled`, (中文(简体) ), `queue_full` 或者说 `consent_missing`,以及 `executed` 数值。 仅在请求未执行时处理 `executed` 实值 `"no"`打开 `"unknown"`,保留原始操作的ID和请求并跟踪 `nextStep`; 不创建替换操作.

### 思考努力

给露娜,准备 `reasoning.effort` 改为 `none`, (中文(简体) ), `low`, (中文(简体) ), `medium`, (中文(简体) ), `high`, (中文(简体) ), `xhigh` 或者说 `max`; 省略它保持了弗洛维亚的 `none` 默认。 更大的努力需要更长的时间,并使用更多的推理符号. 这些纪念品份额 `max_output_tokens` 与可见的答案,所以一个答案可能更短或 `incomplete`。默认产出限额为1,000个,明确上限为4,000个。 努力并不能提高弗洛维亚的每个要求支出上限或保证更好的答案. 与请求的其余部分一起省去努力;在同一操作id下更改是不同的请求,被拒绝.

### 操作 ID 和重放

`generate()` 需要操作 id (8-128 字符) `A-Z a-z 0-9 _ . : -`) (中文(简体) ). 创建一个 `newOperationId()` 并随请求而存储 **在此之前** 发送.

如果回复丢失( 超时、 网络出错 , `executed: "unknown"`),保留请求和 **不变** 编号. 完整或不完整的已保存的答案可在未更改的请求下重新打开, `replayed: true` 并且没有额外收费。 对于根据数据使用通知18(包括匹配的登记条款)制作的几代人,期限自创建起可长达30天. 这涵盖了2026-12-01T00:00Z的被接受用途,或者在您之前明确同意通知18后工作. 早期保留约15分钟;后期协议不延长时间. 保存失败或缺少副本甚至可以在过期前阻止重开 。 跟随 `nextStep` 页:1 `generation_pending` 或者说 `generation_unknown`;答案可能尚未获得。 之后 `answer_expired` 或者说 `operation_retired`,弗洛维亚无法返回所保存的文本。 过期或被删除的副本不恢复。 永远不要启动新的身份证明来恢复一个丢失的答案:这可能会运行和充电两次. 新一代需要个人决定再花. [数据使用](https://docs.flovia.dev/data-use/) 解释检索期及其限制.

## 错误

拒绝(`ok: false`)或请求失败 `FloviaError`数字 :

| 字段 | 含义 |
| --- | --- |
| `code` | 公共代码,例如 `rate_limited` 或者说 `window_5h` (单位:千美元)`PUBLIC_CODES` 列入清单)或 `http_<status>` |
| `message` | 发生了什么事 |
| `nextStep` | 接下来怎么办 |
| `executed` | `"yes"`, (中文(简体) ), `"no"` 或者说 `"unknown"`: 请求是否有效。 打开 `"unknown"`,保留相同的操作 id |
| `retryAfterSeconds` | 等待多久,当给与 |
| `status` | hTTP 状态, 当存在时 |
| `operationId` | 请求的编号 |
| `reply` | 整个答复机构 |

HTTP 401 为 `code: "formal_registration_required"` 测试访问结束: 注册于 [https://console.flovia.dev/auth/register 页面存档备份,存于互联网档案馆](https://console.flovia.dev/auth/register) 带有电子邮件验证和一个 Passkey(或者如果有的话在邀请邮件中使用链接); 如果您已经注册, 请在 Console 上签名, 按 Create API 键, 然后与新密钥重新连接 。 通用软件 `unauthorized` 表示该密钥未被接受; 请检查您的账户和 Console 中的当前密钥 。 二者均不予同意(`executed: "no"`),从不自动复试. SDK不暴露任意认证响应机构.

### 通知和同意

这两个代码故意停止呼叫. 完整显示通知并跟随 `nextStep`;可能需要单独的明确选择加入。 SDK从来不同意这个人.

1.  显示完整 `error.reply.user_notice` 不变(`error.reply.notice` 案件报告),以及 `error.reply.consent.question` 当在现相. 对于 `data_consent_needed`,使用时 `consent.line` (b) 简短的问题不能取代通知.
2.  对于 `data_consent_needed`通过你正常的流量 得到个人的答案 跟随 `nextStep` 关于同意工具: 寻找同意用途 `flovia_data_consent`; 运行道使用 `flovia_runway` 与 `action: "consent"`。通过 `answer` (单位:千美元)`"y"` 或者说 `"n"` 从这个答案, `consent_version` 从 `error.reply.consent.version`,以及 `user_words` 包含他们真实的话语。 不替换当前 SDK 版本或生成的答案 。 案例报告 `notice_first` 使用自己的明确选择并返回 `consent_version`没有 `flovia_data_consent`。 。 。 .
3.  对于 `data_consent_needed`中,只在其 `y` 已接受 `n`停下来 对于 `notice_first`,显示通知并跟随 `nextStep`; 添加 `notice_shown: true` 只有在接到请求时。 永远不要自动选择报告.

不要从代码或代理中自动回答这些问题 .

## 检索

-   `client.generate()` (HTTP生成路径)从不自动怨恨.
-   与 `new FloviaClient({ retryRateLimited: true })`,拒绝使用的工具呼叫 `rate_limited`, (中文(简体) ), `too_many_in_parallel` 或者说 `reservation_changed` 财务报告和审定财务报表 `executed: "no"` 不满一次,不变(同: `operation_id`),在 `retry_after_seconds` (至少1 s,最多60 s). 默认关闭。 这涵盖通过调用生成工具 `client.call()` (单位:千美元)`flovia_openai`, (中文(简体) ), `flovia_minimax`, (中文(简体) ), `flovia_fal`)同样:这种拒绝意味着没有跑,也没有受到任何指控. `flovia_runway` 永远不要怨恨.
-   任何东西 `executed: "unknown"` 没有怨恨.

## 超时

每一次请求在300秒后默认出局(长一代需要几分钟). 换一个 `timeoutMs` (0以上,最多2147483647毫秒; `--timeout` 最多为2147483秒). 超时抛出 `FloviaError` 有代码 `timeout` 财务报告和审定财务报表 `executed: "unknown"`。 。 。 .

丢失或无法读取的答复也是 `executed: "unknown"`即使在HTTP 200之后。 保留已保存的操作 ID并请求; 不启动其它操作以恢复答案 。 退休手术从不被视为无所事事的证据.

## 合同版本

`status()` 比较服务器的 `contract_version` 用这个 SDK 是写给 (`EXPECTED_CONTRACT_VERSION`和警告者 `console.warn` 当他们分歧的时候。 将警告替换为 `onContractMismatch`。 。 。 .

## 国 际

软件包安装一个 `flovia` 命令.

```sh
export FLOVIA_KEY=flv_...              # or: --key-file ~/.config/flovia/key
npx flovia status
npx flovia usage --days 30
npx flovia tools
npx flovia tools --json              # includes each tool's inputSchema
npx flovia tools flovia_coingecko --json # only this tool's description and inputSchema
npx flovia call flovia_usage_today '{}'
npx flovia generate --op sdk-example-0001 --max-output 1000 --reasoning-effort low "Explain a DEX aggregator."
# Only to reopen that exact request while its saved answer is available:
npx flovia generate --op sdk-example-0001 --max-output 1000 --reasoning-effort low --yes "Explain a DEX aggregator."
npx flovia resets                    # saved resets and both free windows (read-only)
npx flovia resets use 42 --yes       # use saved reset 42 (cannot be undone)
npx flovia consent                   # current notice version, your yes and the notice text (read-only)
npx flovia consent accept relay-consent-19 --yes   # your own yes to the version just shown (same as Console)
npx flovia key-caps                  # each key's daily and monthly spending cap and use (read-only)
npx flovia key-caps set <key-id> --day 5 --month none   # cap one key; a call over it is refused, nothing charged
npx flovia spend-mode                # free-only or allow-paid (read-only)
npx flovia spend-mode free-only      # never use the purchased balance or plan credit
npx flovia sandbox run python job.py   # queue your own code; prints an operation_id first, then the run_id
npx flovia sandbox run python job.py --op sdk-run-0001   # the same request again (a lost reply): returns that run, queues nothing new
npx flovia sandbox result <run-id> --wait   # the run's status and output (your code's output)
npx flovia sandbox schedules         # your schedules (read-only)
npx flovia workspace                 # a Team key's shared tasks (read-only)
npx flovia workspace read <schedule-id>   # a Team task's latest result (read-only)
npx flovia agents-md                 # a short note for CLAUDE.md or AGENTS.md
npx flovia help
npx flovia --version
```

这些命令安装后运行 `@flovialabs/sdk` 在当前项目中。 没有本地安装, 请指定软件包 : `npx --package=@flovialabs/sdk@0.1.23 flovia --help`对每项新请求使用独特的操作代号; `sdk-example-0001` 仅是一个例子。 在发送前保存 id, 即时和选项, 并保持它们不变的重放 .

获取或管理您的密钥 [控制台](https://console.flovia.dev/groupbuy/),私自保存,然后运行 `flovia status --key-file <saved-key-file>`。连接的密钥仍然可以减少、撤消或停止共享; `status` 显示与提供者可用性分开。 它从来没有回答同意给你.

对于数据搜索,请保存其 JSON 对象(包括您所选择的) `operation_id`(在私人场合) `request.json` 发送前。 而不是用空壳来引用:

```sh
flovia call flovia_coingecko - < request.json
```

此发送保存的请求一次 。 重新打开它使用相同的文件和操作ID;从不创建新的ID来恢复丢失的答案. CLI 并不为 `call`检查现场 `inputSchema` 首先,遵守任何退回的同意或追回指示. `tools <tool> --json` 返回一个工具对象; `tools --json` 继续返回完整阵列。 既不执行数据查询 。 无 `--json`, (中文(简体) ), `tools <tool>` 以示例结尾 `call` 线条由 schema 所需的参数(替换位置符)所建。 Exa 和 Firecrawl 实例还包括默认动作输入和 `operation_id` 提供这些字段时占位符。 一个未知的工具名称获得最接近的要用的名称 .

与 `--json`,错误也是 Stdout 上的 JSON 对象 : `ok: false`, (中文(简体) ), `code`, (中文(简体) ), `meaning`,当存在时 `next_step`, (中文(简体) ), `executed`, (中文(简体) ), `retry_after_seconds` 财务报告和审定财务报表 `operation_id`,在回复自己字段旁边。 退出代码保持0,1和2.

在一个指令中连接一个AI客户端到弗洛维亚的MCP服务器(自0.118起;不包含在0.117中):

```sh
npx flovia install --client claude-code           # or codex, cursor, claude-desktop, hermes
npx flovia install --client cursor --auth key --dry-run
```

默认 `--auth oauth` 添加服务器并让客户端签名; 没有使用密钥 . `--auth key` 键文件的 Claude 代码(`--key-file`默认值 `~/.config/flovia/key`和 Codex 和光标 `FLOVIA_KEY` 财务报告和审定财务报表 `FLOVIA_API_KEY`;密钥从未被写入客户端的设置,命令参数或输出. Claude代码和 Codex 是通过自己的代码更改的 `claude mcp add` 财务报告和审定财务报表 `codex mcp add`光标 `~/.cursor/mcp.json` 保留其他条目。 赫尔墨斯探员有了新的 `~/.hermes/config.yaml` 仅当它缺失或为空;一个相同的生成条目保持不变。 其他已存在的赫尔墨斯设置则未受影响:使用Console的"快安装"手动将弗洛维亚合并. Claude桌面获得自定义连接器链接. `--dry-run` 显示命令和文件而不改变任何内容.

Hermes Agent默认使用它的客户端ID元数据文档. 如果登录报告 `invalid_client` 或时间已过期, 请遵守手册 [Hermes 指南中的 DCR 倒计时](https://docs.flovia.dev/connect/hermes/#if-sign-in-fails)。安装器使已有的Hermes设置保持不变.

检查什么 `install` (自0.118起;未包括在0.117中):

```sh
npx flovia doctor                                  # every client
npx flovia doctor --client codex --network
```

`doctor` 只读取每个客户端的个人设置( e)`~/.claude.json`, (中文(简体) ), `~/.codex/config.toml`, (中文(简体) ), `~/.cursor/mcp.json`, (中文(简体) ), `~/.hermes/config.yaml`) (中文(简体) ). 报告是否 `flovia` 入境点 `https://api.flovia.dev/mcp`,它是否在密钥中签名或使用密钥,以及该密钥文件是可读的还是设置了环境变量。 它从不写,从不运行客户端或帮助者,也从不打印密钥,信头值或URL的查询. 登录入站会让客户端的指令再次登录:在被撤销或过期的登录入站后,客户端会继续重新尝试,直到有人重新签名. Claude 桌面在 Claude 设置 > 连接器中检查 . `--network` 也问弗洛维亚: `/mcp` 必须回答其登录挑战,并且一个Flovia格式的密钥必须被公认条目的使用被接受 `flovia_status`。获取和读取回复时共享 `--timeout` 期限,默认为300秒。 无 `--client`,未设置的客户端被列出但不失败;当检查失败时,退出代码为 1.

对于 Claude Code, 医生只检查密钥文件 `headersHelper` 完全匹配帮助者 `install` 生成默认路径或提供的路径 `--key-file` 路径。 其他帮助者和不安全或类似证书式的环境可变名称产生认证警告并需要人工检查;医生既不读取另一把钥匙,也不发出该条目的请求. URL警告显示预期终点,而不与配置的URL主机或路径相呼应. 它不分析完整的TOML或YAML:内入式表和流量映射可以报告为缺入,需要人工检查.

对于一个AI特工, `flovia agents-md` 打印一个要粘贴到 `CLAUDE.md` 或者说 `AGENTS.md`。它没有钥匙,也没有提出要求.

对于多行生成文本,将原始输入保留在私有文件中 :

```sh
flovia generate --new-op --max-output 1000 --reasoning-effort high --yes - < prompt.txt
# To recover this request, use its printed id, the SAME file and options:
flovia generate --op <saved-id> --max-output 1000 --reasoning-effort high --yes - < prompt.txt
```

保持不变 `--key-file` 财务报告和审定财务报表 `--base-url` 我也一样。 以连字符开头的提示, 请使用 `--` {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}在催泪弹之前 {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}在催泪弹之前 长时间的回答需要几分钟;交互式终端显示在stderr上经过时间. 管道和JSON输出保持不变。 超时不能证明什么也没有跑:从不重复恢复 `--new-op`。部分答案被发送和解决,但CLI从未自动生成续作。 HTTP的答复不包括确切的弗洛维亚成本;使用费 `flovia usage` 总计,不是这个答案的价格。 重放会增加不收费.

`status` 显示您的购买余额. `usage` 显示查询数、免费备抵百分比以及从服务器购买的余额总额;其生成的小计已计入该期间的总额。 缺额显示 `-`,不是零,没有。 它没有增加四舍五入终点百分比。 要继续列名,请将打印的命令及其准确性复制 `--since` 财务报告和审定财务报表 `--cursor`; 不合并 `--days` 与 `--cursor`。 。 。 .

-   每个命令都用 `--json` (原始答复), `--base-url URL`, (中文(简体) ), `--timeout SECONDS` 财务报告和审定财务报表 `--key-file PATH`。 。 。 .
-   `generate` 先使用免费补贴,然后使用购买的余额。 这需要 `--op ID` 或者说 `--new-op`,并请求在终端上确认;添加 `--yes` 脚本.
-   `generate` 打印响应状态和不完整的理由. `incomplete` 编号 : `max_output_tokens` 指已交付的文本被停止在输出极限,而不是继续运行. 0出局指响应已经送达,而非文本完整或正确. `--json` 保持公众的充分反应.
-   `resets` 仅读取:被保存的重排数,下一个过期,以及5小时和每周窗口. `resets use <id> --yes` 使用 1; 免费窗口( 5小时和每周) 从0% 重新开始 。 无 `--yes` 即使是在终端上 也没有寄出去 它从来不是自动的怨恨:在回复失败后,运行 `flovia resets` 在再次尝试之前. `Not used; nothing changed.` 1. 在代码中: `client.bankedResets()` 财务报告和审定财务报表 `client.useBankedReset(id)`。 。 。 .
-   `consent` 仅读取:当前通知版本,您上次表示是的版本,是否是更早的版本(它继续工作;继续使用接受当前版本),以及完整的通知. `consent accept <version> --yes` 记录您自己对这个版本的肯定, 和在 Console 中回答的相同; 旧版本被拒绝, 没有记录, 重复更改任何内容 。 无 `--yes` 它显示文本, 并发送任何信息( Exit 2) 。 只有账户所有者才能管理,从不代表他们代理. 在代码中 : `client.consent()` 财务报告和审定财务报表 `client.acceptConsent(version)`。 。 。 .
-   退出代码:0好,1个来自弗洛维亚的错误,2个使用错误.

### 安全问题

-   密钥只读取自 `FLOVIA_KEY` 或密钥文件,绝不来自命令行参数(其他用户可以在 `ps`) (中文(简体) ). 从未印出.
-   可供其他用户读取的密钥文件获得警告; 使用 `chmod 600`。 。 。 .
-   `--base-url` 必须是 `https`,因此密钥从未被加密发送。 平面 `http` 仅允许 `localhost`, (中文(简体) ), `127.0.0.1` 财务报告和审定财务报表 `[::1]`。 。 。 .
-   CLI显示完整的通知, `next_step` 和任何返回的 `consent.question`然后停下来。 打开 `data_consent_needed`, (中文(简体) ), `consent.line` (作为跑道返回)提供问题的时间 `consent.question` 缺席。 问题列在下面 `Your choice:`。通知文本、链接和问题保持不变;只缩短标题和帮助文本。 此人应答; `--yes` 确认支出,而不是数据同意或报告选择进入.

## 许可证

麻省理工学院

## 常见问题

### @flovialabs/sdk 是什么？

TypeScript客户端和CLI for Flovia:在HTTP和OpenAI相容生成上使用MCP工具\. 零从属\.

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

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

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

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

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

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

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

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

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

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

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

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

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

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