make-ai-assistant

Make AI Assistant

この Skill が所有するのはホスト統合の契約であり、パッケージ内部の UI やステートマシンではありません。Make App ホストは、ID、範囲を限定したページコンテキスト、認証済みの生バイト転送手段 1 つ、明示的な Service ルート、デプロイ設定を所有します。 この Skill の Make App v1 リファレンスは、Agent Public API v1 の OpenAPI リビジョン 60bbbcfe90c6defce46a0ed715e008fa4db20deb およびパッケージの公開 v1 エントリポイントに準拠しています。Skill のバージョンと npm パッケージのバージョンは独立しています。実装前に、実際にインストールされているバージョンを確認してください。

ワークフロー

1. 対象ホストのパッケージマネージャー、認証済みシェルと ID、共有認証アダプター、UI／Service ルート、権限チェック、実行時オリジン、テスト、既存のアシスタント統合を調査します。安定した呼び出しチェーンは維持してください。
2. references/package-integration.md を読みます。新規インストールまたは最新バージョンへのアップグレードが求められている場合は、設定済みのレジストリを照会し、コンシューマー UI ワークスペースに公開済みの最新パッケージをインストールして、ロックファイル内の正確なバージョン、公開エクスポートマップ、宣言ファイルを確認します。インストール済みのバージョンがこの Skill で必要な公開契約を公開していない場合は、不足しているエクスポート／型とバージョンを示して中止してください。別のプロジェクトやパッケージの説明文から互換性を推測して補ってはいけません。
3. references/make-app-protocol.md にある、バージョン指定済みの Make App AI Chat 契約を使用します。スキーマ、制限、拡張可能な公開エラー、固定されたバックエンドのリビジョンも含めて確認してください。本番対応を表明する前に、現在のバックエンド契約とデプロイ済みの動作を確認します。その確認ができない、または異なる場合は、文書化された v1 実装を維持しつつ、実行時の互換性は未検証と報告してください。別のプロジェクトから古い API を推測してはいけません。
4. 完全な統合の場合は、以下に示すパッケージ、ホスト、プロトコル、ストリーム／添付ファイル、UI、テストのリファレンスを読みます。対象を絞った修正の場合は、関連するリファレンスだけを読みます。TDD を使用します。契約／動作テストを失敗させ、最小限の実装を行い、テストがすべて成功した状態でリファクタリングします。
5. 公開インポートのみを使用し、styles.css は 1 回だけインポートします。ホストで認証された AuthenticatedTransport を使って公開 /client を作成し、すべてのページネーションを通じて、現在の App に属する一意の app_internal Agent を検出してから、await createMakeAppAssistantTransport({ client, agentId, signal }) を呼び出します。v1 DTO、デコード、再試行、アップロード、SSE、UI トランスポートのマッピングは SDK が担います。新しい Make App にはすべて、認証済みトランスポートに make-app-observability を適用してください。JSON、SSE、バイナリーの各リクエストは traceparent と、それに対応する X-Log-Id ヘッダーを送信します。トレースコンテキストをクエリパラメーターに含めてはいけません。
6. 文書化された Make App v1 Service オペレーション 18 個のみを公開します。転送前に、App のスコープ、メソッド／パス／クエリ／本文、GET／HEAD 以外のすべてのリクエストで単一の同一オリジン HTTP(S) Origin、サイズ、上流の転送先を検証してください。
7. パッケージ UI の内部実装はパッケージ側の所有とします。ホストへの配置や表示には公開 props／テーマ変数を使用してください。reducer、ストリームパーサー、アップロードエンジン、タスクリスト、コンポーザー、CSS をコピーしてはいけません。
8. 静的監査、対象を絞った UI／Service テスト、型チェック、ビルド、認証済みの既存ルートに対するスモークテストを実行します。静的な事前チェックに合格しても、Service オペレーション 18 個すべての動作、実行時の正しさ、デプロイ準備完了を証明することはできません。

Skill 契約のリリースでは、このガイダンスの準備完了を宣言する前に、references/testing-and-pitfalls.md にある独立したフォワードテストを完了してください。

node skills/make-ai-assistant/scripts/audit-make-ai-assistant-project.mjs <project-root> \
  --expected-package-version=<resolved-exact-version>

想定バージョンは範囲指定ではなく、実際にインストールされた解決バージョンです。より広範なモデル入力への対応を主張するには、デプロイ済みモデルに関する別個のエビデンスが必要です。統合の完了を報告する前に、公開済みの同一オリジンリクエストとレスポンスストリーミングを対象の Dev App に対して検証してください。

参照マップ

トピック	参照先
パッケージの解決、公開型、React の props	references/package-integration.md
Make App のホスト構成、Agent の検出と識別	references/make-app-host-integration.md
Make App v1 の18操作 API と Service の境界	references/make-app-protocol.md
SDK のストリーム復旧とファイル／画像の動作	references/make-app-stream-and-attachments.md
パッケージの UI、テーマ、アクセシビリティ	references/ui-and-templates.md
テストとリリースゲート	references/testing-and-pitfalls.md

厳守すべき境界と引き継ぎ

• ブラウザーからの Make App リクエストは、同一オリジンの /api/make/app/ai/v1/** を使用します。SDK はパスを含まないバージョンベースに /v1 を追加するため、二重に追加しないでください。ローカルプレビューのアップストリームは make_api_origin + /api/make/app/ai/v1/** を使用し、公開済み Service は設定済みの Make Gateway オリジンに /make/app/ai/v1/** を追加して使用します。Agent Gateway のオリジン、トークン、ハードコードされた Agent ID を別途追加しないでください。
• 選択する App Agent は agentType === "app_internal" を満たし、現在の appKey と完全に一致している必要があります。channel と不明な Agent タイプは無視しますが、一致する App 内部 Agent が0件または複数件の場合はエラーにしてください。1件を受け入れる前に、すべてのページを読み込んでください。
• AuthenticatedTransport.request は、認証情報を付与した同一オリジンの I/O を1回実行し、ステータス、ヘッダー、生の AsyncIterable<Uint8Array> を返します。ブラウザートークンを読み取ったり、SSE／バイト列を JSON として展開したりすることはありません。retryOwner は所有者を1つだけ指定してください。201／202／204、Make-AI-Api-Version、AbortSignal、401／403 のログイン／権限処理を維持してください。
• capabilities はアダプター作成時にパッケージが取得します。これらはオプションの UI 機能を制御し、モデルの入力種別／上限を提供しますが、認可を行うものではありません。アップロードが利用可能だからといって、モデルがファイルや画像を解釈できるとは限りません。現在の Make App アダプターは Artifact を扱いません。サポートされていないコンテキスト、Artifact、ネゴシエーションフィールドを追加したり、Artifact UI を提供すると約束したりしないでください。
• App、テナント、またはユーザーが切り替わったら、古い検出処理を中断し、古いクライアントを破棄してください。パネルを閉じる操作はローカル UI の状態変更であり、リモートの実行をキャンセルするものではありません。Agent／capabilities の検出に失敗した場合は、再試行可能なランチャーを維持してください。
• 周囲の App シェルと外部への配置は makeui が所有し、この Skill とパッケージはアシスタント内部の動作／スタイルを所有します。明示的なプロキシ、検証、安全なエラーは make-app-service が所有します。統合ログインと、AI の生バイトを扱う限定的なブリッジ規則は make-app-auth が所有します。アクセスとアクションの認可は make-app-permission が所有します。プレビュー／公開オリジンとビルド契約は make-app-runtime が所有します。Skill のインストール／同期は make-env-setup が所有し、makecli はプラットフォームの調査を担当します。ランタイムの Service リクエストは担当しません。
• ページコンテキストは範囲を限定し、秘密情報を含めないでください。認可として扱ったり、サーバーから提供された HTML、JSX、CSS、JavaScript、検証されていないアクション URL を実行したりしないでください。テスト用モックは明示的に有効にする必要があり、バックエンドの準備状況を証明するものではありません。