stream-unreal

Stream Unreal - Unreal Engine 文档编排器

仅支持聊天。 Unreal 没有 Stream Video 或 Stream Feeds SDK（/video/docs/unreal 和 Feeds Unreal 索引均返回 404）。如果用户询问 Unreal 中的通话或动态，请一开始就说明这一点，并提供替代方案（在配套移动应用中使用平台 SDK，或使用 REST/服务器 API），而不要编造 API。

SDK 处于 beta 阶段。 .uplugin 中的 IsBetaVersion: true 表示这一点；不同版本间的接口可能会变化，且 C++ 与 Blueprint 对各项操作的覆盖范围不同。用户指定版本或计划升级时，务必说明这一点。

此技能负责编排：根据引擎和功能支持情况筛选请求，路由到准确的文档页面，实时获取文档并据此执行，同时提供文档未涵盖的 Unreal 特定知识（ApiKey/BeginPlay 顺序陷阱、UMG 控件层、打包，以及决定打包构建是否可用的各平台配置）。

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

---

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

根据用户的描述和只读探测结果，确定以下三项。每一项都可能将回答从“这是代码”变成“无法实现”，因此没有一项是可选的，也不能等到之后才在编译错误中发现。

Gate 1：引擎版本（选择发布资源，或停止任务）

目标引擎	操作
5.7 或 5.8	支持。下载匹配的发布资源 - 参见 setup.md 2。
4.27 / 5.0 / 5.1	只有 v1.3.0（2022 年 12 月）支持这些版本。请说明：该 API 早于 v2.0.0，且不存在 BlockUser/UnblockUser/GetBlockedUsers，本技能中的 v2 指引均不保证适用。
5.2 至 5.6	立即停止 - 没有支持这些版本的发布资源。 立即说明这一点。可选方案：将项目升级到 5.7/5.8，或针对不受支持的引擎从源码构建插件（未经验证，不推荐）。不要下载资源后抱着侥幸心理。

从 .uproject 检测版本，而不是询问：

find . -maxdepth 2 -name "*.uproject" -exec sh -c 'echo "== $1"; grep -m1 EngineAssociation "$1"' _ {} \;

每个引擎版本只有一个发布归档（StreamChat-5.7.zip、StreamChat-5.8.zip），选错会造成无提示的不匹配，而不会明确报错。先确定版本，再下载。

Gate 2：功能支持（在计划中说明不支持，而不是等到编译时报错）

截至 v2.0.0，Unreal SDK 尚未实现以下功能。如果请求需要其中任何一项，请在编写代码前说明：

• 附件和文件/图片上传
• 发送线程回复，以及线程列表
• 引用消息、提及、置顶消息
• 离线持久化和乐观发送
• 频道归档和频道置顶
• 投票、草稿消息、消息提醒、位置共享

已实现：消息（发送 / 编辑 / 获取 / 全文搜索 / 软删除，C++ 支持硬删除，C++ 支持双向分页），频道（查询 / 监听 / 创建 / 更新 / 清空 / 隐藏+显示 / 冻结 / 成员），表情回应（计分 + 强制唯一、移除，C++ 支持分页），已读状态和未读计数、输入指示器、审核（封禁、影子封禁、禁言用户、禁言频道、屏蔽和解除屏蔽用户、标记消息和用户、查询已封禁用户）、慢速模式、推送设备注册、在线状态 + 观察者 + 自身权限、实时事件和预览 UI 控件。

文档在此处与 SDK 矛盾。 Unreal 简介页面仍将“用户屏蔽”列为未实现，但 v2.0.0 中的 UStreamChatClientComponent 已包含 BlockUser、UnblockUser 和 GetBlockedUsers。以 SDK 为准。仓库 README 的功能列表才是准确信息。

第 3 关：C++ 还是 Blueprint

只有确实不明确时才询问；否则请推断（存在 Source/ 目录和 .Build.cs 文件即表示支持 C++）。

• C++ 功能最完整。支持基于回调的形式（TFunction<void(...)>）、TOptional<> 参数以及所有分页功能。
• Blueprint 通过潜在节点覆盖常见操作；对于 C++ 签名使用 TOptional 的情况，提供了带 ...BP 后缀的变体（SendMessageBP、BanUserBP、ShadowBanUserBP、MuteUserBP、BanMemberBP）。
• 分页和较底层的 API 仅支持 C++。 如果用户想要仅使用 Blueprint 集成，请预先说明哪些部分需要 C++，并提醒他们注意命名陷阱：BanUserBP(User, FTimespan, FString, bool) 接受必填参数，而 BanUser(User, TOptional<FTimespan>, TOptional<FString>, bool) 接受可选参数。零值 FTimespan 表示“无限期”，而不是“已过期”。

---

文档约定——以及这里至关重要的覆盖范围注意事项

Stream 的每个文档页面都有对应的 Markdown 版本：取页面 URL，去掉末尾的 /，再加上 .md。

https://getstream.io/chat/docs/unreal/query-channels/   ->   https://getstream.io/chat/docs/unreal/query-channels.md

始终获取 .md 版本——它是干净的 Markdown，代码原样保留，也没有页面装饰。列出所有 Unreal 页面的网站索引：https://getstream.io/cli/docs/chat-unreal.md。

现在说说注意事项，这是这套文档中最重要的一点。 /chat/docs/unreal/ 目录大部分是各 SDK 共用的说明内容。61 个页面中只有约 26 个页面带有 Unreal 代码选项卡；其余页面展示的是 JavaScript、Node、Kotlin——甚至限流页面上还有 C#/Unity 示例。有几个页面介绍的功能 Unreal SDK 完全不支持（file-uploads、threads、pinned-messages、polls-api、drafts、message-reminders、location-sharing、archiving-channels、pinning-channels），却提供了可运行的 JavaScript 示例，而且页面上没有任何警告。还有些页面介绍了 SDK 确实支持的功能，却没有 Unreal 代码（send-reaction、moderation、search、message-delivery-and-read-status、freezing-channels）。

因此：

1. 切勿将 JavaScript 代码片段翻译成 C++。 channel.sendReaction(...) 并不能告诉你 UChatChannel::SendReaction 的形式。只有 JS 的页面，适用的是页面的概念，而不是其中的代码。
2. 页面没有 Unreal 选项卡时，请改用以下事实来源优先级获取 API，并说明你使用的是哪一级来源。
3. docs-map.md 标注了每页对 Unreal 的覆盖情况。请使用它——这样可以避免白费功夫地获取页面，也能避免签名错误。

事实来源优先级

按顺序查看。找到能回答问题的第一个来源后即停止，并注明使用了哪一级来源。

级别	来源	用途
1	页面中的 Unreal 代码选项卡（docs-map.md 会标注哪些页面有此选项卡）	适用于所有涵盖的内容。原样复制。
2	插件头文件——用户项目中的 Plugins/StreamChat/Source/StreamChat*/Public/**.h，否则使用 raw.githubusercontent.com/GetStream/stream-chat-unreal/<tag>/...	获取准确的签名、默认值、UFUNCTION 元数据以及 Blueprint 可用性。这是最终依据。
3	Doxygen C++ 参考文档——https://getstream.github.io/stream-chat-unreal/	不知道头文件名称时，用于浏览类接口。
4	示例项目——仓库根目录本身就是示例：Source/StreamChatSample/、Source/DocsSamples/	查看端到端的实际接线方式。StreamChatSampleHud.cpp 用 40 行代码演示了可运行的连接、查询和显示 UI。

请阅读项目实际引入版本中的头文件（插件已复制到 Plugins/，因此就在项目中——优先使用它，而不是 GitHub 上的 main）。

URL 确认： 仅获取从 docs-map.md 或本次对话中的实时索引获取的页面 URL。不要凭记忆编造文档路径。

第 1 步：对请求分类

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

• 操作指南 / 参考（“如何查询频道？”，“EChannelFlags::Watch 有什么作用？”）-> 直接进入 查阅文档。无需设置，也无需凭据。
• 集成（“在我的游戏中添加聊天”，“将 Stream 接入此项目”）-> 运行 setup.md，然后按功能查阅文档。
• 新项目（“为我构建一个 Unreal 聊天应用”）-> 运行 setup.md，然后查阅文档，范围限定在用户要求的屏幕。如果没有 Unreal 项目，请告知用户先在 Epic 启动器 / Unreal Editor 中创建项目——不要尝试手动搭建 .uproject。
• 聊天 UI（“显示频道列表”，“把聊天放到 HUD 上”，“设置消息气泡样式”）-> 运行 widgets.md。这一层完全没有官方文档，因此操作手册就是信息来源：WBP_* 清单、按路径使用 LoadClass 的模式、先调用 Setup() 再调用 AddToViewport() 的规则、上下文祖先模型、主题设置，以及路径加载所需的打包指令。
• 打包 / 发布 / 在设备上运行（“为 iOS 构建”，“为什么我的手机上卡住了？”，“打包为 Android 应用”）-> 运行 platforms.md。其中各平台的配置至关重要，并非可有可无：缺少配置时，打包后的移动版本可能显示得难以辨认、运行几帧后冻结，或无法响应触摸。

如果用户要求聊天 UI，却没有说明要哪种，优先使用随附的 WBP_* widgets，而不是手动构建 UMG，作为首次集成方案——这些 widgets 已处理安全区域、主题设置和列表分页，而自行复现这些功能十分繁琐。

---

第 2 步：查阅文档（每个请求最终都要到这里）

1. 打开 docs-map.md。找到对应功能的行；其中会给出确切的 .md URL，以及该页面是否包含 Unreal 代码。
2. 如果功能不在映射表中，获取实时索引（https://getstream.io/cli/docs/chat-unreal.md），并从中选择。
3. 使用 WebFetch 获取 .md 页面。每个请求最多获取 3 个页面；超过此数量时，将索引 URL 提供给用户。
4. 如果页面有 Unreal 标签页，逐字使用其中的代码，仅根据项目的 actor / 生命周期结构进行调整。如果没有，则降到梯子的第 2 级并阅读头文件。
5. 注明所用资料： Source: [Title](https://getstream.io/...)，或者针对头文件使用 Source: Plugins/StreamChat/Source/StreamChat/Public/Channel/ChatChannel.h。切勿根据训练数据回答 SDK 相关细节——如果本次对话中没有阅读过相关内容，现在就去阅读，否则说明未能找到。
6. 遵循最佳实践——使用一个带筛选条件的 QueryChannels，然后调用 Watch 并接收 WebSocket 事件；不要每个 tick 都查询；只连接一次。参见 RULES.md 中的“谨慎使用 API”。

---

此技能包含的内容

官方文档在包含 Unreal 标签页的部分，对底层客户端已有充分介绍，因此此技能不再重复。整理后的非文档内容包括：

文件	内容
RULES.md	不容违反的规则，以及会导致构建失败或静默出错的 Unreal 陷阱。每条规则只在此处说明一次。
setup.md	感知引擎版本的插件安装、Build.cs 模块依赖、CLI 凭据，以及经验证的最小客户端接入方式。
widgets.md	UMG widget 层——上游没有相关文档。包含清单、按路径加载、Setup 顺序、上下文、主题设置和烹饪。
platforms.md	iOS / Android / 桌面端配置、签名，以及构建与打包的区别。包含部署和读取日志的命令。
docs-map.md	意图 -> 确切文档页面，并标注各页面对 Unreal 代码的覆盖情况，以及源代码回退方案。

---

支持

如果用户询问如何获得支持或联系他人，请引导他们访问 getstream.io/contact。SDK 缺口和功能请求请提交到仓库的 issues。