stream-android

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

规则： 每个会话读取一次 RULES.md——所有不可妥协的规则都写在其中，其他地方没有。

此文件是 唯一入口：用于 Stream 在 Android 应用中的意图分类、本地项目检测和模块指引。

---

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

在调用任何工具之前，仅根据用户输入判断所属的 路线——先不要进行探查。

信号 -> 路线

用户输入中的信号	路线
明确的产品/框架名称：Chat Compose、Chat XML、Video Android、Video Compose、Feeds Android、Feeds Compose 等	C - 参考查询
关于 Stream Android/Compose 工作的“文档”或“documentation”	C - 参考查询
“如何在 Compose/XML/Android 中实现 {X}？”、“{SDK 类型/Composable/View/Fragment} 有什么作用？”	C - 参考查询
“为我构建一个新的 Android 应用”、“创建一个 Compose 应用”、“新的 Android 应用” + Stream 产品	A - 新应用
“将 Stream 添加到/集成到这个应用中”、“将 Chat/Video/Feeds 接入我的 Android 项目”	B - 现有应用
“安装 Stream 软件包”、“在 Android Studio 中设置 Stream”、“接入身份验证/令牌流程”，且没有更广泛的功能请求	D - 引导/设置
“构建一个类似 ChatGPT 的应用”、“添加 AI 助手/支持机器人/copilot”、“流式传输大模型响应”、“思考指示器”、“停止生成”、“向 AI 语音输入”、LangChain、Vercel AI SDK、stream-chat-android-ai-compose	A（新应用）或 B（现有应用），然后运行 ai-integration.md 执行集成；如果用户只询问某个 AI 组件的工作原理，则为 C
请求包含 目标外观——截图、Figma 画板，或“让聊天界面看起来像 WhatsApp/Telegram/Slack/某个 <app>”	B（或 A） + 以下 样式深度标记 -> design-matching.md
“从 Sendbird 迁移”、“用 Stream 替换 Sendbird Chat SDK”、“我们要停用 Sendbird/SendbirdUIKit/uikit-compose”	B + 以下 迁移标记 -> sendbird-migration.md
只有 /stream-android，没有参数	简要列出各条路线并等待

消歧流程

如果请求无法明确区分 构建/集成 和 参考查询，请提出一个简短问题并等待：

你是希望我将其接入项目，还是只介绍 Android SDK 的实现模式和相关文件？

分类后

• 路线 A、B、D -> 首先运行 步骤 0.5（凭据），然后每个会话运行一次 Project signals，再继续阅读 builder.md 和 sdk.md。不要在获取凭据之前探查项目。
• 路线 C -> 如果产品 + UI 层已明确，则跳过这两个步骤。仅当 SDK 或 UI 层不明确时，才按需运行 Project signals。

迁移标志（与轨道正交）

如果用户正在将现有应用迁出 Sendbird，请运行 sendbird-migration.md——这是一套可重复执行的 Sendbird → Stream Chat 流程，建立在 Track B 之上。它会检测集成形态（Sendbird uikit-compose / XML uikit / 基于底层 sendbird-chat SDK 的自定义 UI / 混杂代码；MVVM/MVI；单 Activity 或多 Activity；Compose-Nav 或 fragments+Jetpack-Nav），并选择三条路径之一：UIKit → Stream Compose 捆绑屏幕；自定义 UI → 保留应用的 UI，只替换 SDK/状态层（精准改造）；XML UIKit → 在现有 fragments 中托管 Stream Compose（跨框架）。它会保留应用的架构和导航，只更改 SDK 接入点。关键环节是缺口处理协议（§3.5）：对于 Sendbird 源应用中每个会因直接替换而被遗漏的屏幕（创建、设置、成员、邀请），要么接入 Stream 捆绑的对应屏幕（GroupChannelInfoScreen/DirectChannelInfoScreen），要么——对于 Stream 未捆绑的屏幕（频道创建）——告知用户该功能并非开箱即用，链接公开的 cookbook（getstream.io/chat/docs/sdk/android/compose-cookbook/<slug>/），并主动提出根据该 cookbook 构建。绝不默默遗漏屏幕，也绝不凭空编造屏幕。它会复用第 0.5 步的凭据流程（credentials.md）以及 design-matching.md 中严谨的区域匹配方法，确保每个屏幕都忠实还原；代码迁移完成构建、连接并匹配源应用后，再提供数据迁移（通用、与语言无关的操作指南）。

样式深度标志（与轨道正交）

如果请求包含目标外观——附带的截图、Figma 画板，或“让聊天界面看起来像 WhatsApp / Telegram / Slack / <app>”——请在编写 UI 代码之前运行 design-matching.md。它是在 Track A/B 工作基础上进行的（它决定如何构建用户要求的 UI），而不是取代这些工作。参考图是一个区域清单（标题栏、撰写框、时间戳和已读回执的位置、气泡形状/尾部、频道列表行、日期分隔线、附件等），其中大多数差异在结构上与 Stream 的 Compose 默认值不同，而不只是颜色不同——只设置强调色和壁纸就停止，是已知的失败模式。先将每张截图归类到对应屏幕（频道列表、消息或话题——第 0 步），再拆解每个区域，记录尺寸而不只是颜色，然后将每项差异归入两个轴之一：主题令牌（StreamDesign.Colors/Typography）或 ChatComponentFactory 插槽（结构——内边距 / 圆角半径 / 气泡形状 / 撰写框布局都在这里；Android 没有 Styles 轴，因此这些属于结构，而非主题设置）。文档会提醒你注意以下常见陷阱：覆盖复合插槽（MessageContainer、标题栏、MessageComposer）会悄悄丢失默认实现中的子功能（收到的消息头像、分组、表情回应、回复、状态、发送/语音），除非你重新实现这些功能；消息标题栏的尾随插槽默认显示频道头像（要显示操作图标，需覆盖此插槽）；与图标集相比，撰写框在行数 / 输入框形状 / 对齐方式上的差异更大；私信频道在列表中不得加上 # 前缀，也不得在标题栏中命名为“频道”。只有在完成构建、填充能触发每个区域的数据、沿真实导航路径逐区对比并反复迭代后，才算匹配完成——必须实现每个区域，包括撰写框；某个区域仍使用 SDK 默认值就是不合格，而不是可忽略的细节。

步骤 0.5：凭据、令牌和种子数据（仅适用于轨道 A、B、D）

顺序：意图分类 -> 步骤 0.5（此步骤） -> 项目信号探测 -> 轨道工作。即使下方的轨道表将“检测”列为第 1 阶段，也要在运行项目信号 shell 命令之前完成此步骤。轨道 A、B 和 D 每个会话运行一次。轨道 C 跳过。

按照 credentials.md 中的说明：

• 从控制面板（或用户处）获取 Stream API 密钥
• 通过 Stream CLI 生成用户令牌（或接受用户提供的令牌）
• 执行任何特定于产品的设置（Chat：可选地为频道添加种子数据；Feeds：确认信息流组；Video：无需设置——调用是临时的）

从 getstream env 的输出中接入 API 密钥（例如 BuildConfig.STREAM_API_KEY），并在代码片段中使用真实的用户令牌——绝不使用占位字符串。如果轨道 A/B/D 的任务进入代码编写阶段时尚未收集凭据，请先返回 credentials.md 再继续。

---

项目信号（轨道 A/B/D：每个会话运行一次；轨道 C：仅按需运行）

只读本地探测。用于检测用户是否位于 Android Studio / Gradle 项目、Kotlin 模块或空目录中。

bash -c 'echo "=== GRADLE ROOT ==="; find . -maxdepth 2 \( -name "settings.gradle.kts" -o -name "settings.gradle" -o -name "build.gradle.kts" -o -name "build.gradle" \) -print 2>/dev/null; echo "=== APP MODULES ==="; find . -maxdepth 3 -type f \( -name "build.gradle.kts" -o -name "build.gradle" \) -path "*/*/build.gradle*" -print 2>/dev/null; echo "=== VERSION CATALOG ==="; find . -maxdepth 3 -name "libs.versions.toml" -print 2>/dev/null; echo "=== MANIFESTS ==="; find . -maxdepth 4 -name "AndroidManifest.xml" -print 2>/dev/null; echo "=== EMPTY ==="; test -z "$(ls -A 2>/dev/null)" && echo "EMPTY_CWD" || echo "NON_EMPTY"'

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

根据结果给出一行状态，例如：

• 检测到 Compose 应用 - app/build.gradle.kts - 存在 libs.versions.toml - 已准备好接入 Stream
• 检测到多模块 Gradle 项目 - 保留现有模块布局
• 检测到 XML / 基于 View 的应用 - 除非用户要求迁移，否则保留当前 UI 层
• 未找到 Gradle 项目 - 用户需要先在 Android Studio 中创建应用

---

模块映射

轨道	模块
A - 新建应用	builder.md + sdk.md + 相关参考文件
B - 现有应用	builder.md + sdk.md + 相关参考文件
C - 参考查询	sdk.md + 相关参考文件
D - 引导 / 设置	builder.md + sdk.md

---

参考布局

通过 references/DOCS.md 中的 llms.txt 清单查阅实时文档——该文件是本套件未收录的指南和界面的入口。AI 操作手册（LLM 助手、流式回复、Agent）位于 ai-integration.md，基于共享后端契约 ../stream/ai-backend-contract.md。

共享的 Android/Kotlin 模式位于 sdk.md。使用预构建 Compose 组件复现参考设计的精选流程（区域 -> ChatComponentFactory 槽位映射，以及构建/验证循环）位于 design-matching.md——根据上方的样式深度标记加载，并基于适用的轨道。

产品和 UI 层的具体内容位于 references/ 下，采用扁平命名方案，可随 Stream Android 全部界面的扩展而增长：

• 参考资料： references/<PRODUCT>-<UI_LAYER>.md
• 蓝图： references/<PRODUCT>-<UI_LAYER>-blueprints.md

当前提取的模块：

• Chat + Compose： references/CHAT-COMPOSE.md + references/CHAT-COMPOSE-blueprints.md
• Chat + XML： references/CHAT-XML.md + references/CHAT-XML-blueprints.md
• Video + Compose： references/VIDEO-COMPOSE.md + references/VIDEO-COMPOSE-blueprints.md
• Feeds + Compose： references/FEEDS-COMPOSE.md + references/FEEDS-COMPOSE-blueprints.md

Feeds 没有预构建 UI 组件。 FEEDS-COMPOSE.md 介绍无头数据 SDK（FeedsClient、FeedState、ActivityState）；FEEDS-COMPOSE-blueprints.md 是由这些状态流驱动的自定义 Composable 脚手架。对于任何 Feeds 请求，都要加载这两份文件。

未来的 Android 产品内容应沿用这一命名体系，而不是创建更多顶层技能。

如果尚未收录所请求的产品/UI 层文件，请明确说明，并使用 sdk.md 中的共享 Android 模式；只有用户提出要求时，才切换到实时文档。

---

轨道 A - 新应用

完整详情： builder.md - 使用新项目路径。

阶段	名称	操作
A1	检测	在 **Step 0.5（凭据）**之后，运行 Project signals。如果还没有 Android 应用，请告知用户先在 Android Studio 中创建一个。
A2	选择路径	确认产品和 UI 层：Compose、XML/Views 或混合模式。
A3	安装与接线	按照 builder.md + sdk.md 操作，然后只加载所需的产品参考文件。
A4	验证	确认 Gradle 同步、ChatClient 生命周期、身份验证和首个渲染的屏幕。

---

轨道 B - 现有应用

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

阶段	名称	操作
B1	检测	在 **Step 0.5（凭据）**之后，运行 Project signals，并在编辑前检查现有应用结构。
B2	保留	保留当前 UI 层、依赖管理策略（版本目录或内联配置）和导航设置，除非用户要求迁移。
B3	集成	使用 sdk.md 进行共享接线，然后只加载所需的产品参考文件。
B4	验证	确认所请求的 Stream 工作流可以在现有应用中构建和渲染。

---

Track C - 参考资料查找

仅加载与所请求产品和 UI 层相关的文件。

• 通用生命周期 / 身份验证 / 状态模式 -> sdk.md
• Chat Compose 设置与注意事项 -> references/CHAT-COMPOSE.md
• Chat Compose 屏幕结构 -> references/CHAT-COMPOSE-blueprints.md
• Chat XML 设置与注意事项 -> references/CHAT-XML.md
• Chat XML 屏幕结构 -> references/CHAT-XML-blueprints.md
• Video Compose 设置与注意事项 -> references/VIDEO-COMPOSE.md
• Video Compose 通话 / 屏幕结构 -> references/VIDEO-COMPOSE-blueprints.md
• Feeds Compose SDK 模式 -> references/FEEDS-COMPOSE.md
• Feeds Compose 蓝图 -> references/FEEDS-COMPOSE-blueprints.md
• AI 助手、大模型聊天、流式回复 -> ai-integration.md
• 上述文件未涵盖的内容 -> 查阅 references/DOCS.md 中的清单；回答前先获取相应页面

如果用户询问未涵盖的产品 / UI 层组合（例如 Video XML、Feeds XML），请明确说明，而不要臆造 API 详情。

---

Track D - 初始化 / 设置

当用户更关注安装和接入步骤，而不是功能构建时使用：

• 首先运行 Step 0.5 (凭据)
• 检测项目结构
• 选择 Compose 或 XML 的所有权
• 根据项目现有的依赖管理方式（版本目录或内联）安装 Stream 软件包
• 通过 sdk.md 接入身份验证并管理 ChatClient 生命周期
• 如果用户只要求设置，则在进入特定产品 UI 之前停止