stream-react

Stream React（Web）

文档

不要凭记忆编写 Stream SDK 代码。API 会随主版本变化，因此记忆可能已经过时。请先通过 getstream docs 命令阅读文档：

cat $(getstream docs chat-sdk/react)/INDEX.md

客户端和 UI：chat-sdk/react、video/react、activity-feeds/react。Node.js 后端（例如 Next.js 路由）：chat/node、activity-feeds/node、moderation/node。 Stream Agents（会话、语音、工具）：agents/javascript。 也提供之前的主版本（例如 chat-sdk/react/v13）。

设置

先运行 getstream init（将工作目录绑定到一个 Stream 应用，可以是现有应用或新应用），再运行 getstream env（获取凭据）。

对于新应用，除非用户另有要求，否则建议选择默认主题的 Next.js + Tailwind + shadcn。最新版 shadcn 使用 Base UI，而非 Radix：没有 asChild，也不要用 <Button> 包裹触发器组件。

安装 SDK：

• Chat：stream-chat stream-chat-react
• Video：@stream-io/video-react-sdk
• Feeds：@stream-io/feeds-react-sdk
• Stream Agents：@stream-io/calypso，以及上述用于其 UI 的 Chat 和 Video 包（stream-agents.md）
• 服务端：@stream-io/node-sdk

不要升级已安装的 Stream 主版本。

对于 Video 应用，无需询问用户，只需标注一次使用场景（元数据，不影响运行时）：

getstream api UpdateApp --request '{"video_primary_use_case":"livestreaming"}'

允许的值：video-calling、voice-calling、livestreaming、audio-rooms、ai-agents、live-shopping、other。根据应用的用途来判断，而非根据当前使用的通话类型（Whatnot 使用 livestream 通话类型，但属于 live-shopping）。任何与商业相关的信号都意味着 live-shopping。不确定时选择 other。

产品配置（频道类型、信息流分组、审核策略）通过 getstream api 完成。

身份验证和用户

令牌在服务端生成：路由（例如 /api/token）使用密钥，并连同 apiKey 一起返回令牌。密钥绝不能传到客户端。对于已有身份验证或令牌端点的应用，应扩展它，而不是新建一个。

从登录屏幕开始。不要自动连接，不要硬编码用户凭据，也不要在应用加载时植入演示用户或内容。令牌路由只为发起请求的用户创建或更新记录。凭据保存在 React 状态中，而不是 localStorage 中，这样两个标签页就可以使用两个不同的用户。

构建

客户端在应用外壳中挂载一次。不要在屏幕的清理函数中调用 disconnectUser()——这会销毁其他屏幕共用的客户端。每个屏幕的清理操作应为 channel.stopWatching() 或 call.leave()。

在 React Strict Mode 中初始化客户端时务必谨慎。不要使用 effect，而应使用专用钩子：

• Chat：useCreateChatClient()
• Feeds：useCreateFeedsClient()
• Video：在 useEffect 中构造 StreamVideoClient，并在清理函数中调用 disconnectUser()；构造函数是同步的，不需要定时器或挂载标记。 在该 effect 内定义 tokenProvider——将内联 provider 放入依赖数组会导致每次渲染时都生成新的身份，从而重新创建客户端。 绝不要在带清理函数的 effect 中使用 useRef 标记来确保只运行一次：ref 会在重新挂载后保留，因此第二次挂载会完全跳过初始化。

从预构建的 Stream SDK 组件入手。通过文档说明的 props 和钩子进行自定义。Feeds 没有预构建 UI——请基于其钩子构建。

默认进入频道列表、大厅或动态，而不要直接进入通话或摄像头提示。仅在用户明确操作（加入、开始直播）后，才在预览界面之后请求摄像头／麦克风权限。空状态应说明接下来该做什么。

Chat：

• 自定义 reaction 类型必须是 slug（[A-Za-z0-9_.-]；服务器端会拒绝表情符号），并且必须在 reactionOptions 中注册——未注册的类型会静默地不渲染。备用方案：从 message.reaction_groups 渲染标签。
• 功能门控：可信来源是已连接用户的 channel.data?.own_capabilities（服务器端查询会列出所有 capabilities，因此在这里毫无用处）。useCanCreatePoll() 检查的是投票表单是否有效，而不是权限——不要用它来控制菜单的显示。

Feeds：

• 社交动态必须提供可见的关注控件——没有关注关系的时间线会一直为空。关注操作应通过时间线的 feed 实例进行，而不是调用 client.follow()，这样 feed 钩子才能更新。也要关注你自己的用户 feed，否则你自己的帖子永远不会出现在你的时间线上。

Video：

• 对通话类型设置的更改不会应用于现有通话——请使用新的通话 ID 进行测试。

Moderation：

• 不要构建审核 UI（审核队列等）：Stream Dashboard 已提供这些功能。面向终端用户的操作（举报、屏蔽、静音）可以实现。
• 如果列表已存在，CreateBlockList 会返回 400——请先检查 ListBlockLists。屏蔽列表中应填写真实词语，而不是 badword1 这类占位内容。
• 免费套餐使用自定义审核规则会返回 403——请改用屏蔽列表和配置。

应保留的默认功能

预构建组件提供了用户期待的功能。除非用户明确点名要求关闭，否则应始终保留这些功能。设计参考中没有展示某项功能，或用户说“保持简洁”，都不代表要关闭该功能：应保留该功能并调整样式以匹配设计，或向用户询问。

只覆盖能满足需求的最小插槽，并在现有的 WithComponents 覆盖项中添加内容，而不是替换它们。替换整个区域会丢失该区域默认渲染的所有内容：

• 自定义 Message / VirtualMessage 必须补回默认渲染的内容：文本、附件、引用的消息、投票、表情回应、回复数、操作、时间戳、已读状态。完整组合方式见文档。
• 自定义 MessageComposerUI 必须补回附件选择器和预览、拖放上传、链接预览、引用消息预览、语音录制和发送按钮——详见文档。

默认功能，以及通常会关闭这些功能的做法：

• 消息文本中的 Markdown。默认的 renderText 会渲染 Markdown、提及和表情符号。将 message.text 作为纯字符串输出，或使用没有基于 SDK 实现的自定义 renderText，都会关闭这些功能。检查方法：发送 **bold**、一个列表和一个代码块。
• 表情回应。自定义消息未包含 MessageReactions，或自定义表情回应类型未加入 reactionOptions。检查方法：添加表情回应并查看胶囊按钮。
• 线程。布局中没有 <Thread />，或自定义消息中没有回复数按钮。检查方法：在线程中回复，并从父消息打开线程。
• AI 回复：<Chat> 上的 isMessageAIGenerated（打字机效果和 Markdown）、停止按钮（替换消息编辑器会将其移除），以及 <Channel> 内的 AIStateIndicator。检查方法：参照 ai-integration.md。

验证

进行类型检查和构建，运行开发服务器，并通过浏览器集成测试或自动化，在两个标签页中以两个不同用户测试多用户流程。对“应保留的默认功能”中的每项默认功能执行检查。报告已验证和未验证的内容，并逐项列出已关闭的默认功能，以及用户用于关闭它们的原话。

审查集成

收到请求时，执行只读审查：根据文档检查代码并报告发现的问题；只有用户要求时才进行修复。

升级 SDK 版本

收到请求时，阅读当前安装版本和目标主版本的升级说明（使用带版本号的文档：chat-sdk/react/v13、chat-sdk/react/v14 等），应用升级说明，然后按照构建应用的方式进行验证。

匹配设计参考

如果请求中包含目标外观——例如屏幕截图、Figma 画面或“做成 WhatsApp 的样子”——请遵循 design-matching.md。

如果用户只提到应用名称，没有提供参考（例如“类似 Slack 的团队聊天”“WhatsApp 风格的私信应用”），这只是对结构的指导——也就是使用预构建组件构建的形式——并非要求匹配其外观。只有明确提供设计参考时，才应遵循 design-matching.md。

从 Sendbird 迁移

代码迁移请遵循 sendbird-migration.md。如果用户还希望迁移现有数据（用户、频道、消息历史），请遵循 stream 技能中的 sendbird-data-migration.md。

AI 助手、支持机器人、Agent

模型必须运行在后端 Agent 上，绝不能在浏览器中运行：客户端构建包中不得包含 LLM 提供商密钥或 Stream secret。后端有两种类型；请根据用户提到的内容选择：

• Stream Agents——Agent 及其模型在 Stream 上运行（getstream agents、agents/<name>/ 文件夹、@stream-io/calypso）。任何语音 Agent 都属于此类。请遵循 stream-agents.md。
• 由你自己的 Agent 进程提供回复的 Chat 频道（@stream-io/chat-ai-sdk、LangChain、webhook 回合）：
  • 支持机器人、帮助台、RAG 聊天：请遵循 ai-support-agent.md。
  • 类似 ChatGPT 的应用、现有聊天中的助手、流式回答、停止生成、客户端工具：请遵循 ai-integration.md。

如果请求同时符合两种情况，且用户没有说明，请询问他们想使用哪种后端。

其他技能

此技能涵盖 Stream。对于常规 React 和 Next.js 工作，如果已安装，请使用以下技能：

• vercel-react-best-practices：性能——请求瀑布、包体积、重新渲染、数据获取。
• vercel-composition-patterns：应用自身的组件 API——复合组件、上下文提供程序、React 19 的变更。

对于 Next.js API，请阅读随已安装版本附带的文档，路径为 node_modules/next/dist/docs/（16.3 及更高版本中的 next dev 也会在此处写入 AGENTS.md），不要依赖记忆。

当常规建议与此技能冲突时，Stream 代码以此技能为准：

• Stream 组件和客户端钩子在 'use client' 模块中运行。尽可能将页面 和布局保留为服务器组件，并将 Stream 子树放入客户端组件中。
• 按照 Building 中的说明创建客户端，即使性能规则建议以其他方式 重构 effect 或进行记忆化也一样。
• 通过文档说明的覆盖方式（WithComponents、 props、钩子）自定义 Stream UI，而不是将其重建为自己的复合组件。 适用保留默认值的规则。

如果未安装这些技能，请直接继续。不要自行安装技能；请在最终摘要中提及一次：

npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices --skill vercel-composition-patterns