# @atcute/firehose 中文文档 规范地址：https://npmcn.com/package/%40atcute/firehose/ 版本：1\.2\.0 npm 元数据更新时间：2026-09-10T13:43:29.912Z 中文译文更新时间：2026-11-07T01:51:52.526Z 软件包许可：0BSD 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40atcute/firehose 原文对照：https://npmcn.com/package/%40atcute/firehose/?lang=original 源码仓库：https://tangled.org/did:plc:pljn5qch4tgadongtc7i6qij ## 关键信息（来自 npm 元数据） - 包体积（解压后）：21.1 kB，13 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - 运行依赖：6 个 - peer 依赖：@atcute/lexicons ^2\.1\.0 - 首次发布：2025-11-05T23:39:09.340Z - 最新版本发布：2026-09-10T13:43:29.746Z - 近 30 天下载量：13918（2026-10-07 至 2026-11-05，npm 官方下载统计） - 已发布版本数：7（近 12 个月 6 个） ## 中文简介 aT 协议的轻量级和可爱的 XRPC 订阅客户端 ## 安装 ```sh npm install @atcute/firehose ``` 也可以使用：`pnpm add @atcute/firehose`、`yarn add @atcute/firehose`、`bun add @atcute/firehose` ## README # @ atcute/ firehose (法语) aT协议的轻量级XRPC订阅客户端. ```sh npm install @atcute/firehose ``` 此软件包为 XRPC 订阅提供通用客户端 - 基于 WebSocket 的流线 aT议定书使用的协议。 它处理框架解码、自动重接和可选计划 审定. 用于消费 Bluesky 网络起火,请考虑使用 `@atcute/jetstream` 相反, 它提供了更简单的基于JSON的界面. ## 使用量 ### 连接到接力火花 ```ts import { FirehoseSubscription } from '@atcute/firehose'; import { ComAtprotoSyncSubscribeRepos } from '@atcute/atproto'; const subscription = new FirehoseSubscription({ service: 'wss://bsky.network', nsid: ComAtprotoSyncSubscribeRepos.mainSchema, }); for await (const message of subscription) { console.log(message.$type, message.seq); } ``` 当您从循环中跳出时,连接会打开,然后关闭。 页:1 基础的 WebSocket 在断开时自动重接. ### 取消订阅 通过一个 `AbortSignal` 关闭连接并拒绝重复: ```ts const subscription = new FirehoseSubscription({ service: 'wss://bsky.network', nsid: ComAtprotoSyncSubscribeRepos.mainSchema, signal: AbortSignal.timeout(10_000), }); for await (const message of subscription) { console.log(message.$type); } ``` ### 处理信件类型 信件包括: `$type` 字段表示其类型 : ```ts for await (const message of subscription) { switch (message.$type) { case 'com.atproto.sync.subscribeRepos#commit': { // repository commit (record creates, updates, deletes) console.log('commit:', message.repo, message.rev); break; } case 'com.atproto.sync.subscribeRepos#handle': { // handle change console.log('handle:', message.did, message.handle); break; } case 'com.atproto.sync.subscribeRepos#migrate': { // account migration console.log('migrate:', message.did, message.migrateTo); break; } case 'com.atproto.sync.subscribeRepos#tombstone': { // account deletion console.log('tombstone:', message.did); break; } case 'com.atproto.sync.subscribeRepos#identity': { // identity update console.log('identity:', message.did); break; } case 'com.atproto.sync.subscribeRepos#account': { // account status change console.log('account:', message.did, message.active); break; } } } ``` ### 跟踪光标以恢复 使用函数用于 `params` 为每次连接尝试提供当前光标: ```ts let cursor: number | undefined; // load saved cursor if resuming const saved = localStorage.getItem('firehose-cursor'); if (saved) { cursor = Number(saved); } const subscription = new FirehoseSubscription({ service: 'wss://bsky.network', nsid: ComAtprotoSyncSubscribeRepos.mainSchema, // function is called on each connection/reconnection params: () => ({ cursor }), }); for await (const message of subscription) { if ('seq' in message) { cursor = message.seq; // periodically save cursor for recovery if (cursor % 1000 === 0) { localStorage.setItem('firehose-cursor', String(cursor)); } } } ``` 每次连接尝试时都会调用参数函数,所以当 WebSocket 在一个 断开,它自动使用最新的光标值. ### 使用多个服务器 通过一系列 URL 自动失效。 客户端在每次连接上随机选择一个: ```ts const subscription = new FirehoseSubscription({ service: ['wss://bsky.network', 'wss://bsky-relay.example.com'], nsid: ComAtprotoSyncSubscribeRepos.mainSchema, }); ``` ### 处理出错 XRPC订阅可以发送出出错帧. 处理他们与 `onError` 回调 : ```ts const subscription = new FirehoseSubscription({ service: 'wss://bsky.network', nsid: ComAtprotoSyncSubscribeRepos.mainSchema, onError(err) { console.error('firehose error:', err); // common errors: // - "FutureCursor": cursor is ahead of the server // - "ConsumerTooSlow": client is not consuming messages fast enough }, }); ``` ### 连接周期召回 处理记录或 UI 更新的连接事件 : ```ts const subscription = new FirehoseSubscription({ service: 'wss://bsky.network', nsid: ComAtprotoSyncSubscribeRepos.mainSchema, onConnectionOpen(event) { console.log('connected to firehose'); }, onConnectionClose(event) { console.log('disconnected:', event.code, event.reason); }, onConnectionError(event) { console.error('connection error:', event.error); }, }); ``` ### 在运行时更新选项 使用 `updateOptions()`。这引发了重联: ```ts const subscription = new FirehoseSubscription({ service: 'wss://bsky.network', nsid: ComAtprotoSyncSubscribeRepos.mainSchema, }); // later, switch to a different service subscription.updateOptions({ service: 'wss://different-relay.example.com', }); ``` ### 禁用信件验证 默认情况下,电文将对照计划进行验证。 如果您为更好的性能, 请禁用此选项 信任服务器 : ```ts const subscription = new FirehoseSubscription({ service: 'wss://bsky.network', nsid: ComAtprotoSyncSubscribeRepos.mainSchema, validateEvents: false, }); ``` ### WebSocket 选项 将选项传递给基础 [派对](https://github.com/partykit/partykit/tree/main/packages/partysocket) 网络安全套 自定义再连接行为 : ```ts const subscription = new FirehoseSubscription({ service: 'wss://bsky.network', nsid: ComAtprotoSyncSubscribeRepos.mainSchema, ws: { maxRetries: 10, minReconnectionDelay: 1000, maxReconnectionDelay: 30000, }, }); ``` ## 常见问题 ### @atcute/firehose 是什么？ aT 协议的轻量级和可爱的 XRPC 订阅客户端 ### 如何安装 @atcute/firehose？ 在项目目录运行 npm install @atcute/firehose，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@atcute/lexicons（^2\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @atcute/firehose 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/atcute\_\_firehose 是否存在。 ### @atcute/firehose 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @atcute/firehose 可以商用吗？ @atcute/firehose 使用 0BSD 许可。几乎没有限制：可自由使用、修改和分发，连保留版权声明也不要求。以上为概括，不构成法律意见，请以许可原文为准。 ### @atcute/firehose 的下载量有多少？ 根据 npm 官方下载统计，@atcute/firehose 在 2026/10/07 – 2026/11/05 这 30 天内被下载 13,918 次，日均约 464 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @atcute/firehose 还在维护吗？ 最新版本 1\.2\.0 发布于 2026/09/10（1 个月前）；至今共发布 7 个版本，其中过去 12 个月发布了 6 个；首次发布于 2025/11/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。