在 Swift/iOS 项目中集成、迁移或查询…

当需要在 SwiftUI/UIKit 应用中集成、迁移到 Stream Chat/Video/Feeds，或查询其用法、复刻参考设计时，用文档编排流程实时获取官方 iOS 文档并应用。

适用场景

解决思路

1. 每个会话先读一次 RULES.md，了解不可协商的规则和 iOS 陷阱，再写任何代码。
2. 使用文档约定机制：把页面 URL 去掉末尾的 /，加上 .md，即可得到供编码代理直接读取的 Markdown 版本，始终抓取 .md 变体。
3. 用各产品的实时索引页发现或确认页面：Chat iOS SDK 用 https://getstream.io/cli/docs/chat-sdk-ios.md，Chat 低层客户端 API 用 https://getstream.io/cli/docs/chat-ios-swift.md，Video 用 https://getstream.io/cli/docs/video-ios.md，Feeds 用 https://getstream.io/cli/docs/activity-feeds-ios.md。
4. URL 必须来自 docs-map.md 或本次对话中实时抓取的索引页，不要凭记忆编造文档路径；若页面不在 map 中，抓取实时索引后从中选择。
5. Step 0 先分类请求：从用户话语中确定产品（Chat/Video/Feeds 或组合）、框架（SwiftUI/UIKit/混合，新项目默认 SwiftUI）、模式（How-to/参考、Integrate、New app、从 Sendbird 迁移、Push 设置）。
6. 若产品与框架已明确，不要追问，直接进行；若在“接入项目”和“仅解释”之间确实含糊，只问一个简短问题：要我接入项目，还是只映射文档页面和模式？
7. How-to/参考模式：直接进入文档查询，不做 setup、不需要凭据。
8. Integrate 模式：先运行 setup.md，再对具体功能做文档查询。
9. New app 模式：先运行 setup.md，再按所需界面做文档查询。
10. 从 Sendbird 迁移模式：运行 sendbird-migration.md，检测现有 Sendbird 集成形态，替换包与初始化，针对 Stream 重新实现每个触点并尽量少改应用代码，再重新应用主题，逐屏对照 Sendbird 原版验证设计与功能一致性；完成后询问是否也迁移 Sendbird 数据，若是则交给 ../stream/sendbird-data-migration.md（§10）。
11. Push 设置模式：运行 push.md，用 CLI 创建 Stream push provider，并接入客户端能力与代码。
12. 样式深度标志（与模式正交）：若请求带有目标外观（截图、Figma 链接或“做成像 WhatsApp/iMessage/Telegram/Slack 那样”），在文档查询前逐区域复刻。
13. Chat 的样式请求先做策略决策（组件 vs 自定义）：若选组件，运行 design-matching.md；若选自定义（直播/覆盖层/定制），运行 custom-ui.md，两者同样逐区域严格。
14. 复刻参考设计时，先把设计拆成区域清单（header、composer 按钮、时间戳与已读回执位置、气泡形状/尾巴、日期分隔符、附件等），记录每个区域的尺寸而非仅颜色。
15. 把每个区域路由到三条轴之一：主题 token（Appearance）、Styles 修饰符（factory.styles，用于 padding/insets/圆角/chrome）、ViewFactory 槽位（结构）；把 padding 路由到主题、把结构路由到颜色是核心失败。
16. 注意陷阱：覆盖复合槽位（makeMessageItemView、header、composer、makeComposerInputTrailingView）会静默丢弃默认渲染的子功能（头像、分组、反应、回复、状态、发送/语音/编辑/慢速模式按钮），除非读默认的 body 并复现它们。
17. 注意陷阱：channel header 修饰符作用于 composer 上方的分隔线，用 safeAreaInset/VStack 渲染的 header 会落到底部，应使用 .toolbar 放置，且不要为单个 channel 在应用根节点伪造 header。
18. 注意陷阱：composer 的发送/语音按钮位于输入框内部（makeComposerInputTrailingView），把按钮移到输入框右侧需要重新布局，而不只是 makeTrailingComposerView。
19. 注意陷阱：气泡/拼贴的 padding 属于 Styles（makeMessageAttachmentsViewModifier），不是主题。
20. 匹配未完成前必须构建、运行、灌入能触发每个区域的数据，在真实导航路径上逐区域对照参考并迭代（design-matching.md Step 5），回退任何临时验证脚手架；UI 必须尽可能接近参考，而非近似。
21. 实现每个区域包括 composer，绝不交付部分匹配并把其余标为“已知外观差距”；停留在 SDK 默认的区域是 FAIL 而非脚注。
22. 分批工作以保持速度：一次性固定 SDK 版本与 checkout，一次读完所需源码，实现所有区域，然后在持久化的 -derivedDataPath 上针对一个固定模拟器构建一次，不要每次小改动都重建并截图。
23. Chat 先选 UI 策略（写代码前）：默认用预构建 UI 组件（StreamChatSwiftUI/StreamChatUI），适用于 messenger 类（气泡、频道列表→会话、每条消息头像/时间戳/回执/反应/附件），通过主题 + ViewFactory + Styles 定制。
24. 仅当设计不是 messenger（无气泡的作者内联流、视频覆盖层/滚动条、高流量临时直播聊天、直播购物，每条消息渲染一致、外围定制 chrome）时，才选自定义 UI：直接在 StreamChat（可选 StreamChatCommonUI）上用 SwiftUI 构建，不用 StreamChatSwiftUI。
25. 强烈倾向组件：判断标准是“若主题 + 几个 ViewFactory 槽位 + Styles 能达到，就是组件任务”，即使像 WhatsApp 这样的强改皮；仅当匹配设计意味着同时替换消息行、composer、header 和列表时才选自定义。
26. 不确定时先构建组件版本，它更快确认或否决；完整信号评分与判断标准见 custom-ui.md Step 0。
27. Workplace/Slack 风格混合也是组件任务，通常是 Liquid Glass：消息行扁平左对齐（头像顶部圆角方块、作者·自定义状态·时间戳头行、正文、底部反应胶囊、线程回复摘要），无收发气泡区分，通过覆盖 makeMessageItemView 复现（复合槽位，需复现其子功能）。
28. Workplace 的 header 与 chrome 通常自定义且玻璃质感，推荐 SDK 现成的 Liquid Glass 外观（factory.styles = LiquidGlassStyles()，Styles 轴基线，适用于 iOS 26+/Swift 6.2+）；workplace 应用线程优先，需接入线程回复槽位与线程列表。
29. 策略同时决定频道类型与权限模型（如社交/市场的 messaging 成员门控 vs 直播的 livestream 公开 + 匿名观众），见 RULES.md 的 Permissions，两个轴一起决定。
30. 若确实不清楚，问一个问题：这个聊天看起来像标准 messenger（频道列表 + 气泡），还是像直播/覆盖层聊天这样的定制界面？这决定是定制预构建组件还是在低层客户端上构建自定义 UI。
31. Step 1 文档查询（每个请求都以此结束）：打开 docs-map.md，找到匹配产品 + 框架 + 功能的那一行，得到确切的 .md URL。
32. 若功能不在 map 中，抓取该产品的实时索引并选最匹配的页面。
33. 用 WebFetch 抓取 .md 页面，每个请求最多抓 3 页；若需要更多，把索引 URL 交给用户。
34. 把页面指导应用到用户项目：尽量逐字使用其代码，仅按现有应用形态（生命周期、导航、包管理器）适配。
35. 引用所用页面：Source: [Title](https://getstream.io/...)。绝不凭训练数据回答 SDK 细节——若本次对话未抓取，现在就抓或说明找不到。
36. 若文档未完全覆盖（特定 UI 定制、确切的 ViewFactory 签名、未文档化选项、真实接线），升级到 SDK 源码 + 示例应用（见 docs-map.md 的 When the docs fall short）；源码是最终真相，读项目实际固定的版本，并说明来源而非当作已文档化。
37. 匹配参考设计时，升级到源码是常态：约 100 个 ViewFactory 槽位大多未文档化，读 ViewFactory.swift（每个槽位）+ DefaultViewFactory.swift（各自渲染什么）+ 相关 Options/*.swift；design-matching.md 把每个区域路由到其槽位并给出 grep 命令。
38. 覆盖复合槽位时，也读它返回的默认视图（如 makeMessageItemView 的 MessageContainerView），枚举它渲染的每个子功能，以便复现而非静默丢弃。
39. 应用最佳实践：按 RULES.md 的 Mindful API usage，避免 queryChannels 滥用、渲染循环，只认证一次；扩展前先读该垂直领域的最佳实践页（如直播）。
40. Setup（仅 integrate/new app）：每个会话在功能工作前运行一次 setup.md，依次：检测项目信号（Xcode 项目/Swift 包/Podfile/空目录）；通过 Stream CLI 获取 API key + 用户 token（或用户粘贴），可选种子频道；用项目现有包管理器安装正确的 Stream 包；在应用启动时初始化一次客户端并连接用户。
41. 若完全没有 iOS 项目，不要用 CLI 脚手架创建，告诉用户先在 Xcode 创建应用再继续。

适用边界 · 注意事项

• 没有 iOS/Xcode 项目时不要用 CLI 脚手架创建项目，应先让用户在 Xcode 中创建应用。
• 不要凭记忆编造文档路径，许多看似可猜的路径实际是错的；只使用 docs-map.md 或本次对话实时索引中的 URL。
• 不要凭训练数据回答 SDK 具体细节；若本次对话未抓取文档，应现在抓取或说明找不到。