InkQuest

InkQuest

Next.js、Supabase、OpenNext Cloudflare で構築された、対話型の語学学習フィクションです。

はじめに

依存関係をインストールして、開発サーバーを起動します。

pnpm install
pnpm dev

http://localhost:3000 を開きます。

生成ストーリーの基盤

最初のクラウド生成基盤には、以下が含まれます。

• supabase/migrations/202608220001_generated_story_billing.sql にある、Supabase のクレジット台帳、予約、ストーリーグラフ、ジョブ、アウトボックス、課金テーブル、RLS。
• サーバーで作成する Lemon Squeezy のチェックアウトと、冪等性を備えた Webhook 処理。
• 認証済みの見積もり API と、生成ストーリーのジョブ作成 API。
• クラウドアダプターのコントラクトと、再利用可能なシーン補完コア（tools/story-pipeline/src/core）。

必須のサーバー環境変数：

NEXT_PUBLIC_SUPABASE_URL
NEXT_PUBLIC_SUPABASE_ANON_KEY
NEXT_PUBLIC_GOOGLE_CLIENT_ID
SUPABASE_SERVICE_ROLE_KEY
NEXT_PUBLIC_SITE_URL

LEMONSQUEEZY_API_KEY
LEMONSQUEEZY_STORE_ID
LEMONSQUEEZY_WEBHOOK_SECRET
LEMONSQUEEZY_SUBSCRIPTION_VARIANT_ID
LEMONSQUEEZY_SUBSCRIPTION_CREDIT_GRANT
LEMONSQUEEZY_CREDIT_PACK_VARIANT_ID
LEMONSQUEEZY_CREDIT_PACK_GRANT

GENERATION_PRICING_VERSION
GENERATION_OPENING_TEXT_CREDITS
GENERATION_OPENING_TTS_CREDITS
GENERATION_SCENE_TEXT_CREDITS
GENERATION_SCENE_TTS_CREDITS

NEXT_PUBLIC_GOOGLE_CLIENT_ID は、Google Cloud の Web OAuth クライアント ID です。デプロイした各サイトのオリジン（ローカル開発環境を含む）を、許可された JavaScript オリジンに追加し、Supabase で Google プロバイダーを有効にしてください。

クレジットパックの環境変数は、該当する製品を有効にするまでは任意です。対応する環境変数が未設定または無効な場合、生成料金は、オープニングテキストが 20 クレジット、オープニング TTS が 10 クレジット、シーンテキストが 12 クレジット、シーン TTS が 6 クレジットにフォールバックします。TTS 料金が必須となるのは、every_scene を提供する場合のみです。サービスロールキー、Lemon API キー、Webhook シークレットを NEXT_PUBLIC_ 変数で公開しないでください。

マイグレーションはファイル名の順に適用してください。最初の 2 つのマイグレーションをすでに実行した環境では、次に supabase/migrations/202608230001_generated_story_tts.sql を適用してください。これにより、非公開のオーディオバケットが作成され、TTS のコミット、再試行、払い戻しに関する独立したトランザクションが追加されます。

生成の実行経路は次のとおりです。

Next.js → inkquest-generation Queue → generation-dispatcher → Cloud Run story-pipeline Worker

メインアプリに追加する環境変数：

GENERATION_DISPATCH_SECRET
GENERATED_AUDIO_BUCKET

Cloud Run Worker の環境変数：

SUPABASE_URL
SUPABASE_SERVICE_ROLE_KEY
GENERATION_WORKER_TOKEN
LLM_CHAT_COMPLETIONS_URL
LLM_API_KEY
LLM_MODEL
LLM_PROMPT_VERSION
TENCENT_SECRET_ID
TENCENT_SECRET_KEY
TENCENT_REGION
TENCENT_TTS_VOICE
AZURE_SPEECH_KEY
AZURE_SPEECH_REGION
AZURE_TTS_VOICE_ZH
AZURE_TTS_VOICE_EN
STORY_TTS_ZH_PROVIDER
STORY_TTS_EN_PROVIDER
GENERATED_AUDIO_BUCKET

GENERATED_AUDIO_BUCKET の既定値は generated-audio です。Azure Speech のキーとリージョンを Cloud Run Worker に設定してください。検証済みの評価用リソースでは eastasia を使用します。設定されている場合、中国語と英語の両方で Azure が優先され、既定値はそれぞれ zh-CN-Xiaoxiao:DragonHDFlashLatestNeural と en-US-JennyNeural です。選択を上書きするには、STORY_TTS_ZH_PROVIDER または STORY_TTS_EN_PROVIDER に azure または tencent を設定してください。Worker イメージには FFmpeg もインストールされており、アップロード前に Tencent の分割音声を 1 つのシーク可能な MP3 に正規化します。

Cloudflare で inkquest-generation と inkquest-generation-dlq を作成してメインアプリをデプロイし、その後 tools/generation-dispatcher/wrangler.jsonc をデプロイしてください。ディスパッチャーに GENERATION_WORKER_URL を設定し、wrangler secret put で GENERATION_WORKER_TOKEN を保存します。

ローカル開発では、ストーリーを生成する前に、別のターミナルで Worker を起動してください。

PORT=8080 pnpm --filter @inkquest/story-pipeline worker:start

Next.js の開発サーバーは、既定で新しいジョブを http://127.0.0.1:8080 にディスパッチします。上書きするには GENERATION_WORKER_URL を設定し、Next.js と Worker で同じ GENERATION_WORKER_TOKEN を使用してください。

失敗したキューへの公開や期限切れの Worker リースを回復するには、Authorization: Bearer <GENERATION_DISPATCH_SECRET> を指定して、毎分 POST /api/internal/generation/outbox を呼び出してください。

MCP

公開ストーリーカタログ向けの読み取り専用Model Context Protocol サーバーを、/api/mcp（Streamable HTTP）で提供しています。無料のストーリーを一覧表示し、オープニングシーンを返し、候補をおすすめします。各項目には https://inkquest.dev/stories/{id} のリンクが含まれます。生成ストーリーやプレミアムシーンは公開しません。セットアップ、ローカルでのチェック、レジストリへの公開については、docs/mcp.md を参照してください。

検証

pnpm exec tsc --noEmit
pnpm --filter @inkquest/story-pipeline typecheck
pnpm lint
pnpm build

デプロイには OpenNext Cloudflare を使用します。wrangler.jsonc と package.json の preview／deploy スクリプトを参照してください。