stream-swift

Stream Swift - iOS 文档编排器

这项技能有意保持精简。它不会打包 SDK 参考文档——官方 iOS 文档才是准确信息来源，涵盖全部功能（Chat、Video、Feeds；SwiftUI 和 UIKit；投票、草稿、语音、AI、推送、屏幕共享、CallKit、SIP、转录、审核等）。

你的工作是编排：对请求分类，指向确切的文档页面，实时获取文档，并在用户的项目中应用文档内容，同时遵守文档中没有明确强调的精选规则和注意事项。

规则（每个会话只需阅读一次）： RULES.md - 不容违反的规则 + iOS 注意事项。编写任何代码之前都要阅读。

---

文档约定（核心机制）

每个 Stream 文档页面都有一个 Markdown 版本，可供编码 Agent 直接阅读：取页面 URL，去掉末尾的 /，再添加 .md。

https://getstream.io/chat/docs/sdk/ios/basics/integration/   ->   https://getstream.io/chat/docs/sdk/ios/basics/integration.md

始终获取 .md 版本——它是整洁的 Markdown，包含原样代码，不含页面装饰元素。

每个产品的索引页面都列出了所有文档页面及其 .md URL。获取这些索引以查找或确认页面：

产品	在线索引（始终为最新）	页面 URL 格式
Chat（iOS SDK：UI + 状态层）	https://getstream.io/cli/docs/chat-sdk-ios.md	https://getstream.io/chat/docs/sdk/ios/...md
Chat（低级客户端 API 参考）	https://getstream.io/cli/docs/chat-ios-swift.md	https://getstream.io/chat/docs/ios-swift/...md
Video	https://getstream.io/cli/docs/video-ios.md	https://getstream.io/video/docs/ios/...md
Feeds	https://getstream.io/cli/docs/activity-feeds-ios.md	https://getstream.io/activity-feeds/docs/ios/...md

URL 溯源： 只能获取通过 docs-map.md 或本次对话中实时获取的索引得到的页面 URL。不要凭记忆编造文档路径——很多看似合理的路径都是错的。如果页面不在映射文件中，请获取在线索引并从中选择。

---

步骤 0：对请求分类（始终首先执行）

仅根据用户的描述，确定以下三项：

1. 产品 - 聊天、视频、动态，或这些功能的组合。
2. 框架 - SwiftUI、UIKit，或混合使用（用户刚开始且未说明时，默认使用 SwiftUI）。
3. 模式 - 以下之一：
   • 操作指南 / 参考（“如何添加表情回应？”、“CallViewModel 有什么作用？”、“主题设置”）-> 直接进行 文档查找。无需设置，也无需凭据。
   • 集成（“将 Chat 添加到我的应用中”、“将 Video 接入此项目”）-> 运行 设置（setup.md），然后查找该功能的文档。
   • 新应用（“构建一个直播应用”、“新的 SwiftUI 聊天应用”）-> 运行 设置，然后查找与所请求屏幕相关的文档。
   • 从 Sendbird 迁移（“将我的应用从 Sendbird 迁移到 Stream”、“用 Stream 替换 Sendbird Chat SDK”、“我们要停用 Sendbird / SendbirdUIKit / SendbirdSwiftUI”）-> 运行 sendbird-migration.md：检测现有 Sendbird 集成方式，替换软件包并初始化；针对 Stream 重新实现每个接入点，同时尽可能少地修改应用代码；然后重新应用主题设置，并按屏幕对照 Sendbird 原版验证 设计和功能的保真度。它沿用设置流程中的 CLI 凭据流程（setup.md）以及 design-matching.md 中逐区域严谨比对的方法。该运行手册涵盖 代码 / SDK 迁移；完成并验证后，它会询问是否也要迁移 Sendbird 数据（用户、频道、消息历史记录、表情回应），如果需要，则交由通用语言无关的数据迁移运行手册 ../stream/sendbird-data-migration.md（§10）处理。
   • AI 助手 / LLM / Agent（“构建一个类似 ChatGPT 的应用”、“添加 AI 助手 / 支持机器人 / 副驾驶”、“流式传输 LLM 响应”、“思考指示器”、“停止生成”、“渲染模型返回的 Markdown”、“显示 Agent 的推理 / 工具调用”、“在 Agent 执行操作前征求确认”、“让 Agent 调用设备上的工具”、MCP、“显示语音 Agent 的转录文本”、“显示与语音 Agent 对话内容的聊天视图”）-> 运行 ai-integration.md：首先确定要使用哪个 StreamChatAI（5.13.0 起，stream-chat-swift 的一部分——建议更新版本；独立的 stream-chat-swift-ai 软件包可作为备选方案）；然后判定应用的类型（AI 优先的应用、现有即时通信应用中的机器人、展示执行步骤并在操作前征求确认的 Agent、设备端工具，或语音 Agent 的转录文本）；将模型保留在后端 Agent 中（绝不在应用中存放 LLM 密钥）；并通过主要方式 AIConversationView 展示对话，同时接入其他 StreamChatAI 组件（AIComposerView、AIMessagePartsView、AIToolApprovalView、AIClientToolRunner、SuggestionsView）。另一种方案是使用预构建的 StreamChatSwiftUI 消息列表并接入这些组件，适用于需要即时通信功能的对话，或现有即时通信应用中的助手。在 Video 通话中的语音 Agent，如果应用要将其转录文本显示为聊天，也属于此类（类型 E）：当一人和一个 Agent 对话时，使用 AIConversationView（5.15.0）渲染转录文本，而不是手动构建气泡列表。对于集成 / 新应用，先运行设置。仅询问某个 AI 组件的操作指南则转到 文档查找（docs-map.md“Chat - AI 集成”）。
   • 推送设置（“为聊天添加推送通知”、“来电时响铃应唤醒应用”、VoIP、CallKit）-> 运行 push.md：通过 CLI 创建 Stream 推送提供程序，并接入客户端功能和代码。使用与设置相同的 Stream CLI。 还有一个与上述模式正交的 styling-depth 标志：如果请求中包含 目标外观——附带的截图、Figma 链接，或“把它做得像 WhatsApp / iMessage / Telegram / Slack / ”——那么在查阅 Docs 之前，先按区域逐一复现。对于 Chat，先运行下面的策略决策（组件还是自定义）：如果选择组件，则运行 design-matching.md；如果选择自定义（直播／叠加层／定制方案），则改为运行 custom-ui.md——同样严格按区域复现，只是机制不同。本段其余内容针对组件情形（最常见的情况）。参考设计是一份区域清单（标题栏、输入框按钮、时间戳和已读回执的位置、气泡形状／尾部、日期分隔符、附件等），其中大多数与 Stream 的默认样式在结构上不同，而不只是颜色不同。不要只调整壁纸和气泡颜色——这是已知的失败模式。先分解每个区域（记录其尺寸，不只是颜色），然后将其归入以下三个轴之一——主题令牌（Appearance）、Styles 修饰符（factory.styles，用于内边距／内嵌边距／圆角半径／界面装饰），或 ViewFactory 插槽（结构）。把内边距归到主题设置，或把结构归到颜色，是根本性的错误。文档特别提醒了以下常见陷阱：(1) 重写复合插槽（makeMessageItemView、标题栏、输入框、makeComposerInputTrailingView）会悄然丢失默认实现中的子功能——传入消息的头像、分组、表情回应、回复、状态，或发送／语音／编辑／慢速模式按钮——除非你阅读默认实现的 body 并将其复现；(2) 频道标题栏修饰符应用在输入框上方的分隔线上，因此通过 safeAreaInset／VStack 在那里渲染的标题栏会出现在底部——应使用 .toolbar 放置方式，而且绝不要在应用根视图中为单个频道伪造标题栏；(3) 输入框的发送／语音按钮位于输入框 内部（makeComposerInputTrailingView），因此要把按钮移到输入框右侧，需要重新布局，而不只是使用 makeTrailingComposerView；(4) 气泡／拼贴布局的内边距属于 Styles（makeMessageAttachmentsViewModifier），而不是主题设置。只有完成构建和运行、植入能触发每个区域的数据、沿真实导航路径逐区域对照参考设计，并反复迭代后，才算匹配完成（design-matching.md 第 5 步）；验证用的临时脚手架应予以撤销——界面必须尽可能贴近参考设计，而不是大致相似。实现每个区域，包括输入框——绝不要交付不完整的匹配结果，再把其余部分标为“已知外观差异”；某个区域保留 SDK 默认样式就是不合格，不是脚注。并且分批工作以保持速度：一次性确认固定的 SDK 版本和检出版本，一次性阅读所需的全部源码，实现所有区域，然后使用持久化的 -derivedDataPath，针对一个固定的模拟器构建一次——不要每做一点小改动就重新构建并截图（参见 design-matching.md 中的“分批工作”）。

如果产品和框架都明确，就不要追问，直接继续。如果“接入项目”和“只做说明”之间确实存在歧义，就简短地问一个问题：

你希望我把它接入项目，还是只梳理文档页面和实现模式？

仅聊天：先选择 UI 策略（再编写任何代码）

Stream Chat 提供两个层级，选择哪一层是一个远比任何样式选择都重要的架构决策——选错了，无论哪种情况都会浪费一天。因此请慎重决定，并且默认选择预构建组件：

策略	适用的设计类型	实现方式	操作指南
预构建 UI 组件（StreamChatSwiftUI / StreamChatUI）——默认选择	即时通信应用：消息气泡，或频道列表 → 对话，或每条消息都带有头像／时间戳／回执／表情回应／附件。社交、市场平台、职场、客服、私信。“让它看起来像 WhatsApp / iMessage / Telegram / Slack。”	通过主题设置 + ViewFactory + Styles 自定义	design-matching.md
在低级客户端 + 状态层上构建自定义 UI——例外情况	非即时通信应用：没有气泡、作者信息内嵌的平面信息流、视频上的叠加聊天／滚动字幕、高流量的临时直播聊天（Twitch / YouTube / Kalshi）、直播购物。所有消息的渲染方式都相同；应用界面采用专门设计的样式。	直接基于 StreamChat 构建 SwiftUI（可选使用 StreamChatCommonUI）；不使用 StreamChatSwiftUI	custom-ui.md

优先选择组件。 这些组件本来就是为自定义而设计的，判断标准是：如果通过主题设置 + 几个 ViewFactory 插槽 + Styles 就能实现，那么这就是组件的适用场景——即使是 WhatsApp 这样的深度换肤也一样。只有当匹配设计意味着要同时替换消息行、输入框、标题栏和列表时，才选择自定义 UI——也就是说，你只会把 SDK 当作数据源，而不会使用它的任何视图。过度选择自定义 UI（手动重建出更差的即时通信应用，失去头像／分组／表情回应／话题串／附件／正在输入状态／回执／选择器）是最常见、代价最高的错误；过度选择组件则只会花几个小时处理布局问题。不确定时，先构建组件版本——确认是否适用或排除它都更快。完整的判断标准和测试方法见 custom-ui.md 第 0 步。

职场／Slack 风格的混合界面也适合使用组件——而且通常应该采用 Liquid Glass。 Slack / Teams / Discord 界面由频道列表 + 消息列表 + 输入框构成，因此仍应使用预构建组件；不过它有两点不同于即时通信应用，需要匹配，而不是搁置不管：（1）消息行采用平面、左对齐布局（头像位于顶部的圆角方形，作者·自定义状态·时间戳标题行、正文、底部表情回应标签以及话题串回复摘要），没有接收／发送消息的气泡区分——可通过重写 makeMessageItemView（复合插槽——需复现其子功能）来实现；（2）标题栏和界面装饰是自定义的，通常带有玻璃质感——建议使用 SDK 提供的现成 Liquid Glass 外观（factory.styles = LiquidGlassStyles()，适用于半透明／悬浮输入框设计的 Styles 轴基准样式；可在 iOS 26+ / Swift 6.2+ 上渲染）。职场应用也以话题串为先，因此应接入话题串回复插槽和话题串列表。完整的应用类型说明和 Liquid Glass 实现方式见 design-matching.md。

该策略还决定了频道类型和权限模型（例如，面向社交／市场平台的成员限制型 messaging，与面向公开用户及匿名观众的 livestream）——参见 RULES.md 中的“Permissions”。请同时确定这两个维度。

如果确实无法判断，只需问一个问题：

这个聊天界面看起来像标准即时通信应用（频道列表 + 气泡），还是像直播／叠加聊天这样的定制界面？这决定了我们是自定义预构建组件，还是基于低级客户端构建自定义 UI。

---

第 1 步：查找文档（每个请求都以此结束）

1. 打开 docs-map.md。查找与产品 + 框架 + 功能匹配的行，即可找到准确的 .md URL。
2. 如果地图中没有该功能，获取产品的实时索引（见上表），并选择最匹配的页面。
3. 使用 WebFetch 获取 .md 页面。每个请求最多获取 3 个页面；如果还需要更多页面，请将索引 URL 提供给用户。
4. 将页面中的指导应用到用户的项目中：尽可能原样使用其中的代码，只做必要调整以适配现有应用结构（生命周期、导航、包管理器）。
5. 引用所用页面：Source: [Title](https://getstream.io/...)。绝不要根据训练数据回答 SDK 相关细节——如果本次对话中尚未获取该页面，就现在获取；否则说明无法找到。
6. 如果文档未完整涵盖相关内容——例如特定的 UI 自定义、准确的 ViewFactory 签名、未记录的选项或实际接线方式——请进一步查阅 SDK 源代码和示例应用（参见 docs-map.md 中的“文档不足时”）。源代码才是最终事实依据；请查看项目实际固定的版本，并说明你在哪里找到相关内容，不要将其说成文档中已有说明。对于 匹配参考设计，通常必须进行这一步，而非例外：约 100 个 ViewFactory 插槽大多没有文档说明，因此请阅读 ViewFactory.swift（所有插槽）、DefaultViewFactory.swift（各插槽的渲染内容）以及相关的 Options/*.swift——design-matching.md 会将各个区域对应到相应插槽，并展示 grep 命令。覆盖 复合 插槽时，还要阅读它返回的默认 视图（例如 makeMessageItemView 对应的 MessageContainerView），并列出其渲染的所有子功能，以便逐一复现，而不是无意中将其遗漏。
7. 遵循最佳实践。 谨慎使用 API——遵循 RULES.md 中的“谨慎使用 API”，避免频繁调用 queryChannels、渲染循环和重复身份验证；在扩大规模前，还要阅读对应垂直领域的最佳实践页面（例如直播）。

---

设置（仅限集成 / 新应用）

在集成或新应用模式下，请在开始功能开发前，每个会话运行一次 setup.md。该文档按顺序涵盖：

1. 项目信息 - 检测 Xcode 项目 / Swift 包 / Podfile / 空目录。
2. 凭据 - 通过 Stream CLI 获取 API key + 用户令牌（也可由用户粘贴），以及可选的种子频道。
3. 安装 - 使用项目现有的包管理器添加合适的 Stream 包。
4. 接入客户端 - 在应用启动时初始化一次，并连接用户。

然后返回此处，为特定屏幕查找文档。

如果完全没有 iOS 项目，不要通过 CLI 搭建项目——请告知用户先在 Xcode 中创建应用，然后再继续。

此技能不再包含的内容

此处已没有 references/*.md 蓝图文件。过去存放在其中的内容，现在都通过映射从实时文档中获取。这样一来，技能会自动保持最新，覆盖范围也远超旧版内置内容。唯一经过整理的非文档内容包括：RULES.md（规则和注意事项）、setup.md（由 CLI 驱动的设置流程）、push.md（关于推送 / VoIP / CallKit 的 CLI 和代码操作手册，可自动完成文档中仅有说明的操作）、ai-integration.md（AI 助手和 Agent：文档交由示例应用处理的 StreamChatAI 接线方式，以及共享后端契约 ../stream/ai-backend-contract.md）、design-matching.md（使用预构建组件复现参考设计的流程，以及区域到 ViewFactory 插槽的映射）、custom-ui.md（自定义低级路径的流程——组件与自定义实现之间的选择，以及如何在 StreamChat 客户端和 State Layer 上构建直播或定制界面），以及 sendbird-migration.md（可重复执行的 Sendbird -> Stream Chat 迁移流程——识别集成方式，替换软件包 / 初始化 / 视图 / 频道 / 消息，并按屏幕匹配源应用的设计）。中间两份内容涵盖了两种 Chat UI 策略；SKILL.md 中的决策会引导你选择相应策略。