stream-react

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Stream React (web) - scaffold + enhance + audit + migrate

Stream React（Web端）- 脚手架搭建 + 功能增强 + 集成审计 + 迁移

Read first (every session): Read
RULES.md
(React/Next.js non-negotiables) and the cross-cutting
../stream/RULES.md
. Where the two files state the same rule differently (e.g. Strict mode protection, Package manager), this pack's
RULES.md
wins for React work. Glob
../stream/SKILL.md
; if empty, install with
getstream skills stream
.
CLI: CLI usage (onboarding, credentials, auth, every
getstream api
call) lives in the root skill - its "Stream CLI" section in
../stream/SKILL.md
, with CLI safety in
../stream/RULES.md
. Glob
../stream/SKILL.md
; install silently if missing (
getstream skills stream
).

This skill builds, enhances, audits, and migrates Stream Chat, Video, and Feeds in React / Next.js web apps - the default pack for all web React work. It covers five tracks:

Track A - Scaffold a new app: Steps 0-7 below. Use when the cwd is empty / new and the user said "build me a ... app".
Track E - Enhance an existing app: see
```
enhance.md
```
. Skips scaffold + theme; reuses the same SDK wiring and component blueprints.
Track F - Audit an existing integration (read-only): for "audit/review my video integration", "check my app against best practices", "is my video app production-ready?", "what am I missing before launch?". Video only: load the Integration best-practices audit section in
```
references/VIDEO.md
```
and follow its protocol - it has a Video-specific checklist + output contract. If the user asks to audit Chat or Feeds, say up front there is no dedicated best-practices checklist for those yet, then do a general docs-based review (fetch the relevant pages from
```
references/docs-map.md
```
and check the app against them) rather than applying the Video checklist. Skip onboarding, auth, the CLI, and all build steps - this track only reads the app and reports findings. Fix issues only if the user then asks.
Track M - Migrate / upgrade an SDK version: see
```
migrate.md
```
. For "upgrade stream-chat-react to v14", "migrate to the new SDK", "bump my Stream version". Docs-driven: detect the installed version, fetch the matching release guide, apply it. Never migrate from memory.
Track S - Migrate from Sendbird: see
```
sendbird-migration.md
```
. For "migrate my app from Sendbird to Stream", "replace @sendbird/uikit-react with Stream", "we're switching off Sendbird". Detects the existing Sendbird integration shape, swaps packages + init, re-implements each touchpoint (UI composition, channels, messages, events/pagination, moderation, theming) against the grounded Sendbird<->Stream mapping the file carries, then offers the separate data migration.

每次会话必读： 阅读
RULES.md
（React/Next.js 强制规则）和跨领域的
../stream/RULES.md
。若两个文件对同一规则的表述不同（如严格模式保护、包管理器），本工具包的
RULES.md
对React开发具有最高优先级。读取
../stream/SKILL.md
；若文件为空，执行
getstream skills stream
进行安装。
CLI： CLI使用说明（入门、凭据、认证、所有
getstream api
调用）位于根技能中——其“Stream CLI”部分在
../stream/SKILL.md
，CLI安全规则在
../stream/RULES.md
。读取
../stream/SKILL.md
；若文件缺失则静默安装（执行
getstream skills stream
）。

本技能用于在React/Next.js Web应用中构建、增强、审计和迁移Stream聊天、视频及动态流功能——是所有Web React开发的默认工具包。它包含五个流程分支：

分支A - 搭建新应用： 以下步骤0-7。适用于当前工作目录为空/新建，且用户提出“build me a ... app”需求的场景。
分支E - 增强现有应用： 详见
```
enhance.md
```
。跳过脚手架搭建和主题设置；复用相同的SDK连接逻辑和组件蓝图。
分支F - 审计现有集成（只读）： 适用于“audit/review my video integration”、“check my app against best practices”、“is my video app production-ready?”、“what am I missing before launch?”等需求。仅支持视频： 加载
```
references/VIDEO.md
```
中的「集成最佳实践审计」部分并遵循其流程——其中包含视频专属检查清单和输出规范。若用户要求审计聊天或动态流功能，需先告知目前暂无专门的最佳实践检查清单，然后基于文档进行常规审查（从
```
references/docs-map.md
```
获取相关页面并对照应用检查），而非套用视频检查清单。跳过入门引导、认证、CLI及所有构建步骤——此分支仅读取应用并报告发现的问题。仅在用户后续要求时才修复问题。
分支M - 迁移/升级SDK版本： 详见
```
migrate.md
```
。适用于“upgrade stream-chat-react to v14”、“migrate to the new SDK”、“bump my Stream version”等需求。基于文档执行：检测已安装版本，获取对应的升级指南并应用。绝不凭记忆进行迁移。
分支S - 从Sendbird迁移： 详见
```
sendbird-migration.md
```
。适用于“migrate my app from Sendbird to Stream”、“replace @sendbird/uikit-react with Stream”、“we're switching off Sendbird”等需求。检测现有Sendbird集成架构，替换包及初始化逻辑，对照文件中预设的Sendbird<->Stream映射重新实现每个交互点（UI组合、频道、消息、事件/分页、内容审核、主题），然后提供独立的数据迁移选项。

Flow dispatch - choose exactly one

流程调度 - 仅选择一个分支

Track A: run
```
getstream init
```
to onboard (authenticate + select/create org + app + write credentials), then continue to Start and execute Steps 0-7.
Track E: run
```
getstream init
```
to onboard (authenticate + select/create org + app + write credentials), then Read and execute
```
enhance.md
```
. Do not enter Start or any scaffold task.
Track F: skip onboarding and go directly to the audit in
```
references/VIDEO.md
```
. Do not enter Start or any build step.
Track M: skip onboarding and Read
```
migrate.md
```
first; it fetches the live release guide before any edit. Do not enter Start or any scaffold task.
Track S: skip onboarding and Read
```
sendbird-migration.md
```
first; it detects the integration shape before any edit. Do not enter Start or any scaffold task.

Styling-depth flag (orthogonal to the track). If the request carries a target appearance - an attached screenshot, a Figma frame, or "make it look like WhatsApp / Slack / <app>" - route through

references/design-matching.md

: a reference design is a checklist of regions, not a color tweak. Its pipeline is Classify -> Design analysis -> Route -> Ground -> Build -> Verify, run as a coordinator-agent orchestration (parallel subagents where the harness dispatches them; inline serially where not): classify the fidelity tier + viewport, produce a fine-grained design analysis at

.design-verify/design-analysis.md

that names the Stream concept behind every visual signal via per-product identification checklists (chat / video / feeds), route each region to a component + mechanism (theming / injection -> the

references/custom-ui.md

completion contract / bespoke), ground the names against the live docs, build batched, and close with an empirical verify loop - screenshot + computed-style checks via session browser tooling or a Playwright fallback - iterated until the spec table passes. This composes with the track: Track A scaffolds first, then matches before Step 4's build; Track E matches within E3. Load it before writing UI.

分支A： 运行
```
getstream init
```
完成入门引导（认证 + 选择/创建组织 + 应用 + 写入凭据），然后进入「开始」环节并执行步骤0-7。
分支E： 运行
```
getstream init
```
完成入门引导（认证 + 选择/创建组织 + 应用 + 写入凭据），然后阅读并执行
```
enhance.md
```
。请勿进入「开始」或任何脚手架搭建任务。
分支F： 跳过入门引导，直接进入
```
references/VIDEO.md
```
中的审计环节。请勿进入「开始」或任何构建步骤。
分支M： 跳过入门引导，先阅读
```
migrate.md
```
；它会在编辑前获取最新的升级指南。请勿进入「开始」或任何脚手架搭建任务。
分支S： 跳过入门引导，先阅读
```
sendbird-migration.md
```
；它会在编辑前检测集成架构。请勿进入「开始」或任何脚手架搭建任务。

样式深度标记（与分支无关）。 如果请求附带目标外观——如截图、Figma框架，或“make it look like WhatsApp / Slack / <app>”——则遵循

references/design-matching.md

流程：参考设计是区域检查清单，而非单纯的颜色调整。其流程为分类 -> 设计分析 -> 路由 -> 落地 -> 构建 -> 验证，通过协调Agent编排执行（支持并行子Agent的场景由调度器分配；否则串行执行）：分类保真度层级 + 视口，在

.design-verify/design-analysis.md

生成细粒度设计分析，通过各产品识别清单（聊天/视频/动态流）为每个视觉信号关联对应的Stream概念，将每个区域路由至对应组件 + 机制（主题/注入 ->

references/custom-ui.md

完成规范/定制开发），对照实时文档确认概念，批量构建，最后通过实证验证循环——通过会话浏览器工具或Playwright备用方案进行截图 + 计算样式检查——迭代直至规范表通过。此流程可与分支组合：分支A先搭建脚手架，然后在步骤4构建前匹配设计；分支E在E3环节内匹配设计。在编写UI前加载此流程。

Docs-first triggers (consult docs before building)

文档优先触发规则（构建前查阅文档）

For any feature that matches a UI component, cookbook, or advanced-guide topic, fetch the matching Stream docs page BEFORE writing code. The live docs are the source of truth for the current API and the recommended pattern; the bundled

references/*-blueprints.md

cover the prebuilt common path only. Full keyword -> page map with exact URLs:

references/docs-map.md

- it opens with the docs convention (the

.md

-twin rule + per-product live index) so any unmapped page is still reachable: never guess a path, fetch the index. Enforced by

RULES.md

> Docs-first for cookbook / advanced features.

This skill is prebuilt-component-first: build the common path with the SDK's prebuilt React components and customize via the documented hooks/props - see

RULES.md

> Reference authority. The docs-first protocol covers both the component reference pages and the cookbook / advanced recipes:

UI Cookbook (customization / theming): typing indicator, custom message UI, message actions, reactions customization, message composer / input UI, channel header, channel list preview, emoji picker, autocomplete / suggestion list, link previews, pin indicator, thread header, search, collapsible sidebar, system message / banner, mentions actions, attachment actions, hide channel history, localization / i18n; Video: replacing call controls, custom layouts, lobby preview, PiP, network quality, livestream watching, ringing.
Advanced Guides: AI integrations (LangChain, AI SDK), advanced search, multiple lists, infinite scroll, read state, online status, location sharing, blocking, message reminders, notifications / web push, attachment previews, audio playback, date formatting, SDK state management, dialog management, TypeScript custom data, chat + video integration, recording, broadcasting, video filters.

When a request hits one of these: match ->
WebFetch
the page's
.md
URL from
references/docs-map.md
-> implement to match. On fetch failure, hand to the

stream-docs

skill; if neither resolves the API, stop and ask the user - never build from memory.

对于任何匹配UI组件、食谱或高级指南主题的功能，在编写代码前必须先获取对应的Stream文档页面。 实时文档是当前API和推荐模式的唯一来源； bundled的

references/*-blueprints.md

仅覆盖预构建的通用路径。完整的关键词->页面映射及精确URL见：

references/docs-map.md

——开篇包含文档约定（

.md

孪生规则 + 各产品实时索引），因此即使是未映射的页面也可访问：绝不猜测路径，直接获取索引。此规则由

RULES.md

> 食谱/高级功能的文档优先原则强制执行。

本技能遵循预构建组件优先：使用SDK的预构建React组件实现通用路径，并通过文档化的hooks/props进行定制——详见

RULES.md

> 参考权威。文档优先流程覆盖组件参考页面和食谱/高级方案：

UI食谱（定制/主题）： 输入指示器、自定义消息UI、消息操作、 reactions定制、消息编辑器/输入UI、频道头部、频道列表预览、表情选择器、自动补全/建议列表、链接预览、固定指示器、线程头部、搜索、可折叠侧边栏、系统消息/横幅、提及操作、附件操作、隐藏频道历史、本地化/i18n；视频：替换通话控件、自定义布局、 lobby预览、画中画、网络质量、直播观看、来电提醒。
高级指南： AI集成（LangChain、AI SDK）、高级搜索、多列表、无限滚动、已读状态、在线状态、位置共享、屏蔽、消息提醒、通知/Web推送、附件预览、音频播放、日期格式化、SDK状态管理、对话框管理、TypeScript自定义数据、聊天+视频集成、录制、广播、视频滤镜。

当请求命中上述任一内容时：匹配 -> 从
references/docs-map.md
获取页面的
.md
URL并执行
WebFetch
-> 按文档实现。若获取失败，移交至

stream-docs

技能；若两者均无法解决API问题，停止操作并询问用户——绝不凭记忆构建。

Start

开始

Track A only. Tracks E, F, and M branch in Flow dispatch above and never enter this section.

Once

getstream init

has onboarded (authenticated + selected/created org + app + written credentials), announce the network plan once, then immediately start executing Steps 0-7 - do not ask permission to begin (the user has authorized the build by asking for it). The only pause for input is the theme + app pick (Step 1b).

仅适用于分支A。 分支E、F、M从上述「流程调度」环节分支，绝不会进入此部分。

getstream init

完成入门引导（认证 + 选择/创建组织 + 应用 + 写入凭据）后，一次性告知网络计划，然后立即开始执行步骤0-7——无需请求用户许可（用户提出构建需求即视为授权）。唯一需要暂停等待输入的环节是主题 + 应用选择（步骤1b）。

Trust readout (announce, then continue on the same turn - do not wait)

信任声明（告知后继续执行，无需等待回复）

Before the first network command, print this verbatim to the user, then proceed straight into Step 0 without stopping for a reply:

Scaffolding now. Network calls you'll see:
npx shadcn@latest ...
(Vercel) - scaffold + UI components from npm.
npm install <stream-packages> --legacy-peer-deps
- Stream SDKs from npm (
stream-chat-react
,
@stream-io/video-react-sdk
, etc.).
getstream env
- local CLI, no network; writes
.env.local
(gitignored by the Next.js scaffold's default; Task B verifies).
Interrupt me at any point if something looks wrong. I'll pause once for your input: the theme + Stream-app pick (Step 1b).

Full per-command audit (publisher, why unpinned, what each writes): section Install trust & integrity below. The user's continued silence after the readout is implicit consent for this scaffold; an objection or stop instruction aborts the run.

Shadcn/ui is always installed during Step 3. stream-react does not install third-party frontend skills - the build uses Stream references + Shadcn. If frontend skill packs (

frontend-design

vercel-react-best-practices

web-design-guidelines

) are already available in the session, use them for generic React / UI polish only; Stream references remain authoritative for SDK wiring.

在第一个网络命令执行前，向用户逐字打印以下内容，然后直接进入步骤0，无需等待回复：

开始搭建脚手架。您将看到以下网络调用：
npx shadcn@latest ...
（Vercel）——从npm脚手架搭建 + UI组件。
npm install <stream-packages> --legacy-peer-deps
——从npm安装Stream SDK（
stream-chat-react
、
@stream-io/video-react-sdk
等）。
getstream env
——本地CLI，无网络请求；写入
.env.local
（Next.js脚手架默认已将其加入
.gitignore
；任务B会验证此设置）。
若发现异常，可随时打断我。我仅会暂停一次等待您的输入：主题 + Stream应用选择（步骤1b）。

各命令的完整审计信息（发布方、未固定版本的原因、写入内容）见下方「安装信任与完整性」部分。用户在信任声明后保持沉默即视为默认同意此搭建流程；若用户提出反对或停止指令，则终止运行。

步骤3中始终会安装Shadcn/ui。stream-react不会安装第三方前端技能包——构建仅使用Stream参考文档 + Shadcn。如果会话中已存在前端技能包（

frontend-design

、

vercel-react-best-practices

、

web-design-guidelines

），仅将其用于通用React/UI优化；Stream参考文档仍为SDK连接逻辑的权威依据。

Install trust & integrity

安装信任与完整性

This builder runs three classes of network-touching commands. Each is listed here so a reviewer can audit before approving. CLI install instructions live in the root skill's "Stream CLI" section in

../stream/SKILL.md

Command	Publisher	Why unpinned	What it writes
`npx shadcn@latest init ...` (Task A)	Vercel - `shadcn-ui/ui`	Scaffolder; `@latest` is the maintainer's documented usage. Pinning ships outdated scaffolds.	Project files in cwd. Next.js scaffold's `.gitignore` ignores `.env*` by default.
`npx shadcn@latest add ...` (Task A.1)	Vercel - same source as above	Same scaffolder; component sync depends on registry parity.	Component files under `components/ui/` .
`npm install <stream-packages> --legacy-peer-deps` (Task C)	GetStream (npm) for `@stream-io/*` and `stream-chat-react` ; transitive deps via standard npm trust	Latest published versions of GetStream's own SDKs - same trust model as the CLI itself.	Modules under `node_modules/` . Runtime SDKs + transitive deps.
`getstream env` (Task B)	GetStream - install instructions in the root skill's "Stream CLI" section in `../stream/SKILL.md`	n/a (local CLI, no network at this step)	`.env.local` in the project root with `NEXT_PUBLIC_STREAM_API_KEY` + `STREAM_API_SECRET` . Task B verifies `.gitignore` covers `.env*` before writing (Next.js scaffold's default already does). The agent never reads `.env.local` (RULES.md > Secrets).
Playwright into a self-contained `.design-verify/` harness ( `npm install --prefix .design-verify -D playwright` + browser install) - design-matching verify-loop fallback only	Microsoft - `microsoft/playwright`	Latest published; runs only when a design match needs a capture and no in-session browser tooling exists (may never run), announced inline at point of use.	Everything under `.design-verify/` (its own `package.json` + `node_modules` , gitignored) - the app's `package.json` / lockfile are untouched - plus ~120MB Chromium in the shared Playwright cache. Deleted wholesale at loop exit; nothing lands in the app manifest.

Reviewer checklist:

All
```
npx
```
invocations resolve to the publishers listed above; substitute a different publisher and the install fails.
```
.env.local
```
is written by the Stream CLI directly, not by the agent, and is not transmitted into the conversation.
If the user wants to pin a specific shadcn version, replace
```
@latest
```
with
```
@<version>
```
in Tasks A and A.1.
The Playwright row is a design-matching verify-loop fallback, not part of the scaffold: it is announced inline if and when it runs (it may never run), installs only into a self-contained
```
.design-verify/
```
harness (never the app root), and does not appear in the Start trust readout above.

此构建器运行三类涉及网络的命令。以下列出所有命令，供审核人员在批准前检查。CLI安装说明位于根技能的「Stream CLI」部分，见

../stream/SKILL.md

。

命令	发布方	未固定版本的原因	写入内容
`npx shadcn@latest init ...` （任务A）	Vercel - `shadcn-ui/ui`	脚手架工具； `@latest` 是维护方文档指定的用法。固定版本会导致脚手架过时。	当前工作目录下的项目文件。Next.js脚手架默认的 `.gitignore` 已忽略 `.env*` 。
`npx shadcn@latest add ...` （任务A.1）	Vercel - 同上来源	同脚手架工具；组件同步依赖注册表一致性。	`components/ui/` 下的组件文件。
`npm install <stream-packages> --legacy-peer-deps` （任务C）	GetStream（npm）提供 `@stream-io/*` 和 `stream-chat-react` ；传递依赖遵循标准npm信任机制	GetStream自有SDK的最新发布版本——与CLI本身的信任模型一致。	`node_modules/` 下的模块。运行时SDK + 传递依赖。
`getstream env` （任务B）	GetStream - 安装说明见根技能的「Stream CLI」部分， `../stream/SKILL.md`	不适用（本地CLI，此步骤无网络请求）	项目根目录下的 `.env.local` ，包含 `NEXT_PUBLIC_STREAM_API_KEY` + `STREAM_API_SECRET` 。任务B在写入前会验证 `.gitignore` 是否包含 `.env*` （Next.js脚手架默认已配置）。Agent绝不会读取 `.env.local` （ `RULES.md` > 机密信息）。
Playwright安装至独立的 `.design-verify/` 环境（ `npm install --prefix .design-verify -D playwright` + 浏览器安装）——仅作为设计匹配验证循环的备用方案	Microsoft - `microsoft/playwright`	最新发布版本；仅在需要捕获设计匹配且会话中无浏览器工具时运行（可能永远不会运行），运行时会实时告知。	`.design-verify/` 下的所有内容（自有 `package.json` + `node_modules` ，已加入 `.gitignore` ）——应用的 `package.json` /锁文件不会被修改——共享Playwright缓存中约120MB的Chromium。验证循环结束后会彻底删除；不会写入应用清单。

审核人员检查清单：

所有
```
npx
```
调用均解析为上述列出的发布方；若替换为其他发布方，安装将失败。
```
.env.local
```
由Stream CLI直接写入，而非Agent，且不会传输至对话中。
若用户希望固定特定shadcn版本，将任务A和A.1中的
```
@latest
```
替换为
```
@<version>
```
。
Playwright条目是设计匹配验证循环的备用方案，不属于脚手架的一部分：仅在运行时实时告知（可能永远不会运行），仅安装至独立的
```
.design-verify/
```
环境（绝不会安装至应用根目录），且不会出现在上述「开始」环节的信任声明中。

Builder Steps

构建步骤

Execute phases in order (later steps depend on earlier ones). Do not run independent phases in parallel. One exception: when

references/design-matching.md

is active, its Orchestration section governs scheduling - the design-analysis agent runs concurrently with the Steps 0-3 setup work, and builds / verifies fan out per its role table; everything else here stays sequential. Shell discipline (one

bash -c

per phase, no

bash -ce

getstream login

standalone) lives in

../stream/RULES.md

> Shell discipline.

Two-call exception: If you must Read JSON from a

getstream api

call and then choose IDs, use one call for the read, one batched call for all creates.

按顺序执行各阶段（后续步骤依赖于前期步骤）。请勿并行运行独立阶段。唯一例外： 当

references/design-matching.md

生效时，其编排部分控制调度——设计分析Agent与步骤0-3的设置工作并行运行，构建/验证按角色表分散执行；其余所有步骤仍保持顺序执行。Shell规范（每个阶段一个

bash -c

，不使用

bash -ce

，

getstream login

独立运行）见

../stream/RULES.md

> Shell规范。

双调用例外： 若必须从

getstream api

调用中读取JSON并选择ID，使用一个调用读取，一个批量调用执行所有创建操作。

Step 0: Package manager

步骤0：包管理器

Always use

npm

. Never use bun. (

RULES.md

> Package manager.)

始终使用

npm

。绝不使用bun。（

RULES.md

> 包管理器。）

Step 1: Auth

步骤1：认证

Authentication is handled by

getstream init

(Step 2) - it opens the browser as its own invocation if you're not signed in (

builder.md

> Provisioning;

../stream/RULES.md

> Shell discipline). There is no separate
getstream api
auth probe - CLI v1.0.0 removed the pre-1.0

OrganizationRead

probe, and

getstream api

subcommands are now product-namespaced (e.g.

getstream api chat ...

). Continue to Step 1b.

认证由

getstream init

（步骤2）处理——若未登录，它会自行调用打开浏览器（

builder.md

> 资源配置；

../stream/RULES.md

> Shell规范）。无需单独执行
getstream api
认证探测——CLI v1.0.0已移除1.0版本前的

OrganizationRead

探测，

getstream api

子命令现在按产品命名空间划分（如

getstream api chat ...

）。继续执行步骤1b。

Step 1b: Theme + app pick

步骤1b：主题 + 应用选择

Ask both setup questions in one message before doing anything else - a single pause, the same "ask exactly once, then act" pattern the other platform packs use for credentials. Build the app options from what is already in context: the org/app already configured in this project by a prior

getstream init

, if any. If none is configured yet,

getstream init

lists your orgs/apps when it runs (Step 2) - interactively with a TTY; in a non-interactive shell it writes a

.stream/init-*.yaml

command file to uncomment instead (

builder.md

> Provisioning documents the exact headless sequence). Don't try to enumerate them with a raw

getstream api

call.

Quick setup - two questions:
Theme: I can use a random shadcn theme, or you can design your own at ui.shadcn.com/create and share the
--preset
value (e.g.
--preset b1Gdi7z7r
). Random, or do you have a preset? (If you already shared a screenshot or Figma, I'll match that instead - skip this.)
Stream app: (an app is already configured) Use the currently configured app <name>
(default), or pick/create a different one? / (no app configured yet)
getstream init
will list your orgs and apps when it runs - use an existing one, or create a fresh org + app?

STOP here and wait for the user's answer. Do not continue with any other step until the user responds. Asking a question and continuing to work in parallel is confusing - the user misses the question as output scrolls past.

Theme - preset provided -> store it for Task A scaffold command. Random / doesn't care -> pick a random preset from
```
nova
```
,
```
vega
```
,
```
maia
```
,
```
lyra
```
,
```
mira
```
,
```
luma
```
.
Theme - a reference design (screenshot / Figma) was provided -> the design dictates the theme: skip question 1, pick the shadcn preset closest to the sampled palette, ask only question 2 (the Stream app), and match the design via
```
references/design-matching.md
```
.
App - named choice, "default", or "don't care" -> Step 2 applies it (the configured app wins whenever one exists). Create new -> Step 2 runs the create flow.
Account has no orgs at all -> drop question 2, announce that a fresh org + app will be created, and ask only the theme.

在执行任何其他操作前，一次性提出两个设置问题——仅暂停一次，与其他平台工具包选择凭据的“仅询问一次，然后执行”模式一致。根据上下文构建应用选项：若之前的

getstream init

已在此项目中配置了组织/应用，则包含该选项。若尚未配置，

getstream init

运行时（步骤2）会列出您的组织/应用——交互式TTY环境下直接选择；非交互式Shell下会写入

.stream/init-*.yaml

命令文件，需取消注释后使用（

builder.md

> 资源配置文档记录了精确的无头执行流程）。请勿尝试通过原始

getstream api

调用枚举组织/应用。

快速设置 - 两个问题：
主题： 我可以使用随机的shadcn主题，您也可以在ui.shadcn.com/create自行设计并分享
--preset
值（如
--preset b1Gdi7z7r
）。使用随机主题，还是您已有预设值？（如果您已分享截图或Figma，我将直接匹配该设计——跳过此问题。）
Stream应用： （已配置应用） 使用当前已配置的应用**
<name>
**（默认），还是选择/创建其他应用？ / （未配置应用）
getstream init
运行时会列出您的组织和应用——使用现有应用，还是创建新的组织+应用？

在此处暂停并等待用户回复。 用户回复前请勿继续执行任何其他步骤。提问后继续并行操作会造成混淆——用户可能会因输出滚动错过问题。

主题 - 提供了预设值 -> 存储该值用于任务A的脚手架命令。随机/无要求 -> 从
```
nova
```
、
```
vega
```
、
```
maia
```
、
```
lyra
```
、
```
mira
```
、
```
luma
```
中随机选择一个预设值。
主题 - 提供了参考设计（截图/Figma） -> 设计决定主题：跳过问题1，选择与采样调色板最接近的shadcn预设值，仅询问问题2（Stream应用），并通过
```
references/design-matching.md
```
匹配设计。
应用 - 指定选择、“默认”或“无要求” -> 步骤2应用该选择（已配置的应用优先）。创建新应用 -> 步骤2执行创建流程。
账户无任何组织 -> 跳过问题2，告知将创建新的组织+应用，仅询问主题问题。

Step 2: Pick org + app

步骤2：选择组织 + 应用

Run Provisioning in

builder.md

getstream init

handles auth and org/app selection-or-creation (including the Feeds v3 region choice). Let

init

drive it - interactively or via its command file; don't provision with raw

getstream api

calls.

执行

builder.md

中的资源配置：

getstream init

处理认证和组织/应用选择或创建（包括Feeds v3区域选择）。让

init

主导流程——交互式或通过命令文件；请勿通过原始

getstream api

调用进行资源配置。

Step 3: Scaffold + .env + SDKs + Configure - SEQUENTIALLY

步骤3：脚手架搭建 + .env + SDK + 配置 - 按顺序执行

Scaffold order

脚手架搭建顺序

Order:

Steps 1-1b: Auth + theme/app pick (wait for answer).
Step 2: Apply the org/app choice (select existing or create).
Task A: Scaffold with Shadcn + Next.js using the chosen preset.
Task A.1: Add base Shadcn components.
Continue with Task B (.env), Task C (SDKs), Task D (CLI config).

Task A: Scaffold - scaffolds Next.js + Tailwind + Shadcn/ui (Base UI) into the current directory. Use the theme preset chosen in Step 1b.

The scaffold command creates a new directory, so we scaffold into a temporary

.scaffold

subdirectory and move everything up. The

-n .scaffold

flag also lands in the generated

package.json

"name": ".scaffold"

, which npm/pnpm/yarn reject (a package name can't start with

), so the final step rewrites

name

to a valid slug derived from the project directory:

bash

npx shadcn@latest init -t next -b base -n .scaffold --no-monorepo -p <random-preset> && mv .scaffold/* .scaffold/.* . 2>/dev/null; rm -rf .scaffold && node -e "const fs=require('fs'),path=require('path'),j=require('./package.json');j.name=path.basename(process.cwd()).toLowerCase().replace(/[^a-z0-9._-]+/g,'-').replace(/^[._-]+/,'')||'app';fs.writeFileSync('package.json',JSON.stringify(j,null,2)+'\n')"

Task A.1: Add base Shadcn components:

bash

npx shadcn@latest add button input textarea card avatar badge separator

Add more components as the use case requires (e.g.

dialog

dropdown-menu

tabs

popover

Do not modify

layout.tsx

globals.css

after scaffold - use Shadcn's defaults as-is (RULES.md > Theme).

Task B: .env - run AFTER scaffold so the

.env

lands inside the project directory.

First, verify
.env*
is gitignored (

../stream/RULES.md

> Secrets). The Next.js scaffold's default already includes it; this is a safety net for projects whose

.gitignore

was hand-edited or doesn't yet exist. Use the file tools (no shell) so no broad

bash -c

permission is needed:

```
Grep
```
for
```
^\.env
```
in
```
.gitignore
```
(or
```
Read
```
it). If it already ignores
```
.env*
```
, do nothing.
If
```
.gitignore
```
exists but has no
```
.env
```
entry, Edit
it to append a line
```
.env*
```
.
If
```
.gitignore
```
does not exist, Write
a new
```
.gitignore
```
containing
```
.env*
```
.

(Inspecting/editing

.gitignore

is fine; never Read or Edit

.env

itself -

../stream/RULES.md

> Secrets.)

Then write secrets:

bash

getstream env

getstream env

detects the Next.js project and writes

NEXT_PUBLIC_STREAM_API_KEY

STREAM_API_SECRET

.env.local

. The secret is server-side only - used by

/api/token

to mint tokens, never in the client bundle. The public API key may be read client-side from

NEXT_PUBLIC_STREAM_API_KEY

or returned via

/api/token

. The agent never reads

.env.local

(

RULES.md

> Env vars).

Task C: Install Stream SDKs + verify icons - Only what the use case needs:

bash

undefined

顺序：

步骤1-1b： 认证 + 主题/应用选择（等待回复）。
步骤2： 应用组织/应用选择（选择现有或创建新的）。
任务A： 使用选定的预设值搭建Shadcn + Next.js脚手架。
任务A.1： 添加基础Shadcn组件。
继续执行任务B（.env）、任务C（SDK）、任务D（CLI配置）。

任务A：脚手架搭建 - 在当前目录中搭建Next.js + Tailwind + Shadcn/ui（基础UI）。使用步骤1b中选择的主题预设值。

脚手架命令会创建新目录，因此我们先在临时

.scaffold

子目录中搭建，然后将所有内容移至上层目录。

-n .scaffold

标志还会在生成的

package.json

中写入

"name": ".scaffold"

，而npm/pnpm/yarn会拒绝此名称（包名不能以

开头），因此最后一步将

name

重写为基于项目目录的有效slug：

bash

npx shadcn@latest init -t next -b base -n .scaffold --no-monorepo -p <random-preset> && mv .scaffold/* .scaffold/.* . 2>/dev/null; rm -rf .scaffold && node -e "const fs=require('fs'),path=require('path'),j=require('./package.json');j.name=path.basename(process.cwd()).toLowerCase().replace(/[^a-z0-9._-]+/g,'-').replace(/^[._-]+/,'')||'app';fs.writeFileSync('package.json',JSON.stringify(j,null,2)+'\
')"

任务A.1：添加基础Shadcn组件：

bash

npx shadcn@latest add button input textarea card avatar badge separator

根据使用场景添加更多组件（如

dialog

、

dropdown-menu

、

tabs

、

popover

）。

脚手架搭建完成后请勿修改
layout.tsx
或
globals.css
——使用Shadcn的默认设置（

RULES.md

> 主题）。

任务B：.env - 在脚手架搭建完成后运行，确保

.env

写入项目目录内。

首先，验证
.env*
已加入git忽略（

../stream/RULES.md

> 机密信息）。Next.js脚手架默认已配置此设置；这是针对

.gitignore

被手动编辑或尚未存在的项目的安全保障。使用文件工具（不使用Shell），无需

bash -c

的广泛权限：

在
```
.gitignore
```
中
```
Grep
```
查找
```
^\\.env
```
（或直接
```
Read
```
文件）。若已忽略
```
.env*
```
，则无需操作。
若
```
.gitignore
```
存在但无
```
.env
```
条目，**
```
Edit
```
**文件并添加一行
```
.env*
```
。
若
```
.gitignore
```
不存在，**
```
Write
```
**新的
```
.gitignore
```
文件，内容为
```
.env*
```
。

（检查/编辑

.gitignore

是允许的；绝不读取或编辑

.env

本身——

../stream/RULES.md

> 机密信息。）

然后写入机密信息：

bash

getstream env

getstream env

检测到Next.js项目后，会将

NEXT_PUBLIC_STREAM_API_KEY

STREAM_API_SECRET

写入

.env.local

。机密信息仅在服务器端使用——用于

/api/token

生成令牌，绝不会出现在客户端包中。公开API密钥可从

NEXT_PUBLIC_STREAM_API_KEY

客户端读取，或通过

/api/token

返回。Agent绝不会读取

.env.local

（

RULES.md

> 环境变量）。

任务C：安装Stream SDK + 验证图标 - 仅安装使用场景所需的SDK：

bash

undefined

Chat: stream-chat stream-chat-react

聊天: stream-chat stream-chat-react

Video: @stream-io/video-react-sdk

视频: @stream-io/video-react-sdk

Feeds: @stream-io/feeds-react-sdk

动态流: @stream-io/feeds-react-sdk

Server: @stream-io/node-sdk

服务器: @stream-io/node-sdk

npm install <packages> --legacy-peer-deps


After installing SDKs, note the resolved **Stream Chat React major**: the bundled blueprints assume **v14** (`MessageComposer`, `stream-chat-react/css/index.css`). `@latest` is v14 today; if a future install resolves a **newer major**, fetch that major's component reference from [`references/docs-map.md`](references/docs-map.md) (Version note) before writing the provider tree - don't apply v14 names from memory.

Also verify an icon package is available. Some Shadcn presets bundle one, others don't:

```bash
node -e "const p=['lucide-react','@phosphor-icons/react','@hugeicons/react'];console.log(p.some(m=>{try{require.resolve(m);return true}catch{return false}})?'ICONS_OK':'NO_ICONS')"

NO_ICONS

, install

lucide-react

npm install lucide-react --legacy-peer-deps

. If an icon package is already present, use that one throughout the app - do not install a second.

Task D: Configure Stream - run the CLI commands from the relevant

references/<Product>.md

(App Integration -> Setup) for each product the use case needs.

npm install <packages> --legacy-peer-deps


安装SDK后，记录解析后的**Stream Chat React主版本**：bundled的蓝图假设为**v14**（`MessageComposer`、`stream-chat-react/css/index.css`）。目前`@latest`为v14；若未来安装解析到**更新的主版本**，在编写提供程序树前需从[`references/docs-map.md`](references/docs-map.md)（版本说明）获取对应主版本的组件参考——绝不凭记忆使用v14的名称。

同时验证是否有可用的图标包。部分Shadcn预设已捆绑图标包，其他则没有：

```bash
node -e "const p=['lucide-react','@phosphor-icons/react','@hugeicons/react'];console.log(p.some(m=>{try{require.resolve(m);return true}catch{return false}})?'ICONS_OK':'NO_ICONS')"

若输出

NO_ICONS

，安装

lucide-react

：

npm install lucide-react --legacy-peer-deps

。若已存在图标包，在整个应用中使用该包——请勿安装第二个图标包。

任务D：配置Stream - 针对使用场景所需的每个产品，运行相关

references/<Product>.md

（应用集成 -> 设置）中的CLI命令。

Step 4: Generate code and UI

步骤4：生成代码和UI

Prebuilt-component-first. Build the common path with the SDK's prebuilt React components and customize via the documented hooks/props (

RULES.md

> Reference authority). Writing your own component for a region (custom message row, composer, channel preview/header, call layout) - not just passing props - loads

references/custom-ui.md

(the completion contract) first; see

RULES.md

> Reference authority.

Docs-first: before implementing any component, cookbook, or advanced feature (typing indicator, custom message UI, reactions, AI integrations, read state, notifications, call layouts, ...), follow the Docs-first triggers section above -

WebFetch

the matching

references/docs-map.md

page first, then build to match.

Load
builder-ui.md
and
sdk.md
(cross-cutting SDK wiring: token route, instantiation, CSS imports), plus only the relevant

references/<Product>.md

header +

references/<Product>-blueprints.md

(the prebuilt provider tree + props) for the product(s) you are implementing - not every reference file. For any customization, fetch the matching live page from

references/docs-map.md

first (and if you are writing your own component for a region, load

references/custom-ui.md

first per Step 4's rule above /

RULES.md

> Reference authority). Pull Use Case Matching and Page Flow from

builder.md

to choose products and navigation structure. For multi-product apps (Chat + Video, Chat + Feeds, Video + Feeds, etc.), also load
references/CROSS-PRODUCT.md
before writing AppShell - it has the canonical multi-client provider hierarchy and an error -> cause -> fix table.

预构建组件优先。 使用SDK的预构建React组件实现通用路径，并通过文档化的hooks/props进行定制（

RULES.md

> 参考权威）。若为某个区域编写自定义组件（自定义消息行、编辑器、频道预览/头部、通话布局）——不仅传递props——需先加载

references/custom-ui.md

（完成规范）；详见

RULES.md

> 参考权威。

文档优先： 在实现任何组件、食谱或高级功能（输入指示器、自定义消息UI、reactions、AI集成、已读状态、通知、通话布局等）前，遵循上述文档优先触发规则部分——先

WebFetch

匹配的

references/docs-map.md

页面，然后按文档构建。

加载
builder-ui.md
和
sdk.md
（跨领域SDK连接逻辑：令牌路由、实例化、CSS导入），以及仅加载正在实现的产品对应的

references/<Product>.md

头部 +

references/<Product>-blueprints.md

（预构建提供程序树 + props）——无需加载所有参考文件。对于任何定制需求，先从

references/docs-map.md

获取匹配的实时页面（若为某个区域编写自定义组件，需先加载

references/custom-ui.md

，遵循步骤4的规则 /

RULES.md

> 参考权威）。从

builder.md

中提取使用场景匹配和页面流程，以选择产品和导航结构。对于多产品应用（聊天+视频、聊天+动态流、视频+动态流等），编写AppShell前还需加载
references/CROSS-PRODUCT.md
——其中包含规范的多客户端提供程序层级结构和错误->原因->修复表。

Step 5: Verify

步骤5：验证

Type-check first (reports ALL errors at once, ~3s):

bash

npx tsc --noEmit

Fix all type errors. Then run the full build:

bash

npx next build

Fix any remaining errors. Do NOT skip

tsc --noEmit

- it catches every type error in one pass, while

next build

stops at the first error per file and requires multiple rebuild cycles.

先进行类型检查（一次性报告所有错误，约3秒）：

bash

npx tsc --noEmit

修复所有类型错误。然后执行完整构建：

bash

npx next build

修复剩余所有错误。请勿跳过
tsc --noEmit
——它可一次性捕获所有类型错误，而

next build

会在每个文件的第一个错误处停止，需要多次重建。

Step 6: Start dev server

步骤6：启动开发服务器

Pick a random 5-digit port (10000-65535). Run the server using

run_in_background

bash

PORT=$((RANDOM % 55536 + 10000))
npx next dev -p $PORT

Important: The dev server is a long-running process. When run in the background it will eventually emit a "completed" notification - this does not mean the server stopped. The server is still running and serving requests. Do not respond to the background-task completion notification by telling the user the server has stopped. If you receive that notification after Step 7, ignore it silently - do not output anything.

随机选择一个5位端口（10000-65535）。使用

run_in_background

运行服务器：

bash

PORT=$((RANDOM % 55536 + 10000))
npx next dev -p $PORT

重要提示： 开发服务器是长期运行的进程。在后台运行时，它最终会发出“已完成”通知——这不代表服务器已停止。服务器仍在运行并处理请求。请勿响应后台任务完成通知，告知用户服务器已停止。若步骤7后收到该通知，请忽略——无需输出任何内容。

Step 6b: Smoke-check the render (required)

步骤6b：渲染冒烟测试（必填）

A green

tsc

next build

(Step 5) says nothing about what the user sees - it compiles, it does not render. Before the summary, capture at least one screenshot of the logged-in main screen and actually look at it, using the tool ladder in

references/design-matching.md

> 6b (in-session browser tooling first, else the Playwright fallback; the

networkidle

and capture gotchas in 6c apply). You are checking for gross breakage the build cannot catch: a blank / splash-stuck screen, unstyled or collapsed layout, a region not filling its pane, or console errors. Fix what you see and re-capture.

If the request carried any target appearance - an attached screenshot, a Figma frame, or "make it look like <app>" - this smoke check is not enough: you must run the full

references/design-matching.md

Step 6 verify loop (a per-region spec table diffed against a this-round capture). A referenced build that skipped that loop is unfinished, not merely unpolished - catching it here is the backstop if the styling-depth flag was missed at Start.

tsc

next build

（步骤5）显示绿色仅代表编译通过，不代表用户能看到正常内容——它只是编译，不进行渲染。在生成总结前，至少捕获一张登录后主屏幕的截图并实际查看，使用

references/design-matching.md

> 6b中的工具优先级（优先使用会话浏览器工具，否则使用Playwright备用方案；6c中的

networkidle

和捕获注意事项适用）。检查构建无法捕获的严重问题：空白/卡在启动页、样式丢失或布局坍塌、区域未填充面板、控制台错误。修复发现的问题并重新捕获。

如果请求附带任何目标外观——如截图、Figma框架，或“make it look like <app>”——此冒烟测试不够：必须运行完整的

references/design-matching.md

步骤6验证循环（逐区域规范表与当前捕获截图对比）。跳过该循环的参考设计构建视为未完成，而非仅未优化——此处是“开始”环节遗漏样式深度标记的最后保障。

Step 7: Summary

步骤7：总结

Show the org/app used (created or selected), plus resources and files created. Include the local URL. Do NOT say "you can now start the dev server" - it's already running.

End with:

Open
http://localhost:<PORT>
, enter a username, and start testing. Open a second tab with a different username to test multi-user interactions.

展示使用的组织/应用（创建或选择），以及创建的资源和文件。包含本地URL。请勿说“您现在可以启动开发服务器”——服务器已在运行。

结尾附上：

打开
http://localhost:<PORT>
，输入用户名开始测试。打开第二个标签页，使用不同用户名测试多用户交互。

Use Case Matching and Page Flow

使用场景匹配和页面流程

Both live in

builder.md

(Use Case Matching, Page Flow). Match the user's words to a use case there, then build only the products that use case needs and follow the hub-first navigation it describes. Moderation is configured via CLI during setup only - never build moderation review UI (

RULES.md

> Moderation is Dashboard-only).

两者均位于

builder.md

（使用场景匹配、页面流程）。将用户的需求与其中的使用场景匹配，然后仅构建该场景所需的产品，并遵循其描述的中心优先导航结构。内容审核仅在设置期间通过CLI配置——绝不构建内容审核审查UI（

RULES.md

> 内容审核仅通过控制台操作）。

Cross-Product Integration

跨产品集成

When building apps that combine multiple products, read each relevant

references/<Product>.md

App Integration section. Key patterns:

Combined token route:
```
/api/token
```
returns tokens for each product (
```
{ chatToken, videoToken, feedToken, apiKey }
```
). Upsert only the requesting user - never seed demo users (
```
../stream/RULES.md
```
> No auto-seeding).
Video + Feeds (Livestreaming): Feed hub separates
```
type === "live"
```
activities as prominent live cards. "Go Live" posts a live activity via
```
/api/feed/live
```
. "End Stream" removes it.
Video + Chat (Livestreaming): Chat alongside video on the watch screen. Use
```
livestream
```
channel type - one channel per stream, keyed by call ID. Create the chat channel in the
```
/api/token
```
route.
Moderation (all use cases): Run Moderation CLI setup commands from
```
references/MODERATION.md
```
(App Integration -> Setup), adjusting channel type name. Never build moderation review UI (
```
RULES.md
```
> Moderation is Dashboard-only).

For multi-product provider nesting, load

references/CROSS-PRODUCT.md

构建多产品组合的应用时，阅读每个相关

references/<Product>.md

的应用集成部分。关键模式：

组合令牌路由：
```
/api/token
```
返回每个产品的令牌（
```
{ chatToken, videoToken, feedToken, apiKey }
```
）。仅更新请求用户的令牌——绝不自动创建演示用户（
```
../stream/RULES.md
```
> 不自动创建演示用户）。
视频 + 动态流（直播）： 动态流中心将
```
type === "live"
```
的活动作为显眼的直播卡片单独展示。“开始直播”通过
```
/api/feed/live
```
发布直播活动。“结束直播”移除该活动。
视频 + 聊天（直播）： 观看页面中视频旁显示聊天。使用
```
livestream
```
频道类型——每个流对应一个频道，按通话ID关联。在
```
/api/token
```
路由中创建聊天频道。
内容审核（所有场景）： 运行
```
references/MODERATION.md
```
（应用集成 -> 设置）中的内容审核CLI设置命令，调整频道类型名称。绝不构建内容审核审查UI（
```
RULES.md
```
> 内容审核仅通过控制台操作）。

对于多产品提供程序嵌套，加载

references/CROSS-PRODUCT.md

。

Reference file paths

参考文件路径

Blueprint files live in the

references/

directory next to this SKILL.md. Resolve them relative to this skill's own directory, wherever the pack is installed (e.g.

<skill-dir>/references/FEEDS.md

). Do not hardcode machine-specific absolute paths or assume a repo-checkout layout.

蓝图文件位于本SKILL.md旁的

references/

目录中。相对于本技能自身的目录解析路径，无论工具包安装在何处（如

<skill-dir>/references/FEEDS.md

）。请勿硬编码机器特定的绝对路径，或假设仓库 checkout 布局。",