stream-unity

Stream Unity - Unity 引擎文档编排器

聊天和视频。 Unity 没有 Stream Feeds SDK（/activity-feeds/docs/unity 和 https://getstream.io/cli/docs/activity-feeds-unity.md 均返回 404）。如果用户询问 Unity 中的动态 Feed，请一开始就说明这一点，并提供替代方案（通过后端调用 REST/服务器 API，或在配套应用中使用平台 SDK），不要凭空编造 API。

这是两个独立的 SDK，几乎没有任何共用内容。 它们使用不同的仓库、安装方式、成熟度、支持的平台，文档质量也不同。没有统一的客户端，也没有共用的 AuthCredentials 类型（StreamChat.Libs.Auth.AuthCredentials 和 StreamVideo.Libs.Auth.AuthCredentials 是不同程序集中的不同类型）；连接用户到其中一个 SDK，并不会让用户同时连接到另一个。应将“给我的 Unity 通话应用添加聊天”视为两个共用 API 密钥的独立集成。

	聊天	视频
仓库	GetStream/stream-chat-unity（默认分支 develop）	GetStream/stream-video-unity（默认分支 main）
最新版本	v5.7.0（稳定版，5.x 系列）	0.11.0（pre-1.0，接口仍在变化）
安装	从 GitHub Releases 获取 .unitypackage，导入到 Assets/	通过 git URL 安装 UPM 包
入口点	StreamChatClient.CreateDefaultClient() -> IStreamChatClient	StreamVideoClient.CreateDefaultClient() -> IStreamVideoClient
命名空间	StreamChat.Core	StreamVideo.Core
平台	Unity 支持的所有平台，包括 WebGL	Android（ARM64）、iOS、Windows x64、macOS、Linux。不支持 WebGL 和 UWP
预构建 UI	无 - 提供的是示例项目，不是组件	无 - 提供的是示例项目，不是组件
文档覆盖情况	良好：几乎每个页面都包含实际的 Unity C# 代码	较少：共 22 个页面；若干已发布的功能完全没有对应文档

两个 SDK 都不提供可复用的 UI。 两者提供的都是供你导入并阅读的示例项目，而不是可直接添加的组件库。用户游戏中的每个聊天气泡、频道行、参与者磁贴和通话按钮，都需要你自行编写代码。承诺提供界面之前，请先说明这一点；构建界面时，请使用 ui.md。

此技能负责编排：根据产品、平台和功能支持情况对请求进行把关，路由到确切的文档页面，实时获取文档并加以应用，同时补充文档中没有的 Unity 专属知识（客户端隐藏的 DontDestroyOnLoad 运行器、轨道绑定要求、IL2CPP 剥离，以及决定构建是否能在设备上运行的 Player 设置）。

规则（每个会话只需阅读一次）： RULES.md - 不可妥协的规则和 Unity 陷阱。编写任何代码之前都要阅读。

---

步骤 0：编写任何代码之前，先通过三道关卡

根据用户的表述和只读探查结果，确认以下三项。每一项都可能让“这是代码”变成“这无法实现”，因此没有一项是可选的，也不能等到运行时失败后才处理。

关卡 1：产品（以及 Unity 是否支持该产品）

询问内容	答案
聊天 / 消息传递 / 游戏内文字聊天	支持。使用 Chat SDK。
视频通话 / 音频通话 / 音频房间 / 直播广播	支持。使用 Video SDK。
两者都需要	两次安装、两个客户端、两次连接调用。不要试图将它们统一起来。
动态 Feed / 时间线 / 关注关系图	没有 Unity SDK。 立即说明这一点，并提供服务器 API 方案。
内容审核队列 / 仪表板 UI	不是应用界面。内容审核在 Stream Dashboard 中进行；SDK 仅提供终端用户操作（标记、静音、封禁）。

Gate 2：Unity 版本和构建目标（Video SDK 是限制因素）

先探查，不要询问：

bash -c 'echo "=== UNITY VERSION ==="; cat ProjectSettings/ProjectVersion.txt 2>/dev/null; \
echo "=== UPM MANIFEST ==="; cat Packages/manifest.json 2>/dev/null; \
echo "=== STREAM CHAT PRESENT ==="; find . -maxdepth 5 -type d -name "StreamChat" -not -path "*/Library/*" 2>/dev/null; \
echo "=== STREAM VIDEO PRESENT ==="; grep -n "io.getstream.video" Packages/manifest.json 2>/dev/null; \
echo "=== SCRIPTING BACKEND / TARGET ==="; grep -nE "scriptingBackend|AndroidTargetArchitectures|apiCompatibilityLevel|managedStrippingLevel" ProjectSettings/ProjectSettings.asset 2>/dev/null | head -20'

情况	操作
Unity 6 / 2023.1 / 2022.3 / 2021.3 / 2020.3	两个 SDK 均受支持。
Unity 2019.4 - 2020.2，仅 Chat	Chat 支持（SDK 声明支持 2019.x）。Video 不支持——其包声明 "unity": "2020.3"，其 WebRTC 分支也相同。
Unity 2019.x - 2020.2，请求使用 Video	Video 必须停止。 立即说明：升级编辑器，或仅发布 Chat。
目标平台为 WebGL，请求使用 Video	必须停止。 Unity 的 WebRTC 包不支持 WebGL，因此 Video SDK 也不支持。Chat 支持 WebGL。可提供：在 WebGL 上使用 Chat，加上基于浏览器的 Video 客户端；或放弃 WebGL。
目标平台为 Android，请求使用 Video	仅支持 ARM64。必须禁用 ARMv7。请参阅 platforms.md。
目标平台为 UWP	不支持 Video。
目标平台为游戏主机	仅使用 Chat，并视为未经验证——SDK 声称支持游戏主机，但未提供针对各主机的说明。

Unity 6 与 Chat 搭配使用时有一个硬性版本下限：Chat v5.4.0 修复了 Unity 6000.0.x 上的 IL2CPP 构建崩溃（IL2CPP 的 vtable 构建器中出现 KeyNotFoundException）。在 Unity 6 上，Chat 版本绝不能低于 v5.4.0。

Gate 3：功能支持（在计划中明确说明不支持，不要等到编译报错）

截至 v5.7.0，Chat 客户端尚未实现以下功能。 如果请求需要其中任一功能，请在编写代码之前说明：

• 访客和匿名用户（不存在 ConnectGuestUser / 匿名连接）——这会导致常见的只读观众直播模式无法实现
• 频道归档、频道置顶（两者都是成员级字段，且没有客户端 API）
• 草稿消息、消息提醒和书签、位置共享
• 屏蔽用户（BlockUser / UnblockUser / 屏蔽用户列表）
• 按需翻译消息（频道上的自动翻译可以使用）
• 连接时设置 invisible 或自定义状态（连接后使用 MarkInvisibleAsync 可以实现）
• 每个频道的未读提及数；通过专用端点对表情回应、观看者和置顶消息进行分页
• 客户端级别的独立文件上传（频道级别的 UploadFileAsync / UploadImageAsync 可以使用）
• 投票回答（文本评论）以及查询投票结果

截至 0.11.0，Video 客户端尚未实现以下功能：

• 发布自己的屏幕共享。 你可以接收远程参与者的 ScreenShareTrack；但没有 API 可以从 Unity 开始共享。仓库 README 的功能列表提到“屏幕共享”时，指的是接收端。
• 任何来电／响铃事件。 call.ring 在内部处理，绝不会对外公开（源码中原文写着 //StreamTodo: expose CallRinging event?）。ring: true 和 AcceptAsync / RejectAsync 均存在，但被叫方没有客户端信号获知来电——你需要自行处理推送。
• 推送设备注册。 CreateDeviceAsync 仅存在于 internal API 中，底层客户端也只能通过 internal 接口访问。请从你的后端注册设备。
• 公共呼叫状态机。CallingState 是 internal；请使用 client.CallStarted / CallLeaving / CallEnded 加上 client.ActiveCall。
• Video 侧聊天集成、深度链接、画中画、降噪、转录控制以及 HLS/RTMP 观看者 UI 均没有 Unity 文档页面。GoLiveAsync / StopLiveAsync / StartHLS / StopHLS / StartRecordingAsync / StopRecordingAsync 确实已在 IStreamCall 上提供——只是没有文档，并非不存在。请阅读接口（下文第 2 级），并说明你从何处找到这些信息。

两个 SDK 的服务器端功能都必须在服务器端处理：呼叫类型、频道类型、权限和角色、webhook、推送模板和提供商、录制／转录配置、数据保留、导入。客户端绝不会持有 API 密钥。

---

文档约定与各产品的覆盖现状

每个 Stream 文档页面都有一个对应的 Markdown 版本：复制页面 URL，删除末尾的 /，再添加 .md。

https://getstream.io/chat/docs/unity/query-channels/   ->   https://getstream.io/chat/docs/unity/query-channels.md
https://getstream.io/video/docs/unity/basics/quickstart/ -> https://getstream.io/video/docs/unity/basics/quickstart.md

始终获取 .md 版本——纯净的 Markdown、原样代码，没有页面边框。以下实时索引列出了所有页面：

产品	实时索引
Chat	https://getstream.io/cli/docs/chat-unity.md
Video	https://getstream.io/cli/docs/video-unity.md

这两套文档树的问题恰好相反，因此每个产品的注意事项也不同。

Chat：代码确实存在，但并非每个 C# 代码块都是 Unity C#

Chat Unity 文档树维护得很好。53 个页面中，大约有 40 个包含真正的 Unity 代码选项卡；如果某项功能缺失，页面通常会直接说明：

// This feature is not yet available in the Unity SDK.

唯一的陷阱是代码围栏标签，而且很容易忽略，因为两者都写着 C#。 这些页面混用了两个不同的 SDK：

围栏	对应的 SDK	能用吗？
```csharp label="Unity"	Unity 客户端 SDK	可以。 原样复制。
```csharp label="C#"	.NET 服务端 SDK（using GetStream;、new StreamClient(apiKey, apiSecret)、chat.SendMessageAsync(...)）	不可以。 它需要 API 密钥，无法在已发布的游戏中运行。

label="C#" 代码片段只是碰巧具有 IStreamChannel 的形状：chat.SendMessageAsync("channel-type", "channel-id", request) 看起来与 channel.SendNewMessageAsync(request) 足够相似，很容易误贴进去，随后有人会试图通过“将 API 密钥添加到客户端”来修复，而这恰恰是错误的。完全使用服务端 C# 的页面（archiving-channels、pinning-channels、location-sharing）记录的是 Unity SDK 根本不具备的功能——参见 Gate 3。混合使用两者的页面（send-message、query-channels、channel-members、moderation、message-delivery-and-read-status）则确实提供了 Unity 用法；请使用 label="Unity" 代码块，并忽略其余内容。

message-delivery-and-read-status 是最典型的例子：已读状态已完整实现（channel.MarkChannelReadAsync、channel.Read、channel.MarkChannelAsUnreadAsync、message.MarkMessageAsLastReadAsync），但页面完全没有 Unity 代码块。请从接口获取 API，而不是参考页面中的服务端 C# 代码。

获取 Chat 文档前，还需了解两点：

• CLI 索引并不完整。 另外 15 个路径可以在 /chat/docs/unity/ 下访问，但它们会 301 重定向到平台或 Node 文档（push-devices -> /docs/platform/push-devices/、chat-permission-policies -> /chat/docs/node/...、update-users -> /docs/platform/users/），而对应的 /chat/docs/unity/<page>.md 页面会返回 404。请改为获取重定向目标的 .md 版本，并且不要期待那里有 Unity 代码。docs-map.md 列出了这些页面及其真实 URL。
• 文档中的示例项目链接已失效。 介绍页面链接到 github.com/GetStream/stream-chat-unity/tree/main/...，但仓库中没有 main 分支。请使用 develop（或版本标签）。

Video：代码可信，文档树只是规模较小

Video Unity 的 22 个页面全部以 Unity 为先，使用 C#——没有混入服务端 SDK，也没有 JavaScript。问题在于内容缺失：没有页面介绍如何开播、使用 backstage、HLS、RTMP、录制控制、呼叫流程或接收屏幕共享，尽管其中大多数功能都已在 IStreamCall 上提供。Video 请求找不到对应页面时，这是正常的——请转到第 2 层并查阅接口。

事实来源优先级

按顺序查找。遇到第一个能回答问题的来源时就停止，并注明你使用的是哪一级来源。

级别	来源	用途
1	页面中的 label="Unity" 区块（Chat），或页面的 C#（Video）——docs-map.md 标明了哪些页面包含此类内容	涵盖的所有内容。逐字复制。
2	项目中的 SDK 源码——Assets/.../StreamChat/Core/** 和 Library/PackageCache/io.getstream.video*/Runtime/Core/**；否则查阅 raw.githubusercontent.com/GetStream/<repo>/<tag>/...	精确的签名、默认值、可空性，以及哪些内容是 public、哪些是 internal。这是最终权威来源。
3	随附文档中的代码示例——Chat：Assets/Plugins/StreamChat/Samples/*.cs；Video：Packages/StreamVideo/DocsCodeSamples/**	文档页面中代码片段的可编译版本。通常比页面更清晰。
4	示例项目——Chat：Assets/Plugins/StreamChat/SampleProject/；Video：Packages/StreamVideo/Samples~/VideoChat/	真实的端到端接线方式，包括消息列表复用和参与者视图生成。
5	变更日志——Chat：Assets/Plugins/StreamChat/Changelog.txt；Video：CHANGELOG.md	从未写入文档的行为和配置（参见 RULES.md）。内容比发布说明更丰富。

请查阅项目实际引入的版本——Chat 已复制到 Assets/，Video 已解析到 Library/PackageCache/，因此两者都已在磁盘上。优先使用它们，不要使用 GitHub 上的 develop/main。

**URL 溯源：**只获取从 docs-map.md 或本次对话中的实时索引请求中得到的页面 URL。不要凭记忆编造文档路径。

---

步骤 1：对请求分类

通过各项检查后，选择模式：

• 操作指南 / 参考（“如何查询频道？”、“SetIncomingVideoEnabled 有什么作用？”）-> 直接进入文档查找。无需设置，无需凭据。
• 集成（“在我的游戏中添加聊天”、“在这个项目中加入视频通话”）-> 运行 setup.md，然后按功能进行文档查找。
• 新建项目（“帮我构建一个 Unity 聊天应用”）-> 运行 setup.md，然后按请求的屏幕范围进行文档查找。如果没有 Unity 项目（缺少 ProjectSettings/ProjectVersion.txt），请告知用户先在 Unity Hub 中创建项目——不要尝试手动拼凑 Unity 项目目录结构。
• UI 工作（“显示频道列表”、“渲染参与者”、“设置消息气泡样式”、“添加通话控制项”）-> 运行 ui.md。两个 SDK 都不包含组件，因此这些代码需要你编写；操作指南中包含预制件/复用模式、轨道绑定约定，以及没有轨道时的本地预览路径。
• 构建 / 发布 / 在设备上运行（“为 Android 构建”、“为什么我的手机上没有视频？”、“IL2CPP 构建崩溃”、“打包 iOS”）-> 运行 platforms.md。其中的 Player 设置至关重要，并非锦上添花：没有这些设置，Android Video 构建将无法正常使用 WebRTC，iOS 构建将无法获得摄像头权限，而 IL2CPP 构建可能会裁剪 SDK 的序列化类型。
• 升级 / 迁移版本（“将 Chat 升级到 5.7”、“我们在用 4.x”）-> Chat 从 4.x 升级到 5.x 需要进行从枚举到结构体的迁移；请从 docs-map.md 中读取 migration-guide-to-5x.md。Video 没有迁移指南——请阅读两个版本之间的 CHANGELOG.md，并明确说明预发布 1.0 的 SDK 可能会在次要版本之间破坏 API。

---

第 2 步：查阅文档（每个请求都到此为止）

1. 打开 docs-map.md。找到对应功能的行；其中列出了准确的 .md URL 以及该页面包含的代码类型。
2. 如果映射表中没有该功能，请获取该产品的实时索引，并从中选择。
3. 使用 WebFetch 获取 .md 页面。每个请求最多获取 3 个；超过此数量时，请将索引 URL 提供给用户。
4. 原样使用 Unity 代码，仅根据项目的 MonoBehaviour 和场景结构进行调整。如果页面没有 Unity 代码块，则降至第 2 级并阅读接口。
5. 注明所用来源： Source: [Title](https://getstream.io/...)，或者对于读取的源码，使用 Source: Assets/Plugins/StreamChat/Core/StatefulModels/IStreamChannel.cs。绝不要根据训练数据回答 SDK 细节——如果本次对话中没有阅读相关内容，就现在阅读，否则说明未能找到。
6. 遵循最佳实践——调用一次 QueryChannelsAsync，之后让 WebSocket 保持状态更新；仅为实际显示在屏幕上的参与者订阅视频；只连接一次。参见 RULES.md 中的 “Mindful API usage”。

---

此技能包含的内容

官方文档在提供 Unity 代码的部分，对底层客户端有很好的介绍，因此此技能不会重复这些内容。整理收录的非文档内容如下：

文件	内容
RULES.md	不容妥协的规则，以及会静默失败的 Unity 陷阱。所有规则均只在此处说明一次。
setup.md	两个 SDK 的固定版本安装方式（.unitypackage 和 UPM manifest）、CLI 凭据，以及经过验证、生命周期正确的最精简客户端配置。
ui.md	自行构建 UI——没有现成组件。包括 UGUI 中的聊天列表和消息输入框、参与者视图、轨道绑定约定、自我预览及订阅管理。
platforms.md	各目标平台的播放器设置、IL2CPP 和托管代码裁剪、Newtonsoft 冲突、WebGL、Android/iOS/桌面平台，以及推送功能的作用与限制。
docs-map.md	两款产品的意图到准确文档页面的映射，标注每个页面包含的代码类型，并提供源码备用方案。

---

支持

如果用户询问支持或如何联系他人，请引导他们访问 getstream.io/contact。SDK 缺陷和功能请求请提交至仓库问题页：Chat、Video。