atcute

atcute：把 AT Protocol 拆回它本来的样子

项目背景与痛点

AT Protocol 并不算一个新协议，但它的实现生态长期被一个“大而全”的问题困住：官方 @atproto/api 把 XRPC 客户端、Lexicon 类型、CBOR 编解码、DID 解析、OAuth 认证、仓库操作都塞进了同一棵依赖树里。对一个只想发帖的 Web 应用来说，这没什么问题；但一旦你要写一个 feed generator、一个 labeler，或者干脆自己实现一个 PDS 或索引器，这份“全家桶”就显得相当笨重——你被迫接受它的运行时假设（Node 内建模块、特定 HTTP 栈、特定加密库），还要为用不到的模块付出打包体积。

atcute 走的是完全相反的路：把协议按层切开，一层一个包。CBOR 编解码、CID、DID 解析、XRPC 传输、Lexicon 类型生成、MST 与仓库结构、JWT/DPoP 认证，各自独立、可以单独引入。它的价值不在于“又一个 SDK”，而在于把 AT Protocol 还原成一组可以自由拼装的协议原语——你不需要一个框架，只需要几块砖。

核心技术揭秘

atcute 的架构可以按“数据从应用层流向 PDS、再回流到本地视图”这条线来理解：

几个关键判断值得展开：

一切建立在 Web 平台原语之上。 atcute 大量依赖 fetch、WebCrypto、Uint8Array、TextEncoder，而不是 Node 的 http、crypto、Buffer。这意味着同一份代码可以跑在浏览器、Cloudflare Workers、Deno、Bun 里，不需要垫片层。对一个需要长连接消费 Firehose 的边缘部署场景来说，这是实打实的优势。

Lexicon 是唯一的真源。 类型定义和运行时校验都从 lexicon 文档生成，而不是手写一套类型、再写一套校验。AT Protocol 的 schema 变更频繁，手写绑定迟早会漂移；把生成器放在中心位置，才能保证“类型正确”约等于“协议正确”。同时它刻意避开了 zod 这类重型校验库，改用更轻的运行时检查，控制冷启动和包体积。

CBOR 不是配角。 AT Protocol 的 wire format 是 DAG-CBOR，CID 以 tag 42 的字节串形式内嵌其中。这带来一堆容易被忽略的边界：大整数、undefined、map key 的排序、tag 的规范化。atcute 单独把这一层拎出来，本质上是在承认：协议正确性始于字节，而不是始于 JSON。

MST 决定了数据模型的上限。 仓库是一棵 Merkle Search Tree，内容寻址、提交带签名、diff 可增量传播。任何想做索引器或自建 AppView 的项目，最终都要落在这套结构上。atcute 把 MST 和仓库操作独立成包，等于把“读懂 Bluesky 数据”这件事从 SDK 里解放了出来。

功能亮点与差异

与 @atproto/api 相比，atcute 的差异不是功能多寡，而是抽象层级的选择：官方包给你一辆车，atcute 给你发动机、变速箱和底盘。它的杀手锏集中在三点——

其一是包粒度与 tree-shaking。你只为一件事付体积代价，这对前端和 Serverless 场景是硬指标。

其二是运行时不设限。不绑定 Node，不做隐式的全局假设，这在 AT Protocol 的“边缘索引器”用法里几乎是刚需。

其三是贴近协议规范本身。DPoP、CID、MST 这些别人藏在内部的东西，它摆在明面上。写代码的人能看清协议长什么样，而不是对着 SDK 猜。

代价同样明显：它没有“开箱即用”的叙事。官方 SDK 的文档、示例、社区问答密度远高于它，遇到问题时你大概率要读源码。

应用场景与落地建议

它适合三类人：写 feed generator / labeler 的服务端开发者、自建 PDS 或索引器的协议实现者、以及需要精细控制打包体积与运行时的客户端团队。如果你只是想调几个 Bluesky API 做业务集成，官方 SDK 仍然更省事。

生产环境要留几个心眼。第一，锁版本：这类项目在 0.x 阶段的接口演进较快，包与包之间的契约也可能调整，浮动版本是自找麻烦。第二，Lexicon 同步：Bluesky 的 schema 在持续变化，生成的绑定需要跟着重新产出，最好把生成步骤纳入 CI。第三，边界用例测试：CBOR/CID 的规范化、Firehose 的背压与断线重连、DPoP 的密钥生命周期，这些是真实事故的高发区。第四，别低估运维成本：消费全量 Firehose 时的带宽、存储和重放策略，比 SDK 选择难得多。

综合评价

优点：分层干净、体积可控、运行时中立、贴近协议底层。它把 AT Protocol 从“Bluesky 的客户端库”还原成了一套可组合的协议工具，这在生态里是有稀缺性的。

缺点：文档与示例稀薄，学习曲线陡；包间版本协同需要使用者自己管；对“只想快速接 API”的团队不友好。

一句话总结：如果你把 AT Protocol 当成一个需要被正确实现和高效运行的协议，atcute 是目前 TypeScript 世界里最不像“框架”、最像“协议本体”的选择；如果你只是把它当成一个 API，那它反而会让你多走几步。