stream-swift

iOS 向け Stream Swift - ドキュメントオーケストレーター

このスキルは、意図的に小規模にしています。SDK リファレンスのダンプは同梱していません。公式の iOS ドキュメントが信頼できる情報源であり、Chat、Video、Feeds、SwiftUI と UIKit、投票、下書き、音声、AI、プッシュ通知、画面共有、CallKit、SIP、文字起こし、モデレーションなど、あらゆる機能を網羅しています。

あなたの役割はオーケストレーションです。リクエストを分類し、正確なドキュメントページを示し、その内容を最新の状態で取得して、厳選されたルールとドキュメントでは強調されていない落とし穴を守りながら、ユーザーのプロジェクトに適用します。

ルール（セッションごとに一度お読みください）： RULES.md - 遵守必須のルールと iOS の落とし穴です。コードを書く前にお読みください。

---

ドキュメントの規約（中核となる仕組み）

Stream の各ドキュメントページには、コーディングエージェントが直接読み取れる Markdown 版があります。ページの URL から末尾の / を削除し、.md を追加してください。

https://getstream.io/chat/docs/sdk/ios/basics/integration/   ->   https://getstream.io/chat/docs/sdk/ios/basics/integration.md

常に .md 版を取得してください。ページの装飾がなく、コードをそのまま含む、すっきりした Markdown です。

製品ごとのインデックスページには、各ドキュメントページとその .md URL が一覧表示されています。ページを見つけたり、確認したりするために、これらを取得してください。

製品	ライブインデックス（常に最新）	ページ URL の形式
Chat（iOS SDK：UI + State Layer）	https://getstream.io/cli/docs/chat-sdk-ios.md	https://getstream.io/chat/docs/sdk/ios/...md
Chat（低レベルクライアント API リファレンス）	https://getstream.io/cli/docs/chat-ios-swift.md	https://getstream.io/chat/docs/ios-swift/...md
Video	https://getstream.io/cli/docs/video-ios.md	https://getstream.io/video/docs/ios/...md
Feeds	https://getstream.io/cli/docs/activity-feeds-ios.md	https://getstream.io/activity-feeds/docs/ios/...md

URL の根拠： docs-map.md またはこの会話でライブインデックスを取得して得たページ URL のみを取得してください。記憶に頼ってドキュメントパスを推測しないでください。一見正しそうでも、実際には間違っているパスが多くあります。ページがマップにない場合は、ライブインデックスを取得し、そこから選んでください。

---

ステップ 0：リクエストを分類する（必ず最初に行う）

ユーザーの言葉だけをもとに、次の 3 つを判断してください。

1. プロダクト - チャット、ビデオ、フィード、またはその組み合わせです。
2. フレームワーク - SwiftUI、UIKit、または混在（ユーザーが新規に始める場合で、指定がない場合はSwiftUIをデフォルトにします）。
3. モード - 次のいずれかです。
   • 使い方 / リファレンス（「リアクションを追加するには？」「CallViewModelは何をしますか？」「テーマ設定」）-> ドキュメントの検索に進みます。セットアップも認証情報も不要です。
   • 統合（「アプリにChatを追加する」「このプロジェクトにVideoを組み込む」）-> セットアップ（setup.md）を実行してから、機能のドキュメントを検索します。
   • 新規アプリ（「ライブ配信アプリを作る」「新しいSwiftUIチャットアプリ」）-> セットアップを実行してから、リクエストされた画面に絞ってドキュメントを検索します。
   • Sendbirdからの移行（「アプリをSendbirdからStreamに移行する」「Sendbird Chat SDKをStreamに置き換える」「Sendbird / SendbirdUIKit / SendbirdSwiftUIから切り替える」）-> sendbird-migration.mdを実行します。既存のSendbird統合の形を特定し、パッケージと初期化処理を置き換え、アプリのコードをできるだけ変更せずに、各接点をStream向けに再実装してから、テーマを再適用し、Sendbirdの元の画面と照らし合わせて、画面ごとにデザインと機能の忠実性を検証します。この手順書では、SetupのCLI認証情報フロー（setup.md）と、design-matching.mdの画面領域ごとの厳密な検証方法を再利用します。この手順書の対象はコード / SDKの移行です。完了して検証した後、Sendbirdのデータ（ユーザー、チャンネル、メッセージ履歴、リアクション）も移行するかどうかを確認し、希望する場合は、言語共通のデータ移行手順書../stream/sendbird-data-migration.md（§10）に引き継ぎます。
   • AIアシスタント / LLM / エージェント（「ChatGPT風のアプリを作る」「AIアシスタント / サポートボット / コパイロットを追加する」「LLMのレスポンスをストリーミングする」「思考中インジケーター」「生成を停止する」「モデルの出力をMarkdownで表示する」「エージェントの推論 / ツール呼び出しを表示する」「エージェントが動作する前に確認を求める」「エージェントがデバイス上のツールを呼び出せるようにする」、MCP、「音声エージェントの文字起こしを表示する」「音声エージェントとの会話内容をチャットビューで表示する」）-> ai-integration.mdを実行します。まず、使用するStreamChatAIを決定します（5.13.0以降のstream-chat-swiftに含まれるため、バージョンの更新を提案します。スタンドアロンのstream-chat-swift-aiパッケージは代替手段です）。次に、構成（AIファーストのアプリ、既存メッセンジャー内のボット、手順を表示して事前に確認を求めるエージェント、デバイス側のツール、音声エージェントの文字起こし）を分類し、モデルはバックエンドのエージェントで動作させ（アプリ内にLLMキーを置かないでください）、会話は主な方法であるAIConversationViewで表示します。ほかのStreamChatAIコンポーネント（AIComposerView、AIMessagePartsView、AIToolApprovalView、AIClientToolRunner、SuggestionsView）も組み込みます。別の方法として、これらのコンポーネントを組み込んだ、ビルド済みのStreamChatSwiftUIメッセージリストを使用できます。これは、メッセンジャー機能が必要な会話や、既存のメッセンジャー内のアシスタントに適しています。アプリが文字起こしをチャットとして表示するVideo通話中の音声エージェントも、ここに該当します（構成E）。1人が1つのエージェントと会話する場合、文字起こしは自作の吹き出しリストではなく、AIConversationView（5.15.0）で表示します。統合 / 新規アプリの場合は、先にセットアップを実行します。1つのAIコンポーネントに関する単純な使い方の質問は、ドキュメントの検索（docs-map.mdの「Chat - AI integrations」）に進みます。
   • プッシュ通知のセットアップ（「チャットのプッシュ通知を追加する」「通話時に着信でアプリを起動する」、VoIP、CallKit）-> push.mdを実行します。CLIでStreamのプッシュプロバイダーを作成し、クライアントの機能とコードを組み込みます。Setupと同様に、Stream CLIを使用します。 styling-depth フラグもあります。これは上記のモードとは独立しています。リクエストに目標とする見た目（添付されたスクリーンショット、Figma のリンク、または「WhatsApp／iMessage／Telegram／Slack／ のような見た目にする」など）が含まれている場合は、Docs を参照する前に、領域ごとに再現してください。Chat では、まず以下の戦略決定（コンポーネントかカスタムか）を実行します。コンポーネントに決まった場合は design-matching.md を実行し、カスタム（ライブ配信／オーバーレイ／オーダーメイド）に決まった場合は、代わりに custom-ui.md を実行してください。領域ごとに厳密に照合する点は同じですが、仕組みが異なります。この段落の残りはコンポーネントの場合（一般的なケース）について説明します。参照デザインは、領域（ヘッダー、コンポーザーのボタン、タイムスタンプと既読通知の位置、吹き出しの形状やしっぽ、日付区切り、添付ファイルなど）のチェックリストです。その多くは色だけでなく、構造的に Stream のデフォルトと異なります。壁紙と吹き出しの色を変えただけで終わらせないでください。これは既知の失敗パターンです。まず各領域を分解し、色だけでなく寸法も記録してから、それぞれを次の3 つの軸のいずれかに振り分けてください。テーマトークン（Appearance）、Styles モディファイア（パディング／インセット／角丸／装飾用。factory.styles）、または ViewFactory スロット（構造）です。パディングをテーマに割り当てたり、構造を色で解決したりすることが、根本的な失敗につながります。ドキュメントで注意を促している、繰り返し発生する落とし穴は次のとおりです。(1) makeMessageItemView、ヘッダー、コンポーザー、makeComposerInputTrailingView などの複合スロットをオーバーライドすると、デフォルトで描画されていたサブ機能（受信メッセージのアバター、グループ化、リアクション、返信、ステータス、送信／音声／編集／スローモードのボタン）が暗黙のうちに失われます。デフォルトの body を読み、その機能を再現しない限り、これらは表示されません。(2) チャンネルヘッダーのモディファイアは、コンポーザーの上にあるディバイダーに適用されるため、そこに safeAreaInset／VStack でヘッダーを描画すると、下部に表示されます。代わりに .toolbar の配置を使い、1 つのチャンネルのヘッダーをアプリのルートで偽装しないでください。(3) コンポーザーの送信／音声ボタンは入力欄の内側にあります（makeComposerInputTrailingView）。そのため、ボタンを入力欄の右側に移動するにはレイアウト変更が必要であり、makeTrailingComposerView だけでは不十分です。(4) 吹き出し／コラージュのパディングはテーマではなく Styles です（makeMessageAttachmentsViewModifier）。ビルドして実行し、各領域を表示させるデータを投入したうえで、実際のナビゲーション経路を通って参照デザインと領域ごとに比較し、調整するまで、マッチングは完了していません（design-matching.md のステップ 5）。一時的な検証用の仕組みは必ず元に戻してください。UI は参照デザインにだいたい似ているだけではなく、可能な限り忠実でなければなりません。コンポーザーも含め、すべての領域を実装してください。残りの領域を「既知の見た目上の差」として残した、不完全な一致を納品してはいけません。SDK のデフォルトのまま残った領域は注記では済まず、FAIL です。そして、速さを保つため、作業はまとめて進めてください。固定した SDK バージョンとチェックアウトを一度確認し、必要なソースを一度にすべて読み、すべての領域を実装してから、固定したシミュレーター 1 台に対し、永続的な -derivedDataPath を指定して一度だけビルドします。小さな編集のたびにビルドしてスクリーンショットを撮り直すのは避けてください（design-matching.md の「作業をまとめて進める」を参照）。

プロダクトとフレームワークが明確な場合、探りを入れずに進めてください。「組み込んでほしい」のか「説明だけしてほしい」のか本当に曖昧な場合は、短い質問を 1 つしてください。

これをプロジェクトに組み込みますか？ それともドキュメントのページとパターンを整理するだけにしますか？

チャットのみ：コードを書く前に、まずUI戦略を決めます

Stream Chat には 2つのレイヤーがあり、どちらを選ぶかは、どのスタイルを選ぶかよりはるかに重要なアーキテクチャ上の決定です。間違えると、どちらの場合も1日を無駄にします。慎重に判断し、基本的にはビルトインコンポーネントを選んでください。

戦略	デザインが次のような場合に使用	仕組み	手順書
ビルトインUIコンポーネント（StreamChatSwiftUI / StreamChatUI）— デフォルト	メッセンジャー：吹き出し、またはチャンネルリストから会話への遷移、あるいはメッセージごとのアバター／タイムスタンプ／既読通知／リアクション／添付ファイル。ソーシャル、マーケットプレイス、職場、サポート、DM。「WhatsApp / iMessage / Telegram / Slack のような見た目にする」。	テーマ設定 + ViewFactory + Styles でカスタマイズ	design-matching.md
低レベルクライアント + State Layer によるカスタムUI — 例外	メッセンジャーではないもの：吹き出しがなく、投稿者情報が本文内に表示されるフラットなフィード、動画上のオーバーレイ／ティッカー、大量の一時的なライブ配信チャット（Twitch / YouTube / Kalshi）、ライブショッピング。すべてのメッセージが同じように表示され、アプリ独自の画面要素で囲まれている。	StreamChat 上に直接 SwiftUI を構築（必要に応じて StreamChatCommonUI を使用）；StreamChatSwiftUI は使用しない	custom-ui.md

コンポーネントを強く優先してください。 コンポーネントは カスタマイズできるように作られています。判断基準は、テーマ設定 + いくつかの ViewFactory スロット + Styles で実現できるなら、コンポーネントを使うべきということです。WhatsApp のような大幅な外観変更でも同じです。カスタムUIを選ぶのは、デザインを再現するためにメッセージ行、入力欄、ヘッダー、リストを一度にすべて置き換える必要がある場合だけにしてください。つまり、SDK のビューを使わず、データソースとしてだけ使う場合です。カスタムを選びすぎる（アバター／グループ化／リアクション／スレッド／添付ファイル／入力中表示／既読通知／ピッカーを失い、より劣ったメッセンジャーを手作業で再構築する）のは、よくある高くつく失敗です。一方、コンポーネントを選びすぎた場合にかかるのは、レイアウト調整に数時間です。迷ったら、まずコンポーネント版を作ってください。確認や却下をより早く判断できます。判断材料の詳細と基準については、custom-ui.md のステップ0を参照してください。

職場向け／Slack風のハイブリッドもコンポーネントで対応します。通常は Liquid Glass を使います。 Slack／Teams／Discord の画面は、チャンネルリスト + メッセージリスト + 入力欄で構成されるため、ビルトインコンポーネントを使います。ただし、メッセンジャーとは異なる次の2点は、後回しにせず再現する必要があります。（1）メッセージ行はフラットで左揃え（上部にアバターを配置した角丸の四角形、投稿者名・カスタムステータス・タイムスタンプを並べたヘッダー行、本文、下部のリアクションピル、スレッド返信の概要）で、受信／送信の吹き出しの区別はありません。makeMessageItemView（複合スロット）をオーバーライドして再現します（そのサブ機能も再現してください）。（2）ヘッダーと画面要素はカスタムで、通常はガラス調です。SDK に用意されている Liquid Glass の外観を推奨します（factory.styles = LiquidGlassStyles()。半透明デザインやフローティング入力欄向けの Styles 軸の基準で、iOS 26+/Swift 6.2+ で描画されます）。職場向けアプリではスレッドが中心となるため、スレッド返信用スロットとスレッドリストも設定してください。アーキタイプと Liquid Glass の仕組みの詳細については、design-matching.md を参照してください。

この戦略によって、チャンネルタイプと権限モデルも決まります（例：ソーシャル／マーケットプレイスではメンバーシップで制限する messaging、ライブ配信では公開で匿名視聴者を許可する livestream）。RULES.md の「Permissions」を参照してください。両方の軸を合わせて決めてください。

本当に判断がつかない場合は、次の質問を1つだけしてください。

このチャットは標準的なメッセンジャー（チャンネルリスト + 吹き出し）のようなものですか。それとも、ライブ配信／オーバーレイチャットのような独自の画面ですか。この答えによって、ビルトインコンポーネントをカスタマイズするか、低レベルクライアント上にカスタムUIを構築するかが決まります。

---

ステップ 1：ドキュメントの検索（すべてのリクエストはここで終了します）

1. docs-map.md を開きます。製品＋フレームワーク＋機能に一致する行を探すと、正確な .md URL がわかります。
2. 機能がマップにない場合は、製品のライブインデックス（上の表）を取得し、最も一致するページを選びます。
3. WebFetch で .md ページを取得します。1 回のリクエストで取得できるページは最大 3 件です。それ以上必要な場合は、インデックス URL をユーザーに提示します。
4. ページのガイダンスをユーザーのプロジェクトに適用します。可能な限りコードをそのまま使い、既存アプリの構成（ライフサイクル、ナビゲーション、パッケージマネージャー）に合わせる場合に限って変更します。
5. 使用したページを必ず引用します：Source: [Title](https://getstream.io/...)。トレーニングデータから SDK の詳細を回答してはいけません。この会話中にページを取得していない場合は、今取得するか、見つけられなかったと伝えます。
6. ドキュメントで十分に説明されていない場合（特定の UI カスタマイズ、正確な ViewFactory シグネチャ、未ドキュメントのオプション、実際の接続方法など）は、SDK のソースコードとサンプルアプリに進みます（docs-map.md の「When the docs fall short」を参照）。ソースが最終的な根拠となるため、プロジェクトで実際に固定されているバージョンを読み、ドキュメントに記載されているかのように説明するのではなく、どこで確認したかを伝えます。リファレンスデザインとの一致では、この手順が例外ではなく原則です。約 100 件ある ViewFactory のスロットのほとんどは未ドキュメントのため、ViewFactory.swift（すべてのスロット）、DefaultViewFactory.swift（各スロットがレンダリングする内容）、関連する Options/*.swift を読みます。各領域に対応するスロットと grep コマンドは design-matching.md に記載されています。複合スロットをオーバーライドする場合は、そのスロットが返すデフォルトのビュー（例：makeMessageItemView の MessageContainerView）も読み、レンダリングされるサブ機能をすべて確認します。そうすることで、機能を黙って削除するのではなく、再現できます。
7. ベストプラクティスを適用します。 RULES.md の「Mindful API usage」に従って API を適切に使います。queryChannels を過剰に呼び出さず、レンダリングループを避け、認証は 1 回だけ行います。また、規模を拡大する前に、その分野のベストプラクティスページ（例：ライブ配信）を読みます。

---

セットアップ（統合／新規アプリのみ）

モードが「統合」または「新規アプリ」の場合は、機能の作業を始める前に、セッションごとに setup.md を 1 回実行します。次の手順を順番に行います。

1. プロジェクトの状況を確認 - Xcode プロジェクト、Swift パッケージ、Podfile、空のディレクトリのいずれかを検出します。
2. 認証情報 - Stream CLI（またはユーザーから提供された情報）を使って API キーとユーザートークンを取得します。シードチャンネルの設定は任意です。
3. インストール - プロジェクトで既に使われているパッケージマネージャーを使って、適切な Stream パッケージを追加します。
4. クライアントを接続 - アプリの起動時に一度だけ初期化し、ユーザーを接続します。

その後、ここに戻って対象画面のドキュメントを検索します。

iOS プロジェクトがまったくない場合は、CLI でプロジェクトを作成しないでください。まず Xcode でアプリを作成するようユーザーに伝えてから続行します。

---

このスキルに含まれなくなったもの

references/*.md の設計図ファイルはありません。以前そこにあった内容はすべて、マップを通じてライブドキュメントから取得します。これにより、スキルは自動的に最新の状態に保たれ、以前同梱されていたセットよりも幅広く対応できます。厳選されたドキュメント以外の内容は、RULES.md（ルールと注意点）、setup.md（CLI 主導のセットアップフロー）、push.md（プッシュ／VoIP／CallKit 向けの CLI とコードの手順書。ドキュメントに説明があるだけの処理を自動化します）、ai-integration.md（AI アシスタントとエージェント：ドキュメントではサンプルアプリに委ねられている StreamChatAI の接続方法と、共有バックエンド契約 ../stream/ai-backend-contract.md）、design-matching.md（ビルド済みコンポーネントを使って参照デザインを再現するための手順と、領域から ViewFactory のスロットへの対応マップ）、custom-ui.md（カスタム低レベルパスの手順：コンポーネントとカスタムの選択、および StreamChat クライアントと State Layer 上にライブ配信／独自の画面を構築する方法）、sendbird-migration.md（再現可能な Sendbird から Stream Chat への移行手順：統合形態を検出し、パッケージ／初期化／ビュー／チャンネル／メッセージを切り替え、各画面で移行元アプリのデザインを再現します）だけです。中央の 2 つのファイルは、両方の Chat UI 戦略を扱います。どちらを使うかは SKILL.md の判断フローで決まります。