How bluesky-social/social-app Works

用户创作并发布一条带图片的多媒体帖子

该流程覆盖了用户从唤起编辑器到成功发布一条图文帖子的完整体验。用户首先通过悬浮按钮或输入框打开编辑器，可以输入文本并从相册选择最多四张图片。在发布前，用户可以选择将当前内容保存为草稿，以便后续编辑。点击发布后，应用会先将图片上传至服务器，在此期间UI会显示上传进度。上传完成后，帖子内容才会被正式发布。为了确保用户能立即看到自己发布的内容且内容已在网络中同步，发布成功后应用会主动轮询应用视图服务（AppView）进行确认，只有在确认帖子可见后，才真正完成整个发布流程，给予用户最终的成功反馈。这一系列设计旨在提供一个既流畅又可靠的创作体验。

1. 用户在Feed流页面点击悬浮按钮，打开帖子编辑器
2. 用户输入文本，并从本地相册选择图片（最多4张）
3. （可选）用户点击“保存草稿”，系统将当前内容序列化并持久化存储
4. 用户点击“发布”，系统开始异步上传图片
5. 图片上传完成后，系统提交帖子内容，并轮询AppView确认帖子已上链可见
6. 确认成功后，编辑器关闭，用户返回Feed流并可能看到自己的新帖子

用户点赞帖子并获得即时反馈

此流程展示了应用如何通过“乐观更新”提供极致流畅的互动体验。当用户在信息流中浏览并对某个帖子进行点赞时，UI几乎在瞬间（无网络延迟）就更新为“已点赞”状态，点赞数也相应增加。这背后是应用的“影子状态”机制在起作用：它在内存中立即创建了一个临时的“已点赞”状态并驱动UI更新，同时才在后台向服务器发起真正的点赞请求。当服务器确认请求成功后，这个临时状态会无缝地被服务器返回的真实状态替换。这种“先响应，后同步”的设计，让用户感觉操作立即生效，极大地提升了应用的响应速度和使用满意度。

1. 用户在Feed流中看到一个帖子，并点击“点赞”按钮
2. 系统立即在内存中创建“影子状态”，UI即时更新为“已点赞”样式，点赞数加一
3. 系统在后台将点赞操作加入防抖队列，并异步向服务器发送API请求
4. 服务器确认点赞成功，返回结果
5. 系统用服务器返回的真实数据更新“影子状态”，完成数据同步

用户在多个账户间安全切换

该流程体现了应用在多账户管理方面的安全设计。用户可以预先登录多个账户，并在它们之间一键切换。当用户发起切换请求时，系统并不会复用旧的会话。相反，它会为目标账户创建一个全新的、完全隔离的AT协议代理（Agent）实例。在新的代理准备就绪并接管应用后，系统会立即销毁前一个账户的代理实例，使其持有的认证令牌失效。这个“用后即焚”的策略，从根本上杜绝了已不在前台的账户在后台发生意外操作（如刷新令牌）的可能性，为用户的多账户使用提供了强大的安全保障。

1. 用户在设置或侧边栏中打开账户列表，选择一个非当前账户
2. 系统根据所选账户的持久化信息，创建一个全新的、独立的会话代理（Agent）
3. 新代理完成初始化后，应用的全局状态（如当前用户、数据查询）切换至新账户
4. 系统立即销毁（dispose）上一个账户的代理实例，使其认证令牌失效
5. 用户看到应用的界面已完全变为新账户的视图

从外部链接或推送通知进入应用指定页面

此流程展示了应用强大的跨应用导航能力。当用户在浏览器、其他应用中点击一个Bluesky的链接，或点击一条推送通知时，应用能够被唤醒并直接导航到目标内容。应用启动时，一个统一的路由系统会解析传入的链接或通知负载，将其转换为一个内部导航状态。例如，一个指向个人主页的链接，在移动端上会被解析为“切换到主页Tab，并推入个人主页页面”。这种设计确保了无论从何处进入，用户都能获得连贯、符合预期的导航体验，并能通过后退操作返回到有意义的上层页面，而非直接退出应用。

1. 用户在外部（如浏览器、聊天应用）点击一个bsky.app链接，或点击系统推送通知
2. 操作系统唤醒Bluesky应用，并将链接或通知负载传递给应用
3. 应用的路由系统解析传入信息，匹配到目标屏幕和参数（如'Profile'屏幕，handle='user.bsky.social'）
4. 系统根据平台（Web/移动端）和目标屏幕，构建一个完整的导航状态栈
5. 应用执行导航操作，用户被直接带到目标内容页面

核心社交体验：动态、帖子与个人主页

该模块构成了产品的核心用户价值，提供了完整的“消费-创作-互动”闭环。在设计上，它通过统一的Feed流组件来承载不同来源的内容（关注、算法推荐、列表），并利用草稿箱和媒体上传队列等功能，打造了媲美中心化应用的流畅创作体验。其核心设计策略是“体验优先”，通过在服务端确认前轮询应用视图（AppView）来确保数据一致性，从而在去中心化架构下实现了可靠的即时发布体验。

• 多源动态信息流浏览 — 【设计策略】采用统一的“Feed流页面”组件来聚合和展示来自不同来源的内容，并通过客户端轮询机制，在不依赖推送的情况下保证内容的新鲜度。 【业务逻辑】 - Step 1: 用户进入一个Feed流页面（如“关注”动态或自定义的“算法推荐”流）。 - Step 2: 系统使用对应的Feed标识符（如'following', 'author|did|posts_and_author_threads', 'feedgen|uri'）从数据层请求数据，并支持无限滚动加载。 - Step 3: 客户端启动一个定时轮询器，以固定的频率（当前为60秒）检查并拉取最新内容，并在UI上提示用户有新帖子可供查看。 - Step 4: 用户可随时通过下拉刷新手动触发内容加载。 - Step 5: Feed流中可混合渲染不同类型的单元，如帖子、推广横幅或趋势性内容，以实现灵活的运营和内容分发。
• 帖子发布与草稿管理 — 【用户价值】为用户提供一个稳定可靠的创作环境，即使在网络不稳定或需要处理多媒体内容时，也能保证创作内容不丢失，并能顺利发布。 【设计策略】采用“本地先行、异步确认”的设计策略。将帖子内容、媒体资源和发布状态在本地进行完整管理，并通过一个独立的“草稿”系统来持久化用户创作，将内容上传与帖子发布流程解耦。 【业务逻辑】 - Step 1: 用户在编辑器中创作内容，可以附加最多4张图片。 - Step 2: 用户可选择“保存草稿”。系统会将当前编辑器的所有状态（文本、图片本地引用、回复对象等）序列化为一个草稿对象，并进行本地持久化存储。 - Step 3: 用户点击“发布”。系统首先处理图片等媒体资源的上传。用户可以选择“等待上传完成后发布”，此时UI会显示排队状态。 - Step 4: 媒体上传完毕后，系统调用AT协议接口发布帖子。 - Step 5: 为确保去中心化网络中的数据最终一致性，发布成功后，系统会启动一个名为 `whenAppViewReady` 的轮询检查机制：在最多5次尝试（每次间隔1秒）内，反复查询AppView（应用视图服务），直到确认新发布的帖子已经可见，才在UI上展示“发布成功”并进行页面跳转。这个设计确保了用户看到的就是已在网络中确认的结果。 - Step 6: 如果发布失败，草稿会保留，用户可以重新编辑或尝试发布。
• 帖子详情与线索式回复 — 【设计策略】为帖子回复提供上下文完整的阅读和创作体验。在帖子详情页中，将回复编辑器作为线索的一部分内联展示，并通过乐观更新机制即时显示用户的回复。 【业务逻辑】 - Step 1: 用户点击帖子进入详情页，系统加载并渲染出该帖子的祖先节点和所有子回复，形成一个树状或线索状视图。 - Step 2: 对于被删除或被屏蔽的内容，系统会用“墓碑”组件（Tombstone）进行占位，以维持线索的完整性。 - Step 3: 在线索中的每个帖子下方，都可以直接拉起一个预设了回复对象的编辑器。 - Step 4: 用户提交回复后，该回复会立即在UI上“乐观地”显示出来，同时在后台进行发布。发布流程与主帖子发布相同，同样包含最终的应用视图一致性校验。
• 个人主页与内容聚合 — 【设计策略】将个人主页设计为一个多维度的内容聚合中心。通过分頁（Tab）形式，复用标准的Feed流组件来展示特定用户的不同内容切片（如帖子、回复、媒体、点赞过的內容）。 【业务逻辑】 - Step 1: 用户进入某用户的个人主页，系统首先展示该用户的个人资料、头像、横幅等信息。 - Step 2: 主页内包含多个标签页，如“帖子与回复”、“媒体”、“点赞”和“Feed流列表”。 - Step 3: 当用户切换标签页时，系统会使用一个特定格式的Feed标识符（例如，`author|{did}|posts_and_author_threads` 用于获取该用户的帖子和回复）来请求并渲染对应的内容流。

实时直接消息（DM）

该模块为用户提供了一对一和群组的私信聊天功能。其技术选型极具特点，放弃了传统的WebSocket方案，转而采用一种基于HTTP轮询的“事件总线”架构。这一设计旨在平衡移动端的电池消耗和消息的实时性，通过动态调整轮询频率（应用活跃时4秒，后台时5分钟），在大多数场景下提供了“准实时”的体验。系统通过乐观更新和待发送消息队列，保证了用户在网络不稳定时也能流畅地发送和查看消息。

• 自适应轮询的事件总线 — 【用户价值】在保证消息近乎实时更新的同时，最大限度地减少移动设备的电量消耗。 【设计策略】采用基于HTTP长轮询的事件总线，并根据应用的生命周期动态调整轮询频率。 【业务逻辑】 - Step 1: 系统为每个账户维护一个全局的“消息事件总线”实例。 - Step 2: 当应用处于前台活跃状态时，事件总线以较短的间隔（如4秒）向服务器请求最新的消息日志。 - Step 3: 当应用切换到后台时，为节省电量，轮询间隔会自动延长至一个较长的时间（如5分钟）。 - Step 4: 当应用从后台恢复时，立即触发一次消息同步。如果非活跃时间超过阈值（如5分钟），则会触发一次完整的会话重置和数据拉取，以确保状态一致性。 - Step 5: 事件总线接收到所有会话的日志后，根据会话ID将事件分发给对应的聊天窗口进行处理。
• 消息发送与待处理队列 — 【用户价值】即使用户处于弱网或离线状态，也能“发送”消息，并确保在网络恢复后消息能够被可靠地送达。 【设计策略】采用“乐观发送”与“待发送队列”相结合的机制。 【业务逻辑】 - Step 1: 用户在输入框中发送消息。消息会立即在UI上显示为“发送中”状态，并被添加到一个内存中的“待发送消息”队列中。每条消息都被分配一个唯一的本地ID。 - Step 2: 系统在后台按顺序处理该队列，依次调用API发送消息。 - Step 3: 如果消息发送成功，它会从队列中移除。后续事件总线拉取到该消息的确认事件后，会用服务器版本替换本地的“发送中”版本。 - Step 4: 如果因网络问题（如断网、服务器超时）发送失败，该消息会保留在队列中，并被标记为“可恢复”。 - Step 5: 当网络连接恢复时（通过事件总线的连接成功事件触发），系统会自动将队列中所有“可恢复”的消息进行批量发送，以提高效率和成功率。
• 会话列表与消息状态管理 — 【设计策略】通过事件总线和乐观更新，实时维护会话列表的顺序和未读状态。 【业务逻辑】 - Step 1: 当用户打开会话列表时，系统拉取所有会话的元数据（最新消息、未读数等）。 - Step 2: 事件总线持续接收新消息事件。如果新消息来自非当前聊天窗口，则对应会话的未读数会增加，并更新其最新消息摘要。会话列表会重新排序，将有新消息的会话置顶。 - Step 3: 当用户进入一个会话时，系统会立即发起一个“标记已读”的请求（同样采用乐观更新），并清除该会话的未读状态。 - Step 4: 为了多端同步，当一个会话被标记为已读时，系统会通过浏览器提供的 BroadcastChannel API通知其他打开的标签页，同步清除未读红点。

内容审核与安全偏好

该模块为用户提供了强大的内容安全自定义能力，是去中心化社交网络中的关键一环。用户不仅可以对内容进行举报，还能精细化地配置内容标签的展示策略（隐藏、警告、显示），并选择信任的第三方“标签服务提供者”（Labeler）。此外，产品还提供了“线程门控”（Threadgate）功能，允许创作者控制谁可以回复自己的帖子，从而有效管理互动环境。

• 内容标签与过滤配置 — 【用户价值】让用户可以根据个人偏好，自主决定看到哪些类型的内容，以及这些内容的展示方式，从而创建个性化的安全浏览环境。 【设计策略】将内容审核的权力下放给用户和其信任的第三方。系统提供一个统一的“审核选项（ModerationOpts）”上下文，供所有内容展示组件消费。 【业务逻辑】 - Step 1: 用户可以在设置中，选择一个或多个“标签服务提供者”（即独立的审核服务）。如果用户未选择，则默认使用Bluesky官方的标签服务。 - Step 2: 用户可以针对每一种内容标签（如“色情”、“暴力”、“垃圾信息”等）设置独立的展示策略：显示、警告（显示覆盖层，需点击确认）、隐藏（内容不展示）。 - Step 3: 当应用渲染内容（帖子、个人主页等）时，会从“审核选项”上下文中获取用户的配置。 - Step 4: 系统会检查内容所附带的所有标签，并根据用户的策略决定其最终的渲染方式。例如，一个被用户设置为“隐藏”的标签，将导致对应帖子被折叠。
• 帖子回复权限控制（Threadgate） — 【用户价值】赋予内容创作者管理其帖子互动范围的能力，有效减少骚扰和不相关的回复。 【设计策略】通过在AT协议层面为每个帖子附加一个“门控”记录来实现权限控制。 【业务逻辑】 - Step 1: 用户在发布帖子时或发布后，可以设置该帖子的回复权限。 - Step 2: 可选的权限规则包括：“任何人”、“仅被提及的用户”、“仅关注的用户”或“指定列表中的成员”。 - Step 3: 用户的选择会被转换成一条AT协议记录，并与原帖关联。例如，“没有人”对应一个空的`allow`数组，“仅关注的人”对应一个`following`规则。 - Step 4: 当其他用户尝试回复该帖子时，客户端或服务器会检查帖子的“门控”记录，判断该用户是否满足回复条件。
• 内容举报 — 【设计策略】提供一个清晰的举报流程，允许用户将内容问题报告给其选择的审核服务，并兼容不同版本的举报原因类型，以适应生态发展。 【业务逻辑】 - Step 1: 用户对帖子、个人主页或私信发起举报。 - Step 2: 举报对话框弹出，要求用户必须选择一个“举报原因”和一个“审核服务”（默认为用户已配置的）。 - Step 3: 系统会检查所选审核服务支持的“举报原因”类型。为了向后兼容，如果一个服务不支持新的、更具体的举报原因，系统会自动降级使用其支持的旧版原因类型。 - Step 4: 提交后，一个结构化的举报请求会被发送到所选的审核服务。

乐观数据与缓存层

这是提升应用响应速度和流畅度的核心技术模块。它基于React Query构建，但其精髓在于一套创新的“影子状态（Shadow State）”机制。当用户进行点赞、关注等操作时，应用不会等待服务器返回，而是立即在内存中创建一个临时的“影子”数据来更新UI，从而实现零延迟的交互反馈。所有的数据获取、缓存策略和乐观更新逻辑都集中在该模块，为上层业务提供了强大而易用的数据支持。

• 影子状态（Shadow State）乐观更新机制 — 【用户价值】用户在进行点赞、转发、关注等高频操作时，能够获得即时的、无延迟的UI反馈，感觉应用“快如闪电”。 【设计策略】通过在内存中为缓存数据附加一个临时的、非持久化的“影子状态”来实现。这个影子状态会与原始数据合并，驱动UI先行更新，并在后台与服务器同步。 【业务逻辑】 - Step 1: 当用户执行一个操作（如点赞一个帖子）。 - Step 2: 系统立即调用 `updatePostShadow` 函数。该函数使用一个 `WeakMap` 数据结构，以原始的帖子对象为键，创建一个“影子”对象。这个影子对象记录了操作的待定状态，例如 ` {likeUri: 'pending'} `。 - Step 3: 所有展示该帖子的UI组件，都会通过 `usePostShadow` 钩子获取一个合并后的视图。这个钩子会计算出新的状态（如 `likeCount` 加一），并立即触发UI重绘。 - Step 4: 一个全局的事件发射器（EventEmitter）会广播此帖子的更新事件，确保屏幕上所有显示此帖子的组件都能同步更新。 - Step 5: 在后台，系统发起真正的点赞API请求。 - Step 6: 请求成功后，返回的真实点赞记录URI会再次通过 `updatePostShadow` 更新到影子状态中，使其从“待定”变为“已确认”。如果请求失败，则影子状态被清除，UI回滚到原始状态。 【权衡】此机制极大提升了用户体验，但代价是增加了前端的复杂性。由于影子状态仅存于内存，若用户在服务器确认前关闭应用，该次操作的乐观状态会丢失。
• 数据查询与缓存策略 — 【设计策略】基于React Query（TanStack Query），为不同类型的数据设计了标准化的缓存键（RQKEY）和不同的缓存策略（StaleTime）。 【业务逻辑】 - **Feed流数据**: 采用无限滚动查询，并设置 `staleTime` 为无限大，意味着除非手动刷新，否则应用会一直使用缓存中的Feed流数据，只在滚动到底部时请求下一页。这优化了性能并减少了不必要的API请求。 - **个人主页数据**: `staleTime`被设置为一个较短的时间（如15秒）。这是一个经过权衡的“关键”值，用于防止在某些UI交互下出现无限重渲染循环，同时保证了数据的相对新鲜。 - **用户偏好设置**: 这类数据被标记为“持久化”，其 `gcTime` (垃圾回收时间) 设为无限大。通过 `PersistQueryClientProvider`，这些查询结果会被自动写入本地存储（如AsyncStorage），实现跨应用启动的持久化。 - **通知**: 通知列表采用无限滚动查询，而未读数则通过一个独立的API进行轮询（每30秒一次），以在不频繁刷新整个列表的情况下更新角标。
• 防抖突变队列 — 【用户价值】防止用户因快速、重复点击（如反复点赞和取消点赞）而向服务器发送大量冗余请求，节省流量并降低服务器压力。 【设计策略】为点赞、关注等“开关”类型的操作实现了一个 `useToggleMutationQueue` 钩子，它能在短时间内将多次连续操作合并为最终的一次请求。 【业务逻辑】 - Step 1: 用户在1秒内快速点击了三次点赞按钮（赞 -> 取消 -> 赞）。 - Step 2: 每次点击都会触发一次突变（Mutation）请求。 - Step 3: `useToggleMutationQueue` 会将这些请求暂存，只在短时间（如500毫秒）内没有新操作时，才将最后一次操作的状态（最终是“点赞”）发送到服务器。 - Step 4: 前面的两次操作（赞、取消）对应的API请求被自动取消，从而避免了不必要的网络开销。

应用外壳与导航

此模块负责应用的启动、初始化和整体导航框架。它实现了平台自适应的导航结构：在移动端使用经典的底部标签页导航，在Web端则采用更适合大屏的扁平化堆栈式导航。该模块精心编排了应用启动时的各种初始化任务（如会话恢复、配置预加载），并通过一个统一的路由系统处理深层链接和推送通知跳转，确保用户可以从任何入口点无缝进入应用内的指定页面。

• 确定性启动与会话恢复 — 【设计策略】采用一个确定性的、分阶段的启动流程，确保在渲染主UI之前，所有核心服务（如会话、持久化状态）都已准备就绪，以避免竞争条件和UI闪烁。 【业务逻辑】 - Step 1: 应用启动时，立即并行执行一系列轻量级、无依赖的预取任务（如地理位置、应用配置、年龄验证配置等）。 - Step 2: 同时，主应用等待几个关键的持久化任务完成，包括 `initPersistedState`（加载本地持久化数据）和 `setupDeviceId`（设置设备ID）。在此期间，UI不渲染任何内容（或显示启动屏）。 - Step 3: 关键任务完成后，应用读取上一次的活跃账户信息。 - Step 4: 如果存在活跃账户，则同步调用 `resumeSession` 尝试恢复会话。这是一个阻塞操作，以确保后续渲染的UI能获取到正确的登录状态。如果恢复失败，错误会被记录，但应用会继续启动，以免无限期卡住。 - Step 5: 会话状态确定后，应用标记为 `isReady`，主UI（Shell）才开始渲染。
• 平台自适应导航 — 【设计策略】基于React Navigation，但根据运行平台（Web或移动端）提供不同的导航器（Navigator）结构，以符合各平台的用户习惯。 【业务逻辑】 - **移动端**: 使用底部标签页导航器（`TabsNavigator`），包含五个主要入口：主页、搜索、消息、通知和我的。每个标签页内部都是一个独立的堆栈导航器，允许用户在各个功能区内进行深度导航。点击已激活的标签页会触发“返回顶部”的行为。 - **Web端**: 使用一个扁平化的堆栈导航器（`FlatNavigator`），所有页面都在同一个堆栈中。侧边栏抽屉在小屏幕上作为覆盖层出现，在大屏幕上则固定显示，提供桌面端的浏览体验。 - **权限控制**: 屏幕可以声明 `requireAuth=true`。一个自定义的导航器包装器 `createNativeStackNavigatorWithAuth` 会在渲染前检查用户会话状态，如果用户未登录，则直接渲染空白或重定向到登录页。
• 统一路由与深层链接 — 【设计策略】通过一个自定义的 `Router` 类来集中管理所有的URL路径模式和解析逻辑，实现从URL到应用内部导航状态的精确转换。 【业务逻辑】 - Step 1: 系统预定义了所有支持的URL格式，如 `/profile/:handle`、`/profile/:did/post/:rkey`。 - Step 2: 当应用通过外部URL（深层链接）启动时，`Router` 会将URL路径与预定义的模式进行匹配，解析出目标屏幕名称和参数。 - Step 3: 链接处理器（`LINKING.getStateFromPath`）根据解析结果和当前平台，构建出一个合法的React Navigation状态对象。例如，在移动端打开一个个人主页链接，它会构建一个导航到“主页”标签页，并在其内部堆栈中推入“个人主页”屏幕的状态。 - Step 4: 对于推送通知的点击，系统会读取通知负载，将其转换为一个内部URL，然后复用上述的深层链接逻辑，实现到目标页面的跳转。

用户认证与多账户管理

该模块负责用户的登录、注册、会话保持和多账户切换功能。其核心设计是“一个账户，一个代理（Agent）”的模式：每次切换账户都会创建一个全新的、隔离的AT协议代理实例，并销毁旧实例，从而在根本上避免了会话数据和凭证的交叉污染。系统通过一个与UI解耦的外部存储（External Store）来管理和持久化会话状态，确保了多标签页（Web）或跨应用重启时账户状态的一致性。

• 多账户切换与会话隔离 — 【用户价值】让用户可以在多个身份之间安全、快速地切换，而不用担心账户间的状态混淆或安全风险。 【设计策略】采用“即时创建，用后即焚”的代理（Agent）生命周期管理策略。 【业务逻辑】 - Step 1: 用户在已登录多个账户的情况下，选择切换到另一个账户。 - Step 2: 系统不会复用任何已有的会话对象。它会根据所选账户的持久化信息，调用 `resumeSession` 创建一个全新的 `BskyAppAgent` 实例。 - Step 3: 在新Agent准备就绪后，应用状态切换到新账户。 - Step 4: **关键步骤**: 系统会立即调用前一个账户Agent的 `dispose()` 方法。此操作会销毁该Agent，使其持有的刷新令牌（Refresh Token）失效，从而防止这个已被切换掉的后台会话意外地进行网络请求或刷新令牌，杜绝了潜在的令牌滥用风险。
• 会话持久化与跨标签页同步 — 【设计策略】使用React的 `useSyncExternalStore` 钩子，配合一个自定义的外部存储对象（SessionStore），来实现会话状态的持久化和跨实例同步。 【业务逻辑】 - Step 1: 用户的账户列表（包含会话凭证）和当前活跃账户的ID被持久化到本地存储中。 - Step 2: 应用启动时，从本地存储加载这些信息来初始化 `SessionStore`。 - Step 3: 当用户进行登录、登出或切换账户操作时，`SessionStore` 的状态会更新，并触发持久化写入操作。 - Step 4: 在Web端，如果用户在另一个浏览器标签页中切换了账户，持久化存储的变化会通过 `persisted.onUpdate` 事件被当前标签页监听到。 - Step 5: 当前标签页监听到变化后，会自动调用会话恢复逻辑，无缝切换到新的账户，从而实现所有标签页的登录状态同步。
• 登出与数据清理 — 【用户价值】确保用户登出时，其个人敏感数据被彻底清除，避免在共享设备上发生数据泄露。 【设计策略】提供区分范围的登出操作，并在登出时精确清理与该账户关联的缓存数据。 【业务逻辑】 - **登出当前账户**: 系统会清除当前账户的年龄验证状态、以及所有与该账户DID关联的持久化查询缓存（如偏好设置）。 - **登出所有账户**: 系统会清除全局的年龄验证状态，并遍历所有已登录过的账户，逐一清除每个账户的持久化查询缓存。 - 两种登出操作都会重置应用的新手引导流程。

跨平台设计系统（ALF）

该模块提供了一套名为 ALF (Abstract Language for Features) 的跨平台设计系统，统一了应用的视觉风格和交互模式。它将设计决策（如颜色、间距、字体）抽象为“设计令牌”（Design Tokens），并提供了响应式的布局工具和一系列可复用的UI组件（如对话框、选择器、图标）。其核心价值在于，通过一套代码库，同时支持Web、iOS和Android，并能根据平台特性提供最优实现（例如，Web端的选择器使用Radix UI以获得更好的可访问性）。

• 设计令牌与主题化 — 【设计策略】将所有基础样式（颜色、渐变、间距、字体大小）定义为中心化的“设计令牌”，组件直接引用令牌名称而非硬编码值。通过 `ThemeProvider` 实现主题切换。 【业务逻辑】 - Step 1: 一个外部NPM包 `@bsky.app/alf` 提供了基础的设计令牌，如 `tokens.color.primary` 或 `tokens.space.lg`。 - Step 2: 应用在此基础上可以扩展或覆盖令牌，例如定义具名的渐变色 `gradients.primary`，其包含具体的颜色断点和悬停颜色。 - Step 3: 所有UI组件都通过 `useTheme()` 或 `useAlf()` 钩子来消费这些令牌。 - Step 4: 应用根节点由 `ThemeProvider` 包裹，当主题（如浅色/深色）或字体缩放比例变化时，所有消费了令牌的组件都会自动更新，实现全局样式的动态切换。
• 响应式布局与间距 — 【设计策略】提供语义化的间距工具（Gutter），将具体的间距数值与屏幕断点（Breakpoint）关联，使组件布局能自适应不同尺寸的屏幕。 【业务逻辑】 - Step 1: 系统定义了几个语义化的间距尺寸，如 `compact`, `base`, `wide`。 - Step 2: 通过 `useGutters` 钩子，每个语义化尺寸被映射到不同屏幕断点下的具体令牌值。例如，`base` 间距在手机上可能是 `tokens.space.lg` (16px)，在平板或桌面端则会自动变为 `tokens.space.xl` (20px)。 - Step 3: 组件在布局时调用 `useGutters('base')`，即可获得当前屏幕尺寸下正确的间距值，无需编写任何媒体查询代码。
• 平台差异化组件实现 — 【用户价值】在保持API一致性的前提下，为不同平台提供最佳的用户体验和可访问性。 【设计策略】利用React Native的平台特定文件扩展名（如 `index.web.tsx`, `index.native.tsx`）来提供同一组件的不同实现。 【业务逻辑】 - **选择器（Select）组件**: 对开发者而言，他们使用的都是统一的 `<Select.Root>`, `<Select.Trigger>`, `<Select.Item>` API。 - **Web端实现**: 在 `Select/index.web.tsx` 文件中，组件内部是基于业界知名的无障碍UI库 `Radix UI` 来构建的。这确保了Web端拥有完整的键盘导航、屏幕阅读器支持等高级可访问性特性。 - **移动端实现**: 在 `Select/index.tsx`（默认或 `*.native.tsx`）文件中，组件则是基于原生的对话框（Dialog）和滚动列表实现的，提供了更符合移动端习惯的触摸交互和模态弹出效果。

Web生态微服务

为了支持主应用在Web生态中的传播和集成，Bluesky架构包含了一组独立部署的微服务。这些服务使用Go和TypeScript编写，分别承担了不同的职责：`bskyweb` 负责提供SEO友好的Web应用服务；`embedr` 提供标准的OEmbed嵌入卡片；`bskylink` 是一个带安全过滤的短链接服务；`bskyogcard` 则为社交分享动态生成预览图（OG Card）。这种微服务化的架构，将Web相关的功能与核心的AT协议后端解耦，提供了更好的扩展性和独立演进的能力。

• Web应用服务与服务端渲染 (SSR) — 【设计策略】使用一个高性能的Go服务（bskyweb）来托管React Native for Web构建的单页应用（SPA），并对关键页面（如个人主页、帖子详情）进行服务端渲染，以优化SEO和首屏加载速度。 【业务逻辑】 - Step 1: 当用户或搜索引擎爬虫请求一个页面（如 `bsky.app/profile/user.bsky.social`）。 - Step 2: Go服务接收请求，并通过XRPC客户端调用后端的AppView API，获取该用户主页所需的数据。 - Step 3: 使用 `pongo2` 模板引擎，将获取到的数据渲染到一个HTML模板中，生成包含核心内容的HTML页面。 - Step 4: 将此HTML返回给客户端。浏览器接收后能立即展示内容，而无需等待JavaScript加载执行。之后，React应用会接管页面，完成“注水”（Hydration），使其成为一个功能完整的单页应用。
• 内容嵌入服务 (OEmbed) — 【用户价值】让其他网站（如博客、新闻文章）可以方便地将Bluesky的帖子嵌入到它们的内容中。 【设计策略】提供一个遵循OEmbed行业标准的独立Go服务（embedr）。 【业务逻辑】 - Step 1: 第三方网站需要嵌入一个帖子时，会请求一个OEmbed URL，如 `embed.bsky.app/oembed?url={post_url}`。 - Step 2: `embedr` 服务解析出原始帖子URL，调用AppView API获取帖子内容。 - Step 3: 它会将帖子内容渲染成一段标准的HTML代码，并将其与其他元数据（如作者、宽度、高度）一起，以JSON格式返回。 - Step 4: 第三方网站收到JSON后，只需将其中的HTML片段插入自己的页面即可完成嵌入。
• 安全短链接服务 — 【用户价值】提供易于分享的短链接，并通过内置的安全检查，保护用户免受恶意网站的侵害。 【设计策略】构建一个独立的TypeScript/Express服务（bskylink），使用PostgreSQL存储链接映射，并集成安全域名检查。 【业务逻辑】 - Step 1: 应用内部生成一个分享链接时，调用 `bskylink` 服务的API，传入原始长链接。 - Step 2: 服务首先通过 `safelinkClient` 检查原始链接的域名是否在白名单或黑名单中，进行初步的安全过滤。 - Step 3: 生成一个6位长的短代码，并将短代码与原始链接的映射关系存入数据库。 - Step 4: 当用户访问该短链接时，服务从数据库查出原始链接。 - Step 5: 如果原始链接曾被标记为不安全，则会向用户展示一个警告页面，而非直接跳转。如果安全，则返回302重定向到原始链接。
• 动态社交分享卡片 (OG Card) — 【用户价值】当用户在其他社交平台（如X、Facebook）分享Bluesky的内容（如“新手包”）时，能自动生成一张信息丰富的预览图，提升分享的吸引力和点击率。 【设计策略】使用一个独立的TypeScript/Express服务（bskyogcard），利用Satori库将React组件在服务端直接渲染成图片。 【业务逻辑】 - Step 1: 当社交平台的爬虫抓取一个分享链接时（如 `ogcard.bsky.app/start/...`）。 - Step 2: `bskyogcard` 服务解析链接，获取对应“新手包”的数据（如名称、创建者、推荐的账户列表等）。 - Step 3: 服务使用这些数据，渲染一个预先设计好的React组件。 - Step 4: Satori库将这个React组件的虚拟DOM结构转换为SVG图像。 - Step 5: Resvg库再将SVG图像快速转换为PNG格式。 - Step 6: 最终，服务将生成的PNG图片作为HTTP响应返回给爬虫。

通过“影子状态”实现的乐观UI更新

Problem: 在社交应用中，如何让用户在执行点赞、关注等高频操作时，即使在网络不佳的情况下也能获得即时的UI反馈，避免看到加载指示器或感到卡顿？

Solution: 该项目实现了一套巧妙的“影子状态”机制，将UI更新与网络请求解耦。 Step 1: 当用户执行操作时，系统并不会等待服务器，而是立即使用 `WeakMap` 在内存中为被操作的数据对象（如帖子）附加一个临时的“影子”对象，记录下待处理的状态（如`{like: 'pending'}`）。 Step 2: 所有UI组件都通过一个统一的钩子（如`usePostShadow`）来消费数据。该钩子会返回一个由原始数据和影子数据合并后的视图，从而驱动UI即时更新（如点赞数加一）。 Step 3: 一个全局事件发射器会通知所有正在展示该数据的地方进行刷新，保证了UI的一致性。 Step 4: 在后台，一个异步的网络请求被发送到服务器。请求成功后，服务器返回的真实数据会更新到影子状态中；如果失败，影子状态则被丢弃，UI自动回滚。 核心价值：这一设计在不修改原始缓存数据、不引入持久化复杂性的前提下，以纯内存方式实现了极致流畅的“乐观UI”，极大提升了用户体验。

Technologies: React Query, WeakMap, EventEmitter

Boundaries & Risks: 该机制的边界在于，“影子状态”是临时的且仅存于内存，不会跨应用重启而持久化。如果用户在服务器确认操作前就关闭了应用，那么这次乐观的UI更新将会丢失。此外，它要求所有相关组件都必须使用特定的钩子来获取数据，否则可能导致UI状态不一致。

基于HTTP轮询的“准实时”消息架构

Problem: 如何在移动端实现私信（DM）的实时性，同时又避免WebSocket长连接带来的巨大电量消耗和服务器维护复杂性？

Solution: 项目选择了一种务实且高效的折衷方案：一个基于HTTP轮询的自适应事件总线。 Step 1: 系统为每个账户维护一个单例的“消息事件总线”，负责从服务器拉取所有对话的消息更新日志。 Step 2: 它不使用WebSocket，而是采用轮询方式。关键在于，轮询频率是动态自适应的：当应用处于前台活跃状态时，它以一个较短的间隔（如4秒）轮询，以保证对话的实时感；当应用被切换到后台时，它会自动将轮询间隔延长到一个很长的时间（如5分钟），以最大程度节省电量。 Step 3: 拉取到的日志包含了所有对话的更新，事件总线会根据对话ID将这些事件分发给各自的聊天窗口进行处理。 核心价值：这种设计在用户体验和系统资源消耗之间取得了精妙的平衡，用一种更简单、更稳健的技术栈，实现了接近WebSocket的“准实时”效果，尤其适合移动端场景。

Technologies: HTTP Polling, React Native AppState, EventEmitter

Boundaries & Risks: 该方案的主要权衡是牺牲了毫秒级的绝对实时性。在最佳情况下，消息的接收也存在最多几秒的延迟。此外，在网络极不稳定的情况下，轮询可能会频繁失败，导致消息同步中断，直到下一次轮询成功。

微服务化的Web生态系统

Problem: 一个以移动端为核心的应用，如何有效地融入广阔的Web生态，支持如搜索引擎优化（SEO）、第三方网站内容嵌入（Embed）和社交媒体分享预览（OG Card）等功能？

Solution: 项目将Web相关的功能剥离出来，形成了一个由多个独立微服务组成的支撑矩阵。 Step 1: **Web应用服务 (bskyweb)**：一个Go服务，负责托管Web版应用，并对帖子、个人主页等关键页面进行服务端渲染（SSR），输出对搜索引擎友好的HTML，解决了单页应用（SPA）的SEO难题。 Step 2: **嵌入服务 (embedr)**：一个独立的Go服务，实现了OEmbed行业标准。它能将任何Bluesky帖子渲染成一段HTML代码，供其他网站方便地嵌入。 Step 3: **短链接服务 (bskylink)**：一个TypeScript服务，提供短链接生成和解析功能，并内置了恶意网址过滤，保障了分享链接的安全性。 Step 4: **社交卡片服务 (bskyogcard)**：一个创新的TypeScript服务，当内容被分享到其他社交平台时，它能动态地将一个React组件渲染成一张精美的PNG预览图。 核心价值：这种微服务架构将核心应用与Web生态功能解耦，使得每个部分都可以独立开发、部署和扩展，架构清晰且灵活。

Technologies: Go, TypeScript/Express, OEmbed, Server-Side Rendering (SSR), Satori (React-to-Image)

Boundaries & Risks: 微服务架构增加了部署和运维的复杂性，需要管理多个独立的服务及其依赖。服务间的调用可能会引入额外的网络延迟，并且需要一套完善的监控和容错机制来保证整个系统的稳定性。

安全的“即抛型”多账户会话管理

Problem: 在支持多账户登录的应用中，如何从架构上杜绝账户间状态混淆的风险，并防止已切换到后台的账户发生非预期的认证行为（如消耗刷新令牌）？

Solution: 项目采用了一种被称为“一个账户，一个代理”的严格隔离模型。 Step 1: 系统中存在的不是一个可切换内部状态的会话对象，而是为每个登录的账户都维护一个独立的、完整的AT协议代理（Agent）实例蓝图。 Step 2: 当用户请求从账户A切换到账户B时，系统并不会去修改现有代理的状态。相反，它会使用账户B的凭证，创建一个全新的代理实例。 Step 3: 在新代理完全就绪并接管应用后，最关键的一步发生：系统会立即调用账户A的代理实例的 `dispose()` 方法。 Step 4: `dispose()` 方法会销毁该实例，并使其内部持有的刷新令牌等认证凭证失效。 核心价值：这种“用后即焚”的策略，确保了任何时候只有一个代理是活跃的。它从根本上消除了后台会话意外刷新令牌或进行API调用的可能性，是一种极其稳健和安全的多账户管理方案。

Technologies: AT Protocol Agent, Session Management

Boundaries & Risks: 频繁创建和销毁代理实例会比简单地切换内部状态有略高的性能开销，尽管在现代设备上这种开销几乎可以忽略不计。此模式要求代理实例的设计是轻量且易于初始化的。

基于去中心化协议的全功能跨平台社交客户端基线

一套可直接参考的“完整社交产品客户端”实现，而不是零散组件。

User Benefit: 它不是单一功能演示，而是覆盖登录、多账号、信息流、发帖与草稿、通知、私信、审核与举报等端到端体验的完整客户端实现，并同时支持 iOS、Android 与 Web。对希望进入去中心化社交生态的团队来说，这显著缩短从“协议可用”到“可运营产品”的时间。

Competitive Moat: 要在多平台同时做到功能齐全、交互一致、并与协议生态深度兼容，通常需要跨客户端工程、产品交互与协议理解的长期投入。竞争者即使复刻功能列表，也很难在短期内复刻这套经过真实用户使用打磨的整体集成与工程体系。

多账号会话切换与跨标签同步的可运营用户体验

在多账号与 Web 多标签场景下保持登录态一致，提升可用性与可运营性。

User Benefit: 同一设备可登录多个账号，并在切换时清理旧会话代理以降低令牌误用风险；Web 端还可在多标签页之间同步会话变化，减少“在一个标签登录另一个标签不生效”的用户困扰（src/state/session/index.tsx、src/state/persisted/index.web.ts）。

Competitive Moat: 多账号与跨实例同步会牵涉到会话一致性、缓存清理与边界条件处理，容易产生安全与体验问题；要做到稳定可用通常需要较多线上反馈与工程迭代。其实现复杂度高于常见的单账号登录态管理。

高响应的社交交互体验（大规模乐观更新与缓存一致性）

交互“秒响应”，靠的是一整套缓存与乐观更新体系，而非单点技巧。

User Benefit: 点赞、转发、关注等高频操作可先在本地即时反馈，再与服务端确认，减少用户等待与操作不确定性；并通过统一的数据缓存层减少重复请求与页面抖动（src/state/cache/post-shadow.ts、src/state/cache/profile-shadow.ts、src/state/queries）。

Competitive Moat: 要在复杂信息流与多入口（搜索、通知、个人页、列表）同时保持一致的乐观状态并在失败时回滚，需要较成熟的数据层架构与大量边界条件处理。对多数团队而言，这类一致性问题会消耗大量调试与维护时间。

低基础设施复杂度的私信准实时同步与失败恢复

用轮询+状态机实现可用的私信体验，降低后端长连接成本。

User Benefit: 私信在不依赖长连接的情况下，通过事件总线与前后台自适应轮询保持消息更新，并在网络恢复时对待发送消息进行批量重试，减少“消息发不出去/丢失”的用户投诉（src/state/messages/events、src/state/messages/convo）。

Competitive Moat: 在移动端要兼顾电量、网络波动与一致性，构建可靠的消息状态机与重试策略并不简单；尤其是待发送队列、批量补发与修订号排序等机制，需要系统性设计与长期测试。

面向运营的Web生态配套能力（嵌入、短链、分享卡片与SSR）

一套围绕增长与分发的 Web 周边服务组合，不只是一个 App。

User Benefit: 不仅有客户端，还包含网页端的服务端渲染、第三方站点嵌入、短链与动态分享卡片生成等能力，能支撑增长、SEO/可索引性、内容分发与活动运营（bskyweb、embedr、bskylink、bskyogcard）。

Competitive Moat: 这些能力跨 Go/Node/数据库/模板渲染/安全策略等多个技术栈，并且需要与上游内容 API 紧密配合。对新团队而言，端到端搭建与打通往往是一个“产品化工程”而非简单编码。

Web 页面缺少内容安全策略导致脚本注入风险 (Commercial Blocker)

网页服务的安全中间件明确将内容安全策略标注为待办事项，当前未设置内容安全策略头，无法有效限制第三方脚本来源与内联脚本执行（bskyweb/cmd/bskyweb/server.go 中 SecureConfig 的 TODO）。

Business Impact: 一旦出现跨站脚本注入（例如反射或第三方资源被污染），用户会话可能被窃取、页面被篡改，导致账户被接管与品牌信任受损；在多数企业安全评审中会被直接判定为阻断项。

服务端到上游的TLS校验被关闭导致中间人攻击风险 (Commercial Blocker)

网页服务中用于访问 ipcc 的 HTTP 客户端显式设置跳过 TLS 证书校验（InsecureSkipVerify 为 true），会使 HTTPS 连接无法验证对端身份（bskyweb/cmd/bskyweb/server.go）。

Business Impact: 在不可信网络或被劫持的网络环境中，上游响应可能被篡改，带来错误的业务决策、内容注入或隐私泄露；该配置通常无法通过安全审计。

刷新令牌在本地存储的保护等级不足以支撑安全敏感场景 (Commercial Blocker)

移动端持久化使用通用键值存储写入整份应用状态（含会话分区），Web 端使用浏览器本地存储保存同一份状态；当前证据未显示使用操作系统级安全存储（例如系统密钥链/安全硬件）对刷新令牌等敏感信息进行专门保护（src/state/persisted/index.ts、src/state/persisted/index.web.ts；会话层会将账号与会话写入持久化存储）。

Business Impact: 在设备丢失、越狱/Root、恶意浏览器扩展或共享设备场景下，令牌被窃取会导致账户被接管。对金融、政企、合规要求高的客户，这是典型的上线阻断项。

私信缺少端到端加密不适用于高敏感沟通场景 (Commercial Blocker)

现有私信模块依赖服务端存储与 atproto API 传输，未在该层实现端到端加密能力；这意味着服务端或具备访问权限的系统仍可能读取消息内容（当前证据未发现客户端侧端到端加密实现）。

Business Impact: 若产品定位包含高隐私通信（例如企业内部沟通、合规行业），该能力缺失会直接导致无法满足客户与监管预期，从而阻断商业合作。

短链服务缺少删除与过期机制可能触发数据合规风险 (Commercial Blocker)

短链创建后没有生命周期管理策略：没有可配置的过期时间、后台清理或删除能力的证据，数据会长期累积（bskylink/src/routes/createShortLink.ts、bskylink/src/db/schema.ts 的结构未体现 TTL/清理机制）。

Business Impact: 长期运营会带来存储成本上升，并可能与“可删除/可追溯/数据最小化”等合规要求冲突；在面向欧盟或企业客户时会显著增加法务与运营风险。

Web 服务对上游内容API强依赖导致大规模故障时体验崩溃 (Scale Blocker)

网页服务端渲染页面需要从上游 AppView API 拉取数据，当前证据未显示断路器、降级缓存或兜底渲染策略；上游不可用时会影响页面输出与用户体验（bskyweb/cmd/bskyweb/server.go 与相关渲染/路由逻辑）。

Business Impact: 在热点事件或上游限流/故障时，Web 端可能出现空白页或关键内容不可用，形成舆情风险并放大客服压力；对需要稳定对外展示的业务（媒体/公关/活动）是规模化阻碍。

搜索语法可绕过用户审核偏好导致安全体验不一致 (Notable)

帖子搜索对包含 from: 的查询存在硬编码分支，导致绕过常规审核过滤逻辑，从而与用户在其他入口的内容过滤体验不一致（src/state/queries/search-posts.ts）。

Business Impact: 用户可能在搜索中看到自己明确不想看到的内容，降低对安全设置的信任，并增加内容治理与客服成本。

路由构建缺参会生成无效链接影响深链与分享可靠性 (Notable)

路由构建在缺少路径参数时会把缺失值替换为字符串“undefined”，从而生成语义错误的 URL（src/lib/routes/router.ts）。

Business Impact: 深链、分享链接或通知跳转可能出现不可用或指向错误页面，影响增长转化与用户信任。

个人资料查询的关键缓存参数缺乏机制性保护易引发回归 (Notable)

个人资料查询使用 15 秒的缓存新鲜期并在注释中说明“移除会导致界面无限循环”，暗示存在隐含的响应式依赖环；该“负载承重”参数缺少测试与约束会导致未来改动引发严重回归（src/state/queries/profile.ts）。

Business Impact: 一旦被无意修改，可能导致关键页面卡死或耗电/耗流量异常，影响留存并增加线上事故概率。

通知未读轮询失败缺少即时重试导致徽标长期不准 (Notable)

未读通知检查在失败时仅复位状态而不做快速重试，依赖下一次固定间隔轮询恢复（src/state/queries/notifications/unread.tsx）。

Business Impact: 网络抖动后用户可能长时间看不到正确的未读数，降低对通知系统的信任，影响回访与互动。

私信实时性依赖轮询在活跃对话中可能显得迟缓 (Notable)

私信使用轮询策略（前台/后台不同间隔）而非长连接，意味着在某些状态下消息到达可能延迟到下一次轮询（src/state/messages/events/const.ts）。

Business Impact: 与即时通讯类产品相比，活跃会话体验可能显得不够“实时”，影响用户对私信功能的满意度与使用频率；若未来要对标强实时体验，可能需要架构级改造。

消息草稿不落盘导致用户误操作时丢失输入 (Notable)

消息草稿仅保存在内存状态中，应用关闭或被系统回收后会丢失（src/state/messages/message-drafts.tsx）。

Business Impact: 用户可能因切后台、崩溃或误关闭而丢失未发送内容，带来负面体验与差评风险。

短链跨域与环境扩展需要改代码影响交付灵活性 (Notable)

Web 服务的允许跨域来源在启动参数中配置，但证据中也存在面向固定域名的部署假设与环境列表管理方式；在多域名/客户化部署场景下容易变成反复改动与发布（bskyweb/cmd/bskyweb/server.go 与启动配置逻辑）。

Business Impact: 做企业私有化或多地区多域名部署时，交付周期变长、变更风险增大，且更容易因配置遗漏引发线上故障。

Web 服务不内置TLS终止导致部署错误概率上升 (Notable)

Web 服务以 HTTP 方式监听并依赖外部负载均衡或反向代理完成 TLS 终止（bskyweb/cmd/bskyweb/server.go 的 ListenAndServe 使用方式）。

Business Impact: 一旦外部代理配置错误，就可能出现明文传输或安全头缺失等问题；增加部署复杂度与运维门槛。

会话恢复与后台重试可能产生未捕获异常影响稳定性 (Notable)

会话恢复在未过期时会先直接注入旧会话并在后台进行多次重试；失败分支中记录错误后重新抛出，若调用方未正确处理可能产生未捕获的异步错误（src/state/session/agent.ts，配合会话提供者逻辑）。

Business Impact: 弱网或切换账号时可能出现间歇性掉线、错误上报噪音或启动阶段不稳定，影响留存与问题定位效率。