From d05b56411042788a87e3b4e30e9c5dfa0c83ef48 Mon Sep 17 00:00:00 2001
From: yuanzonghao <yuanzonghao123@gmail.com>
Date: Mon, 29 Jun 2026 13:15:05 +0800
Subject: [PATCH] docs(readme): add demo video and restore config guide inline

Add demo video with inline <video> playback in all three README
language variants (zh/en/ja), hosted via GitHub user-attachments.

Restore the configuration guide from docs/configuration*.md back into
the main READMEs (positioned between Deploy and Roadmap) for better
discoverability. docs/configuration*.md files preserved for Vercel
button envLink references.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.en.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++--
 README.ja.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++--
 README.md    | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++--
 3 files changed, 195 insertions(+), 6 deletions(-)

diff --git a/README.en.md b/README.en.md
index ea5a8e1..c71fc13 100644
--- a/README.en.md
+++ b/README.en.md
@@ -52,6 +52,14 @@ Free to play, no setup required: [infiplot.com](https://infiplot.com)
 
 ---
 
+## 🎬 Demo
+
+<div align="center">
+  <video src="https://github.com/user-attachments/assets/414f0534-50c4-46d3-bc85-c681283b8c79" controls width="100%"></video>
+</div>
+
+---
+
 ## 📸 Screenshots
 
 <table>
@@ -103,7 +111,7 @@ Cloudflare deployment requires the Workers Paid Plan because the scene pipeline
 <a href="https://vercel.com/new/clone?repository-url=https://github.com/zonghaoyuan/infiplot&env=TEXT_BASE_URL,TEXT_API_KEY,TEXT_MODEL,IMAGE_BASE_URL,IMAGE_API_KEY,IMAGE_MODEL,VISION_BASE_URL,VISION_API_KEY,VISION_MODEL,TTS_BASE_URL,TTS_API_KEY,TTS_SPEECH_MODEL,MOCK_IMAGE&envDescription=Three%20required%20providers%20%2B%20optional%20TTS.%20Any%20OpenAI-compatible%20endpoint%20works%20for%20text%2Fvision.%20TTS%3A%20Xiaomi%20MiMo%20%28free%29%20or%20StepFun%20%28paid%2C%20better%20quality%29.&envLink=https://github.com/zonghaoyuan/infiplot/blob/main/docs/configuration.en.md"><img src="https://vercel.com/button" alt="Deploy with Vercel" height="34"></a>&nbsp;
 <a href="https://deploy.workers.cloudflare.com/?url=https://github.com/zonghaoyuan/infiplot"><img src="https://deploy.workers.cloudflare.com/button" alt="Deploy to Cloudflare" height="34"></a>
 
-After deploy, set up your environment variables following the [Configuration guide](docs/configuration.en.md). The repo root is the app itself: Vercel needs no special root directory; on Cloudflare, just set the build command to `pnpm build:cf`.
+After deploy, set up your environment variables following the [Configuration guide](#configuration-guide). The repo root is the app itself: Vercel needs no special root directory; on Cloudflare, just set the build command to `pnpm build:cf`.
 
 ### Docker (self-hosted)
 
@@ -116,7 +124,7 @@ curl -fsSL https://raw.githubusercontent.com/zonghaoyuan/infiplot/main/.env.exam
 [ -f .env.local ] || cp .env.example .env.local
 ```
 
-Edit `.env.local` with your API keys (see [Configuration guide](docs/configuration.en.md)), then start:
+Edit `.env.local` with your API keys (see [Configuration guide](#configuration-guide)), then start:
 
 ```bash
 docker compose up -d
@@ -131,6 +139,61 @@ Visit `http://localhost:3000` to start playing.
 
 ---
 
+## Configuration guide
+
+InfiPlot talks to four kinds of model providers. **Text and Vision use any OpenAI-compatible endpoint**, so you can mix and match freely — for Google Gemini, point `*_BASE_URL` at its OpenAI-compatible endpoint (`https://generativelanguage.googleapis.com/v1beta/openai`). For Anthropic Claude, a compatible gateway (e.g. LiteLLM) is recommended — Anthropic's official endpoint offers an OpenAI-compatible layer but no caching, which raises cost and latency. **Image** supports **Runware** (its own task-array protocol) and **OpenAI** (`gpt-image`). **TTS** supports **Xiaomi MiMo** (its own voice design / clone protocol — per-character voice design, clone, and per-line delivery direction; free) and **StepFun** (32 preset voices, auto-matched by AI; paid but better quality).
+
+### 1. Choose your providers
+
+| Provider | Variables | Required? | Recommended |
+|---|---|---|---|
+| Text · story director  | `TEXT_BASE_URL` `TEXT_API_KEY` `TEXT_MODEL`        | ✅ | `deepseek-v4-flash` via DeepSeek |
+| Image · scene renderer  | `IMAGE_BASE_URL` `IMAGE_API_KEY` `IMAGE_MODEL`     | ✅ | `runware:400@6` (FLUX.2 [klein] 9B KV) via [Runware](https://runware.ai) |
+| Vision · click reader  | `VISION_BASE_URL` `VISION_API_KEY` `VISION_MODEL`  | ✅ | `gemini-3.5-flash` via Google |
+| TTS · per-character voice | `TTS_BASE_URL` `TTS_API_KEY` `TTS_SPEECH_MODEL` | optional — leave blank to run silently | `mimo-v2.5-tts` via Xiaomi MiMo (free); paid alternative: `step-tts-2` via [StepFun](https://www.stepfun.com) |
+
+> **Optional · explicit protocol override**: each provider slot accepts a `*_PROVIDER` variable (`TEXT_PROVIDER` / `VISION_PROVIDER` / `IMAGE_PROVIDER`) to force a specific protocol. **Leave unset for backwards-compatible defaults** — text/vision default to OpenAI-compatible, image auto-detects from `*_BASE_URL` (`runware.ai` → Runware, otherwise OpenAI-compatible; models served via OpenAI protocol on `runware.ai` — such as `image-2-vip` — are handled as OpenAI-compatible; override with `IMAGE_PROVIDER` when needed).
+>
+> | Value | Applies to | Description |
+> |---|---|---|
+> | `openai_compatible` (default) | Text · Vision · Image | OpenAI Chat Completions / `/images/generations` |
+> | `openai` | Image | OpenAI `gpt-image`, supports reference-image editing |
+> | `runware` | Image | Runware task-array protocol |
+>
+> Text and vision **only** support `openai_compatible`. For Gemini, point `*_BASE_URL` at its OpenAI-compatible endpoint (`https://generativelanguage.googleapis.com/v1beta/openai`). For Claude, a compatible gateway (e.g. LiteLLM) is recommended — Anthropic's official endpoint offers an OpenAI-compatible layer but no caching, raising cost and latency.
+>
+> `*_BASE_URL` works with or without a trailing `/v1` (or even a trailing `/chat/completions`) — the engine normalizes automatically.
+
+### 2. Set the environment variables
+
+Nine variables are required; TTS is optional (leave blank to run silently). There's also a flag for cheap testing:
+
+| Variable | Effect |
+|---|---|
+| `MOCK_IMAGE=true` | Skip image generation; the renderer returns a static placeholder. Story, voice, and choices still run normally. Great for iterating on TTS without burning Runware credits. |
+
+Where to set them (see `.env.example` for the exact shape):
+
+- **Local dev** — `.env.local`
+- **Vercel** — Project Settings → Environment Variables
+- **Cloudflare Workers** — from the repo root, run `wrangler secret put <NAME>` for each variable, or set them in the dashboard (Workers → infiplot → Settings → Variables and Secrets). For a private staging instance, gate the Worker behind [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/applications/) — zero-code email-whitelist auth in front of the Worker.
+
+### 3. Mind the cost
+
+With the recommended trio, each scene's cost comes mainly from the image generation model. The FLUX.2 [klein] 9B KV image is roughly **$0.00078** per scene (1792×1024, 4 steps, sub-second); the text model uses `deepseek-v4-flash`, so text costs are negligible by comparison. Tapping through a scene's beats is free. To keep transitions instant, the engine also pre-generates scenes you might pick but ultimately don't — so real spend runs somewhat higher than the scenes you actually see.
+
+### 4. Image proxy (optional)
+
+By default the browser fetches images directly from the provider — no setup needed; leave `NEXT_PUBLIC_IMAGE_PROXY_URL` blank and you're completely unaffected. You only want this if you hit progressive "top-to-bottom" image loading (Chrome's `ERR_QUIC_PROTOCOL_ERROR` on some networks paints partial PNGs row by row): deploy a tiny Cloudflare Worker that re-fetches images server-side and serves them atomically over HTTP/2. One-click deploy at **[infiplot-image-proxy](https://github.com/zonghaoyuan/infiplot-image-proxy)**, then paste the `workers.dev` URL it prints into `NEXT_PUBLIC_IMAGE_PROXY_URL`.
+
+### 5. Let players bring their own voice Key (optional, recommended)
+
+Xiaomi rate-limits the TTS model by RPM/TPM. When a public deployment has many people playing at once through a single shared `TTS_API_KEY`, those limits are easy to hit — the symptom is **story and visuals work fine, but there's no audio**. To fix this, players can optionally enter **their own** Xiaomi MiMo key on the homepage (free to obtain). Synthesis then runs **browser-direct to Xiaomi**, the **key stays in the player's browser and never touches your server**, and they get stable voice with lower latency. It's purely additive: leave it blank and playback falls back to your server key exactly as before.
+
+See the [Bring-your-own voice Key guide](docs/xiaomi-tts-key.md) for how to obtain and enter one.
+
+---
+
 ## Roadmap
 
 **Completed**
diff --git a/README.ja.md b/README.ja.md
index 3270465..80909f8 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -52,6 +52,14 @@ InfiPlot は、AI がコンテンツをリアルタイムに生成するイン
 
 ---
 
+## 🎬 デモ
+
+<div align="center">
+  <video src="https://github.com/user-attachments/assets/414f0534-50c4-46d3-bc85-c681283b8c79" controls width="100%"></video>
+</div>
+
+---
+
 ## 📸 スクリーンショット
 
 <table>
@@ -103,7 +111,7 @@ Cloudflare へのデプロイはシーンパイプラインがより長い CPU 
 <a href="https://vercel.com/new/clone?repository-url=https://github.com/zonghaoyuan/infiplot&env=TEXT_BASE_URL,TEXT_API_KEY,TEXT_MODEL,IMAGE_BASE_URL,IMAGE_API_KEY,IMAGE_MODEL,VISION_BASE_URL,VISION_API_KEY,VISION_MODEL,TTS_BASE_URL,TTS_API_KEY,TTS_SPEECH_MODEL,MOCK_IMAGE&envDescription=Three%20required%20providers%20%2B%20optional%20TTS.%20Any%20OpenAI-compatible%20endpoint%20works%20for%20text%2Fvision.%20TTS%3A%20Xiaomi%20MiMo%20%28free%29%20or%20StepFun%20%28paid%2C%20better%20quality%29.&envLink=https://github.com/zonghaoyuan/infiplot/blob/main/docs/configuration.ja.md"><img src="https://vercel.com/button" alt="Deploy with Vercel" height="34"></a>&nbsp;
 <a href="https://deploy.workers.cloudflare.com/?url=https://github.com/zonghaoyuan/infiplot"><img src="https://deploy.workers.cloudflare.com/button" alt="Deploy to Cloudflare" height="34"></a>
 
-デプロイ後、[設定ガイド](docs/configuration.ja.md)に従って環境変数を設定してください。リポジトリのルートがアプリ本体です：Vercel では特別なルート設定は不要です。Cloudflare ではビルドコマンドを `pnpm build:cf` に設定するだけで済みます。
+デプロイ後、[設定ガイド](#設定ガイド)に従って環境変数を設定してください。リポジトリのルートがアプリ本体です：Vercel では特別なルート設定は不要です。Cloudflare ではビルドコマンドを `pnpm build:cf` に設定するだけで済みます。
 
 ### Docker デプロイ（セルフホスト）
 
@@ -116,7 +124,7 @@ curl -fsSL https://raw.githubusercontent.com/zonghaoyuan/infiplot/main/.env.exam
 [ -f .env.local ] || cp .env.example .env.local
 ```
 
-`.env.local` を編集して API キーを設定し（[設定ガイド](docs/configuration.ja.md)を参照）、起動します：
+`.env.local` を編集して API キーを設定し（[設定ガイド](#設定ガイド)を参照）、起動します：
 
 ```bash
 docker compose up -d
@@ -131,6 +139,61 @@ docker compose up -d
 
 ---
 
+## 設定ガイド
+
+InfiPlot は 4 種類のモデルプロバイダと通信します。**テキスト（Text）・ビジョン（Vision）は、任意の OpenAI 互換エンドポイント**を使用でき、自由に組み合わせられます —— Google Gemini を使う場合は、`*_BASE_URL` をその OpenAI 互換エンドポイント（`https://generativelanguage.googleapis.com/v1beta/openai`）に向けるだけです。Anthropic Claude を使う場合は、互換ゲートウェイ（LiteLLM など）の経由を推奨します —— Anthropic の公式エンドポイントは OpenAI 互換レイヤーを提供していますがキャッシュ非対応のため、コストとレイテンシが上昇します。**画像（Image）**は **Runware**（独自の task-array プロトコル）と **OpenAI**（`gpt-image`）に対応します。**音声（TTS）**は **Xiaomi MiMo**（独自の音声デザイン/クローンプロトコル —— キャラクターごとの音声デザイン、クローン、行ごとの抑揚指示に対応、無料）と **StepFun**（32 種のプリセット音声を AI が自動マッチング、有料ですがより高品質）に対応します。
+
+### 1. プロバイダを選ぶ
+
+| プロバイダ | 環境変数 | 必須？ | 推奨 |
+|---|---|---|---|
+| Text · ストーリー監督  | `TEXT_BASE_URL` `TEXT_API_KEY` `TEXT_MODEL`        | ✅ | DeepSeek の `deepseek-v4-flash` |
+| Image · シーン描画  | `IMAGE_BASE_URL` `IMAGE_API_KEY` `IMAGE_MODEL`     | ✅ | [Runware](https://runware.ai) の `runware:400@6`（FLUX.2 [klein] 9B KV） |
+| Vision · クリック解釈  | `VISION_BASE_URL` `VISION_API_KEY` `VISION_MODEL`  | ✅ | Google の `gemini-3.5-flash` |
+| TTS · キャラクター音声 | `TTS_BASE_URL` `TTS_API_KEY` `TTS_SPEECH_MODEL` | 任意 —— 空欄なら無音で動作 | Xiaomi MiMo の `mimo-v2.5-tts`（無料）；有料の選択肢：[StepFun](https://www.stepfun.com) の `step-tts-2` |
+
+> **オプション · プロトコルの明示的指定**：各プロバイダスロットには `*_PROVIDER` 変数（`TEXT_PROVIDER` / `VISION_PROVIDER` / `IMAGE_PROVIDER`）を追加して、使用するプロトコルを明示的に指定できます。**未設定なら後方互換のデフォルト**を維持します —— テキスト/ビジョンは OpenAI 互換がデフォルト、画像は `*_BASE_URL` から自動判定（`runware.ai` → Runware、それ以外は OpenAI 互換。`runware.ai` 上で OpenAI プロトコルで提供されるモデル —— `image-2-vip` など —— は OpenAI 互換として処理されます。必要に応じて `IMAGE_PROVIDER` で上書きしてください）。
+>
+> | 値 | 対象 | 説明 |
+> |---|---|---|
+> | `openai_compatible`（デフォルト） | Text · Vision · Image | OpenAI Chat Completions / `/images/generations` |
+> | `openai` | Image | OpenAI `gpt-image`、参照画像編集に対応 |
+> | `runware` | Image | Runware task-array プロトコル |
+>
+> テキストとビジョンは `openai_compatible` **のみ**対応。Gemini を使う場合は `*_BASE_URL` をその OpenAI 互換エンドポイント（`https://generativelanguage.googleapis.com/v1beta/openai`）に向けてください。Claude を使う場合は互換ゲートウェイ（LiteLLM など）の経由を推奨 —— Anthropic の公式エンドポイントは OpenAI 互換レイヤーを提供していますが、キャッシュ非対応のためコストとレイテンシが上昇します。
+>
+> `*_BASE_URL` は末尾に `/v1` があってもなくても（`/chat/completions` まで付いていても）正常に動作します —— エンジンが自動で正規化します。
+
+### 2. 環境変数を設定する
+
+9 つの変数が必須で、TTS は任意です（空欄なら無音で動作）。低コストなテスト用のフラグもあります。
+
+| 変数 | 効果 |
+|---|---|
+| `MOCK_IMAGE=true` | 画像生成をスキップし、レンダラが静的なプレースホルダを返します。ストーリー・音声・選択肢は通常どおり動作します。Runware のクレジットを消費せずに TTS を調整するのに最適です。 |
+
+設定場所（正確なフォーマットは `.env.example` を参照）：
+
+- **ローカル開発** —— `.env.local`
+- **Vercel** —— Project Settings → Environment Variables
+- **Cloudflare Workers** —— リポジトリのルートから各変数について `wrangler secret put <NAME>` を実行するか、ダッシュボード（Workers → infiplot → Settings → Variables and Secrets）で設定します。ステージング環境にアクセス制限を掛けたい場合は、Worker の前に [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/applications/) を挟むと、ゼロコードでメール許可リスト方式の認証が利用できます。
+
+### 3. コストに注意
+
+推奨の 3 点セットでは、各シーンのコストは主に画像生成モデルによるものです。FLUX.2 [klein] 9B KV の画像は 1 シーンあたり概ね **$0.00078**（1792×1024、4 ステップ、サブ秒）。テキストモデルは `deepseek-v4-flash` を使用するため、テキストコストは比較になりません。シーン内のビートをタップしていくのは無料です。切り替えを一瞬に保つため、エンジンは選ぶ可能性はあるが最終的に選ばないシーンも先行生成します —— そのため実際の支出は、あなたが実際に見るシーン数よりやや高くなります。
+
+### 4. 画像プロキシ（オプション）
+
+デフォルトではブラウザが画像プロバイダーに直接アクセスするため、設定は不要です —— `NEXT_PUBLIC_IMAGE_PROXY_URL` を空欄のままにすれば、まったく影響ありません。画像が「上から順に」表示される現象（一部のネットワークで Chrome の `ERR_QUIC_PROTOCOL_ERROR` により PNG が行ごとに描画される）に遭遇した場合のみ必要です。小さな Cloudflare Worker をデプロイすると、画像をサーバー側で再取得し HTTP/2 で一括返却します。ワンクリックデプロイは **[infiplot-image-proxy](https://github.com/zonghaoyuan/infiplot-image-proxy)** を参照し、出力された `workers.dev` の URL を `NEXT_PUBLIC_IMAGE_PROXY_URL` に設定してください。
+
+### 5. プレイヤー自身の音声 Key（任意・推奨）
+
+Xiaomi は TTS モデルに RPM/TPM 制限を設けています。公開デプロイで多数のプレイヤーが単一の `TTS_API_KEY` を共有して同時にプレイすると、この制限に達しやすく、**ストーリーも画像も正常なのに音声だけ出ない**という症状になります。対策として、プレイヤーはトップページで**自分の** Xiaomi MiMo Key（無料で取得可）を任意で入力できます。合成は**ブラウザから Xiaomi へ直接**行われ、**Key はプレイヤーのブラウザ内にのみ保存され、あなたのサーバーを一切経由しません**。これにより安定した音声と低遅延が得られます。完全な追加機能であり、未入力ならこれまで通りサーバー側の Key にフォールバックします。
+
+取得・入力の手順は [音声 Key 持ち込みガイド](docs/xiaomi-tts-key.md) を参照してください。
+
+---
+
 ## Roadmap
 
 **実装済み**
diff --git a/README.md b/README.md
index 51d27a4..0f19633 100644
--- a/README.md
+++ b/README.md
@@ -52,6 +52,14 @@ InfiPlot是一款AI实时生成内容的互动剧情游戏，这里没有预设
 
 ---
 
+## 🎬 Demo
+
+<div align="center">
+  <video src="https://github.com/user-attachments/assets/414f0534-50c4-46d3-bc85-c681283b8c79" controls width="100%"></video>
+</div>
+
+---
+
 ## 📸 游戏截图
 
 <table>
@@ -103,7 +111,7 @@ Cloudflare 部署因场景流水线需要更长 CPU 时间，需要 Workers Paid
 <a href="https://vercel.com/new/clone?repository-url=https://github.com/zonghaoyuan/infiplot&env=TEXT_BASE_URL,TEXT_API_KEY,TEXT_MODEL,IMAGE_BASE_URL,IMAGE_API_KEY,IMAGE_MODEL,VISION_BASE_URL,VISION_API_KEY,VISION_MODEL,TTS_BASE_URL,TTS_API_KEY,TTS_SPEECH_MODEL,MOCK_IMAGE&envDescription=Three%20required%20providers%20%2B%20optional%20TTS.%20Any%20OpenAI-compatible%20endpoint%20works%20for%20text%2Fvision.%20TTS%3A%20Xiaomi%20MiMo%20%28free%29%20or%20StepFun%20%28paid%2C%20better%20quality%29.&envLink=https://github.com/zonghaoyuan/infiplot/blob/main/docs/configuration.md"><img src="https://vercel.com/button" alt="Deploy with Vercel" height="34"></a>&nbsp;
 <a href="https://deploy.workers.cloudflare.com/?url=https://github.com/zonghaoyuan/infiplot"><img src="https://deploy.workers.cloudflare.com/button" alt="Deploy to Cloudflare" height="34"></a>
 
-部署完成后，按照 [配置教程](docs/configuration.md) 设置环境变量即可开始游戏。仓库根目录就是应用本身：Vercel 无需额外设置 root directory；在 Cloudflare 上把构建命令设为 `pnpm build:cf` 即可。
+部署完成后，按照[配置教程](#配置教程)设置环境变量即可开始游戏。仓库根目录就是应用本身：Vercel 无需额外设置 root directory；在 Cloudflare 上把构建命令设为 `pnpm build:cf` 即可。
 
 ### Docker 部署（自托管）
 
@@ -116,7 +124,7 @@ curl -fsSL https://raw.githubusercontent.com/zonghaoyuan/infiplot/main/.env.exam
 [ -f .env.local ] || cp .env.example .env.local
 ```
 
-编辑 `.env.local` 填入你的 API Key（详见 [配置教程](docs/configuration.md)），然后启动：
+编辑 `.env.local` 填入你的 API Key（详见[配置教程](#配置教程)），然后启动：
 
 ```bash
 docker compose up -d
@@ -131,6 +139,61 @@ docker compose up -d
 
 ---
 
+## 配置教程
+
+InfiPlot 会与四类模型供应商通信。**文本（Text）和视觉（Vision）** 只走 OpenAI 兼容接口——想用 Google Gemini 的话，把 `*_BASE_URL` 指向其 OpenAI 兼容端点（`https://generativelanguage.googleapis.com/v1beta/openai`）即可；想用 Anthropic Claude 的话，推荐通过兼容网关（如 LiteLLM）转发，官方 OpenAI 兼容层不支持缓存，可能推高成本与延迟。**图像（Image）** 支持 **Runware**（其自有 task-array 协议）与 **OpenAI**（`gpt-image`）。**语音（TTS）** 支持**小米 MiMo**（自有的音色设计/克隆协议——支持角色级音色设计、克隆与逐行演绎指导，免费）和 **StepFun 阶跃星辰**（32 个预设音色，由 AI 自动匹配，付费但体验更好）。
+
+### 1. 选择你的供应商
+
+| 供应商 | 环境变量 | 是否必填 | 推荐 |
+|---|---|---|---|
+| Text · 剧情导演  | `TEXT_BASE_URL` `TEXT_API_KEY` `TEXT_MODEL`        | ✅ | DeepSeek 的 `deepseek-v4-flash` |
+| Image · 场景渲染  | `IMAGE_BASE_URL` `IMAGE_API_KEY` `IMAGE_MODEL`     | ✅ | [Runware](https://runware.ai) 的 `runware:400@6`（FLUX.2 [klein] 9B KV） |
+| Vision · 点击解读  | `VISION_BASE_URL` `VISION_API_KEY` `VISION_MODEL`  | ✅ | Google 的 `gemini-3.5-flash` |
+| TTS · 角色配音 | `TTS_BASE_URL` `TTS_API_KEY` `TTS_SPEECH_MODEL` | 可选 —— 留空则静音运行 | 小米 MiMo 的 `mimo-v2.5-tts`（免费）；付费可选 [StepFun](https://www.stepfun.com) 的 `step-tts-2` |
+
+> **可选 · 指定接口协议**：每类模型都可加一个 `*_PROVIDER` 变量（`TEXT_PROVIDER` / `VISION_PROVIDER` / `IMAGE_PROVIDER`）显式选择接口协议。**不设则保持向后兼容**——文本/视觉默认走 OpenAI 兼容接口，图像按 `*_BASE_URL` 自动判断（`runware.ai` → Runware，否则 OpenAI 兼容；个别在 `runware.ai` 上以 OpenAI 协议提供的模型——如 `image-2-vip`——会按 OpenAI 兼容处理，需要时用 `IMAGE_PROVIDER` 显式覆盖即可）。
+>
+> | 取值 | 适用 | 说明 |
+> |---|---|---|
+> | `openai_compatible`（默认） | Text · Vision · Image | OpenAI Chat Completions / `/images/generations` |
+> | `openai` | Image | OpenAI `gpt-image`，支持参考图编辑 |
+> | `runware` | Image | Runware task-array 协议 |
+>
+> 文本和视觉**仅**支持 `openai_compatible`。要用 Gemini，把 `*_BASE_URL` 指向其 OpenAI 兼容端点（`https://generativelanguage.googleapis.com/v1beta/openai`）即可。要用 Claude，推荐通过兼容网关（如 LiteLLM）转发——Anthropic 官方端点虽提供 OpenAI 兼容层，但不支持缓存，会推高成本与延迟。
+>
+> 此外，`*_BASE_URL` 带不带 `/v1`（甚至末尾多写了 `/chat/completions`）都能正常工作——引擎会自动规范化。
+
+### 2. 填写环境变量
+
+九个变量为必填；TTS 可选（留空则静音运行）。此外还有一个用于低成本测试的开关：
+
+| 变量 | 作用 |
+|---|---|
+| `MOCK_IMAGE=true` | 跳过图像生成，渲染器返回一张静态占位图。剧情、语音、选项照常运行。非常适合在不消耗 Runware 额度的情况下调试 TTS。 |
+
+在哪里设置（确切字段见 `.env.example`）：
+
+- **本地开发** —— `.env.local`
+- **Vercel** —— Project Settings → Environment Variables
+- **Cloudflare Workers** —— 在仓库根目录下逐个执行 `wrangler secret put <NAME>`，或在 dashboard 里设置（Workers → infiplot → Settings → Variables and Secrets）。如果要给 staging 加访问限制，可以在 Worker 前面挂一个 [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/applications/)（零代码，邮箱白名单）。
+
+### 3. 注意成本
+
+使用推荐的三件套时，每一幕场景的开销主要来自图像生成模型。FLUX.2 [klein] 9B KV 的图像大约 **$0.00078** 一张（1792×1024，4 步，亚秒级）；文本模型使用 `deepseek-v4-flash` 时，成本极低。逐拍点过一个场景是免费的。为了让切换瞬间完成，引擎还会预测式地生成那些你可能选、但最终可能没选的场景 —— 所以真实花费会比你实际看到的场景数略高一些。
+
+### 4. 图片代理（可选）
+
+默认浏览器直连图片供应商，无需任何配置 —— 留空 `NEXT_PUBLIC_IMAGE_PROXY_URL` 即可，完全不受影响。只有当你遇到图片「层层加载」（Chrome 在某些网络下 `ERR_QUIC_PROTOCOL_ERROR` 导致 PNG 逐行渲染）时才需要它：部署一个极小的 Cloudflare Worker，把图片改为服务端转发 + HTTP/2 原子返回。一键部署见 **[infiplot-image-proxy](https://github.com/zonghaoyuan/infiplot-image-proxy)**，然后把它给出的 `workers.dev` 地址填进 `NEXT_PUBLIC_IMAGE_PROXY_URL`。
+
+### 5. 玩家自带配音 Key（可选，推荐）
+
+小米对 TTS 模型有 RPM/TPM 限额。当你的公共部署有多人同时游玩、共用同一把 `TTS_API_KEY` 时，很容易撞到限额，表现为**剧情、画面都正常，唯独没有声音**。为此，玩家可以在首页可选地填入**自己的**小米 MiMo Key（免费申请）——配音请求由**浏览器直连小米**完成，**Key 只存在玩家本地、绝不经过你的服务器**，从而获得稳定配音与更低延迟。这是纯增强：不填则照常使用你部署的服务器 Key，行为不变。
+
+申请与填写步骤见 [自带配音 Key 教程](docs/xiaomi-tts-key.md)。
+
+---
+
 ## Roadmap
 
 **已实现**