InkQuest

InkQuest

使用 Next.js、Supabase 和 OpenNext Cloudflare 构建的互动式语言学习小说。

开始使用

安装依赖并运行开发服务器：

pnpm install
pnpm dev

打开 http://localhost:3000。

生成故事基础设施

首个云端生成基础设施包括：

• Supabase 积分账本、预留记录、故事图谱、作业、发件箱、账单表和 RLS，位于 supabase/migrations/202608220001_generated_story_billing.sql。
• 由服务端创建的 Lemon Squeezy 结账会话，以及幂等的 Webhook 处理。
• 经过身份验证的报价和生成故事作业创建 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 积分。仅当提供 every_scene 时才需要设置 TTS 定价。切勿通过 NEXT_PUBLIC_ 变量公开服务角色密钥、Lemon API 密钥或 Webhook 密钥。

按文件名顺序应用迁移。已经运行前两个迁移的现有环境，接下来应应用 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。在 Cloud Run Worker 上配置 Azure Speech 密钥和区域；已验证的评估资源使用 eastasia。配置后，中文和英文均优先使用 Azure，默认语音分别为 zh-CN-Xiaoxiao:DragonHDFlashLatestNeural 和 en-US-JennyNeural。设置 STORY_TTS_ZH_PROVIDER 或 STORY_TTS_EN_PROVIDER 为 azure 或 tencent，即可覆盖选择。Worker 镜像还会安装 FFmpeg，以便在上传前将 Tencent 的多段音频规范化为一个可搜索的 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。

每分钟调用一次 POST /api/internal/generation/outbox，并使用 Authorization: Bearer <GENERATION_DISPATCH_SECRET>，以恢复失败的队列发布和已过期的 Worker 租约。

MCP

公共故事目录通过 /api/mcp 提供只读的 Model Context Protocol 服务（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 脚本。