Bluesky Protocol Services

Today we’re launching Bluesky Protocol Services: a new brand, and a new website, for the public infrastructure Bluesky operates on the AT Protocol network. Bluesky has always run more than the Bluesky app. We operate Jetstream instances, relays, and the Bluesky API endpoints built on atproto. But if you were a developer trying to build on that infrastructure, our docs didn’t always make it easy to tell what we run as a service or where to start. We’re fixing that today. Bluesky Protocol Services organizes all the documentation developers need within the ecosystem, clarifies the service contracts around Bluesky-provided infrastructure, replaces the old docs.bsky.app site and gives us a clean way to ship future releases like the ones in this post!

今天，我们正式推出 Bluesky Protocol Services：这是一个全新的品牌和网站，旨在为 Bluesky 在 AT Protocol 网络上运营的公共基础设施提供支持。Bluesky 一直以来运营的不仅仅是 Bluesky 应用程序本身，我们还运行着 Jetstream 实例、中继器（relays）以及基于 atproto 构建的 Bluesky API 端点。然而，对于试图基于这些基础设施进行开发的开发者来说，我们之前的文档并不总是能清晰地说明我们提供了哪些服务，或者从哪里开始。今天，我们解决了这个问题。Bluesky Protocol Services 整理了开发者在生态系统中所需的所有文档，明确了 Bluesky 所提供基础设施的服务协议，取代了旧的 docs.bsky.app 网站，并为我们发布未来版本（如本文所述）提供了一个清晰的渠道。

Jetstream v2: Network Replay

The headline release shipping alongside the new site is Jetstream v2. Jetstream is the best way for most developers to use the network at scale: you describe the slice you want, and it arrives as plain JSON over a WebSocket. What it couldn’t give you was history. If you needed the records that already existed on the network, you had to backfill repos yourself then cut over to the live stream. Jetstream v2 adds that capability to the server. It keeps a compressed archive of the whole network and adds a new way to consume it, alongside the live tail: Network Replay lets you catch up from any point in the past and cut over to live with no gap. You POST your filters to planSnapshot, download the sealed segments it returns over plain HTTP, then connect the live WebSocket once at the tip. Replay is stateless on the server, with no per-consumer cursor, no subscription to register, and nothing to stage on the client. Jetstream is your buffer.

与新网站一同发布的重磅更新是 Jetstream v2。对于大多数需要大规模使用该网络的开发者来说，Jetstream 是最佳选择：你只需描述你想要的数据切片，它就会通过 WebSocket 以纯 JSON 格式发送给你。但它之前无法提供历史数据。如果你需要网络中已有的记录，你必须自己回填（backfill）存储库，然后再切换到实时流。Jetstream v2 在服务器端增加了这一功能。它保留了整个网络的压缩存档，并增加了一种新的消费方式，与实时流（live tail）并存：Network Replay 允许你从过去的任何时间点开始追赶数据，并无缝切换到实时流。你只需将过滤器 POST 到 planSnapshot，通过普通 HTTP 下载它返回的密封分段，然后在数据末端连接实时 WebSocket 即可。Replay 在服务器端是无状态的，没有针对每个消费者的游标，无需注册订阅，客户端也无需暂存任何内容。Jetstream 就是你的缓冲区。

You can also just snapshot the network — a point-in-time copy of the archive over HTTP only (listSegments + getSegment), with no live tail. Same archive, same filters, no WebSocket. This unlocks much more sophisticated server-side slicing without ever backfilling locally: you can spin up an App, run an analysis over a month of posts, or recover from downtime, all through the same JSON shape as the live tail. Serving these archives is bandwidth-intensive. To ensure the service remains reliable and cheap to run, we’re now requiring an API token just for these requests. The live tail remains open and unauthenticated, it’s only when you request an archive that we require a token. We have no plans to introduce an auth requirement for the live stream.

你也可以只对网络进行快照——即通过 HTTP 获取存档的时间点副本（使用 listSegments + getSegment），而不使用实时流。同样的存档，同样的过滤器，无需 WebSocket。这解锁了更复杂的服务器端切片功能，而无需在本地进行回填：你可以启动一个应用程序，对一个月的帖子进行分析，或者从停机中恢复，所有这些都通过与实时流相同的 JSON 格式完成。提供这些存档非常消耗带宽。为了确保服务保持可靠且运行成本低廉，我们现在仅针对这些请求要求提供 API 令牌。实时流保持开放且无需身份验证，只有当你请求存档时，我们才需要令牌。我们目前没有计划对实时流引入身份验证要求。

The v2 instances are live now at wss://jetstream.us-west.bsky.network and wss://jetstream.us-east.bsky.network. The existing v1 instances will keep running unchanged for a while, and the live tail behaves identically on both, so there’s no rush to move. Read the full flow in the Network Replay docs. And! As always, this infrastructure is open source and self-hostable. See Running your own Jetstream for details.

v2 实例现已上线，地址为 wss://jetstream.us-west.bsky.network 和 wss://jetstream.us-east.bsky.network。现有的 v1 实例将继续运行一段时间，且两者的实时流表现一致，因此无需急于迁移。请在 Network Replay 文档中阅读完整流程。此外，一如既往，该基础设施是开源且可自托管的。详情请参阅“运行你自己的 Jetstream”。

A Jetstream SDK

Jetstream is plain JSON, so you never need an SDK. But there’s some common glue: reconnecting, deduping, cursor management, decoding events into typed records. Hence, the new Jetstream SDKs: TypeScript and Go clients where you construct a Jetstream object, pass a filter, and for await over decoded, typed events:

Jetstream 使用的是纯 JSON，因此你并不一定需要 SDK。但通常需要一些“胶水代码”：重连、去重、游标管理、将事件解码为类型化记录等。因此，我们推出了新的 Jetstream SDK：TypeScript 和 Go 客户端。你可以构建一个 Jetstream 对象，传入过滤器，并使用 for await 遍历解码后的类型化事件：

import { Jetstream } from '@bsky/jetstream'
import { app } from '@bsky/sdk/lexicons'

const js = new Jetstream('https://jetstream.us-east.bsky.network')

for await (const evt of js.live({ collections: [app.bsky.feed.post] })) {
  if (evt.kind === 'commit' && evt.commit.operation === 'create') {
    console.log(evt.commit.collection, evt.commit.record.text)
  }
}

The TypeScript SDK is available from npm, including npmx. The Go SDK is available as part of the Jetstream project. The Jetstream SDK docs go into more detail.

TypeScript SDK 可通过 npm 获取（包括 npmx）。Go SDK 作为 Jetstream 项目的一部分提供。Jetstream SDK 文档中有更详细的说明。

The Bluesky TypeScript SDK, rebased on lex

Back in May we promoted the lex SDK to stable preview and promised that the standalone Bluesky docs would follow. That’s now done: the Bluesky TypeScript SDK is rebuilt on top of @atproto/lex, which means we’re no longer maintaining legacy code paths for Bluesky-specific helpers. This is the lexicon toolchain, fully typed end to end, from the protocol layer up through app.bsky records. Every TypeScript example on this new site is written against it, marking a huge move away from legacy technical debt—this is good code hygiene for us, and should eliminate LLM recommendations for deprecated SDKs. If you’re still using @atproto/api code, it continues to work as before, and the Bluesky API guides serve as a migration reference.

早在五月份，我们就将 lex SDK 提升为稳定预览版，并承诺随后会推出独立的 Bluesky 文档。现在这一工作已经完成：Bluesky TypeScript SDK 已基于 @atproto/lex 重构，这意味着我们不再维护针对 Bluesky 特定辅助工具的遗留代码路径。这是 lexicon 工具链，从协议层到 app.bsky 记录实现了完全的端到端类型化。新网站上的每一个 TypeScript 示例都是基于此编写的，这标志着我们摆脱了大量的遗留技术债务——这对我们来说是良好的代码规范，也应该能消除大模型（LLM）对已弃用 SDK 的推荐。如果你仍在使用 @atproto/api 代码，它将继续像以前一样工作，Bluesky API 指南可作为迁移参考。

Updates to endpoints.bsky.app

Finally, the HTTP reference has been updated. Spinning those docs out of https://docs.bsky.app was actually step 1 of this overhaul; we’re now landing the remainder. The new network.bsky.jetstream.* methods that power Replay — planBackfill, listSegments, getSegment, and getBlock — are now browsable with full request and response schemas, and the reference now documents Jetstream’s WebSocket endpoints too, so the entire Jetstream v2 surface lives in one place.

最后，HTTP 参考文档也已更新。将这些文档从 https://docs.bsky.app 中剥离出来实际上是此次全面改革的第一步；我们现在正在完成其余部分。支持 Replay 的新 network.bsky.jetstream.* 方法（包括 planBackfill、listSegments、getSegment 和 getBlock）现在可以浏览完整的请求和响应模式，参考文档现在也记录了 Jetstream 的 WebSocket 端点，因此整个 Jetstream v2 的功能接口都集中在了一个地方。

What’s next

Everything above is live today: the new site, the v2 Jetstream instances, the SDK preview, and the updated HTTP reference. If you’re new to the network, start with How It Works, a visual walkthrough of how records, lexicons, and the firehose fit together. If you’re building against the Bluesky app’s data model, the Bluesky API guides are all still there, freshly rewritten (more on that below). If you build something on Replay in the next few weeks, we’d love to hear about it; the fastest way to shape where the SDK’s orchestration goes is to show us what you’re folding the stream into.

以上所有内容今天均已上线：新网站、v2 Jetstream 实例、SDK 预览版以及更新后的 HTTP 参考文档。如果你是网络新手，请从“How It Works”开始，它通过可视化方式介绍了记录、词汇表（lexicons）和 firehose 是如何协同工作的。如果你是基于 Bluesky 应用程序的数据模型进行开发，Bluesky API 指南依然存在，并且已经过重新编写（详见下文）。如果你在接下来的几周内基于 Replay 构建了什么，我们非常乐意听听你的反馈；塑造 SDK 编排方向的最快方式，就是向我们展示你如何利用这些数据流。