当用户明确点名 stream-builder 并要搭建…

在用户明确要求 stream-builder 或 /stream-builder 时，用于 Stream 多产品应用的新建脚手架、已有应用增强，或只读视频集成最佳实践审计。

适用场景

解决思路

1. 每次会话先执行 Read first：Glob `../stream/SKILL.md`；若路径为空，运行 `getstream skills stream` 安装（无需确认，直接运行）；然后 Read `../stream/RULES.md`，其中包含 Peer skills 表，用于按需安装/调用其他 pack 技能。
2. 判断三条流程：Track A 新应用脚手架（Step 0-7），用于 cwd 为空/新建且用户说 build me a ... app；Track E 增强已有应用，读 `enhance.md`，跳过 scaffold 和主题，复用 SDK wiring 和组件蓝图；Track F 只读审计已有集成，用于 audit/review my video integration、check my app against best practices、is my video app production-ready、what am I missing before launch。
3. Track F：加载 `references/VIDEO.md` 中 Integration best-practices audit 一节并遵循协议；跳过 onboarding、auth、CLI 和所有 build steps；只读应用并报告发现；仅当用户随后要求修复时才修复。
4. Track F 跳过 Start 整节：只读最佳实践审查不运行 onboarding、auth、CLI 和 Step 0-7；直接进入 `references/VIDEO.md` 的审计一节并报告发现；仅当用户要求修复审计发现时才进入 build flow。
5. Start：一次性宣布网络计划（Trust readout），随后立即执行 Step 0-7；开始时不要交互式提示，因为用户请求构建即已授权。
6. Trust readout：在第一条网络命令前，逐字打印给用户，然后同一轮直接进入 Step 0，不要停下等待回复。内容：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` (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.
7. 逐命令审计见 Install trust & integrity。用户在 readout 后继续沉默视为对该 scaffold 的隐式同意；反对或停止指令则中止运行。
8. Shadcn/ui 总是在 Step 3 安装。第三方前端 skills（`vercel-react-best-practices`、`web-design-guidelines`、`frontend-design`）仅在用户明确同意后安装，见 Task A.2；若拒绝，Step 4 只使用 Stream references。优先级：存在 skills 时，Stream references 在 SDK wiring 上优先；frontend skills 指导通用 React/UI 打磨。
9. Install trust & integrity：列出三类联网命令供审查。表格：`npx shadcn@latest init ...`（Task A）发布者 Vercel - `shadcn-ui/ui`；为何不 pin：脚手架，`@latest` 是维护者文档用法，pin 会发布过时脚手架；写入：cwd 中项目文件，Next.js scaffold 默认 `.gitignore` 忽略 `.env*`。
10. 表格：`npx shadcn@latest add ...`（Task A.1）发布者 Vercel - 同上；为何不 pin：同一脚手架，组件同步依赖 registry 对齐；写入：`components/ui/` 下组件文件。
11. 表格：`npm install <stream-packages> --legacy-peer-deps`（Task C）发布者 GetStream（npm）用于 `@stream-io/*` 和 `stream-chat-react`，传递依赖走标准 npm 信任；为何不 pin：GetStream 自有 SDK 的最新发布版本，与 CLI 本身同一信任模型；写入：`node_modules/` 下模块，运行时 SDK + 传递依赖。
12. 表格：`npx skills add <github>`（Task A.2）发布者 `vercel-labs/agent-skills` 和 `anthropics/skills`；可选；仅 markdown skill packs；`npx skills add` 是发布的安装路径；写入用户 skills 目录中的 markdown 文件；必须在 Task A.2 明确用户同意后才运行，绝不在未获肯定答复时运行。
13. 表格：`getstream env`（Task B）发布者 GetStream（local CLI）；为何不 pin：n/a（本地 CLI，此步骤无网络）；写入项目根 `.env`，含 `STREAM_API_KEY` + `STREAM_API_SECRET`；Task B 在写入前验证 `.gitignore` 覆盖 `.env*`（Next.js scaffold 默认已覆盖）；agent 从不读取 `.env`（RULES.md > Secrets）。
14. Reviewer checklist：所有 `npx` 调用解析到上述发布者；换成不同发布者安装会失败。
15. Reviewer checklist：`npx skills add` 只在 Task A.2 披露提示和用户明确 yes 后运行。
16. Reviewer checklist：`.env` 由 Stream CLI 直接写入，不由 agent 写入，也不传输进对话。
17. Reviewer checklist：若用户想 pin 特定 shadcn 版本，在 Tasks A 和 A.1 中用 `@<version>` 替换 `@latest`。
18. Builder Steps：按顺序执行各阶段（后续步骤依赖前面），不要并行运行独立阶段。Shell discipline（每阶段一个 `bash -c`，不用 `bash -ce`，浏览器登录独立运行）在 `stream` 技能的 `RULES.md` > Shell discipline。
19. Step 0：始终用 `npm`。绝不用 bun。
20. Step 1：运行 `getstream init`。它认证，然后选择/创建 org 和 app，并写入项目凭据；遵循其提示和输出。如果应用使用 Feeds，在 `getstream init` 提供 region 列表时选择 Feeds v3 region（其他 region 默认 legacy v2）。若未安装 `getstream`，请用户从 https://getstream.io 安装并等待——绝不 fetch 或运行安装脚本。浏览器登录必须独立调用（RULES.md > Shell discipline）。
21. Step 2：在 scaffold 前询问用户想要哪个 Shadcn 主题。提示：Quick theme pick: I can use a random shadcn theme, or you can design your own at [ui.shadcn.com/create](https://ui.shadcn.com/create) and share the `--preset` value (e.g. `--preset b1Gdi7z7r`). Want a random one or do you have a preset? 在此 STOP 并等待用户回答，直到回答前不要继续 scaffold 或其他步骤；一边问一边并行工作会让用户因输出滚动错过问题。
22. Step 2 后续：若用户提供 preset，保存供 Task A scaffold 命令使用；若用户说 random/不在意/想继续，从 `nova`、`vega`、`maia`、`lyra`、`mira`、`luma` 随机选一个 preset。
23. Step 3：Scaffold + .env + SDKs + Configure 按顺序执行。
24. Scaffold order：1 `getstream init`（auth + org/app + credentials）；2 主题选择（等待回答）；3 Task A 用所选 preset 通过 Shadcn + Next.js scaffold；4 Task A.1 添加基础 Shadcn 组件；5 Task A.2 披露并询问第三方前端 skill 安装，仅在同意后安装；6 继续 Task B（.env）、Task C（SDKs）、Task D（CLI config）。
25. Task A：scaffold Next.js + Tailwind + Shadcn/ui（Base UI）到当前目录，使用 Step 2 选的主题 preset。scaffold 命令会创建新目录，所以先 scaffold 到临时 `.scaffold` 子目录再把所有内容移上来；`-n .scaffold` 也会写进生成的 `package.json` 的 `name` 为 `.scaffold`，npm/pnpm/yarn 会拒绝（包名不能以 `.` 开头），所以最后一步把 `name` 重写为从项目目录派生的有效 slug。命令：`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')"`
26. Task A.1：运行 `npx shadcn@latest add button input textarea card avatar badge separator`。按用例需要添加更多组件（如 `dialog`、`dropdown-menu`、`tabs`、`popover`）。
27. Task A.2：第三方 skill packs。必须先披露并询问再安装。不要构造自己的命令变体。逐字打印披露内容，然后停下等待用户回答：I'd like to install three third-party skill packs that improve generic UI quality: - `vercel-react-best-practices` - from [`vercel-labs/agent-skills`](https://github.com/vercel-labs/agent-skills) - `web-design-guidelines` - from [`vercel-labs/agent-skills`](https://github.com/vercel-labs/agent-skills) - `frontend-design` - from [`anthropics/skills`](https://github.com/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?
28. Task A.2 同意：运行 `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`。拒绝：静默跳过并继续 Task B，不要重试，本 session 不再提。安装失败：只用 Stream reference files 继续；简短提及失败。
29. Task A 后不要修改 `layout.tsx` 或 `globals.css` - 按原样使用 Shadcn 默认值（RULES.md > Theme）。
30. Task B：在 scaffold 之后运行，使 `.env` 落在项目目录内。先验证 `.env*` 被 gitignore（`stream` 技能 `RULES.md` > Secrets）；Next.js scaffold 默认已包含，这是对 `.gitignore` 被手工改过或尚不存在项目的安全网。命令：`bash -c 'test -f .gitignore && grep -qE "^\\.env" .gitignore || echo ".env*" >> .gitignore'`
31. Task B：然后写 secrets：`getstream env`。`getstream env` 检测 Next.js 项目并写 `NEXT_PUBLIC_STREAM_API_KEY` + `STREAM_API_SECRET` 到 `.env.local`。secret 仅服务端使用，由 `/api/token` 铸造 token，绝不出现在 client bundle。public API key 可在客户端从 `NEXT_PUBLIC_STREAM_API_KEY` 读取，或经由 `/api/token` 返回。agent 从不读取 `.env.local`（RULES.md > Secrets）。
32. Task C：只安装用例需要的 Stream SDKs：Chat: `stream-chat stream-chat-react`；Video: `@stream-io/video-react-sdk`；Feeds: `@stream-io/feeds-react-sdk`；Server: `@stream-io/node-sdk`。命令：`npm install <packages> --legacy-peer-deps`。
33. Task C：安装 SDK 后验证 icon 包可用。有些 Shadcn presets 自带，有些没有。命令：`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`。若已有 icon 包，全程使用该包 - 不要安装第二个。
34. Task D：配置 Stream - 针对用例需要的每个产品，从相关 `references/<Product>.md` 的 App Integration -> Setup 运行 CLI 命令。
35. Step 4：生成代码和 UI。加载 `builder-ui.md`，并且只加载正在实现部分的相关 `references/<Product>.md` 头部 + `references/<Product>-blueprints.md` - 不要加载所有 reference 文件。多产品应用（Chat + Video、Chat + Feeds、Video + Feeds 等）还须在写 AppShell 前加载 `references/CROSS-PRODUCT.md` - 其中有规范的多 client provider 层级和 error -> cause -> fix 表。如果匹配 use-case recipe（见 Use-case recipes），加载该 recipe 及其 `load_with` references，并按它作为 build plan，而不是自行推断产品集。
36. Step 5：验证。先 type-check（一次报告所有错误，约 3s）：`npx tsc --noEmit`。修复所有类型错误。然后运行完整 build：`npx next build`。修复剩余错误。不要跳过 `tsc --noEmit` - 它一次捕获所有类型错误，而 `next build` 每文件停在第一个错误并需要多轮 rebuild。
37. Step 6：启动 dev server。随机选 5 位端口（10000-65535）。用 `run_in_background` 运行服务器：`PORT=$((RANDOM % 55536 + 10000))` 然后 `npx next dev -p $PORT`。
38. Step 6 重要：dev server 是长运行进程。后台运行最终会发出 completed 通知 - 这不表示服务器停止。服务器仍在运行并服务请求。不要因后台任务完成通知告诉用户服务器已停止。若在 Step 7 后收到该通知，静默忽略 - 不要输出任何内容。
39. Step 7：总结创建的内容：org、app、resources、files。包含本地 URL。不要说 you can now start the dev server - 它已在运行。最后说：Open `http://localhost:<PORT>`，输入用户名并开始测试。打开第二个标签页用不同用户名测试多用户交互。
40. Use Case Matching：只用用户明确提到的产品构建。如果不清楚，询问。表格：用户说 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。
41. Moderation 仅在 setup 时通过 CLI 配置。绝不在应用中构建 moderation review UI（RULES.md > Moderation is Dashboard-only）- 审查发生在 Stream Dashboard（https://dashboard.getstream.io）。
42. Use-case recipes：部分请求映射到 use-case recipe：针对特定产品的即用 build plan（如 AI support agent），同时保持本 skill 通用。在 Step 4 前读 `references/use-cases/_use-cases.yaml`。若请求匹配 recipe 的 `signals`，加载该 recipe 文件并作为 build plan 遵循 - recipe 声明要 scaffold 的 Stream 产品、要 `load_with` 的产品 references、要询问的决策。若没有匹配，使用上面的通用产品蓝图。
43. 增加 use-case：在 `references/use-cases/` 下新增文件，并在 `_use-cases.yaml` 增加条目 - 绝不修改本 SKILL.md。
44. Video 应用 - 也要在此决定 `video_primary_use_case`。当 Use Case Matching 表（或 recipe）选择 Video 时，在还在推理 video 形态时就决定应用持久化的 `video_primary_use_case` 值，使用 `references/VIDEO.md` > Primary use case 中的表和优先级。记录它并带到 Video setup（Task D），在那里通过 CLI 写入一次。在此决定可防止它后来静默默认成 call type - 例如 Whatnot 风格 live-shopping 应用使用 `livestream` call type 但设置 `video_primary_use_case: live-shopping`，而不是 `livestreaming`。这是标签，不是产品选择：它是后端 onboarding/展示元数据，不改变你构建哪些产品或加载哪些蓝图 - 表和 recipes 仍决定这些。
45. Page Flow：每个应用需要清晰导航结构。用户应始终知道自己在哪、能做什么。绝不让用户在没有上下文的情况下落入摄像头/麦克风提示、空状态或功能繁重的屏幕。
46. Page Flow 原则：Hub-first。登录后落到 hub - 一个显示正在发生什么并让用户选择路径的首页。Hub 是锚点；其他都是用户有意导航到的目的地。
47. Livestreaming flow：Login -> Feed hub（live streams + posts）-> Watch a stream（viewer: video + chat, no camera）-> Go Live（explicit action -> then camera/mic setup -> streaming）。Feed hub 将直播流（如有）作为醒目卡片，普通 posts 在下方。点击 live card 打开 watch 视图 - video player + chat 作为 viewer，无摄像头权限。Go Live 是刻意动作（header 按钮或专用屏幕）。只有那时才提示 camera/mic。streamer 在开播前看到设置/预览。Viewers 和 streamers 是同一用户类型 - 区别在动作，不在落地页。
48. Video Conferencing flow：Login -> Lobby（calls 列表或 start a call）-> Join call（camera/mic preview -> join）。落地在 lobby 或 call list - 不直接进入通话。加入通话前显示 preview screen（camera/mic toggles）。用户选择加入。
49. Team Messaging flow：Login -> Channel list + active channel -> Browse/search channels。落地在 channel list，打开最近 channel（或无 channel 时欢迎状态）。
50. Direct Messaging flow：Login -> Conversation list -> Open a conversation -> Start new conversation。
51. Social Feed flow：Login -> Feed hub（follow users + composer + tabs: Timeline | My Posts）-> Comments -> User profiles。用户发到自己的 `user:<userId>` feed，读 `timeline:<userId>`（聚合关注用户 posts）。Feed hub tabs：用 `Tabs` 组件，两个视图：Timeline（默认）- 显示 `timeline:<userId>`；My Posts - 显示 `user:<userId>`。Refresh button：放在 tabs 旁边，点击时对 active feed 重新调用 `feed.getOrCreate({ watch: true })` 拉取最新 activities，给用户显式刷新方式。Follow User 输入（username + follow button）必须可见，让用户填充 timeline。没有关注则 timeline 永久为空 - 此组件非可选。Follow wiring：Follow 组件必须接收 timeline feed 实例并调用 `timelineFeed.follow('user:targetId')` - 不是 `client.follow()`。使用 feed 实例保持 `useFeedActivities()` 同步，使 timeline 在关注后立即更新。
52. Page Flow key rules：Camera/mic 仅 opt-in。绝不在页面加载时请求权限。只在用户明确动作（Go Live、Join Call）时请求。No empty ambiguity：若还没有内容，显示清晰空状态告诉用户做什么（No live streams yet - be the first to Go Live）。Navigation is visible：用户应总能回到 hub。用 App Header 或 sidebar 导航。One primary action per screen：hub 的主任务是浏览/发现；watch 的主任务是观看；Go Live 的主任务是推流。不要混在一起。
53. Cross-Product Integration：构建组合多个产品的应用时，读每个相关 `references/<Product>.md` 的 App Integration 一节。关键模式：Combined token route：`/api/token` 返回每个产品的 token（`{ chatToken, videoToken, feedToken, apiKey }`）。仅 upsert 请求用户 - 绝不 seed demo users。
54. Video + Feeds（Livestreaming）：Feed hub 将 `type === "live"` activities 分离为醒目 live cards。Go Live 通过 `/api/feed/live` 发布 live activity。End Stream 移除它。
55. Video + Chat（Livestreaming）：在 watch screen 上 chat 与 video 并排。使用 `livestream` channel type - 每个 stream 一个 channel，以 call ID 为键。在 `/api/token` route 创建 chat channel。
56. Moderation（所有用例）：从 `references/MODERATION.md` 的 App Integration -> Setup 运行 Moderation CLI setup 命令，调整 channel type 名称。绝不要构建 moderation review UI（RULES.md > Moderation is Dashboard-only）- 审查在 Stream Dashboard。
57. Reference file paths：蓝图文件位于 Stream skill pack 内的 `agent-skills/skills/stream-builder/references/`。从本 repository 根引用为 `agent-skills/skills/stream-builder/references/FEEDS.md`。不要使用机器特定绝对路径。

适用边界 · 注意事项

• 当用户没有明确点名 `stream-builder` 或 `/stream-builder` 时不要使用；通用 web build 请求不会自动选择它。Web React / Next.js 工作（如 build me a chat app、scaffold、create a new ...、add Chat/Video/Feeds to this app、integrate Video、livestreaming、video conferencing、team messaging、direct messaging、social feed）默认使用 `stream-react` skill，而不是本 skill。
• Track F 只读审计时不要 onboarding、auth、CLI、scaffold、install 或 build；直接审计并报告，只有用户要求才修复。
• 不要构建 moderation review UI；审查在 Stream Dashboard 进行。