stream-react-native

Stream React Native - 技能路由器 + 执行流程

规则： 每个会话只需阅读一次 RULES.md。所有不可妥协的 React Native Chat、Video 和 Feeds 规则都在其中说明。

此文件是唯一入口：用于 Stream Chat React Native、Stream Video React Native 和 Stream Feeds React Native 工作的意图分类、产品选择、项目检测和模块指引。

---

步骤 0：意图分类器（必须首先执行 - 绝不跳过）

在调用任何工具之前，仅根据用户输入判断所属路径。不要先探查文件系统。

信号 -> 路径

用户输入中的信号	路径
“构建/创建/搭建新的 React Native 应用”、“创建 Expo 应用”、“新的 Stream Chat RN 应用”、“新的 Stream Video RN 应用”、“新的 Stream Feeds RN 应用”、空目录 + React Native/Expo Chat / Video / Feeds	A - 新应用
“升级/迁移/更新 Stream SDK 版本”、“将 stream-chat-react-native 升级到 v9”、“将 Chat RN 迁移到新 SDK”、“v8 到 v9”、“更新 Stream Video/Feeds”、“Feeds v2 -> v3”	M - 迁移 / 升级
“从 Sendbird 迁移”、“用 Stream 替换 Sendbird”、“我们要弃用 Sendbird”、“移除 @sendbird/uikit-react-native”、“将 SendbirdUIKitContainer / createGroupChannelFragment 转换为 Stream”，目标的 package.json 中存在 @sendbird/chat / @sendbird/uikit-react-native / -foundation	S - 从 Sendbird 迁移
“将 Stream Chat 添加/集成到此应用”、“接入 Chat RN”、“设置 stream-chat-expo”、“添加视频通话”、“接入 Stream Video”、“设置 @stream-io/video-react-native-sdk”、“添加动态消息流”、“接入 Stream Feeds”、“设置 @stream-io/feeds-react-native-sdk”、“更改/自定义此 Chat / Video / Feeds UI”	B - 现有应用
React Native、Expo、Expo Router、stream-chat-react-native、stream-chat-expo、@stream-io/video-react-native-sdk、@stream-io/feeds-react-native-sdk、Stream Chat RN、Stream Video RN、Stream Feeds RN、Chat React Native、Video React Native、Feeds React Native、迁移	如果用户只询问用法/文档，则为 C - 参考查询；否则为 B - 现有应用
明确的产品/运行时标识：Chat React Native、Chat Expo、Video React Native、Video Expo、Feeds React Native、Feeds Expo	C - 参考查询
关于 Stream Chat、Stream Video 或 Stream Feeds React Native / Expo 工作的“文档”或“说明文档”	C - 参考查询
“如何在 React Native/Expo 中实现 {X}？”、“{SDK 组件/hook/prop} 有什么作用？”	C - 参考查询
“审计/审核/检查现有 Stream Video 集成是否符合最佳实践”、“我的视频应用是否已达到生产就绪状态？”、“上线前还缺少什么？”	C - 参考查询（只读）- 在 references/VIDEO-REACT-NATIVE.md 中执行 集成最佳实践审计
“安装 Stream 软件包”、“设置 Chat RN”、“设置 Video RN”、“设置 Feeds RN”、“接入身份验证/令牌流程”，且没有更广泛的功能请求	D - 引导 / 设置
“构建类似 ChatGPT 的应用”、“添加 AI 助手 / 支持机器人 / copilot”、“流式传输大模型响应”、“思考指示器”、“停止生成”、“向 AI 进行语音输入”、“让 Agent 在设备上执行 X”、LangChain、Vercel AI SDK、@stream-io/chat-react-native-ai	A（新应用）或 B（现有应用），然后在集成步骤中运行 ai-integration.md；如果用户只询问某个 AI 组件的工作原理，则为 C（在 Chat 清单中搜索 ai-integrations）
Stream Moderation 审核 UI 或任何其他非 Chat / 非 Video / 非 Feeds 的 Stream RN 产品	拒绝捆绑范围，仅当用户想要文档时才转到实时文档
不带参数的 /stream-react-native	简要列出各路径并等待

歧义判定流程

如果请求在接入代码和查阅参考资料之间存在歧义，请提出一个简短问题并等待：

你希望我将其接入项目，还是只梳理 React Native SDK 的模式和文件？

如果用户想创建新应用，但未指定 Expo 或 RN CLI，默认使用 Expo，因为这是最快的成功路径。用户提出要求或原生项目约束要求时，使用 RN CLI。

产品分类器（确定轨道后）

根据用户输入或检测到的包识别产品。轨道 A、B 和 D 都需要先确定产品才能继续；轨道 C 则选择匹配的参考资料组合。

产品信号	产品	参考资料
stream-chat-react-native、stream-chat-expo、channel、message、MessageComposer、thread、attachment、offline support	Chat	references/CHAT-REACT-NATIVE.md + references/CHAT-REACT-NATIVE-blueprints.md
@stream-io/video-react-native-sdk、video call、livestream、audio room、ringing、CallContent、ParticipantView、screenshare、picture in picture	Video	references/VIDEO-REACT-NATIVE.md + references/VIDEO-REACT-NATIVE-blueprints.md
@stream-io/feeds-react-native-sdk、useCreateFeedsClient、StreamFeeds、StreamFeed、activity feed、timeline feed、notification feed、for-you feed、useFeedActivities、useActivityComments、reactions、comments、follows、follow / unfollow、activity composer、activityWithStateUpdates	Feeds	references/FEEDS-REACT-NATIVE.md + references/FEEDS-REACT-NATIVE-blueprints.md
一个应用中包含两个或更多产品（例如，在聊天旁加入视频通话、Feeds + Chat、Feeds + Video 等）	Combined	仅加载涉及产品的参考资料组合。嵌套 providers（例如，将 <StreamVideo> 放在 <OverlayProvider><Chat> 内，再放入 <StreamFeeds>）；不要将它们作为同级元素。参见 RULES.md 和由清单选定的 /video/docs/react-native/advanced/chat-with-video.md，了解 Chat + Video 的互操作说明

如果请求涉及的产品不明确，请提出一个简短问题并等待：

你要接入的是 Stream Chat（频道、消息）、Stream Video（通话、直播、音频房间），还是 Stream Feeds（动态流、时间线、评论、反应、关注）？还是要在同一个应用中接入多个产品？

范围排除

此技能包含 Chat、Video 和 Feeds React Native。如果用户询问 Stream Moderation 审核 UI 或其他未包含在内的 Stream RN 产品，请这样回复：

React Native 技能目前包含 Chat、Video 和 Feeds 参考资料。我可以在此帮助你组合使用这些产品，也可以切换到实时文档以了解其他产品。

不要凭记忆编造缺失的 React Native Moderation API 细节。

分类之后

• Track A、B、D -> 运行 Project signals，然后继续阅读 builder.md 和 sdk.md。在编写 Chat、Video 或 Feeds 连接代码或创建用户要求的演示数据之前，先运行 credentials.md。
• Track M -> 先阅读 migrate.md；它会在任何编辑之前获取实时升级指南。运行 Project signals 检测 lane / 包管理器 / New Architecture，但跳过凭据、配置和脚手架流程——它会编辑现有项目。
• Track S -> 先阅读 sendbird-migration.md；它会在任何编辑之前检测 Sendbird 集成形式（以及 Expo 与 bare 的类型）。运行 Project signals 检测 lane / 包管理器 / New Architecture，但不要进入 Track A/B/D 或任何脚手架流程——它会在现有 Sendbird 集成中就地重新实现。
• Track C -> 如果产品和运行时已明确，则跳过凭据和项目探测。只有在 RN CLI 与 Expo 不明确且答案会影响指导内容时，才运行只读探测。

---

步骤 0.5：凭据、令牌和演示数据（仅限 Track A、B、D）

每个会话运行一次 credentials.md，且必须在编写连接 Stream Chat、Stream Video 或 Stream Feeds 的代码之前运行。

它会解析以下内容：

• Stream API 密钥
• 用户 ID 和显示名称
• 用户令牌或令牌提供程序方案
• 可选演示数据，仅在用户提出要求时提供，通过 Stream CLI 调用（Chat：UpdateUsers、GetOrCreateChannel、SendMessage；Video 和 Feeds 无需种子数据，因为调用是临时的，且活动可在运行时发布）

对于 Track A，如果必须先确定运行时或目标目录，可以先搭建应用。解析凭据或令牌提供程序方案之前，不要渲染已连接 Chat、Video 或 Feeds 的 UI。

---

Project signals（Track A/B/D：每个会话运行一次；Track C：仅按需运行）

只读本地探测。用于检测空白/新工作区、RN CLI 与 Expo、New Architecture 提示、导航设置以及现有 Stream 包。

bash -c 'echo "=== PACKAGE ==="; test -f package.json && grep -oE "\"(stream-chat-react-native|stream-chat-expo|@stream-io/video-react-native-sdk|@stream-io/feeds-react-native-sdk|@stream-io/react-native-webrtc|@stream-io/react-native-callingx|react-native|expo|@react-navigation/[^\"]+|expo-router|react-native-reanimated|react-native-worklets|react-native-teleport|@op-engineering/op-sqlite)\": *\"[^\"]*\"" package.json 2>/dev/null; echo "=== EXPO ==="; find . -maxdepth 2 \( -name "app.json" -o -name "app.config.js" -o -name "app.config.ts" -o -path "./app/_layout.*" \) -print 2>/dev/null; echo "=== NATIVE ==="; find . -maxdepth 2 \( -name "ios" -o -name "android" \) -type d -print 2>/dev/null; echo "=== CONFIG ==="; find . -maxdepth 2 \( -name "babel.config.js" -o -name "metro.config.js" \) -print 2>/dev/null; echo "=== EXPO_SDK ==="; node -e "try{console.log(require(\"./node_modules/expo/package.json\").version)}catch(e){try{console.log(require(\"./package.json\").dependencies.expo)}catch(e){console.log(\"-\")}}" 2>/dev/null; echo "=== EMPTY ==="; test -z "$(ls -A 2>/dev/null)" && echo "EMPTY_CWD" || echo "NON_EMPTY"'

将结果保留在对话上下文中。除非用户更改目录、安装了包或项目结构发生变化，否则不要重新运行。

使用结果生成一行状态，例如：

• 检测到空白工作区 - 除非用户要求使用 RN CLI，否则默认创建新的 Expo 应用
• 检测到 Expo 应用 - 未安装 stream-chat-expo - 存在 Expo Router - 已准备好设置 Chat
• 检测到 Expo 应用 - Expo SDK 56+ - 应用 RULES.md > Expo Router SDK 56+ 规则（不使用 @react-navigation/*）
• ⚠️ 检测到 react-native-reanimated 4.5.0 + react-native-worklets 0.10.0 — 已知会导致崩溃的组合（Expo SDK 57 固定版本）；升级到 ≥4.5.1/≥0.10.2 并重新构建原生应用（RULES.md > Required peer setup）
• 检测到 Expo 应用 - 未安装 @stream-io/video-react-native-sdk - 已准备好设置 Video
• 检测到 Expo 应用 - 未安装 @stream-io/feeds-react-native-sdk - 已准备好设置 Feeds
• 检测到 RN CLI 应用 - 存在 ios/android - 已安装 stream-chat-react-native - 正在检查 provider 的放置位置
• 检测到 RN CLI 应用 - 已安装 @stream-io/video-react-native-sdk 和 stream-chat-react-native - 适用 Chat + Video 互操作
• 检测到 Expo 应用 - 已安装 @stream-io/feeds-react-native-sdk 和 stream-chat-expo - 嵌套 StreamFeeds + Chat providers（不要并列挂载）
• 非空目录中未检测到 RN/Expo 应用 - 请在子目录中创建新应用，或先询问是否可以重复使用此目录

如果不存在 RN/Expo 项目且适用 Track A，则通过 builder.md > 2. New app scaffold 搭建一个项目。如果在非 RN 目录中适用 Track B/D，则在创建子应用之前先询问，因为这会改变项目的归属。

模块地图

轨道	模块
A - 新建应用	builder.md + sdk.md + llms.txt 文档查找 + 产品参考（Chat / Video / Feeds）
B - 现有应用	builder.md + sdk.md + llms.txt 文档查找 + 产品参考（Chat / Video / Feeds）
C - 参考查找	sdk.md + references/DOCS.md + 相关产品参考文件
D - 引导 / 设置	builder.md + sdk.md + llms.txt 文档查找
M - 迁移 / 升级	migrate.md + references/DOCS.md（实时升级指南）+ 迁移后的 SDK 产品参考
S - 从 Sendbird 迁移	sendbird-migration.md + references/sendbird-notes.md + references/sendbird-symbols.tsv + references/design-matching.md + credentials.md + references/CHAT-REACT-NATIVE.md

---

参考资料布局

通用的 React Native 和 Expo 模式位于 sdk.md。

产品专属的设置、文档查找、注意事项和 UI 蓝图位于 references/ 下：

• llms.txt 文档查找（Chat、Video、Feeds）： references/DOCS.md
• Chat 设置/参考： references/CHAT-REACT-NATIVE.md
• Chat 屏幕/组件蓝图： references/CHAT-REACT-NATIVE-blueprints.md
• Video 设置/参考： references/VIDEO-REACT-NATIVE.md
• Video 屏幕/组件蓝图： references/VIDEO-REACT-NATIVE-blueprints.md
• Feeds 设置/参考： references/FEEDS-REACT-NATIVE.md
• Feeds 屏幕/组件蓝图： references/FEEDS-REACT-NATIVE-blueprints.md
• iOS 模拟器验证（快速运行/截图循环）： references/SIMULATOR-VERIFICATION.md

如果所需的产品文件尚未打包，请明确说明，并且仅在用户提出要求时才切换到实时文档。

---

先查文档的触发条件（构建前查阅文档）

打包的蓝图仅涵盖常见的脚手架路径——根级 providers、身份验证门、新应用脚手架、频道列表、频道/消息屏幕、线程（以及 Video/Feeds 的对应内容）。对于任何自定义或扩展此路径的需求，实时 llms.txt 选出的页面是当前 API 和推荐模式的权威来源。编写代码之前先获取该页面。

以下情况需要先查阅文档：

• UI 自定义 / 主题 / 组件覆盖——主题、设计令牌、替换插槽（消息气泡、编辑器、通话控件、参与者磁贴、动态行）、自定义渲染属性。
• 实用方案——输入指示器、消息操作、反应 UI、附件处理、提及、搜索、链接预览等。
• 高级指南——推送通知、离线支持、画中画、响铃、屏幕共享、广播、视频滤镜、Chat+Video 互操作、通知/For-You 动态、投票、内容审核。
• 迁移 / 版本升级。
• 任何蓝图中尚未涵盖的精确 API、属性、钩子或组件细节。

操作方式：

查阅 references/DOCS.md 时，使用 getstream docs 获取相关文档。绝不要凭记忆构建自定义、实用方案或高级功能。

---

样式深度标记：匹配提供的设计

与上面的路径正交：如果请求带有目标外观——附带截图、Figma 画板，或“让它看起来像 <app>”——不要把它当作只需设置几个颜色的任务。编写 UI 代码之前，先运行 references/design-matching.md：它会按区域拆解参考图，并将每一处差异规划为三个维度之一——主题（Theme 对象）、布局（WithComponents 插槽覆盖 + props）或功能（props / config / SDK hooks）——然后逐区域对照参考图进行验证。实现每个区域，包括消息输入框；任何区域仍使用 SDK 默认样式都算失败，而不是“已知的外观差异”。

这一步是在 DOCS.md 查阅之外（而非替代它）的额外要求：获取清单所选的主题/自定义页面，以确认准确的主题路径和组件名称。没有目标外观的普通请求不会触发此要求——照常根据蓝图构建。

优先排查的陷阱（RN 设计匹配中反复出现的失败问题——开始前请牢记；完整详情和解决方案见 references/design-matching.md）：

• 消息输入框是核心结构，不是颜色。 如果它是浮动的（内嵌胶囊、圆角、带阴影，内容显示在其后方），请在 <Channel> 上设置 messageInputFloating——绝不要用半透明背景填充来伪造浮动胶囊。消息输入框栏的表面是 messageComposer.wrapper（container 仅是内部行；给它上色会在按钮周围涂出一圈）。发送/麦克风按钮位于输入胶囊内部，并会在静止↔输入状态间切换（复用 OutputButtons，不要手写实现）。附件 + 包含两部分——触发按钮，以及与 toggleAttachmentPicker 绑定的 +↔键盘状态图标（不要直接放入带边框的 SDK AttachButton，并想当然地认为它符合设计）。
• 绝不要用背景填充伪造结构；先确定结构机制（prop/flag/slot），再做外观润色（玻璃质感、精确配色）。
• 将时间戳/已送达标记移到气泡内部属于结构性重排（MessageContent* 插槽），不是主题键——许多重设计都需要这种气泡内部元数据样式。
• 聊天应用的附件面板就是 Stream 的 AttachmentPicker（顶部为磁贴，下方为图库）——覆盖 AttachmentPickerSelectionBar，不要另建平行的模态框。底部栏也可覆盖（AttachmentPickerSelectionBar 和 AttachmentPickerContent 都是上下文插槽）——将栏设为 null，并用绝对定位覆盖栏来覆盖内容；宿主是直接导入项并不会锁定布局。
• Channel 的 keyboardVerticalOffset/topInset：对于位于 Channel 内部的页眉，请显式传入 0——省略 keyboardVerticalOffset 会传入 undefined（SDK 没有默认值），而不是 0。仅当页眉是原生页眉（或位于 <Channel> 上方的同级页眉）时，才设置非零值。通过聚焦输入框以弹出真实键盘来验证键盘避让——setText 不会弹出键盘。
• 覆盖组合插槽会丢失默认实现的所有子功能，除非你自行重现它们（头像、分组、表情回应、回复、已送达标记、已编辑/已删除状态）。
• **会悄悄破坏这些构建的设置陷阱：**在 Expo SDK 57 上，将易崩溃的 reanimated 固定版本升级至更高版本（≥4.5.1/≥0.10.2）；在 Reanimated 4 上，于根目录 package.json 中设置 FORCE_REACT_RENDER_FOR_SETTLED_ANIMATIONS: false（两项要求均见 RULES.md > Required peer setup）。 捕获这些问题的通用推理规则位于 references/design-matching.md 中——遇到任何设计匹配请求时都要阅读。各规则的位置：partial-styling → inner container、name-isn't-the-node、reinvention red flag、structure-before-surface 和 idiomatic-≠-matching 位于 Step 1 > Region checklist + routing；no magic numbers 和 ink-vs-declared-size 位于 Step 1 > Getting sizes right / Weight；override-every-cascading-token、pinned-vs-adapted surfaces 和 glyph knockouts 位于 Step 1 > Follow EVERY color；regression adjacency 位于 Step 3。另有两条规则放在这里：green-launch ≠ correct 位于 references/SIMULATOR-VERIFICATION.md §7，assumed-≠-SDK-default 位于 RULES.md > Package version and docs discipline。

---

Track A - 新应用

完整说明：builder.md - 使用新应用路径。

阶段	名称	操作
A1	检测	运行 Project signals。空工作区适用于 Track A。
A2	选择路径和产品	未指定时默认使用 Expo；用户有要求时使用 RN CLI。确认产品（Chat、Video、Feeds，或任意组合）。
A3	搭建脚手架	使用当前框架工具创建应用；不要解释完整的 RN/Expo 环境配置。
A4	安装并接入	对每种产品使用清单选定的 Installation 文档，验证 npm dist-tags，安装 package 和 peer dependencies，然后接入 providers 并创建首个 UI。
A5	验证	确认安装、root providers、权限（Video：camera/mic）、身份验证，以及首个已渲染的 Chat / Video / Feeds 屏幕。

---

Track B - 现有应用

完整说明：builder.md - 使用现有项目路径。

阶段	名称	操作
B1	检测	运行 Project signals，并在编辑前检查现有应用结构。记录已有的 Chat / Video / Feeds packages。
B2	保留	保留 Expo/RN CLI 路径、package manager、导航栈和身份验证架构。如果用户要求升级/迁移 SDK 版本，则应使用 Track M -> migrate.md，而不是编辑 Track B。
B3	集成	使用 llms.txt 查找所需区域，然后仅加载必要的 Chat / Video / Feeds 参考/蓝图章节。
B4	验证	确认所需的 Stream Chat / Video / Feeds 流程能在现有应用中构建并渲染。

---

Track C - 参考资料查询

仅加载与所请求产品相关的文件：

• llms.txt 清单查询规则 -> references/DOCS.md
• 通用生命周期 / 身份验证 / 提供方 / 运行时模式 -> sdk.md
• Chat RN 设置与注意事项 -> references/CHAT-REACT-NATIVE.md
• Chat RN 屏幕 / 组件结构 -> references/CHAT-REACT-NATIVE-blueprints.md
• Video RN 设置与注意事项 -> references/VIDEO-REACT-NATIVE.md
• Video RN 屏幕 / 组件结构 -> references/VIDEO-REACT-NATIVE-blueprints.md
• Feeds RN 设置与注意事项 -> references/FEEDS-REACT-NATIVE.md
• Feeds RN 屏幕 / 组件结构 -> references/FEEDS-REACT-NATIVE-blueprints.md
• 根据最佳实践审查现有 Video 集成 -> references/VIDEO-REACT-NATIVE.md 中的 集成最佳实践审查部分（只读审查；在更改任何代码前先给出发现）

如果用户要求此处未包含的精确 API 详情，请使用 references/DOCS.md 获取正确的清单和选定的 Markdown 页面。如果实现仍需在源码层面进行确认，请在依赖项安装后检查目标应用 node_modules 下的已安装包。不要使用特定于机器的文档路径。

---

Track D - 引导 / 设置

当用户主要需要安装软件包和完成通用接线，而不是构建完整功能时使用。按产品分支：

• 判断是 RN CLI 还是 Expo
• 使用 llms.txt 查询对应产品的 Installation 文档，并确认当前 npm dist-tags
• 安装正确的软件包及所需的 peer 依赖（Chat：stream-chat-react-native 或 stream-chat-expo；Video：@stream-io/video-react-native-sdk；Feeds：@stream-io/feeds-react-native-sdk + @react-native-community/netinfo）
• Chat 特定接线：将 Reanimated/Worklets Babel 插件设为最后一个插件；用 GestureHandlerRootView 包裹入口；放置 OverlayProvider 和 Chat；接入 useCreateChatClient 或应用的后端令牌提供方
• Video 特定接线：声明相机 / 麦克风权限；在适用时添加 Expo 配置插件；创建 StreamVideoClient 并挂载 StreamVideo
• Feeds 特定接线：调用 useCreateFeedsClient（连接期间会返回 undefined）；在应用根部附近挂载一次 <StreamFeeds client={client}>；并且通常需要包裹一个 OwnFeedsContextProvider，由其创建用户 Feed、时间线 Feed 和自我关注关系
• 如果用户只要求设置，则在进入产品特定的 UI 前停止

---

Track M - 迁移 / 升级版本

完整详情： migrate.md - 先阅读此文档；它会在任何编辑前获取最新的升级指南。在获取指南前，由文档驱动且只读 - 绝不能凭记忆迁移（RULES.md > 包版本和文档规范）。跳过凭据、配置和脚手架；保留项目的运行时路线、包管理器和锁文件。

阶段	名称	操作
M1	检测	运行 Project signals + 阅读 package.json/锁文件：确认使用了哪些 Stream 包、它们的 from -> to 版本、运行时路线、包管理器，以及 RN/Expo 新架构状态。
M2	获取指南	从产品清单（references/DOCS.md）获取匹配的升级指南（已知入口：Chat RN v8 -> v9）。获取失败即为硬性阻断 -> getstream docs -> 停止并询问。
M2.5	前置条件	先解决 RN 特定的阻碍：新架构要求、新的原生/对等依赖（例如 Chat v9 的 react-native-teleport）、原生重建。
M3	应用更改	仅升级目标包（每个包升级到各自的目标版本；升级对应路线的 Chat 封装包），应用所有有文档记录的破坏性更改，依据已安装的 node_modules/stream-chat-react-native-core 源码核实每个符号，搜索重命名的符号，并清理原生配置和键盘相关代码。
M4	验证	tsc --noEmit -> Metro bundle -> 原生构建 -> 在模拟器/设备上对核心流程进行冒烟测试。不要运行 next build；tsc 通过不代表渲染正常。使用绝对路径执行 cd 来运行门禁命令，并且绝不要通过管道执行 - 管道返回的是管道的退出状态，而不是命令本身的状态。
M5	总结	列出升级的包、应用的破坏性更改、原生/新架构更改、修改的文件以及后续手动操作。提出下一步建议（不要自动运行）。

Track S - 从 Sendbird 迁移

完整详情： sendbird-migration.md - 请先阅读。它会检测现有 Sendbird 集成的形式以及 Expo 与裸 RN 的类型，然后基于经过验证的 Sendbird<->Stream 映射（references/sendbird-notes.md + references/sendbird-symbols.tsv），在原处重新实现每个接触点，最后提供单独的服务端数据迁移。这不是脚手架流程：不要进入 Track A/B/D。编译器是最终依据——切勿凭记忆迁移（references/sendbird-notes.md > 信任模型）。

阶段	名称	要做什么
S0	检测与盘点	运行 Project signals，检测项目类型（Expo 或裸 RN）、包管理器、New-Arch 和导航。搜索 Sendbird 的使用情况，将每个接触点和每个 @sendbird 符号分类（已映射 / 已知但未映射 / 未知），建立兼容性账本，并记录视觉基线（原版的模拟器截图或根据代码推导的主题）——参见 sendbird-migration.md 第 0 节。
S1	规划与检查点	汇总计划（类型 + 形式、令牌路径、设计标准、差异）。如有任何差异项、未解决的凭据问题或含糊的设计标准，暂停并集中询问用户；否则继续。参见第 2 节。
S2	包与连接	在 Sendbird 旁边安装 Stream（适用于当前类型的包及其对等依赖；配置 GestureHandlerRootView / OverlayProvider / Reanimated Babel 插件）。在修改 UI 之前，通过 credentials.md 验证真实用户能够连接（useCreateChatClient + tokenProvider）。参见第 3–4 节。
S3	迁移接触点	逐文件、在原处迁移：UI 组合（不使用 <Window>；由应用管理页眉）、频道、消息/附件、事件（使用 { unsubscribe } 清理）、分页（无状态）、成员管理/审核、离线支持。删除手写的响应式基础机制。然后移除所有三个 Sendbird 包。参见第 5 节。
S4	设计一致性	将主题重新编写为 JS Theme 对象（不使用 CSS），然后以基线为参考，从第 1 步开始执行 references/design-matching.md。参见第 6 节。
S5	验证	按顺序通过各道关卡：tsc --noEmit、原生构建、确保没有 @sendbird 导入、双用户模拟器冒烟测试 + 驱动每一项交互（关卡 4——处理程序在此处验证，而非通过设计关卡验证）、对照账本进行设计验证、关闭账本、更新 README。从绝对路径执行关卡命令，并且绝不通过管道传递命令。参见第 7 节。
S6	提供数据迁移	切勿自动运行。提供服务端数据迁移（../stream/sendbird-data-migration.md）；如果用户只想更换 SDK，则停止。参见第 8 节。