customware-ai

Customware AI

Customware AI Gateway を通じて AI 機能を構築します。チャット UI が必要な場合は、Hono バックエンドで AI SDK を、React Router SPA で AI Elements を使用します。

事前セキュリティルール： .env とすべての .env.* ファイルにはアクセスできないものとして扱ってください。読み取り、一覧表示、検索、プレビューを行ったり、アクセス許可を求めたりしないでください。.env を参照できるのは node --env-file=.env ... を使用するランタイムコマンドだけで、そのコマンドで環境変数の値を出力してはなりません。

これは統合全体を対象とする唯一のスキルです。別の AI Elements スキルをインストールしたり、エージェントに使用を求めたりしないでください。関連する AI Elements のガイダンスは、このスキルのリファレンスに反映されています。

まず読むもの

• 必ず references/gateway-backend.md を読んでください。
• 必ず references/models.md を読んでください。
• チャットなどの会話型 UI については、references/ai-elements-ui.md を読んでください。
• サーバーツール、ツール連携型チャット、またはアプリの最新データを取得する AI アクションについては、references/tool-usage.md を読んでください。
• カード形式の AI UI、ツールで描画する UI、型付きメッセージパーツ、またはストリーミングされるカスタム UI 状態については、references/generative-ui.md を読んでください。
• AI UI については、references/ai-elements-catalog.md を読み、必要なコンポーネントを選んでから、references/components/ 内のリンク先ファイルだけを読んでください。コンポーネントのリンク先にあるサンプルファイルを開くのは、実装時だけにしてください。components フォルダー全体やすべてのサンプルを読み込まないでください。
• JSON やその他の型付き出力については、references/structured-output.md を読んでください。
• 同梱コードを起点にする場合は、references/examples.md を読んでください。
• 実装を完了する前に、必ず references/verification.md を読み、その指示に従ってください。

必須事項

• Customware AI Gateway はサーバーコードからのみ呼び出してください。ブラウザーコードはアプリ独自の Hono エンドポイントを呼び出します。
• ゲートウェイのシークレットは CUSTOMWARE_AI_GATEWAY_KEY からのみ読み取ってください。
• このキーを VITE_*、ブラウザーバンドル、API レスポンス、ログ、HTML、クライアント側の状態を通じて決して公開しないでください。
• .env または .env.* ファイルをファイル／ツール読み取りで決して読み取らないでください。また、その許可を求めないでください。.env に対して cat、head、tail、sed、awk、rg、grep、ls、stat、その他のコマンドを決して実行しないでください。唯一許可される参照方法は、引数が正確に node --env-file=.env ... であるチェックコマンドです。このコマンドで環境変数を出力してはいけません。printenv、リクエストヘッダー、プロバイダーオブジェクトを出力してキーを調べないでください。ログには機密情報を含まない成功／失敗の証拠のみを記録してください。
• Customware ゲートウェイのベース URL はサーバーコードにハードコードしてください。ゲートウェイ URL の環境変数は追加しないでください。
• アダプターのベース URL には、必ず次の値を使用してください。 https://app.customware.ai/api/orgs/${orgId}/projects/${projectId}/ai/v1
• 実際の Customware orgId と projectId を必ず使用してください。プレースホルダーを使用したり、リクエストごとにブラウザーから値を受け取ったりしないでください。
• @openrouter/ai-sdk-provider を使用してください。プロバイダー固有の SDK を使用したり、OpenRouter を直接呼び出したりしないでください。
• プリセット、プロバイダーのルーティング、フォールバックモデルのリスト、メタデータ、トレース ID、OpenRouter のユーザー ID を渡さないでください。これらの制御はゲートウェイが担います。
• ユーザーが別のモデルを選択する場合、またはタスクで明らかに必要な場合を除き、デフォルトは google/gemini-3-flash-preview にしてください。
• 選択したモデル ID とプロバイダーオプションは、サーバーが所有する 1 つのモジュール／定数にまとめてください。ルートとサービスはその値をインポートする必要があります。機能上ユーザーによる選択が不要な場合、モデルの文字列を重複させたり、モデルカタログ／ピッカーを追加したりしないでください。
• 開発中にユーザーがモデルを指定または変更した場合、完了前に、そのモデルを正確に指定したライブの hi リクエストを送信してください。
• 機能で JSON を生成する場合、完了前に 1 キー構造化出力チェックを実行してください。
• JSON のフィールド名と形状は、要求どおりに正確にしてください。アプリとサーバーの両方がインポートできるよう、中立的な共有モジュール／パッケージ（例：shared/contracts/）に共通の Zod コントラクトを 1 つ定義してください。ブラウザーから server/ をインポートしてはいけません。また、スキーマ／列挙型を重複して定義してはいけません。機能の仕様に明記されている場合は、20,000 文字の入力上限など、プロダクト要件の制限を設定できます。
• 上流の AI で発生した障害はすべて、アプリの境界で汎用的かつユーザーに安全なエラーに変換してください。生の通信エラー／プロバイダーエラーを決して表示しないでください。
• データベースへのアクセスはサーバー側で管理してください。モデルが生成した任意の SQL を決して実行しないでください。機能でデータベースへのアクセスが必要な場合は、モデルに構造化されたツール入力を選ばせ、サーバーが許可リストに登録されたフィルター、テーブル、またはクエリーヘルパーを使って、読み取り専用のパラメーター化クエリーを組み立ててください。
• AI Elements は React Router のクライアント専用 SPA で動作します。Next.js や App Router のルートハンドラーを導入しないでください。生成された "use client" ディレクティブは React の境界マーカーとして問題なく、Next.js は必要ありません。
• pnpm のみを使用してください。AI Elements のインストールには同梱のインストーラーを使用してください。このインストーラーは、非対話型の pnpm dlx shadcn@latest add ... --yes コマンドを実行し、レジストリに一致するプリミティブをテンプレート既存の UI コントラクトから分離します。

ワークフロー

1. 生成されたアプリを調べ、パッケージマネージャー、Hono のエントリーポイント、React Router の構成、実際の Customware の組織 ID／プロジェクト ID を確認します。
2. 上記に記載された関連リファレンスを読みます。
3. 不足している場合に限り、ai、@ai-sdk/react、@openrouter/ai-sdk-provider、zod を pnpm のみで追加します。AI Elements のインストーラーやライブチェックを実行する前に、この依存関係のインストールを完了してください。
4. CUSTOMWARE_AI_GATEWAY_KEY と固定のゲートウェイ URL を使用する、用途を絞ったサーバープロバイダーヘルパーを追加します。
5. 静的ファイルの配信ルートと SPA フォールバックルートより前に Hono エンドポイントを追加します。この React Router SPA では、ルート以外のルートから HydrateFallback をエクスポートしないでください。テンプレートに既存のルートフォールバックのみを使用します。
6. モデルとその推論設定はサーバー側で管理します。UI でモデルを選択できる場合は、references/models.md に記載された少数の許可リストに照らして検証します。
7. チャットでは、選択した AI Elements のみを scripts/install-ai-elements.mjs でインストールし、useChat をアプリの Hono エンドポイントに接続します。
8. 構造化出力には、Zod スキーマを使った現在の AI SDK の generateText と Output.object を使用します。
9. ツール呼び出しでは、サーバー上で tool({ inputSchema, execute }) を使ってツールを定義し、アクションの境界をサーバー側で管理します。ツールの結果を受けてモデルが回答する必要がある場合は、stopWhen: stepCountIs(5) のような、上限のある複数ステップ設定を使用します。
10. PromptInputSubmit では、ステータスが submitted または streaming の間は停止アクションを使用できるようにします。送信済みの入力がクリアされた後に停止アクションが無効になるような、入力が空の場合の disabled 条件は渡さないでください。
11. 対象プロジェクトから references/verification.md に記載された必須のライブチェックとブラウザーレベルの UI 検証を実行し、その後、アプリの通常の型チェック／チェック／ビルドコマンドを実行します。インタラクティブな検証に失敗した場合は、アプリに問題があると結論づける前に、プロジェクト内のスクリプトから実際のページ／コンソールを調べてください。
12. ルートまたはペインの境界で、React.lazy／動的インポートを使ってクライアント側の AI UI を遅延読み込みします。サーバー専用の AI SDK 呼び出し（streamText、generateText、ツール）とゲートウェイプロバイダーはサーバー専用にします。DefaultChatTransport は useChat でサポートされているクライアントトランスポートです。サーバーコードをブラウザーに遅延読み込みしないでください。大きな AI UI バンドルの警告は実際のパフォーマンス問題として扱い、重い Streamdown／AI Elements のコードを初期チャンクから分離します。

バージョンを考慮した API の使用

パッケージの API は変更されることがあります。使い方が不確かな場合は、コードを書く前に対象プロジェクトの node_modules/ にあるインストール済みパッケージを調べてください。

• 型の契約と利用可能なプロパティ／戻り値を確認するには、.d.ts ファイルを読みます。
• 実行時の動作とデフォルトを確認するには、実際の .js／.mjs 実装を読みます。
• これは ai、@ai-sdk/react、@openrouter/ai-sdk-provider、インストール済みの AI Elements コンポーネントに適用します。インストール済みのバージョンとソースを、コピーしたサンプルや古いドキュメントより優先してください。

そのまま使えるサンプル

• 最小構成のストリーミングチャットには assets/ai-chat/ を使用します。
• ツール状態を表示する、読み取り専用の安全な SQL パターンを使ったツール連携チャットには assets/sql-tool-chat/ を使用します。
• チャット内でツールを利用してエンドユーザー向けカード UI を表示するには assets/generative-ui-chat/ を使用します。
• 内部サーバー専用の型付き JSON 生成には assets/email-parser/ を使用します。
• 対象機能に必要なファイルのみをコピーし、インポートパスを調整して、ルートまたはサービスをマウントする箇所に実際の組織 ID／プロジェクト ID を指定します。
• assets は出発点となるコードとして扱い、スキルのリポジトリ内で実行するファイルとして扱わないでください。

境界

• 依頼が既存のサポートエージェントウィジェットの埋め込みだけである場合は、代わりに customware-support-widget を使用します。
• Hono 経由の経路と並行して、ブラウザーからゲートウェイへの経路を別途構築しないでください。
• ユーザーが選択したモデルを利用できない場合に、別のモデルへ黙って置き換えないでください。
• 生成されたアプリに、2 つ目のキー、プロジェクトごとのキー、または OpenRouter への直接キーを作成しないでください。
• CUSTOMWARE_AI_GATEWAY_KEY を UI に表示、マスク、コピー、その他の方法で露出させないでください。これは AI Elements の環境変数を表示する用途ではありません。