在 React Native / Expo 应用中集成…

当需要在 React Native CLI 或 Expo 应用中搭建、集成、升级或从 Sendbird 迁移 Stream Chat、Stream Video、Stream Feeds 时，按意图分类走对应执行流程。

适用场景

解决思路

1. 在任何工具调用前，先仅根据用户输入做意图分类（Step 0），不要先探测文件系统；根据信号判定轨道：新建应用（A）、迁移/升级（M）、从 Sendbird 迁移（S）、已有应用集成（B）、参考查询（C）、引导/安装（D）。
2. 若请求在「接线代码」与「参考查询」之间含糊，先问一个简短问题并等待：你是想让我把它接入项目，还是只梳理 React Native SDK 的模式和文件？
3. 若用户要新建应用但未指定 Expo 或 RN CLI，默认用 Expo（最短成功路径）；仅当用户要求或原生项目约束需要时才用 RN CLI。
4. 确定轨道后做产品分类：根据输入或检测到的包判定是 Chat、Video、Feeds 还是组合（Combined）；若产品含糊，先问一个简短问题并等待。
5. 若用户请求 Stream Moderation 审核 UI 或其他未捆绑的 Stream RN 产品，明确说明本技能只捆绑 Chat、Video、Feeds，不要凭记忆编造缺失的 API 细节。
6. 分类完成后：轨道 A/B/D 先运行 Project signals，再进入 builder.md 和 sdk.md，并在写连接代码或创建演示数据前运行 credentials.md；轨道 M 先读 migrate.md（它会先拉取在线升级指南）；轨道 S 先读 sendbird-migration.md（它会先检测 Sendbird 集成形态）；轨道 C 若产品与运行时明确则跳过凭据和项目探测。
7. 运行 Project signals 只读本地探测（每条会话一次，轨道 C 按需）：用给定的 bash 命令检测 package.json 中的 Stream/RN/Expo 相关包、Expo 配置文件、ios/android 原生目录、babel/metro 配置、Expo SDK 版本、当前目录是否为空；把结果保存在对话上下文中，除非用户换目录、安装包或项目形态变化，否则不要重跑。
8. 根据 Project signals 结果产出一行状态摘要，例如：检测到空工作区默认用 Expo 新建应用；检测到 Expo 应用且缺少 stream-chat-expo 可开始 Chat 设置；Expo SDK 56+ 应用 RULES.md 的 Expo Router 规则（不用 @react-navigation/*）；检测到 react-native-reanimated 4.5.0 + react-native-worklets 0.10.0 已知崩溃组合需升级到 ≥4.5.1/≥0.10.2 并重建原生；检测到 RN CLI 应用且同时装了 Video 和 Chat 包则适用 Chat + Video 互操作；检测到 Feeds 和 Chat 包则嵌套 StreamFeeds + Chat provider（不要并列挂载）；非空目录中无 RN/Expo 应用则新建子目录或先询问。
9. 若没有 RN/Expo 项目且适用轨道 A，通过 builder.md 的「2. New app scaffold」搭建；若轨道 B/D 在非 RN 目录中适用，先询问再创建子应用，因为这会改变项目归属。
10. 按模块映射表加载对应模块：A/B 用 builder.md + sdk.md + llms.txt 文档查询 + 产品参考；C 用 sdk.md + references/DOCS.md + 相关产品参考；D 用 builder.md + sdk.md + llms.txt 文档查询；M 用 migrate.md + references/DOCS.md（在线升级指南）+ 被迁移 SDK 的产品参考；S 用 sendbird-migration.md + references/sendbird-notes.md + references/sendbird-symbols.tsv + references/design-matching.md + credentials.md + references/CHAT-REACT-NATIVE.md。
11. 按参考布局加载文件：共享 RN/Expo 模式在 sdk.md；产品专属设置、文档查询、坑与 UI 蓝图在 references/ 下（DOCS.md、CHAT-REACT-NATIVE.md、CHAT-REACT-NATIVE-blueprints.md、VIDEO-REACT-NATIVE.md、VIDEO-REACT-NATIVE-blueprints.md、FEEDS-REACT-NATIVE.md、FEEDS-REACT-NATIVE-blueprints.md、SIMULATOR-VERIFICATION.md）；若请求的产品文件未捆绑，直说，仅当用户要求时才切到在线文档。
12. 在构建前触发文档优先：当请求涉及 UI 定制/主题/组件覆盖、cookbook 配方、高级指南（推送、离线、PiP、响铃、屏幕共享、直播、视频滤镜、Chat+Video 互操作、通知/For-You feed、投票、审核）、迁移/版本升级，或任何不在捆绑蓝图中的精确 API/prop/hook/组件细节时，先按 references/DOCS.md 的 manifest 查找，再 WebFetch（或 curl -Ls）选中的 .md 页面，然后按它实现；拉取失败则交给 stream-docs 技能，若仍无法解决就停下问用户，绝不凭记忆构建定制、cookbook 或高级功能。
13. 若请求带有目标外观（截图、Figma 帧或「做成像某应用那样」），在写 UI 代码前运行 references/design-matching.md：按区域分解参考，把每个差异归为三类轴之一——主题（Theme 对象）、布局（WithComponents 槽覆盖 + props）、功能（props/config/SDK hooks），然后逐区域对照参考验证；每个区域都要实现，包括 composer；某区域停留在 SDK 默认即为 FAIL，不是「已知外观差距」。
14. 设计匹配时先内化前端陷阱：composer 是一等结构而非颜色（浮动时在 <Channel> 上设 messageInputFloating，不要用半透明背景伪造；composer 栏表面是 messageComposer.wrapper；发送/麦克风在输入胶囊内部并在静止↔输入时切换；附件 + 是触发器加 +↔键盘有状态图标，接到 toggleAttachmentPicker）；绝不用背景填充伪造结构，先解决结构机制再做外观打磨；气泡内时间戳/回执是结构性重排（MessageContent* 槽）而非主题键；聊天应用的附件面板就是 Stream 的 AttachmentPicker（覆盖 AttachmentPickerSelectionBar，不要另建模态）；<Channel> 的 keyboardVerticalOffset/topInset 对 Channel 内头部显式传 0；覆盖复合槽会丢掉默认绘制的所有子功能，除非你重现它们；Expo SDK 57 上要升级过易崩溃的 reanimated 版本，Reanimated 4 上在根 package.json 设 FORCE_REACT_RENDER_FOR_SETTLED_ANIMATIONS: false。
15. 轨道 A（新建应用）按阶段执行：A1 运行 Project signals（空工作区对 A 有效）；A2 选择通道和产品（未指定默认 Expo，确认产品）；A3 用当前框架工具创建应用，不解释完整 RN/Expo 环境搭建；A4 用 manifest 选中的各产品安装文档，核对 npm dist-tags，安装包和 peer，然后接线 provider 和首个 UI；A5 验证安装、根 provider、权限（Video 的相机/麦克风）、认证和首个渲染的 Chat/Video/Feeds 屏幕。
16. 轨道 B（已有应用）按阶段执行：B1 运行 Project signals 并在编辑前检查现有应用结构，记录已有 Chat/Video/Feeds 包；B2 保留 Expo/RN CLI 通道、包管理器、导航栈和认证架构（若用户要求升级/迁移 SDK 版本，那是轨道 M，不是 B 的编辑）；B3 用 llms.txt 查询请求区域，只加载所需的 Chat/Video/Feeds 参考/蓝图章节；B4 确认请求的 Stream 流程在现有应用中能构建并渲染。
17. 轨道 C（参考查询）只加载相关文件：DOCS.md 的 llms.txt manifest 查找规则、sdk.md 的共享生命周期/认证/provider/运行时模式、各产品的 setup/gotchas 与 blueprints；若要审计现有 Video 集成是否符合最佳实践，读 references/VIDEO-REACT-NATIVE.md 的「Integration best-practices audit」章节（只读审查，先出发现再改代码）；若需精确 API 细节，用 DOCS.md 拉取正确 manifest 和选中 markdown 页面；若实现仍需源码级确认，在依赖安装后检查目标应用 node_modules 下的已安装包；不要使用机器特定的文档路径。
18. 轨道 D（引导/安装）按产品分支：检测 RN CLI vs Expo；用 llms.txt 查询对应产品的安装文档并核对当前 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 或应用后端 token provider；Video 接线：声明相机/麦克风权限，适用处加 Expo config 插件，创建 StreamVideoClient 并挂载 StreamVideo；Feeds 接线：调用 useCreateFeedsClient（连接期间返回 undefined），在应用根附近挂载一次 <StreamFeeds client={client}>，并（通常）用 OwnFeedsContextProvider 包裹以创建用户 + timeline feed 和自关注；若用户只要设置，则在产品专属 UI 前停下。
19. 轨道 M（迁移/升级）按阶段执行：M1 运行 Project signals 并读 package.json/lockfile，确定 Stream 包、from→to 版本、运行时通道、包管理器和 RN/Expo 新架构状态；M2 从产品 manifest 拉取匹配的升级指南（已知入口：Chat RN v8→v9），失败则硬门禁交给 stream-docs 并停下问用户；M2.5 先清 RN 专属阻塞（新架构要求、新原生/peer 依赖如 Chat v9 的 react-native-teleport、原生重建）；M3 只升级目标包（各自目标版本，升级通道的 Chat wrapper），应用所有文档化破坏性变更，在已安装的 node_modules/stream-chat-react-native-core 源码中核对每个符号，grep 重命名符号，做原生配置和键盘清理；M4 验证：tsc --noEmit → Metro bundle → 原生构建 → 模拟器/设备冒烟核心流程（不要 next build；tsc 通过不等于能渲染；门禁命令从绝对 cd 运行且绝不接管道，因为管道返回的是管道的退出状态）；M5 总结升级的包、应用的破坏性变更、原生/新架构变更、改动文件、手动后续，并提议（不自动运行）下一步。
20. 轨道 S（从 Sendbird 迁移）按阶段执行：S0 运行 Project signals 检测形态（Expo vs 裸 RN）、包管理器、新架构、导航，grep Sendbird 足迹，分类每个触点及每个 @sendbird 符号（已映射/未映射已知/未知），建立 parity ledger 并捕获视觉基线；S1 组装计划（形态、token 路径、设计标准、缺口），对任何 GAP 行、未解决凭据或含糊设计标准暂停并批量询问用户，否则继续；S2 在 Sendbird 旁边安装 Stream（形态正确的包 + peer；接线 GestureHandlerRootView / OverlayProvider / Reanimated Babel 插件），在碰 UI 前先通过 credentials.md 证明真实用户能连接（useCreateChatClient + tokenProvider）；S3 逐文件原地迁移触点：UI 组合（不用 <Window>；应用自有头部）、频道、消息/附件、事件（{ unsubscribe } 清理）、分页（无状态）、成员/审核、离线，删除手写机制改用响应式原语，然后移除全部三个 Sendbird 包；S4 设计对齐：把主题重写为 JS Theme 对象（不用 CSS），然后以基线为参考从 Step 1 运行 references/design-matching.md；S5 按序验证：tsc --noEmit、原生构建、零 @sendbird 导入、双用户模拟器冒烟 + 驱动每个交互（gate 4，handler 在此验证而非设计门禁）、对照 ledger 的设计验证循环、ledger 关闭、README（门禁命令从绝对 cd 运行且绝不接管道）；S6 提议数据迁移：绝不自动运行，提议服务端数据迁移（../stream/sendbird-data-migration.md），若用户只要 SDK 替换则停下。
21. 轨道 A/B/D 在写连接 Stream Chat、Video 或 Feeds 的代码前，每条会话用一次 credentials.md 解析：Stream API key、用户 id 和显示名、用户 token 或 token provider 方案、可选演示数据（仅在请求时通过 Stream CLI 调用：Chat 用 UpdateUsers、GetOrCreateChannel、SendMessage；Video 和 Feeds 不需要种子数据）；轨道 A 若必须先解析运行时或目标目录，可先搭建应用，但在凭据或 token provider 方案解决前不要渲染已连接的 Chat/Video/Feeds UI。
22. 每条会话读一次 RULES.md，所有不可协商的 React Native Chat、Video、Feeds 规则都在那里。
23. 组合产品（同一应用两个或更多产品）只加载范围内产品的参考对，并嵌套 provider（例如 <StreamVideo> 放在 <OverlayProvider><Chat> 内，再放在 <StreamFeeds> 内），不要并列挂载；参见 RULES.md 和 manifest 选中的 /video/docs/react-native/advanced/chat-with-video.md 的 Chat + Video 互操作说明。

适用边界 · 注意事项

• 不适用于 Web React（应使用 stream-react 技能）
• 不适用于 Stream Moderation 审核 UI 或其他未捆绑的 Stream RN 产品
• 不适用于没有 React Native 或 Expo 项目且用户未要求新建应用的场景