stream-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Stream Builder — scaffold + enhance

Stream Builder — 项目搭建与功能增强

Read first (every session): the
stream
skill's
RULES.md
— non-negotiable rules apply, especially Secrets, No auto-seeding, Login Screen first, Strict mode protection, Package manager, Theme, Reference authority, Base UI, and Moderation is Dashboard-only.

This skill covers two flows:

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.

Preflight: hand off to the

stream-cli

skill before any Steps 0–7 work — it owns CLI install, credential resolution, and auth. Wait for its

✓ Stream CLI vN.N.N · …

readout, then continue from "Start" below. Do not inline-read

preflight.md

bootstrap.md

; loading the CLI skill primes its endpoint cache + cookbook for any ad-hoc query later in the build (RULES.md › CLI safety). The same hand-off applies to any

stream api

query the builder needs mid-flow — never improvise an endpoint name.

每次会话必读：
stream
技能的
RULES.md
— 需遵守不可协商的规则，尤其是保密规则、禁止自动填充数据、优先登录界面、严格模式保护、包管理器、主题、参考权威、基础UI以及仅通过Dashboard进行内容审核。

本技能包含两种流程：

**流程A — 搭建新应用：**以下步骤0-7。适用于当前工作目录为空/新建，且用户提出“build me a … app”需求的场景。
**流程E — 增强现有应用：**查看
```
enhance.md
```
。跳过搭建与主题设置环节；复用相同的SDK连接逻辑和组件蓝图。

**前置准备：**在执行步骤0-7之前，先移交至

stream-cli

技能 — 该技能负责CLI安装、凭证解析与认证。等待其输出

✓ Stream CLI vN.N.N · …

后，再从下方“开始”环节继续。请勿直接读取

preflight.md

bootstrap.md

；加载CLI技能会预先缓存其端点信息与操作指南，以便在后续构建过程中处理临时查询（参考RULES.md › CLI安全规范）。若构建过程中需要执行任何

stream api

查询，同样需移交至该技能 — 切勿自行指定端点名称。

Start

开始

Once preflight has reported

✓ Stream CLI vN.N.N · …

, announce the network plan once, then immediately start executing Steps 0–7 — no interactive prompts at the start (the user has authorized the build by asking for it).

当前置准备输出

✓ Stream CLI vN.N.N · …

后，先一次性告知网络操作计划，然后立即执行步骤0-7 — 初始阶段无需交互式提示（用户提出构建需求即视为授权）。

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.).
stream env
— local CLI, no network; writes
.env
(gitignored by the Next.js scaffold's default; Task B verifies).
Interrupt me at any point if something looks wrong. The only step that pauses for explicit consent is the optional third-party skill packs in Task A.2.

Full per-command audit (publisher, why unpinned, what each writes): § 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. Third-party frontend skills (

vercel-react-best-practices

web-design-guidelines

frontend-design

) are installed only with explicit user consent — see Task A.2 for the disclosure script. If the user declines, Step 4 proceeds using Stream references only. Precedence (when the skills are present): Stream references win for SDK wiring; frontend skills guide generic React / UI polish.

在执行第一个网络命令前，向用户打印以下内容，然后直接进入步骤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
等）。
stream env
— 本地CLI操作，无网络请求；用于写入
.env
文件（Next.js模板默认已将其加入
.gitignore
；任务B会对此进行验证）。
若发现异常，可随时中断操作。唯一需要明确同意的步骤是任务A.2中的第三方技能包安装。

各命令完整审计信息（发布方、未固定版本原因、写入内容）：详见下方“安装信任与完整性”部分。用户查看声明后保持沉默即视为默认同意本次搭建；若提出异议或停止指令，则终止运行。

步骤3中始终会安装Shadcn/ui。第三方前端技能包（

vercel-react-best-practices

、

web-design-guidelines

、

frontend-design

）仅在获得用户明确同意后才会安装 — 详见任务A.2中的披露脚本。若用户拒绝，步骤4将仅使用Stream参考文档继续执行。**优先级（当技能包存在时）：**SDK连接逻辑以Stream参考文档为准；前端技能包负责指导通用React/UI优化。

Install trust & integrity

安装信任与完整性

The builder runs three classes of network-touching commands. Each is listed here so a reviewer can audit before approving. The full CLI installer audit (SHA-256 verification, TTY confirmation, scoped platform) lives in the

stream-cli

skill's

bootstrap.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.
`npx skills add <github>` (Task A.2)	`vercel-labs/agent-skills` and `anthropics/skills`	Optional. Markdown-only skill packs; `npx skills add` is the published install path.	Markdown files in the user's skills directory. Gated by explicit user consent in Task A.2 — never runs without an affirmative answer.
`stream env` (Task B)	GetStream — installed via the `stream-cli` skill's `bootstrap.md` (SHA-256 verified)	n/a (local CLI, no network at this step)	`.env` in the project root with `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` (RULES.md › Secrets).

Reviewer checklist:

All
```
npx
```
invocations resolve to the publishers listed above; substitute a different publisher and the install fails.
```
npx skills add
```
runs only after the disclosure prompt in Task A.2 and an explicit user "yes."
```
.env
```
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.

构建器会执行三类涉及网络的命令。以下列出所有命令，供审核人员在批准前进行审计。完整的CLI安装审计信息（SHA-256验证、TTY确认、平台范围）可在

stream-cli

技能的

bootstrap.md

中查看。

命令	发布方	未固定版本原因	写入内容
`npx shadcn@latest init …` （任务A）	Vercel — `shadcn-ui/ui`	项目模板工具； `@latest` 是维护方推荐的使用方式。固定版本会导致模板过时。	当前工作目录下的项目文件。Next.js模板默认已将 `.env*` 加入 `.gitignore` 。
`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及传递依赖。
`npx skills add <github>` （任务A.2）	`vercel-labs/agent-skills` 和 `anthropics/skills`	可选。仅包含Markdown的技能包； `npx skills add` 是官方发布的安装方式。	用户技能目录下的Markdown文件。需在任务A.2中获得用户明确同意后方可执行 — 未经肯定答复绝不能运行。
`stream env` （任务B）	GetStream — 通过 `stream-cli` 技能的 `bootstrap.md` 安装（已通过SHA-256验证）	不适用（本地CLI操作，此步骤无网络请求）	项目根目录下的 `.env` 文件，包含 `STREAM_API_KEY` + `STREAM_API_SECRET` 。任务B会在写入前验证 `.gitignore` 是否包含 `.env*` （Next.js模板默认已包含）。代理绝不会读取 `.env` 文件（参考RULES.md › 保密规则）。

审核人员检查清单：

所有
```
npx
```
调用均解析为上述发布方；若替换为其他发布方，安装将失败。
```
npx skills add
```
仅在**任务A.2的披露提示后且用户明确答复“是”**时才会运行。
```
.env
```
文件由Stream CLI直接写入，而非代理，且不会传输到对话中。
若用户希望固定特定shadcn版本，可在任务A和A.1中将
```
@latest
```
替换为
```
@<version>
```
。

Builder Steps

构建步骤

Execute phases in order (later steps depend on earlier ones). Do not run independent phases in parallel. Shell discipline (one

bash -c

per phase, no

bash -ce

stream auth login

standalone) lives in the

stream

skill's

RULES.md

› Shell discipline.

Two-call exception: If you must Read JSON (e.g.

OrganizationRead

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

stream config set

按顺序执行各阶段（后续步骤依赖于前置步骤）。请勿并行执行独立阶段。Shell规范（每个阶段使用一个

bash -c

，不使用

bash -ce

，

stream auth login

单独执行）可在

stream

技能的

RULES.md

› Shell规范中查看。

**双调用例外：**若需要读取JSON（如

OrganizationRead

）并选择ID，可先执行一次读取调用，再执行一次批量创建+

stream config set

调用。

Step 0: Package manager

步骤0：包管理器

Always use

npm

. Never use bun.

始终使用

npm

。禁止使用bun。

Step 1: Auth

步骤1：认证

Test auth first, then act — don't skip this and don't wait until Step 2 surfaces an error. Run

stream api OrganizationRead

as a probe:

Exit 0 → already authenticated, continue to Step 1b.
Exit 2 / "not authenticated" → immediately run
```
stream auth login
```
as its own Bash invocation. This is a hard constraint:
- Browser PKCE requires an unwrapped
```
stream auth login
```
  call — never chain with
```
&&
```
  , embed in a heredoc, or bundle with other commands.
- Do not ask the user first; just run it. Give it up to ~3 minutes for the browser flow.
Login hangs past ~60s, or the user reports the browser is stuck → run
```
stream auth logout
```
to clear any stale session state, then retry
```
stream auth login
```
once. If the second attempt also hangs, stop and ask the user to run
```
! stream auth login
```
themselves (the
```
!
```
prefix runs it in-session so you see the result).

**先测试认证，再执行操作 — 请勿跳过此步骤，也不要等到步骤2出现错误再处理。**运行

stream api OrganizationRead

作为探测：

退出码0 → 已完成认证，继续步骤1b。
退出码2 / “未认证” → 立即单独执行
```
stream auth login
```
命令。这是硬性约束：
- 浏览器PKCE需要独立的
```
stream auth login
```
  调用 — 绝不能使用
```
&&
```
  链式调用、嵌入 heredoc 或与其他命令捆绑。
- 无需先询问用户；直接运行即可。给浏览器流程约3分钟时间。
登录超时超过约60秒，或用户反馈浏览器卡住 → 运行
```
stream auth logout
```
清除过期会话状态，然后重试一次
```
stream auth login
```
。若第二次尝试仍超时，停止操作并请用户自行运行
```
! stream auth login
```
（
```
!
```
前缀表示在会话中运行，以便查看结果）。

Step 1b: Theme pick

步骤1b：主题选择

Ask the user which Shadcn theme they'd like before doing anything else:

Quick theme pick: 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
). Want a random one or do you have a preset?

STOP here and wait for the user's answer. Do not continue with org/app creation or any other steps until the user responds. Asking a question and continuing to work in parallel is confusing — the user misses the question as output scrolls past.

User provides a preset → store it for Task A scaffold command.
User says random / doesn't care / wants to move on → pick a random preset from
```
nova
```
,
```
vega
```
,
```
maia
```
,
```
lyra
```
,
```
mira
```
,
```
luma
```
.

在执行其他操作前，先询问用户想要的Shadcn主题：

**快速选择主题：**我可以随机选择一个shadcn主题，或者您可以在ui.shadcn.com/create自定义主题并分享
--preset
值（例如
--preset b1Gdi7z7r
）。想要随机主题还是自定义预设？

在此处停止并等待用户回复。在用户回复前，请勿继续执行组织/应用创建或其他步骤。若提问后继续并行操作会造成混淆 — 用户可能会因输出滚动而错过问题。

用户提供预设值 → 保存该值用于任务A的项目搭建命令。
用户选择随机/无所谓/希望继续 → 从
```
nova
```
、
```
vega
```
、
```
maia
```
、
```
lyra
```
、
```
mira
```
、
```
luma
```
中随机选择一个预设。

Step 2: Create org + app

步骤2：创建组织与应用

First, check existing orgs with

stream api OrganizationRead

. If there are already 10 orgs, do NOT create a new one — pick an existing

builder-*

org and create a new app inside it.

App names are globally unique. Always use

app-<hash>

where hash =

openssl rand -hex 4

bash

undefined

首先，检查现有组织：运行

stream api OrganizationRead

。若已有10个组织，则不能创建新组织 — 选择一个现有的

builder-*

组织，并在其中创建新应用。

应用名称全局唯一。始终使用

app-<hash>

格式，其中hash =

openssl rand -hex 4

。

bash

undefined

Check existing orgs first:

先检查现有组织:

stream api OrganizationRead

If under 10 orgs, create new:

若组织数量少于10个，创建新组织:

HASH=$(openssl rand -hex 4) stream api OrganizationCreate name=builder-$HASH slug=builder-$HASH

Create app with Feeds v3 + US East (region_id=1):

创建支持Feeds v3 + 美国东部（region_id=1）的应用:

stream api AppCreate name=app-$HASH org_id=<org_id> is_development=true region_id=1 feeds_version=v3

Set defaults:

设置默认值:

stream config set org <org_id> && stream config set app <app_id>


**Never use the auto-created app** from OrganizationCreate — it uses Feeds v2 and US Ohio.

**Fallback (org limit / 429):** Use `OrganizationRead` to list existing builder orgs, pick one, create a new app in it.

stream config set org <org_id> && stream config set app <app_id>


**绝不能使用OrganizationCreate自动创建的应用** — 它使用Feeds v2和美国俄亥俄地区。

** fallback方案（组织数量超限/429错误）：**使用`OrganizationRead`列出现有builder组织，选择其中一个，在里面创建新应用。

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

步骤3：项目搭建 + .env + SDK + 配置 — 按顺序执行

Scaffold order

搭建顺序

Order:

Steps 1–1b: Auth + theme pick (wait for answer).
Step 2: Create org/app.
Task A: Scaffold with Shadcn + Next.js using the chosen preset.
Task A.1: Add base Shadcn components.
Task A.2: Disclose + ask about third-party frontend skill installs; install only with user consent.
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:

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

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

Task A.2: Frontend skills — third-party skill packs. You must disclose and ask before installing. Do NOT construct your own command variant.

Print this disclosure verbatim, then stop and wait for the user's answer:

I'd like to install three third-party skill packs that improve generic UI quality:
vercel-react-best-practices
— from
vercel-labs/agent-skills
web-design-guidelines
— from
vercel-labs/agent-skills
frontend-design
— from
anthropics/skills
The packs are markdown only — no scripts execute. If you say yes, I'll run
npx skills add … -y
once per pack from those GitHub repos at their current
main
branch (
-y
skips the installer's own confirmation since you've consented here). These aren't required — Stream reference files cover SDK wiring either way. Install them?

User agrees → run:

bash

npx skills add https://github.com/vercel-labs/agent-skills --skill vercel-react-best-practices -y && npx skills add https://github.com/vercel-labs/agent-skills --skill web-design-guidelines -y && npx skills add https://github.com/anthropics/skills --skill frontend-design -y

User declines → skip silently and continue to Task B. Do not retry, do not bring it up again this session.
Install fails → continue with Stream reference files only; mention the failure briefly.

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 (the

stream

skill's

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:

bash

bash -c 'test -f .gitignore && grep -qE "^\.env" .gitignore || echo ".env*" >> .gitignore'

Then write secrets:

bash

stream env

stream env

writes

STREAM_API_KEY

and

STREAM_API_SECRET

— both server-side. The client never reads env vars directly; it gets

apiKey

userId

, and its token from the

/api/token

response and holds them in React state. No

NEXT_PUBLIC_*

duplication, no

.env

gymnastics.

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

bash

undefined

顺序：

**步骤1–1b：**认证 + 主题选择（等待用户回复）。
**步骤2：**创建组织/应用。
**任务A：**使用选定的预设搭建Next.js + Tailwind + Shadcn/ui（基础UI）。
**任务A.1：**添加基础Shadcn组件。
**任务A.2：**披露并询问第三方前端技能包安装事宜；仅在用户同意后安装。
继续执行任务B（.env）、任务C（SDK）、任务D（CLI配置）。

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

搭建命令会创建新目录，因此我们先在临时子目录

.scaffold

中搭建，再将所有内容移至当前目录：

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

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

bash

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

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

dialog

、

dropdown-menu

、

tabs

、

popover

）。

任务A.2：前端技能包 — 第三方技能包。必须先披露并询问用户，然后才能安装。请勿自行修改命令格式。

打印以下披露内容，然后停止并等待用户回复：

我想安装三个可提升通用UI质量的第三方技能包：
vercel-react-best-practices
— 来自
vercel-labs/agent-skills
web-design-guidelines
— 来自
vercel-labs/agent-skills
frontend-design
— 来自
anthropics/skills
这些技能包仅包含Markdown内容 — 无脚本执行。若您同意，我将针对每个包运行
npx skills add … -y
（从上述GitHub仓库的当前
main
分支拉取；
-y
会跳过安装器自身的确认步骤，因为您已在此处同意）。这些包并非必需 — Stream参考文档已涵盖所有SDK连接逻辑。是否安装？

用户同意 → 执行：

bash

npx skills add https://github.com/vercel-labs/agent-skills --skill vercel-react-best-practices -y && npx skills add https://github.com/vercel-labs/agent-skills --skill web-design-guidelines -y && npx skills add https://github.com/anthropics/skills --skill frontend-design -y

用户拒绝 → 静默跳过，继续执行任务B。本次会话中请勿重试或再次提及。
安装失败 → 仅使用Stream参考文档继续执行；简要提及安装失败即可。

搭建完成后请勿修改
layout.tsx
或
globals.css
— 保持Shadcn的默认设置（参考RULES.md › 主题规范）。

任务B：.env配置 — 需在搭建完成后执行，确保

.env

文件位于项目目录内。

首先，验证
.env*
已加入git忽略列表（参考

stream

技能的

RULES.md

› 保密规则）。Next.js模板默认已包含此配置；此步骤为安全兜底，适用于

.gitignore

被手动编辑或尚未创建的项目：

bash

bash -c 'test -f .gitignore && grep -qE "^\.env" .gitignore || echo ".env*" >> .gitignore'

然后写入密钥：

bash

stream env

stream env

会写入

STREAM_API_KEY

和

STREAM_API_SECRET

— 两者均为服务端密钥。客户端绝不会直接读取环境变量；它会从

/api/token

接口获取

apiKey

、

userId

和令牌，并存储在React状态中。无需复制为

NEXT_PUBLIC_*

变量，无需对

.env

进行特殊操作。

任务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, verify an icon package is available. Some Shadcn presets bundle one, others don't:

```bash
node -e "try{require.resolve('lucide-react');console.log('ICONS_OK')}catch{try{require.resolve('@phosphor-icons/react');console.log('ICONS_OK')}catch{console.log('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后，验证是否有可用的图标包。部分Shadcn预设已捆绑图标包，其他则没有：

```bash
node -e "try{require.resolve('lucide-react');console.log('ICONS_OK')}catch{try{require.resolve('@phosphor-icons/react');console.log('ICONS_OK')}catch{console.log('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

Load
builder-ui.md
and only the relevant

references/<Product>.md

header +

references/<Product>-blueprints.md

for the sections you are implementing — not every reference file. 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.

加载
builder-ui.md
以及仅加载实现所需的

references/<Product>.md

头部内容 +

references/<Product>-blueprints.md

— 无需加载所有参考文档。对于多产品应用（Chat + Video、Chat + Feeds、Video + Feeds等），在编写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 7: Summary

步骤7：总结

Show what was created: org, app, resources, files. 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

使用场景匹配

Only build with the products the user explicitly mentions. If unclear, ask.

User says	Use case	Products
"Twitch", "YouTube Live", "Kick", "livestream"	Livestreaming	Video + Chat + Feeds
"Zoom", "Google Meet", "video call", "meeting"	Video Conferencing	Video [+ Chat]
"Slack", "Discord", "team chat", "channels"	Team Messaging	Chat
"WhatsApp", "iMessage", "DM", "messaging"	Direct Messaging	Chat [+ Video]
"Instagram", "Twitter", "social feed", "Reddit"	Social Feed	Feeds + Chat

Moderation is configured via CLI during setup only. Never build moderation review UI in the app (RULES.md › Moderation is Dashboard-only) — review happens in the Stream Dashboard.

仅构建用户明确提及的产品。若存在疑问，请询问用户。

用户表述	使用场景	产品
"Twitch"、"YouTube Live"、"Kick"、"livestream"	直播	Video + Chat + Feeds
"Zoom"、"Google Meet"、"video call"、"meeting"	视频会议	Video [+ Chat]
"Slack"、"Discord"、"team chat"、"channels"	团队消息	Chat
"WhatsApp"、"iMessage"、"DM"、"messaging"	即时通讯	Chat [+ Video]
"Instagram"、"Twitter"、"social feed"、"Reddit"	社交信息流	Feeds + Chat

内容审核仅在设置阶段通过CLI配置。绝不能在应用中构建内容审核界面（参考RULES.md › 仅通过Dashboard进行内容审核） — 审核操作需在Stream Dashboard中进行。

Page Flow

页面流程

Every app needs a clear navigation structure. Users should always understand where they are and what they can do. Never drop a user into a camera/mic prompt, an empty state, or a feature-heavy screen without context.

每个应用都需要清晰的导航结构。用户应始终清楚自己所处位置及可执行操作。绝不能让用户直接进入摄像头/麦克风授权提示、空状态或功能繁杂的界面而无任何上下文说明。

Principle: Hub-first

原则：以枢纽页为先

After login, land on a hub — a home screen that shows what's happening and lets the user choose their path. The hub is the anchor; everything else is a destination the user navigates to intentionally.

登录后，用户应进入枢纽页 — 即展示当前动态并让用户选择操作路径的首页。枢纽页是核心锚点；其他所有页面均为用户主动导航前往的目的地。

Flow by use case

按使用场景划分的流程

Livestreaming (Twitch, YouTube Live, Kick):

Login → Feed hub (live streams + posts) → Watch a stream (viewer: video + chat, no camera)
                                        → Go Live (explicit action → then camera/mic setup → streaming)

The feed hub shows live streams (if any) as prominent cards, plus regular posts below
Clicking a live card opens the watch view — video player + chat as a viewer. No camera permissions.
"Go Live" is a deliberate action (button in header or dedicated screen). Only THEN prompt for camera/mic. The streamer sees a setup/preview before going live.
Viewers and streamers are the same user type — the difference is the action they take, not the page they land on.

Video Conferencing (Zoom, Google Meet):

Login → Lobby (list of calls or "start a call") → Join call (camera/mic preview → join)

Land on a lobby or call list — not directly in a call.
Joining a call shows a preview screen (camera/mic toggles) before connecting. The user opts in.

Team Messaging (Slack, Discord):

Login → Channel list + active channel → Browse/search channels

Land on the channel list with the most recent channel open (or a welcome state if no channels).

Direct Messaging (WhatsApp, iMessage):

Login → Conversation list → Open a conversation → Start new conversation

Social Feed (Instagram, Twitter):

Login → Feed hub (follow users + composer + tabs: Timeline | My Posts) → Comments → User profiles

The user posts to their own
```
user:<userId>
```
feed and reads from
```
timeline:<userId>
```
(aggregates followed users' posts)
Feed hub tabs: Use a
```
Tabs
```
component with two views:
- Timeline (default) — shows
```
timeline:<userId>
```
  (posts from followed users)
- My Posts — shows
```
user:<userId>
```
  (the current user's own posts)
Refresh button: Place a refresh/reload button next to the tabs. On click, re-call
```
feed.getOrCreate({ watch: true })
```
on the active feed to re-fetch the latest activities. This gives users an explicit way to refresh after follows or if real-time events are missed.
A Follow User input (username + follow button) must be visible so users can populate their timeline
Without following, the timeline is permanently empty — this component is not optional
Follow wiring: The Follow component must receive the timeline feed instance and call
```
timelineFeed.follow('user:targetId')
```
— not
```
client.follow()
```
. Using the feed instance keeps
```
useFeedActivities()
```
in sync so the timeline updates immediately after following.

直播场景（Twitch、YouTube Live、Kick）：

登录 → 信息流枢纽页（直播流 + 帖子） → 观看直播（观众端：视频 + 聊天，无摄像头）
                                        → 开启直播（明确操作 → 摄像头/麦克风设置 → 开始直播）

信息流枢纽页将直播流（若存在）展示为显眼卡片，下方显示常规帖子
点击直播卡片进入观看视图 — 视频播放器 + 聊天界面（观众端）。无需摄像头权限。
“开启直播”是一个刻意操作（头部按钮或专属页面）。仅在此时请求摄像头/麦克风权限。主播在开启直播前会看到设置/预览界面。
观众和主播为同一用户类型 — 区别在于执行的操作，而非进入的页面。

视频会议场景（Zoom、Google Meet）：

登录 → 大厅（会议列表或“开始会议”） → 加入会议（摄像头/麦克风预览 → 加入）

进入大厅或会议列表 — 而非直接进入会议。
加入会议时会显示预览界面（摄像头/麦克风开关），然后再连接。用户需主动确认加入。

团队消息场景（Slack、Discord）：

登录 → 频道列表 + 当前活跃频道 → 浏览/搜索频道

进入频道列表，默认打开最近使用的频道（若无频道则显示欢迎状态）。

即时通讯场景（WhatsApp、iMessage）：

登录 → 对话列表 → 打开对话 → 发起新对话

社交信息流场景（Instagram、Twitter）：

登录 → 信息流枢纽页（关注用户 + 发布框 + 标签页：时间线 | 我的帖子） → 评论区 → 用户资料页

用户发布内容至自己的
```
user:<userId>
```
信息流，并从
```
timeline:<userId>
```
信息流读取内容（聚合已关注用户的帖子）
**信息流枢纽页标签：**使用
```
Tabs
```
组件，包含两个视图：
- 时间线（默认） — 展示
```
timeline:<userId>
```
  （已关注用户的帖子）
- 我的帖子 — 展示
```
user:<userId>
```
  （当前用户自己的帖子）
**刷新按钮：**在标签页旁放置刷新按钮。点击时，重新调用当前活跃信息流的
```
feed.getOrCreate({ watch: true })
```
以获取最新内容。这为用户提供了明确的刷新方式，可在关注用户或错过实时事件后使用。
必须显示关注用户输入框（用户名 + 关注按钮），以便用户填充自己的时间线
若未关注任何用户，时间线将始终为空 — 此组件为必填项
关注逻辑：关注组件必须接收时间线信息流实例并调用
```
timelineFeed.follow('user:targetId')
```
— 而非
```
client.follow()
```
。使用信息流实例可保持
```
useFeedActivities()
```
同步，确保关注后时间线立即更新。

Key rules

核心规则

Camera/mic: opt-in only. Never request permissions on page load. Only when the user takes an explicit action (Go Live, Join Call).
No empty ambiguity. If there's no content yet, show a clear empty state that tells the user what to do ("No live streams yet — be the first to Go Live").
Navigation is visible. The user should always be able to get back to the hub. Use the App Header or a sidebar for navigation.
One primary action per screen. The hub's primary action is browsing/discovering. The watch screen's primary action is viewing. The Go Live screen's primary action is streaming. Don't mix them.

摄像头/麦克风：仅允许用户主动授权。绝不能在页面加载时请求权限。仅在用户执行明确操作（开启直播、加入会议）时请求。
避免空状态歧义。若暂无内容，需显示清晰的空状态提示，告知用户应执行的操作（“暂无直播 — 快来成为第一个开启直播的人吧”）。
导航可见。用户应始终能返回枢纽页。使用应用头部或侧边栏进行导航。
每个页面仅一个核心操作。枢纽页的核心操作是浏览/发现。观看页面的核心操作是观看。开启直播页面的核心操作是直播。请勿混合操作。

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.
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) — review happens in the Stream Dashboard.

构建包含多个产品的应用时，请阅读每个相关

references/<Product>.md

的应用集成部分。核心模式：

统一令牌接口：
```
/api/token
```
返回每个产品的令牌（
```
{ chatToken, videoToken, feedToken, apiKey }
```
）。仅为请求用户更新令牌 — 绝不能填充演示用户。
**Video + Feeds（直播场景）：**信息流枢纽页将
```
type === "live"
```
的内容作为显眼的直播卡片单独展示。“开启直播”通过
```
/api/feed/live
```
发布直播活动。“结束直播”则移除该活动。
**Video + Chat（直播场景）：**观看页面中视频旁显示聊天界面。使用
```
livestream
```
频道类型 — 每个直播对应一个频道，以呼叫ID作为标识。在
```
/api/token
```
接口中创建聊天频道。
**内容审核（所有场景）：**执行
```
references/MODERATION.md
```
（应用集成 → 设置）中的内容审核CLI设置命令，调整频道类型名称。绝不能构建内容审核界面（参考RULES.md › 仅通过Dashboard进行内容审核） — 审核操作需在Stream Dashboard中进行。

Authentication

认证

If not authenticated:

Has account →
```
stream auth login
```

No account → Open

https://getstream.io/try-for-free/

, then

stream auth login

after signup

若未完成认证：

已有账号 →
```
stream auth login
```

无账号 → 打开

https://getstream.io/try-for-free/

，注册后执行

stream auth login

Reference file paths

参考文件路径

Blueprint files live under

agent-skills/skills/stream-builder/references/

inside the Stream skill pack. Reference them as

agent-skills/skills/stream-builder/references/FEEDS.md

from the root of this repository. Do not use machine-specific absolute paths.

蓝图文件位于Stream技能包内的

agent-skills/skills/stream-builder/references/

目录下。从本仓库根目录引用时，路径为

agent-skills/skills/stream-builder/references/FEEDS.md

。请勿使用机器特定的绝对路径。