sealos-app-builder

Sealos App Builder

アイデンティティとディスカバリー

• オーナー： sealos-app-builder（/sealos-app-builder および Sealos Desktop アプリ、SDK、iframe、チュートリアル、公開に関するリクエスト）。
• クラス： アプリ／ドキュメント作業では local-artifact-mutation。リクエストがあった場合は、検証済みアプリを sealos-deploy に引き渡します。
• カナリア： APP-CODE-TUTORIAL、APP-SDK-SOURCE、APP-DESKTOP-VERIFY、APP-PUBLISH-HANDOFF。

スコープと境界

編集前に、作成、適応、アイデンティティ統合、チュートリアルのどれに該当するかを分類します。まずローカルの SDK ソースとプロバイダーアプリを調査します。SDK の初期化はクライアント側のみで行い、ビジネスデータはアプリ内に保持し、Desktop 外でのフォールバック動作を明示してください。担当する成果物はプロジェクトコード、パッケージメタデータ、チュートリアルです。Desktop の証拠を得た後に限り、公開を完了したとします。

エントリーコントラクトは次のとおりです。

request -> classify(create|adapt|identity|tutorial) -> inspect local SDK/provider sources
         -> load branch references -> implement or document -> verify -> report terminal state

リクエストごとに 1 つのブランチを使用します。コードかチュートリアルかの判断が曖昧な場合は、ブランチ固有の編集に着手する前に停止します。ローカルの SDK ソースと既存のプロバイダーアプリを汎用パッケージリファレンスより優先し、ローカルソースがない場合は公式パッケージをフォールバックとして使用します。

リスクと確認

ローカルソースを利用できない場合は公式 SDK パッケージを使用し、既存のインストール／ツール確認の境界に従います。セッション、認証、データベース、環境、SDK の診断情報は必ず秘匿化してください。サーバー側での SDK 初期化、Desktop 外でのフォールバックの欠如、未検証の Desktop iframe がある場合は、リクエストを停止します。チュートリアルの結果にはチュートリアルの証拠を、ブラウザーのレンダリングにはブラウザーの証拠を付与します。

ライフサイクルのワークフロー

リクエストごとに、ブランチを特定し、ソースを調査して、SDK とアイデンティティを統合します。該当する場合は実際の Desktop iframe を検証し、公開への引き継ぎを準備します。リクエスト単位で branch、evidence、redaction、next_action フィールドを含む success、stopped、または error を出力します。success はブランチの成果物を証明します。stopped は不足している前提条件と安全な次のアクションを示します。error にはサニタイズ済みの診断情報と復旧アクションを含めます。

段階的な開示

エントリー境界を選択した後に、ブランチ固有のリファレンス（minimal-app-template、フレームワークでの配置、データ統合、ローカルテストアプリ、公開チェックリスト）のみを読み込みます。実際の SDK サーフェスを維持し、サーバー側からの SDK 呼び出しを避けてください。コードブランチでは、フレームワークとローカルソースの調査が済んでからスターターを読み込みます。

出力、停止、エラーの状態

• success：ブランチ固有のソース／チュートリアルの成果物、SDK／セッション／言語の接続、Desktop 外でのフォールバック、および申告する場合は実際の Desktop／公開の証拠。
• stopped：コードかチュートリアルかの判断の曖昧さ、SDK ソースの不足、サーバー側での初期化、フォールバックの欠如、または Desktop／公開の証拠の不足。安全な次のアクションを示し、公開を完了したとは申告しません。
• error：SDK ソースとパッケージの不一致、セッション／ランタイム、または公開の前提条件の失敗。サニタイズ済みの診断情報と復旧アクションを含めます。

すべての結果に terminal_state: success|stopped|error、branch、evidence、redaction: passed|failed、next_action を記録します。セッション値、認証情報、環境値の全体は結果のテキストに含めません。

引き継ぎ

直接のリクエストでは、型付きの引き継ぎとして target: sealos-deploy、inputArtifact: verified app source plus Desktop, identity, language, business-data, and release evidence、allowedAction: deploy after app verification、failureReturn: sanitized SDK, iframe, or publish-prerequisite diagnostic、responseOwner: sealos-app-builder を送信します。デプロイの担当者は、自身のランタイムゲートを再確認します。チュートリアルおよびブラウザーのみのブランチでは、target: none を返します。

検証

実際の Desktop iframe チェックリストと、ベースラインケース app-builder-positive-sdk-iframe-publish および app-builder-violating-tutorial-or-missing-desktop を使用してください。クライアント側のみで初期化が1回だけ行われること、セッションの ID マッピング、言語同期、フォールバック、公開前提条件を、セッション値を公開せずに確認してください。スターターのリンクと共有サービスの契約は、python3 scripts/test_service_skill_contract.py で確認してください。

概要

このスキルを使うと、一般的な Web アプリを Sealos Desktop 内で動作する Sealos アプリにしたり、新しい Sealos アプリをゼロから構築したりできます。SDK の初期化、セッションへのアクセス、言語同期、ビジネスデータの統合、Desktop テストアプリを使ったローカルデバッグ、公開準備など、繰り返し行う作業に重点を置いています。

初心者にも理解しやすく、拡張しやすい、シンプルで説明しやすい実装を優先してください。

基本的なワークフロー

1. 出発点を特定する

依頼を次のいずれかに分類してください。

1. Sealos アプリをゼロから新規作成する。
2. 既存の Web アプリを Sealos Desktop 内で動作するように適応させる。
3. すでにレンダリングされるアプリに、Sealos の ID とビジネスデータの統合を追加する。
4. コードを変更する代わりに、ドキュメントやチュートリアルを作成する。

リポジトリに Sealos 関連のコードがすでに含まれている場合は、まずローカルのソースを調べてください。特に、次の点を確認してください。

1. packages/client-sdk または同等の SDK ソースを探します。
2. providers/ などのディレクトリにある既存のプロバイダーアプリを探します。
3. リポジトリですでに確立されているフレームワークとルーティングのパターンがあれば、それを再利用します。

リポジトリに Sealos のローカルソースが含まれていない場合は、このスキルに同梱されているリファレンスを基準として使用してください。

2. Sealos アプリ SDK を統合する

Sealos Desktop との統合は、ルートレベルの関心事として扱ってください。

スターターテンプレートを使う前に、まず SDK をインストールしてください。

pnpm add @labring/sealos-desktop-sdk

プロジェクトで別のパッケージマネージャーを使用している場合は、npm install @labring/sealos-desktop-sdk または yarn add @labring/sealos-desktop-sdk を使用してください。

1. クライアント専用のルートコンポーネントで createSealosApp() を1回だけ呼び出します。
2. 早い段階で getSession() と getLanguage() を取得します。
3. セッション、言語、読み込み状態、Desktop の利用可否を、共有コンテキストまたはストアに保存します。
4. 実行時の言語同期が必要な場合は、EVENT_NAME.CHANGE_I18N を通じて言語変更を監視します。
5. Sealos Desktop の外部でアプリが開かれた場合に、適切なフォールバックを追加します。

ルート統合を実装する前に、references/minimal-app-template.md を読んでください。 アプリが Next.js App Router を使用している場合は、references/nextjs-app-router.md も読んでください。

次のいずれかのスターターテンプレートを使用してください。

1. React 用の assets/templates/react/sealos-provider.tsx。
2. Vue 用の assets/templates/vue/use-sealos.ts。

3. Sealos の ID をビジネスデータに接続する

多くのアプリにとって、重要な統合対象は iframe 自体ではなく、ユーザーのマッピングです。

1. session.user.id を、アプリレベルで安定して使用できるユーザー識別子として使います。
2. 必要に応じて、name、avatar、k8sUsername、nsid など、表示に適したフィールドを保存します。
3. ビジネスデータは、アプリ独自のデータベースと API ルートに保持します。
4. Sealos のユーザー ID はビジネスロジックへの入力としてモデル化し、バックエンド全体の代わりとして扱わないでください。

スキーマや API に関するガイダンスが必要な場合は、references/data-integration-patterns.md を読んでください。

4. 実際の実行環境でローカルデバッグを準備する

ブラウザーで正常に表示されるからといって、Sealos との統合も機能しているとは限りません。

SDK の getSession() などの呼び出しを成功させるには、通常、Sealos Desktop の iframe 内でアプリを開く必要があります。ローカルデバッグが作業に含まれる場合は、references/local-debug-and-test-app.md を読んでください。

次のルールに従ってください。

1. Sealos Desktop の外部にいる場合は、そのことを明確に説明します。
2. エンドツーエンドの検証には、Sealos Desktop 内のテストアプリを優先します。
3. サーバー側での SDK 呼び出しは避けてください。

5. 公開の準備

ユーザーがデプロイまたはリリースの準備を求めている場合：

1. 環境変数を確認します。
2. データベースへの接続とマイグレーションを確認します。
3. Sealos Desktop から起動したときにアプリが動作することを確認します。
4. アプリ間のナビゲーションやイベントの使用が有効であることを確認します。
5. 残っている手動での登録手順やプラットフォームの設定手順をまとめます。

リリースチェックリストとして references/publish-checklist.md を使用します。

実装ルール

統合はシンプルに保つ

最小限の Sealos 統合をデフォルトにします。

1. ルートプロバイダーまたはストアを 1 つ用意します。
2. ビジネス ID のマッピングパターンを 1 つ用意します。
3. Desktop 以外からのアクセスに対するフォールバックパスを 1 つ用意します。

SDK の初期化を複数のページやコンポーネントに分散させないでください。

リポジトリで実際に使用されている SDK の API を優先する

現在のワークスペースに Sealos SDK の実際のソースや既存の Sealos アプリが含まれている場合：

1. それらのソースを調べます。
2. 実際にエクスポートされている API と型に従います。
3. リポジトリ固有の違いが一般的な例と異なる場合は、その点を明記します。

公式 SDK パッケージ名を使用する

生成する例やスターターコードでは、デフォルトで @labring/sealos-desktop-sdk を使用します。

対象のリポジトリですでにローカルワークスペースのエイリアスが確立されていて、ユーザーがその維持を明示的に希望する場合に限り、別の名前を使用します。

判断ガイド

ユーザーが「Sealos アプリの構築方法」を尋ねた場合

以下を提示します。

1. ランタイムモデルの簡単な説明。
2. SDK の最小限の統合例。
3. ビジネスデータのマッピング例。
4. Sealos Desktop のテストアプリを使ったローカルデバッグ方法。

ユーザーが既存アプリの変更を求めた場合

次の順序で対応します。

1. 現在のアプリのエントリーポイントを確認します。
2. Sealos プロバイダーをルートに 1 つ追加するか、リファクタリングします。
3. ビジネス API を session.user.id に接続します。
4. Desktop 以外でのフォールバック動作を確認します。

ユーザーがドキュメントやチュートリアルを求めた場合

次の構成で出力します。

1. Sealos アプリとは何か。
2. SDK の初期化方法。
3. セッションの取得方法と使用方法。
4. ビジネスデータの統合方法。
5. Desktop テストアプリを使ったデバッグ方法。
6. 公開と検証の方法。

参考資料

タスクに必要なファイルのみを読みます。

1. 利用可能な SDK API とランタイムの動作については、references/sdk-capabilities.md を参照します。
2. 推奨されるルート統合パターンについては、references/minimal-app-template.md を参照します。
3. Next.js App Router における具体的な配置例については、references/nextjs-app-router.md を参照します。
4. ユーザーのマッピング、データベーススキーマ、API の形式については、references/data-integration-patterns.md を参照します。
5. iframe ベースのデバッグと Desktop テストアプリの設定については、references/local-debug-and-test-app.md を参照します。
6. リリース準備の手順については、references/publish-checklist.md を参照します。