stream-swift

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Stream Swift - skill router + execution flow

Stream Swift - 技能路由与执行流程

Rules: Read RULES.md
once per session - every non-negotiable rule is stated there, nowhere else.

This file is the single entrypoint: intent classification, local project detection, and module pointers for Stream work in Swift apps.

规则： 每个会话需阅读一次**

RULES.md

**——所有不可协商的规则均在此处说明，无其他地方。

本文件是唯一入口：用于Swift应用中Stream相关工作的意图分类、本地项目检测和模块指引。

Step 0: Intent classifier (mandatory first - never skip)

步骤0：意图分类器（必须首先执行，不可跳过）

Before any tool call, decide the track from the user's input alone - no probes first.

在调用任何工具前，仅根据用户输入确定处理路径——不要先进行探查。

Signals -> track

信号 → 处理路径

Signal in user input	Track
Explicit product/framework token: `Chat SwiftUI` , `Chat UIKit` , `Video iOS` , `Feeds Swift` , etc.	C - Reference lookup
Words "docs" or "documentation" around Stream Swift/iOS work	C - Reference lookup
"How do I {X} in SwiftUI/UIKit/Xcode?", "What does {SDK type/method/view} do?"	C - Reference lookup
"Build me a new iOS app", "create a SwiftUI app", "new UIKit app" + Stream product	A - New app
"Add/integrate Stream into this app", "wire Chat/Video/Feeds into my Xcode project"	B - Existing app
"Install Stream packages", "set up Stream in Xcode", "wire auth/token flow" with no broader feature request	D - Bootstrap / setup
Bare `/stream-swift` with no args	List the tracks briefly and wait

用户输入中的信号	处理路径
明确的产品/框架标识： `Chat SwiftUI` 、 `Chat UIKit` 、 `Video iOS` 、 `Feeds Swift` 等	C - 参考查询
围绕Stream Swift/iOS工作提及“docs”或“documentation”（文档）	C - 参考查询
“如何在SwiftUI/UIKit/Xcode中实现{X}？”、“{SDK类型/方法/视图}有什么作用？”	C - 参考查询
“帮我构建一个新的iOS应用”、“创建SwiftUI应用”、“新UIKit应用” + Stream产品	A - 新建应用
“将Stream添加/集成到这个应用中”、“在我的Xcode项目中接入Chat/Video/Feeds”	B - 现有应用集成
“安装Stream包”、“在Xcode中配置Stream”、“搭建认证/令牌流程”且无更宽泛的功能需求	D - 初始化/配置
仅输入 `/stream-swift` 且无参数	简要列出所有处理路径并等待用户输入

Disambiguation flow

歧义处理流程

If the request is ambiguous between build/integrate and reference lookup, ask one short question and wait:

Do you want me to wire this into the project, or just map the Swift SDK pattern and files?

如果请求在构建/集成和参考查询之间存在歧义，提出一个简短问题并等待回复：

你希望我将功能接入项目中，还是仅为你梳理Swift SDK的模式和相关文件？

After classification

分类完成后

Tracks A, B, D -> run Project signals once per session, then continue in
```
builder.md
```
and
```
sdk.md
```
.
Track C -> skip the probe if the product + framework are explicit. Only run it on demand if the SDK or UI layer is ambiguous.

路径A、B、D → 每个会话运行一次项目信号检测，之后继续参考
```
builder.md
```
和
```
sdk.md
```
。
路径C → 如果产品和框架明确，则跳过探查。仅当SDK或UI层不明确时，按需执行探查。

Step 0.5: Credentials, token, and seed data (tracks A, B, D only)

步骤0.5：凭证、令牌和种子数据（仅适用于路径A、B、D）

Run this once per session, right after intent classification, before the Project signals probe.

在意图分类完成后、项目信号探查前，每个会话运行一次此步骤。

Goal

目标

Collect the Stream API key, a user token, and optionally seed a few channels - all before touching code - so the app has real data to show from the first run.

收集Stream的API密钥、用户令牌，可选创建几个频道——在接触代码前完成所有操作，确保应用首次运行即可显示真实数据。

Single upfront question (ask exactly once, then act immediately)

一次性前置问题（严格询问一次，然后立即执行操作）

Post one message asking all relevant things together. Do not split into multiple rounds.

For Chat projects:

To wire everything up with real data, I need a few quick answers:
Credentials - Should I fetch your API key from the dashboard and generate a token via the Stream CLI, or will you paste them yourself?
Token expiry - If I'm generating the token: should it expire? (e.g.
1h
,
1d
,
30m
) or never expire?
Seed channels - Should I pre-create a few channels with random usernames so the app has something to show immediately?
If you want to handle everything yourself, just paste your API key and token and tell me whether to seed channels.

For Feeds projects (no channel seeding - feed groups are configured in the dashboard):

To wire everything up with real data, I need a couple of quick answers:
Credentials - Should I fetch your API key from the dashboard and generate a token via the Stream CLI, or will you paste them yourself?
Token expiry - If I'm generating the token: should it expire? (e.g.
1h
,
1d
,
30m
) or never expire?
Feed groups - What feed groups do you need? (defaults:
user
,
timeline
,
notification
- tell me if you want different names)
If you want to handle everything yourself, just paste your API key and token and confirm the feed group names.

For Video projects (calls are ephemeral - no seeding needed):

To wire everything up, I need a couple of quick answers:
Credentials - Should I fetch your API key from the dashboard and generate a token via the Stream CLI, or will you paste them yourself?
Token expiry - If I'm generating the token: should it expire? (e.g.
1h
,
1d
,
30m
) or never expire?
If you want to handle everything yourself, just paste your API key and token.

发布一条消息，一次性询问所有相关内容，不要拆分多次提问。

针对Chat项目：

为了接入真实数据，我需要几个快速回复：
凭证 - 我应该从控制台获取你的API密钥并通过Stream CLI生成令牌，还是由你自行粘贴？
令牌有效期 - 如果由我生成令牌：是否设置有效期？（例如：
1h
、
1d
、
30m
）还是永久有效？
种子频道 - 是否需要我预创建几个带有随机用户名的频道，让应用立即有内容展示？
如果你希望自行处理所有内容，只需粘贴你的API密钥和令牌，并告知我是否需要创建种子频道。

针对Feeds项目（无需创建频道 - 订阅组在控制台配置）：

为了接入真实数据，我需要几个快速回复：
凭证 - 我应该从控制台获取你的API密钥并通过Stream CLI生成令牌，还是由你自行粘贴？
令牌有效期 - 如果由我生成令牌：是否设置有效期？（例如：
1h
、
1d
、
30m
）还是永久有效？
订阅组 - 你需要哪些订阅组？（默认：
user
、
timeline
、
notification
- 如有不同名称请告知）
如果你希望自行处理所有内容，只需粘贴你的API密钥和令牌，并确认订阅组名称。

针对Video项目（通话为临时会话 - 无需创建种子数据）：

为了完成接入，我需要几个快速回复：
凭证 - 我应该从控制台获取你的API密钥并通过Stream CLI生成令牌，还是由你自行粘贴？
令牌有效期 - 如果由我生成令牌：是否设置有效期？（例如：
1h
、
1d
、
30m
）还是永久有效？
如果你希望自行处理所有内容，只需粘贴你的API密钥和令牌。

After the user replies - act without further prompting

用户回复后 - 无需进一步提示直接执行

Once the user answers, execute all CLI steps in sequence without pausing for confirmation between them. Narrate each step briefly as you go (one line per action), but do not stop to ask "shall I continue?".

一旦用户回复，按顺序执行所有CLI步骤不要在步骤间暂停等待确认。执行每个步骤时简要说明（每个操作一行），但不要停下来询问“是否继续？”。

Step A - API key

步骤A - API密钥

bash

stream config get-app

Extract the

api_key

field. Hold it in context.

bash

stream config get-app

提取

api_key

字段并保存在上下文环境中。

Step B - Token

步骤B - 令牌

bash

undefined

bash

undefined

Never-expiring

永久有效

stream token <user_id>

Expiring

带有效期

stream token <user_id> --ttl <duration>


Hold the token in context. Use it (and the API key) in every code snippet - no placeholder strings.

stream token <user_id> --ttl <duration>


将令牌保存在上下文环境中。在所有代码片段中使用该令牌（和API密钥）——不要使用占位符字符串。

Step C - Seed channels (Chat projects only; only if the user said yes)

步骤C - 创建种子频道（仅Chat项目；仅当用户同意时执行）

Create 3-5 channels with random realistic usernames. Use

messaging

as the default channel type.

bash

undefined

创建3-5个带有随机真实用户名的频道。默认使用

messaging

频道类型。

bash

undefined

Create a channel and add members (repeat for each channel)

创建频道并添加成员（每个频道重复此命令）

stream chat channel create --type messaging --id <channel-id> --members <user1>,<user2>


Generate short memorable channel IDs (e.g. `general`, `random`, `team-alpha`) and use a small set of random usernames (e.g. `alice`, `bob`, `carol`, `dave`, `eve`). Make sure the token user is a member of at least one channel so they can see it on first launch.

After seeding, print a brief summary:

> Created channels: `general` (alice, bob), `random` (carol, dave), `team-alpha` (alice, eve)

stream chat channel create --type messaging --id <channel-id> --members <user1>,<user2>


生成简短易记的频道ID（例如：`general`、`random`、`team-alpha`），并使用一组随机用户名（例如：`alice`、`bob`、`carol`、`dave`、`eve`）。确保令牌所属用户至少是一个频道的成员，以便首次启动时可以看到该频道。

创建完成后，打印简要总结：

> 创建的频道：`general`（alice, bob）、`random`（carol, dave）、`team-alpha`（alice, eve）

Step D - Proceed automatically

步骤D - 自动继续

After all CLI steps succeed, move straight to Project signals and then into

builder.md

- no additional prompt needed. If any CLI step fails, explain the error briefly and ask the user to paste the missing value manually before continuing.

所有CLI步骤成功完成后，直接进入项目信号检测，然后参考

builder.md

——无需额外提示。如果任何CLI步骤失败，简要说明错误并要求用户手动粘贴缺失的值后再继续。

What NOT to do

禁止操作

Never put the API secret in app code - the CLI uses it server-side only.
Never invent or fabricate credentials.
Never ask "should I continue?" between Step A, B, C, and D - execute the whole sequence once the user's upfront answers are in.

切勿在应用代码中放入API密钥——仅在服务器端通过CLI使用。
切勿编造或伪造凭证。
在步骤A、B、C、D之间切勿询问“是否继续？”——用户给出前置回复后，执行整个流程。

Project signals (tracks A/B/D - once per session; Track C on demand only)

项目信号检测（路径A/B/D - 每个会话一次；路径C按需执行）

Read-only local probe. Use it to detect whether the user is in an Xcode project, a Swift package, or an empty directory.

bash

bash -c 'echo "=== XCODE ==="; find . -maxdepth 3 \( -name "*.xcodeproj" -o -name "*.xcworkspace" \) -print 2>/dev/null; echo "=== MANIFESTS ==="; find . -maxdepth 3 \( -name "Package.swift" -o -name "Package.resolved" -o -name "Podfile" \) -print 2>/dev/null; echo "=== EMPTY ==="; test -z "$(ls -A 2>/dev/null)" && echo "EMPTY_CWD" || echo "NON_EMPTY"'

Hold the result in conversation context. Don't re-run it unless the user changes directory or the project shape clearly changed.

Use the result to produce a one-line status, for example:

SwiftUI app detected - MyApp.xcodeproj - ready for Stream wiring

UIKit workspace detected - Podfile present - preserve existing package manager

No Xcode project found - user needs to create the app in Xcode first

只读本地探查。用于检测用户当前处于Xcode项目、Swift包还是空目录。

bash

bash -c 'echo "=== XCODE ==="; find . -maxdepth 3 \( -name "*.xcodeproj" -o -name "*.xcworkspace" \) -print 2>/dev/null; echo "=== MANIFESTS ==="; find . -maxdepth 3 \( -name "Package.swift" -o -name "Package.resolved" -o -name "Podfile" \) -print 2>/dev/null; echo "=== EMPTY ==="; test -z "$(ls -A 2>/dev/null)" && echo "EMPTY_CWD" || echo "NON_EMPTY"'

将结果保存在对话上下文中。除非用户切换目录或项目结构明显变化，否则不要重新运行。

根据结果生成一行状态说明，例如：

检测到SwiftUI应用 - MyApp.xcodeproj - 已准备好接入Stream

检测到UIKit工作区 - 存在Podfile - 保留现有包管理器

未找到Xcode项目 - 用户需要先在Xcode中创建应用

Module map

模块映射

Track	Module(s)
A - New app	`builder.md` + `sdk.md` + relevant reference files
B - Existing app	`builder.md` + `sdk.md` + relevant reference files
C - Reference lookup	`sdk.md` + relevant reference files
D - Bootstrap / setup	`builder.md` + `sdk.md`

处理路径	模块
A - 新建应用	`builder.md` + `sdk.md` + 相关参考文件
B - 现有应用集成	`builder.md` + `sdk.md` + 相关参考文件
C - 参考查询	`sdk.md` + 相关参考文件
D - 初始化/配置	`builder.md` + `sdk.md`

Reference layout

参考文件结构

Shared Swift/iOS patterns live in sdk.md
.

Product and framework specifics live under references/
using a flat naming scheme that can grow with the full Stream Swift surface:

Reference:
```
references/<PRODUCT>-<FRAMEWORK>.md
```

Blueprints:

references/<PRODUCT>-<FRAMEWORK>-blueprints.md

Current extracted modules:

Chat + SwiftUI:

references/CHAT-SWIFTUI.md

references/CHAT-SWIFTUI-blueprints.md

Chat + UIKit:

references/CHAT-UIKIT.md

references/CHAT-UIKIT-blueprints.md

Video + SwiftUI:

references/VIDEO-SWIFTUI.md

references/VIDEO-SWIFTUI-blueprints.md

Video + UIKit:

references/VIDEO-UIKIT.md

references/VIDEO-UIKIT-blueprints.md

Combined Chat + Video (SwiftUI or UIKit):
```
references/COMBINED-CHAT-VIDEO.md
```

Feeds (SwiftUI or UIKit):

references/FEEDS-SWIFTUI.md

references/FEEDS-SWIFTUI-blueprints.md

Feeds has no pre-built UI components.
FEEDS-SWIFTUI.md
covers SDK patterns for both SwiftUI and UIKit - only the view layer differs. Load both files for any Feeds request.

Future Swift product coverage should stay in this naming family instead of creating more top-level skills.

通用Swift/iOS模式存放在**

sdk.md

**中。

产品和框架的具体内容存放在**

references/

**目录下，采用扁平化命名规则，可随Stream Swift的完整功能扩展：

参考文件：
```
references/<PRODUCT>-<FRAMEWORK>.md
```

视图蓝图：

references/<PRODUCT>-<FRAMEWORK>-blueprints.md

当前已提取的模块：

Chat + SwiftUI：

references/CHAT-SWIFTUI.md

references/CHAT-SWIFTUI-blueprints.md

Chat + UIKit：

references/CHAT-UIKIT.md

references/CHAT-UIKIT-blueprints.md

Video + SwiftUI：

references/VIDEO-SWIFTUI.md

references/VIDEO-SWIFTUI-blueprints.md

Video + UIKit：

references/VIDEO-UIKIT.md

references/VIDEO-UIKIT-blueprints.md

Chat + Video 组合（SwiftUI或UIKit）：
```
references/COMBINED-CHAT-VIDEO.md
```

Feeds（SwiftUI或UIKit）：

references/FEEDS-SWIFTUI.md

references/FEEDS-SWIFTUI-blueprints.md

Feeds无预构建UI组件。
FEEDS-SWIFTUI.md
涵盖SwiftUI和UIKit的SDK模式——仅视图层不同。处理任何Feeds请求时需加载这两个文件。

未来Swift产品的覆盖内容应沿用此命名规则，而非创建更多顶级技能。

Track A - New app

路径A - 新建应用

Full detail:

builder.md

- use the new-project path.

Phase	Name	What you do
A1	Detect	Run Project signals. If there is no iOS app yet, tell the user to create one in Xcode first.
A2	Choose lane	Confirm product(s) and UI layer: SwiftUI, UIKit, or mixed.
A3	Install + wire	Follow `builder.md` + `sdk.md` , then load only the needed product references.
A4	Verify	Confirm package resolution, client lifetime, auth, and first rendered screen.

详细内容：

builder.md

- 使用新项目流程。

阶段	名称	操作内容
A1	检测	运行项目信号检测。如果尚未创建iOS应用，告知用户先在Xcode中创建。
A2	选择方向	确认产品和UI层：SwiftUI、UIKit或混合模式。
A3	安装与接入	遵循 `builder.md` + `sdk.md` ，然后仅加载所需的产品参考文件。
A4	验证	确认包解析、客户端生命周期、认证和首屏渲染正常。

Track B - Existing app

路径B - 现有应用集成

Full detail:

builder.md

- use the existing-project path.

Phase	Name	What you do
B1	Detect	Run Project signals and inspect the existing app structure before editing.
B2	Preserve	Keep the current UI layer, package manager, and navigation architecture unless the user asks for a migration.
B3	Integrate	Use `sdk.md` for shared wiring, then load only the needed product reference files.
B4	Verify	Confirm the requested Stream flow builds and renders inside the existing app.

详细内容：

builder.md

- 使用现有项目流程。

阶段	名称	操作内容
B1	检测	运行项目信号检测并在编辑前检查现有应用结构。
B2	保留现有配置	保留当前UI层、包管理器和导航架构，除非用户要求迁移。
B3	集成	使用 `sdk.md` 完成通用接入，然后仅加载所需的产品参考文件。
B4	验证	确认请求的Stream流程在现有应用中可正常构建和渲染。

Track C - Reference lookup

路径C - 参考查询

Load only the relevant files for the requested product and UI layer.

Shared lifecycle / auth / state patterns ->
```
sdk.md
```
Chat SwiftUI setup and gotchas ->
```
references/CHAT-SWIFTUI.md
```
Chat SwiftUI view structure ->
```
references/CHAT-SWIFTUI-blueprints.md
```
Chat UIKit setup and gotchas ->
```
references/CHAT-UIKIT.md
```
Chat UIKit view controller structure ->
```
references/CHAT-UIKIT-blueprints.md
```
Video SwiftUI setup and gotchas ->
```
references/VIDEO-SWIFTUI.md
```
Video SwiftUI view structure ->
```
references/VIDEO-SWIFTUI-blueprints.md
```
Video UIKit setup and gotchas ->
```
references/VIDEO-UIKIT.md
```
Video UIKit view controller structure ->
```
references/VIDEO-UIKIT-blueprints.md
```
Combined Chat + Video (collision table, file isolation, UIKit + SwiftUI blueprints) ->
```
references/COMBINED-CHAT-VIDEO.md
```
Feeds SDK patterns (setup, FeedState, activities, reactions, comments, follow, notifications) ->
```
references/FEEDS-SWIFTUI.md
```
Feeds SwiftUI view blueprints (timeline, row, composer, comments, profile, notifications) ->
```
references/FEEDS-SWIFTUI-blueprints.md
```

仅加载所需产品和UI层的相关文件。

通用生命周期/认证/状态模式 →
```
sdk.md
```
Chat SwiftUI配置与注意事项 →
```
references/CHAT-SWIFTUI.md
```
Chat SwiftUI视图结构 →
```
references/CHAT-SWIFTUI-blueprints.md
```
Chat UIKit配置与注意事项 →
```
references/CHAT-UIKIT.md
```
Chat UIKit视图控制器结构 →
```
references/CHAT-UIKIT-blueprints.md
```
Video SwiftUI配置与注意事项 →
```
references/VIDEO-SWIFTUI.md
```
Video SwiftUI视图结构 →
```
references/VIDEO-SWIFTUI-blueprints.md
```
Video UIKit配置与注意事项 →
```
references/VIDEO-UIKIT.md
```
Video UIKit视图控制器结构 →
```
references/VIDEO-UIKIT-blueprints.md
```
Chat + Video组合（冲突表、文件隔离、UIKit + SwiftUI蓝图） →
```
references/COMBINED-CHAT-VIDEO.md
```
Feeds SDK模式（配置、FeedState、活动、互动、评论、关注、通知） →
```
references/FEEDS-SWIFTUI.md
```
Feeds SwiftUI视图蓝图（时间线、行、编辑器、评论、个人资料、通知） →
```
references/FEEDS-SWIFTUI-blueprints.md
```

Track D - Bootstrap / setup

路径D - 初始化/配置

Use when the user wants the install and wiring path more than a feature build:

detect the project shape
choose SwiftUI vs UIKit ownership
install Stream packages with the project's existing package strategy
wire auth and client lifetime via
```
sdk.md
```
stop before product-specific UI if the user only asked for setup

适用于用户更关注安装和接入流程而非功能构建的场景：

检测项目结构
确定使用SwiftUI还是UIKit
使用项目现有包策略安装Stream包
通过
```
sdk.md
```
搭建认证和客户端生命周期
如果用户仅要求配置，则在完成产品特定UI前停止操作