Deploy Virtual Characters for Build Small Hackathon

.gitattributes

@@ -33,3 +33,13 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+assets/characters/star/focus.png filter=lfs diff=lfs merge=lfs -text
+assets/characters/star/focus_preview_check.png filter=lfs diff=lfs merge=lfs -text
+assets/characters/star/focus_preview_check2.png filter=lfs diff=lfs merge=lfs -text
+assets/characters/star/happy.png filter=lfs diff=lfs merge=lfs -text
+assets/characters/star/idle.png filter=lfs diff=lfs merge=lfs -text
+assets/characters/star/listening.png filter=lfs diff=lfs merge=lfs -text
+assets/characters/star/smile.png filter=lfs diff=lfs merge=lfs -text
+assets/characters/star/talk.png filter=lfs diff=lfs merge=lfs -text
+assets/characters/star/thinking.png filter=lfs diff=lfs merge=lfs -text
+assets/characters/star/worried.png filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,19 @@
+.venv/
+.uv-cache/
+.tmp/
+assets/generated/
+.ruff_cache/
+.pytest_cache/
+.gradio/
+.hf-cache/
+__pycache__/
+**/__pycache__/
+*.pyc
+
+.env
+.logs/
+*.log
+*.tmp
+modal_tts_check.wav
+modal_tts_*_check.wav
+modal_image_check.png

BENCHMARK_RESULTS.md

@@ -0,0 +1,406 @@
+# Modal 实测记录
+
+## 2026-06-11：Gemma 4 12B IT / L40S
+
+模型：`google/gemma-4-12B-it`  
+Modal workspace：`veronicaulises0`  
+Modal profile：`verno`  
+GPU：`NVIDIA L40S`  
+脚本：`modal_apps/modal_gemma_benchmark.py`
+
+### 结论
+
+`google/gemma-4-12B-it` 可以在 Modal 的 L40S 上启动并完成中文生成。显存峰值约 22.3 GB，L40S 足够承载当前 Transformers `dtype="auto"` / `device_map="auto"` 路线。
+
+首次运行主要慢在镜像构建和权重缓存；缓存后，冷容器加载模型约 10 秒，短文本生成速度约 12 tokens/s。
+
+### 运行 1：首次构建 + 首次加载
+
+命令：
+
+```powershell
+$env:VC_BENCH_MODEL="google/gemma-4-12B-it"
+$env:VC_BENCH_GPU="L40S"
+modal run modal_apps/modal_gemma_benchmark.py --max-new-tokens 64
+```
+
+结果：
+
+```json
+{
+  "model_id": "google/gemma-4-12B-it",
+  "gpu": "L40S",
+  "processor_load_s": 5.235,
+  "model_load_s": 107.528,
+  "prompt_tokens": 60,
+  "output_tokens": 54,
+  "generation_s": 4.867,
+  "tokens_per_s": 11.095,
+  "remote_function_s": 117.744,
+  "client_wall_s": 149.096,
+  "cuda_peak_memory_gb": 22.327
+}
+```
+
+Modal run：
+
+```text
+https://modal.com/apps/veronicaulises0/main/ap-2117aPK02FBCs96MlEmOyA
+```
+
+### 运行 2：镜像与权重缓存后
+
+命令：
+
+```powershell
+$env:VC_BENCH_MODEL="google/gemma-4-12B-it"
+$env:VC_BENCH_GPU="L40S"
+modal run modal_apps/modal_gemma_benchmark.py --max-new-tokens 128 --prompt "请你作为一个温柔但有一点科幻感的虚拟角色，用中文回答：如果用户今天压力很大，你会怎么安慰他？"
+```
+
+结果：
+
+```json
+{
+  "model_id": "google/gemma-4-12B-it",
+  "gpu": "L40S",
+  "processor_load_s": 3.501,
+  "model_load_s": 10.303,
+  "prompt_tokens": 65,
+  "output_tokens": 100,
+  "generation_s": 7.841,
+  "tokens_per_s": 12.753,
+  "remote_function_s": 21.761,
+  "client_wall_s": 33.73,
+  "cuda_peak_memory_gb": 22.343
+}
+```
+
+Modal run：
+
+```text
+https://modal.com/apps/veronicaulises0/main/ap-qWkxotIpDObX3lLwmHjI9f
+```
+
+### 开发判断
+
+- L40S 能跑 12B，适合作为项目的主力 Modal 路线。
+- 生成速度足够做 demo，但每次冷容器仍有 20-35 秒端到端等待；正式 demo 时应保持一个 LLM 容器 warm。
+- 当前 Transformers 路线能用，但如果要多人并发，需要后续评估 vLLM / batching / quantization。
+- Gemma 4 在关闭 thinking 时仍可能输出空的 `thought` 通道标记，前端事件流需要过滤该前缀。
+
+## 2026-06-11：TTS 初测
+
+### Chatterbox Multilingual / A10G
+
+状态：已跑通中文合成。
+
+命令：
+
+```powershell
+$env:VC_TTS_BACKEND="chatterbox"
+$env:VC_TTS_GPU="A10G"
+$env:VC_TTS_LANGUAGE_ID="zh"
+modal run modal_apps/modal_tts.py --text "你好，我在听。今天辛苦了，先慢慢呼吸一下。" --emotion concerned --output-path modal_tts_chatterbox_check.wav --repeats 2
+```
+
+结果：
+
+```json
+{
+  "run_1": {
+    "remote_s": 58.593,
+    "audio_duration_s": 4.04,
+    "real_time_factor": 14.503,
+    "was_loaded": false
+  },
+  "run_2": {
+    "remote_s": 6.197,
+    "audio_duration_s": 10.36,
+    "real_time_factor": 0.598,
+    "was_loaded": true
+  },
+  "client_s": 67.836
+}
+```
+
+判断：
+
+- 冷启动重，首次加载模型和中文分词资源约 1 分钟。
+- 热容器可用，第二次合成比实时快，RTF 约 0.60。
+- 适合作为当前中文角色 TTS 主方案候选。
+
+### Kokoro-82M / A10G
+
+状态：未完成有效中文合成测速。
+
+模型页显示 Kokoro v1.0 是多语言模型，发布表写到 8 种语言和 54 个声音；但 Hugging Face 顶部任务标签仍偏 English，中文路径依赖 `misaki` 的中文 G2P。实测中中文初始化连续缺少间接依赖：
+
+- 第一次缺 `ordered_set`
+- 补上后缺 `pypinyin`
+
+判断：
+
+- Kokoro 不是纯英文模型，但中文链路不够稳。
+- 不建议作为本项目主 TTS。
+- 可以保留为低成本 fallback，后续只在依赖补齐后再测。
+
+## 2026-06-11：vLLM / Gemma 4 12B IT
+
+状态：未跑通。
+
+命令：
+
+```powershell
+$env:VC_VLLM_MODEL="google/gemma-4-12B-it"
+$env:VC_VLLM_GPU="L40S"
+$env:VC_VLLM_FAST_BOOT="1"
+modal run modal_apps/modal_vllm_gemma.py --max-tokens 128
+```
+
+结果：
+
+- Modal 镜像构建成功。
+- vLLM 0.21.0 能识别模型，但日志提示 `TransformersMultiModalForCausalLM has no vLLM implementation, falling back to Transformers implementation`。
+- 随后 engine profile run 失败，错误为矩阵 shape mismatch：
+
+```text
+RuntimeError: mat1 and mat2 shapes cannot be multiplied (2048x4096 and 8192x3840)
+```
+
+判断：
+
+- 当前 vLLM 0.21.0 不能直接稳定承载 `google/gemma-4-12B-it`。
+- 这个失败不是 Modal 登录、HF token 或显存问题；模型权重已加载到约 22.56 GiB 后，在 vLLM fallback 执行路径失败。
+- 项目当前主 LLM 路线继续使用 Transformers Modal 服务。
+- 如果要追 vLLM 速度，需要等 vLLM 原生支持 Gemma 4 Unified，或改测另一个 vLLM 原生支���的文本模型。
+
+Modal run：
+
+```text
+https://modal.com/apps/veronicaulises0/main/ap-oSGKVGLu8Jih0nLoPQH3Ub
+```
+
+## 2026-06-12：vLLM 0.22.1 / Gemma 4 12B IT
+
+状态：稳定版仍未跑通。
+
+命令：
+
+```powershell
+$env:VC_VLLM_MODEL="google/gemma-4-12B-it"
+$env:VC_VLLM_VERSION="0.22.1"
+$env:VC_VLLM_GPU="L40S"
+$env:VC_VLLM_FAST_BOOT="1"
+.venv\Scripts\modal.exe run modal_apps/modal_vllm_gemma.py --max-tokens 128
+```
+
+结果：
+
+- PyPI 最新稳定版是 `vllm==0.22.1`，发布日期为 2026-06-05。
+- vLLM 0.22.1 仍把该模型解析为 `TransformersMultiModalForCausalLM`。
+- 日志仍提示没有 vLLM 原生实现，并 fallback 到 Transformers。
+- 随后仍在 engine profile run 阶段失败：
+
+```text
+RuntimeError: mat1 and mat2 shapes cannot be multiplied (2048x4096 and 8192x3840)
+```
+
+判断：
+
+- `vllm==0.22.1` 还不能作为 `google/gemma-4-12B-it` 的可用部署版本。
+- 需要追 vLLM main/nightly，而不是继续测 PyPI 稳定版。
+- 后续已用更新的 nightly `0.22.1rc1.dev468+gfbc3a1907.cu129` 跑通，见下一节。
+
+Modal run：
+
+```text
+https://modal.com/apps/veronicaulises0/main/ap-G9ApqBk26I7ftDfnrHNFwh
+```
+
+## 2026-06-12：vLLM nightly / Gemma 4 12B IT 部署成功
+
+状态：已在 Modal 上跑通并部署。
+
+模型：`google/gemma-4-12B-it`  
+Modal workspace：`veronicaulises0`  
+Modal profile：`verno`  
+GPU：`NVIDIA L40S`  
+vLLM：`0.22.1rc1.dev468+gfbc3a1907.cu129`  
+部署 URL：`https://veronicaulises0--virtual-characters-vllm-gemma-serve.modal.run`
+
+### 关键结论
+
+- vLLM nightly 能把模型解析为 `Gemma4UnifiedForConditionalGeneration`，不再 fallback 到 `TransformersMultiModalForCausalLM`。
+- L40S 上权重加载约 22.83 GiB，KV cache 可用约 15.97 GiB。
+- `max_model_len=8192` 时日志显示 GPU KV cache size 约 108,675 tokens，理论最大并发约 13.27x。
+- 当前部署使用 `VC_SKIP_HF_SECRET=1`，没有把 `hf-token` 挂到 nightly 运行环境；能启动是因为 Modal Volume `vc-hf-cache` 中已有模型权重缓存。
+
+### 成功运行命令
+
+```powershell
+$env:PYTHONIOENCODING="utf-8"
+$env:PYTHONUTF8="1"
+$env:VC_SKIP_HF_SECRET="1"
+$env:VC_VLLM_MODEL="google/gemma-4-12B-it"
+$env:VC_VLLM_PACKAGE="vllm==0.22.1rc1.dev468+gfbc3a1907.cu129"
+$env:VC_VLLM_EXTRA_INDEX_URL="https://wheels.vllm.ai/nightly/cu129"
+$env:VC_VLLM_UV_EXTRA_OPTIONS="--index-strategy unsafe-best-match"
+$env:VC_VLLM_PRE="1"
+$env:VC_VLLM_GPU="L40S"
+$env:VC_VLLM_FAST_BOOT="1"
+.venv\Scripts\modal.exe run modal_apps/modal_vllm_gemma.py --max-tokens 16 --test-timeout 900
+```
+
+结果：
+
+```json
+{
+  "model_id": "google/gemma-4-12B-it",
+  "vllm_package": "vllm==0.22.1rc1.dev468+gfbc3a1907.cu129",
+  "gpu": "L40S",
+  "fast_boot": true,
+  "client_total_s": 197.746,
+  "ttft_s": 5.119,
+  "stream_total_s": 5.68,
+  "completion_tokens": 16,
+  "stream_tokens_per_s": 2.817,
+  "response_preview": "辛苦了，抱抱你。我知道今天一定很不容易，但现在你",
+  "non_stream_s": 1.01,
+  "non_stream_completion_tokens": 16,
+  "non_stream_tokens_per_s": 15.846
+}
+```
+
+Modal run：
+
+```text
+https://modal.com/apps/veronicaulises0/main/ap-2yEEKYd6mH1OkpPNNEPnjB
+```
+
+### 持久部署
+
+命令：
+
+```powershell
+$env:PYTHONIOENCODING="utf-8"
+$env:PYTHONUTF8="1"
+$env:VC_SKIP_HF_SECRET="1"
+$env:VC_VLLM_MODEL="google/gemma-4-12B-it"
+$env:VC_VLLM_PACKAGE="vllm==0.22.1rc1.dev468+gfbc3a1907.cu129"
+$env:VC_VLLM_EXTRA_INDEX_URL="https://wheels.vllm.ai/nightly/cu129"
+$env:VC_VLLM_UV_EXTRA_OPTIONS="--index-strategy unsafe-best-match"
+$env:VC_VLLM_PRE="1"
+$env:VC_VLLM_GPU="L40S"
+$env:VC_VLLM_FAST_BOOT="1"
+.venv\Scripts\modal.exe deploy modal_apps/modal_vllm_gemma.py
+```
+
+结果：
+
+```text
+https://veronicaulises0--virtual-characters-vllm-gemma-serve.modal.run
+```
+
+### 正式 endpoint warm 测试
+
+请求：`POST /v1/chat/completions`
+
+结果：
+
+```json
+{
+  "chat_elapsed_s": 2.607,
+  "content": "别给自己太大压力，你已经做得很棒了。\n累了就先停下来歇一会，我会一直陪在你身边的。",
+  "usage": {
+    "prompt_tokens": 48,
+    "completion_tokens": 31,
+    "total_tokens": 79
+  },
+  "system_fingerprint": "vllm-0.22.1rc1.dev468+gfbc3a1907-3443f622"
+}
+```
+
+注意：
+
+- 正式 endpoint 冷启动需要约 3 分钟，外部 `/health` 请求可能在冷启动窗口超时。
+- 第一次生成会触发 Triton JIT，TTFT 会偏高；warm 后短回复约 10-16 tok/s。
+- 如果清空 Modal Volume 或换新 workspace，当前无 secret 部署会因为无法下载权重而失败。要让它在空缓存环境可复现，需要明确允许 nightly vLLM 环境挂载 `hf-token`，或者先用受信任的独立流程把权重预缓存进 Volume。
+
+## 2026-06-11：TTS 分句流式
+
+状态：可行，但不是底层音频流式。
+
+命令：
+
+```powershell
+$env:VC_TTS_BACKEND="chatterbox"
+$env:VC_TTS_GPU="A10G"
+$env:VC_TTS_LANGUAGE_ID="zh"
+modal run modal_apps/modal_tts.py --text "我在听。今天辛苦了。先慢慢呼吸一下，���吗？" --emotion concerned --output-path modal_tts_sentence_stream_check.wav --sentence-stream
+```
+
+结果：
+
+```json
+{
+  "backend": "chatterbox",
+  "gpu": "A10G",
+  "sentences": 3,
+  "first_audio_s": 58.594,
+  "total_s": 63.31,
+  "events": [
+    {
+      "text": "我在听。",
+      "chunk_s": 58.593,
+      "audio_duration_s": 1.4,
+      "real_time_factor": 41.852
+    },
+    {
+      "text": "今天辛苦了。",
+      "chunk_s": 2.138,
+      "audio_duration_s": 3.0,
+      "real_time_factor": 0.713
+    },
+    {
+      "text": "先慢慢呼吸一下，好吗？",
+      "chunk_s": 2.578,
+      "audio_duration_s": 3.84,
+      "real_time_factor": 0.671
+    }
+  ]
+}
+```
+
+判断：
+
+- Chatterbox 当前 API 是整句生成，不是边采样边输出 PCM 的底层流式。
+- 可实现句子级流式：LLM 每完成一句，TTS 合成一句并立刻发给 Gradio。
+- 冷启动首句很慢；容器 warm 后，后续句子 2-3 秒一段，能支撑 demo。
+
+## 2026-06-11：简单 Modal Demo
+
+新增文件：
+
+```text
+demo_modal_stack.py
+```
+
+用途：
+
+- Gradio 最小端到端烟测。
+- 直接调用 Modal class methods，不需要先 deploy endpoint。
+- LLM 使用当前已跑通的 Transformers `PersonaLLM.generate_text`。
+- TTS 使用 Chatterbox `CharacterTTS.synthesize`，按句生成并逐段更新音频。
+
+运行：
+
+```powershell
+python demo_modal_stack.py
+```
+
+默认端口：
+
+```text
+127.0.0.1:7862
+```

CHARACTER_GENERATION_SPIKE.md

@@ -0,0 +1,152 @@
+# 自动化角色生成风险验证
+
+这不是完整角色工坊实现，而是一个可复现的 Modal 技术 spike。目标是先验证“文生图、图生图、身份保持、姿态控制、表情生成”是否能稳定支撑多表情角色包，再决定是否进入完整 UI。
+
+## 入口
+
+```powershell
+python scripts/run_character_generation_spike.py list-models
+python scripts/run_character_generation_spike.py mock-assets --character-id spike_star --display-name 星核
+python scripts/run_character_generation_spike.py import-tavern --input path\to\card.json --output-dir characters
+```
+
+Modal health check 不加载模型权重：
+
+```powershell
+python scripts/run_character_generation_spike.py modal-health
+```
+
+远程生图会消耗 GPU，必须显式确认：
+
+```powershell
+python scripts/run_character_generation_spike.py modal-probe --candidate flux_schnell --batch-size 1 --confirm-gpu
+python scripts/run_character_generation_spike.py modal-benchmark --candidates flux_schnell qwen_image --confirm-gpu
+python scripts/run_character_generation_spike.py modal-benchmark --candidates qwen_image_edit --init-image path\to\reference.png --include-expressions --confirm-gpu
+python scripts/run_character_generation_spike.py modal-benchmark --candidates qwen_controlnet_union --control-image path\to\pose.png --include-expressions --confirm-gpu
+```
+
+## 模型候选
+
+| ID | 目标 | 模型 | 默认步数 | 状态 |
+| --- | --- | --- | ---: | --- |
+| `flux_schnell` | 速度基线、主视觉候选 | `black-forest-labs/FLUX.1-schnell` | 4 | 已接入 |
+| `qwen_image` | 中文 prompt、文生图质量 | `Qwen/Qwen-Image` | 50 | 已接入 |
+| `qwen_image_edit` | 图生图、表情编辑、局部编辑 | `Qwen/Qwen-Image-Edit` | 50 | 已接入 |
+| `qwen_controlnet_union` | pose/canny/depth 控制动作 | `InstantX/Qwen-Image-ControlNet-Union` | 30 | 已接入 |
+| `instantid_sdxl` | 身份一致性候选 | `InstantX/InstantID` | 30 | 暂不启用 |
+
+`InstantID` 暂时只列入候选，不在 Modal runner 中启用。原因是它依赖 face-analysis 组件和额外模型下载路径；在没有锁定 antelopev2/insightface 部署方式前，先避免把高风险依赖混进第一轮 benchmark。
+
+## 产物结构
+
+mock 资产包：
+
+```text
+assets/generated/character_spike/<character_id>/
+  assets/characters/<character_id>/
+    idle.png
+    listening.png
+    thinking.png
+    worried.png
+    smile.png
+    happy.png
+    talk.png
+    focus.png
+  assets/backgrounds/<character_id>_spike_background.png
+  characters/<character_id>.json
+  generated/
+    asset_grid.png
+    manifest.json
+    report.md
+```
+
+Modal benchmark 会额外创建一层 run 目录：
+
+```text
+assets/generated/character_spike/<character_id>/<run_name>/generated/
+  manifest.json
+  report.md
+  <candidate>/<benchmark_case>/00.png
+  <candidate>/<benchmark_case>/grid.png
+```
+
+## Manifest 记录
+
+`manifest.json` 记录：
+
+- prompt、seed、模型、步数、GPU、宽高。
+- Modal 远端耗时和本地调用 wall time。
+- cold/warm 状态：`loaded_before=false` 表示该候选首次加载权重。
+- 输出图片路径、字节数、失败原因。
+- 人工评分占位：`manual_score`。
+- gate 结果：是否满足进入角色工坊的最低门槛。
+
+## 准入门槛
+
+进入完整角色工坊前必须满足：
+
+- warm 4 张主视觉候选耗时小于 60 秒，或明确标记为慢速模式。
+- 8 张表情/动作总耗时小于 180 秒，或产品上接受后台异步等待。
+- 至少 6/8 张资产肉眼可用。
+- 身份一致性不明显崩坏。
+- 透明抠图在当前舞台里可用。
+
+不达标时，目标降级为：
+
+```text
+导入角色卡 + 单张立绘 + 背景 + 对话
+```
+
+多表情先用 prompt/LLM stage 事件驱动现有静态图，不强推模型批量生成。
+
+## Tavern JSON 导入
+
+支持先导入 JSON 角色卡，不直接污染内置 registry：
+
+```powershell
+python scripts/run_character_generation_spike.py import-tavern --input path\to\card.json --output-dir characters
+```
+
+字段映射：
+
+- `name` -> `display_name`
+- `description/personality/scenario` -> `profile` 和 `summary`
+- `first_mes` -> 首句样例
+- `alternate_greetings` -> 备用开场
+- `creator_notes/tags` -> metadata 和 tags
+- `character_book/world_info/lorebook` -> metadata.character_book
+
+PNG metadata 角色卡暂不解析。若用户给 PNG，先当普通参考图处理，再在第二阶段增加 metadata 解包。
+
+## Stage smoke
+
+生成 mock 包后可以临时走现有 `stage_driver` 渲染，不复制资产到主 app：
+
+```powershell
+python scripts/run_character_generation_spike.py stage-smoke --run-dir assets\generated\character_spike\spike_star --character-id spike_star
+```
+
+也可以把 Modal benchmark 的 8 表情 probe 输出打成舞台资产包：
+
+```powershell
+python scripts/run_character_generation_spike.py package-probe-assets --source-run-dir assets\generated\character_spike\spike_eval\qwen_image_expressions_20260614 --candidate qwen_image --character-id qwen_spike_star --display-name 星核
+```
+
+如果浅色头发/皮肤被简单抠图误伤，先保留背景作为降级包：
+
+```powershell
+python scripts/run_character_generation_spike.py package-probe-assets --source-run-dir assets\generated\character_spike\spike_eval\qwen_image_expressions_20260614 --candidate qwen_image --character-id qwen_spike_star_bg --display-name 星核 --keep-background
+```
+
+输出：
+
+```text
+generated/stage_smoke.html
+```
+
+如果人工确认某个包可用，再显式安装到 app 路径：
+
+```powershell
+python scripts/run_character_generation_spike.py install-package --run-dir assets\generated\character_spike\spike_star --dry-run
+python scripts/run_character_generation_spike.py install-package --run-dir assets\generated\character_spike\spike_star
+```

DEVELOPMENT_GUIDE.md

@@ -0,0 +1,455 @@
+# 开发规格
+
+## 目标
+
+后续开发要围绕一个目标：做出低延迟、有角色存在感的多模态虚拟角色。
+
+不要把 MVP 做成普通 chatbot，也不要把用户自定义角色创建器放在第一屏。
+
+## 推荐文件结构
+
+```text
+Virtual-characters/
+  app.py
+  requirements.txt
+  README.md
+  PROJECT_DESIGN.md
+  RESEARCH_NOTES.md
+  DEVELOPMENT_GUIDE.md
+  src/
+    character_registry.py
+    persona_skills.py
+    dialogue_engine.py
+    stream_protocol.py
+    stage_driver.py
+    tts_engine.py
+    vision_engine.py
+    image_engine.py
+  assets/
+    characters/
+    generated/
+    live2d/
+```
+
+## Gradio 页面结构
+
+使用 `gr.Blocks`，不要只用一个 `ChatInterface` 包到底。
+
+建议布局：
+
+```text
+左侧：角色选择、角色简介、模式开关
+中间：角色舞台 gr.HTML
+右侧：Chatbot、输入框、Audio 输出
+底部或折叠区：事件流、当前情绪、skill、模型调试信息
+```
+
+推荐组件：
+
+- `gr.Radio` / `gr.Dropdown`：选择角色。
+- `gr.Chatbot`：聊天历史。
+- `gr.Textbox`：文字输入。
+- `gr.Audio(streaming=True, autoplay=True)`：播放 TTS 音频块。
+- `gr.Image(sources=["upload", "webcam"])`：上传图片或摄像头拍照。
+- `gr.HTML`：角色舞台。
+- `gr.JSON` / `gr.Code`：展示事件流和调试信息。
+- `gr.State`：保存当前角色、短期记忆、当前情绪、视觉观察、事件历史。
+
+## 角色配置
+
+每个内置角色是一套 `CharacterPackage`，不是单独一段 prompt。
+
+```json
+{
+  "id": "star_knight",
+  "display_name": "星萤",
+  "inspiration": "Firefly-like sci-fi heroine, originalized",
+  "profile": {
+    "identity": "星港失事后幸存的装甲驾驶员",
+    "core_traits": ["温柔", "克制", "隐藏痛苦", "战斗时冷静"],
+    "relationship_to_user": "把用户当成临时通讯频道里的同伴",
+    "boundaries": ["不声称自己是官方角色", "不复述商业 IP 的完整剧情"]
+  },
+  "dialogue_style": {
+    "tone": "轻声、真诚、偶尔停顿",
+    "sentence_shape": "短句为主",
+    "catchphrases": ["我还在。", "别担心，我会守住这里。"]
+  },
+  "skills": ["daily_chat", "emotional_support", "lore_hint", "battle_focus"],
+  "voice": {
+    "tts_model": "kokoro_or_other",
+    "voice_preset": "soft_young_female",
+    "pace": "slow",
+    "emotion_strength": 0.6
+  },
+  "visual": {
+    "mode": "static_image_or_live2d",
+    "image_prompt": "original anime sci-fi girl, silver hair, teal eyes, light armor",
+    "expressions": ["idle", "smile", "worried", "thinking", "battle_focus"]
+  }
+}
+```
+
+## 流式设计原则
+
+### 不使用“完整 JSON 后处理”作为主链路
+
+如果模型必须先完整生成：
+
+```json
+{
+  "reply_text": "...很长一段话...",
+  "emotion": "...",
+  "motion": "...",
+  "voice": {}
+}
+```
+
+那么页面必须等 JSON 结束才能知道角色该做什么。用户会看到角色呆住，TTS 也无法尽早开始。
+
+主链路应改成 **事件流协议**：模型一边生成，后端一边解析，Gradio 一边 `yield` 更新 UI。
+
+### 推荐协议：SSE + JSON 事件
+
+外部接口优先使用 SSE，也就是 `text/event-stream`。每个 SSE frame 的 `data:` 里放一个完整 JSON 事件。这样浏览器、Modal、FastAPI 和 OpenAI-compatible 流式接口都更容易衔接。
+
+内部日志和测试文件可以保存成 NDJSON。也就是一行一个 JSON 事件。NDJSON 适合落盘和调试，但不要把“模型必须原生输出合法 NDJSON”作为唯一方案。
+
+示例：
+
+```jsonl
+{"type":"stage","expression":"thinking","motion":"look_down","duration_ms":600}
+{"type":"voice","style":"soft","speed":0.92,"pitch":1.04}
+{"type":"skill","name":"emotional_support"}
+{"type":"text_delta","text":"嗯，"}
+{"type":"stage","expression":"worried","motion":"gentle_blink"}
+{"type":"text_delta","text":"我在听。你今天好像比平时更累一点。"}
+{"type":"sentence_end"}
+{"type":"text_delta","text":"先别急着解释，坐一会儿也可以。"}
+{"type":"sentence_end"}
+{"type":"stage","expression":"soft_smile","motion":"idle"}
+{"type":"done"}
+```
+
+优点：
+
+- `stage` 可以先到，角色先抬头、思考、眨眼。
+- `voice` 可以先到，TTS 知道第一句该用什么语气。
+- `text_delta` 可以流式更新聊天框。
+- `sentence_end` 可以触发分句 TTS，用户不必等整段话结束。
+- `done` 用于收尾和状态归档。
+
+推荐实现：
+
+```text
+LLM / planner / rules
+  -> 后端统一转成 CharacterEvent
+  -> Modal/FastAPI 用 SSE 输出
+  -> Gradio handler 消费事件并 yield 多个组件状态
+  -> 调试面板把事件流另存为 NDJSON
+```
+
+这样即使底层模型只会普通 token streaming，后端也可以在句子边界、关键词、初始规划结果里补充 `stage`、`voice`、`skill` 事件。
+
+### 事件类型
+
+必须支持：
+
+- `stage`：控制角色舞台。
+- `voice`：控制 TTS 参数。
+- `skill`：说明本轮使用的 persona skill。
+- `text_delta`：追加回复文本。
+- `sentence_end`：触发当前句子的 TTS。
+- `vision_note`：可选，说明当前视觉输入的理解结果。
+- `debug`：可选，只展示在调试面板。
+- `done`：结束事件。
+- `error`：模型输出损坏或工具失败。
+
+事件字段：
+
+```json
+{
+  "type": "stage",
+  "expression": "worried",
+  "motion": "gentle_blink",
+  "intensity": 0.7,
+  "duration_ms": 800
+}
+```
+
+```json
+{
+  "type": "voice",
+  "style": "soft",
+  "speed": 0.92,
+  "pitch": 1.04,
+  "energy": 0.45
+}
+```
+
+```json
+{
+  "type": "text_delta",
+  "text": "我在听。"
+}
+```
+
+## Gradio 流式输出实现
+
+Gradio 支持用 Python generator 做流式输出。事件处理函数不要 `return` 一次性结果，而是多次 `yield`。
+
+输出组件建议：
+
+```python
+outputs = [
+    chatbot,
+    character_stage,
+    audio_output,
+    event_debug,
+    state,
+]
+```
+
+伪代码：
+
+```python
+def respond_stream(user_text, chat_history, character_id, state):
+    ctx = build_context(user_text, chat_history, character_id, state)
+
+    partial_text = ""
+    sentence_buffer = ""
+    current_voice = default_voice(character_id)
+    stage_state = make_stage_state(character_id, expression="listening")
+
+    yield update(chat_history, stage_state, None, {"type": "stage", "expression": "listening"}, state)
+
+    for event in llm_event_stream(ctx):
+        if event["type"] == "stage":
+            stage_state = apply_stage_event(stage_state, event)
+            yield update(chat_history, stage_state, None, event, state)
+
+        elif event["type"] == "voice":
+            current_voice = merge_voice(current_voice, event)
+            yield update(chat_history, stage_state, None, event, state)
+
+        elif event["type"] == "text_delta":
+            partial_text += event["text"]
+            sentence_buffer += event["text"]
+            chat_history = set_assistant_partial(chat_history, partial_text)
+            yield update(chat_history, stage_state, None, event, state)
+
+        elif event["type"] == "sentence_end":
+            audio_chunk = synthesize_sentence(sentence_buffer, current_voice)
+            sentence_buffer = ""
+            stage_state = apply_stage_event(stage_state, {"type": "stage", "motion": "talk"})
+            yield update(chat_history, stage_state, audio_chunk, event, state)
+
+        elif event["type"] == "done":
+            stage_state = apply_stage_event(stage_state, {"type": "stage", "expression": "idle"})
+            yield update(chat_history, stage_state, None, event, state)
+```
+
+注意：
+
+- Gradio generator 需要启用 queue。
+- `gr.Audio(streaming=True, autoplay=True)` 可以接收后端逐块 yield 的音频。
+- 音频块最好长度稳定，并且大于 1 秒，避免播放不稳定。
+- 摄像头和麦克风输入可以用 `.stream()`，但第一版建议限制 `time_limit` 和 `stream_every`，避免占满队列。
+
+## LLM 输出策略
+
+### 方案 A：单模型直接输出事件流
+
+一个模型直接输出 JSON event lines，再由后端包装成 SSE。
+
+优点：
+
+- 架构简单。
+- 情绪、文字和动作天然同源。
+
+缺点：
+
+- 小模型可能输出非法 JSON 行。
+- 需要严格 prompt、解析器和修复策略。
+
+只适合实验。不要把它作为唯一生产路径。
+
+### 方案 B：快规划器 + 文本流模型
+
+先用一个很短的规划 prompt 生成首批控制事件：
+
+```jsonl
+{"type":"stage","expression":"thinking","motion":"look_at_user"}
+{"type":"voice","style":"soft","speed":0.95}
+{"type":"skill","name":"emotional_support"}
+```
+
+然后主模型流式输出文字，后端用规则或轻量分类器在分句处补充情绪事件。
+
+优点：
+
+- 页面响应更快。
+- 首屏角色很快有动作。
+- 对 JSON 合法性要求更低。
+
+缺点：
+
+- 情绪和文本可能不完全一致。
+
+建议第一版采用 **B 的变体**：先快速输出一个初始 stage/voice/skill，再让主模型输出文本；后端在分句处补充情绪事件。这样响应最快，也最不容易被非法 JSON 卡住。
+
+### 方案 C：纯文本流 + 后处理情绪分类
+
+模型只流文本。后端每完成一句话，用轻量分类器或规则推断情绪。
+
+优点：最稳。
+
+缺点：不够“模型自己输出情绪”，角色动作也会滞后。
+
+只作为 fallback。
+
+## 解析和容错
+
+模型事件流、Modal SSE、规则补充事件都必须经过 `stream_protocol.py`。
+
+职责：
+
+- 解析 SSE `data:` payload 或内部 NDJSON。
+- 丢弃或修复不合法事件。
+- 对未知字段做忽略，不让 UI 崩。
+- 对缺失字段补默认值。
+- 限制事件频率，防止 stage 抖动。
+- 把模型输出事件归一化为前端可消费状态。
+
+容错策略：
+
+```text
+非法 JSON 行 -> 作为 debug 记录，不进入舞台
+未知 type -> debug
+text_delta 缺 text -> 丢弃
+stage 缺 expression/motion -> 使用当前状态
+voice 参数越界 -> clamp
+长时间没有 text_delta -> ��示 thinking 状态
+模型结束但没有 done -> 后端补 done
+```
+
+## 角色舞台协议
+
+后端不直接控制 Live2D 细节。后端只输出抽象状态：
+
+```json
+{
+  "expression": "worried",
+  "motion": "gentle_blink",
+  "mouth": "talking",
+  "gaze": "user",
+  "intensity": 0.7
+}
+```
+
+`stage_driver.py` 负责映射：
+
+- 静态头像/CSS：切图、晃动、嘴部光效。
+- 2.5D HTML：表情层、CSS transform、嘴型动画。
+- Live2D：expression、motion、parameter、hotkey。
+
+这样以后替换表现层时，不需要改对话模型。
+
+## TTS 流式策略
+
+不要等全文结束再 TTS。使用分句级 TTS：
+
+1. LLM 输出 `voice` 事件。
+2. LLM 流式输出 `text_delta`。
+3. 后端遇到中文句号、问号、叹号、换行，或模型输出 `sentence_end`。
+4. 后端把当前句子送入 TTS。
+5. TTS 产出音频块后立即 yield 到 `gr.Audio(streaming=True, autoplay=True)`。
+6. 角色舞台进入 `talk` motion，音频结束后回 idle 或下一句 motion。
+
+第一版可以不做真正逐 token TTS。分句 TTS 已经能显著降低等待感。
+
+## 摄像头流式策略
+
+第一版不做持续实时视频理解。推荐：
+
+- 上传图片：稳定必做。
+- 摄像头拍照：可选。
+- 低频 stream：实验功能。
+
+如果做 `.stream()`：
+
+- `stream_every` 不要太小，建议先 1-3 秒。
+- `time_limit` 必须设置。
+- VLM 不要每帧都跑，可以抽样或节流。
+- 视觉结果写入 `state.last_vision_note`，下一轮对话使用。
+
+## 生图策略
+
+生图只在后台资产生成或用户明确触发时运行。
+
+流程：
+
+```text
+CharacterPackage.visual.image_prompt
+  -> image_engine
+  -> 角色头像/半身像/背景
+  -> assets/generated/
+  -> stage_driver 使用
+```
+
+用户自定义角色：
+
+```text
+上传参考图/描述
+  -> VLM 提取抽象视觉元素
+  -> LLM 原创化 visual prompt
+  -> 生图
+  -> 保存为新 CharacterPackage
+```
+
+## MVP 开发顺序
+
+### Day 1：角色库和事件流
+
+- 建 `CharacterPackage`。
+- 建 3 个内置角色。
+- 实现 `llm_event_stream` 的 mock 版本。
+- 实现 `stream_protocol.py`。
+- Gradio 页面能流式显示文本和事件调试。
+
+### Day 2：角色舞台和 TTS
+
+- 实现 `CharacterStage(gr.HTML)`。
+- stage 支持 listening、thinking、talking、happy、worried。
+- 接分句 TTS。
+- `sentence_end` 后能播放音频并让嘴部动。
+
+### Day 3：真实模型、视觉输入、生图
+
+- 接真实 LLM 或 Inference Provider。
+- 上传图片后用 VLM 生成 `vision_note`。
+- 接生图生成默认头像或重绘头像。
+
+### Day 4：打磨和演示
+
+- 调整内置角色差异。
+- 优化流式延迟。
+- 加载一个 Live2D 或 2.5D 可动表现层作为加分项。
+- 准备 README、示例对话和演示脚本。
+
+## 必须避免
+
+- 等完整 JSON 结束后才更新 UI。
+- 每轮对话都跑生图。
+- 直接克隆商业角色声音。
+- 公开 Space 直接复刻商业角色图像、台词和官方设定。
+- 把摄像头实时流作为第一版主链路。
+- 让前端执行模型生成的任意 JavaScript。
+
+## 官方能力依据
+
+- Gradio 支持 Python generator 流式输出，可以反复 `yield` 组件值。
+- Gradio `Audio(streaming=True, autoplay=True)` 支持后端逐块 yield 音频。
+- Gradio `Image` 和 `Audio` 支持 `.stream()` 输入事件，适合摄像头和麦克风低频流。
+- Gradio `.stream()` 应设置 `time_limit` 和 `stream_every`，避免单用户长期占用队列。
+- Modal `fastapi_endpoint` 支持 FastAPI `StreamingResponse`，可以用 `text/event-stream` 直接发 SSE。

MODAL_DEPLOYMENT.md

@@ -0,0 +1,478 @@
+# Modal 部署与模型选择
+
+## 目标
+
+Modal 负责承载重模型和 GPU 推理，Hugging Face Space / Gradio 只负责交互界面、状态编排和轻量逻辑。
+
+目标不是把所有模型常驻在 GPU 上，而是按需调用、缓存权重、控制冷启动和并发，尽量节省 hackathon 额度。
+
+```text
+Gradio Space
+  -> Modal LLM / VLM endpoint
+  -> Modal TTS endpoint
+  -> Modal image generation endpoint
+```
+
+## 当前模型判断
+
+### Google / Gemma 系列
+
+截至 2026-06-11，Google 在 Hugging Face 上有最新的 Gemma 4 12B 规格：
+
+- `google/gemma-4-12B-it`
+- `google/gemma-4-12B`
+
+其中 `google/gemma-4-12B-it` 是 Gemma 4 12B Unified instruction-tuned 模型。它支持文本、图片、音频、视频输入并生成文本输出，许可证是 Apache-2.0。这个模型非常适合本项目：它可以同时处理角色对话、图片理解和视频片段理解。当前页面先保留文字 + 图片输入，不接语音输入链路。
+
+当前官方 Hugging Face 页面核到的 Gemma 4 规格是：
+
+- `google/gemma-4-E2B-it`
+- `google/gemma-4-E4B-it`
+- `google/gemma-4-12B-it`
+- `google/gemma-4-26B-A4B-it`
+- `google/gemma-4-31B-it`
+
+关键差异：
+
+- E2B / E4B：支持文本、图片、音频输入，适合“音频直接进模型”的实验。
+- 12B Unified：支持文本、图片、音频、视频输入；约 11.95B 参数，256K context；encoder-free unified multimodal 架构，适合作为主力中等规模模型。
+- 26B A4B：MoE，总参数约 26B，活跃参数约 4B，支持文本和图片，适合主对话、角色推理、视觉理解，但不支持原生音频输入。
+- 31B：文本和图片能力强，但更贵，不适合作为默认在线模型。
+
+结论：
+
+- `google/gemma-4-12B-it` 应该作为当前首选主模型候选。
+- 当前改版暂不提供语音输入，先集中验证文字、图片和 TTS 输出。
+- 如果后续重新评估语音输入，优先单独做一轮 Gemma 音频输入实验，不并入当前 TTS 交付。
+- 如果想要更强文本/图像推理质量，再试 `gemma-4-26B-A4B-it`。
+- 不建议默认上 31B，除非做离线评估或最终 demo 高质量路线。
+
+### TTS 候选
+
+#### Chatterbox
+
+推荐作为第一优先级实验。
+
+原因：
+
+- 支持多语言，包括中文。
+- 支持情绪夸张度 / intensity control。
+- Hugging Face 模型页标 MIT。
+- Modal 官方有 Chatterbox TTS API 示例。
+- 很适合角色项目，因为可以把模型输出的 `voice.energy` / `emotion` 映射成 exaggeration、cfg、语速等参数。
+
+注意：
+
+- 有 voice cloning 能力，但公开 demo 不要克隆商业角色或真实声优。
+- 可先使用内置 voice prompt 或原创 voice prompt。
+
+#### Kokoro-82M
+
+只适合作为省额度 fallback，不建议作为中文角色主 TTS。
+
+原因：
+
+- 82M，非常轻。
+- Apache-2.0。
+- 推理成本低，速度快。
+
+限制：
+
+- Hugging Face 模型页顶部标签偏 English，虽然模型事实里写 v1.0 是多语言。
+- 中文路径依赖额外 G2P 包，实测暴露 `ordered_set` / `pypinyin` 等间接依赖问题。
+- 角色表现力和中文稳定性都不如 Chatterbox Multilingual。
+
+#### Dia-1.6B
+
+适合作为表达力实验，不建议作为第一默认。
+
+原因：
+
+- 能生成对话式 TTS。
+- 支持笑声、叹气等非语言表达。
+
+限制：
+
+- 模型页说明当前主要支持英文生成。
+- 需要约 10GB VRAM。
+- 也有 voice cloning 能力，公开 demo 要避免身份滥用。
+
+#### Sesame CSM-1B
+
+可作为研究候选。
+
+原因：
+
+- Conversational Speech Model，支持文本和音频上下文。
+- Transformers 已支持。
+
+限制：
+
+- 模型 gated，需要接受访问条件。
+- 上手和稳定性要单独验证。
+
+### 语音输入策略
+
+当前实现不提供语音输入，也不部署独立转写服务。第一阶段只做文字输入、图片输入和 TTS 输出，避免把交互问题和模型冷启动问题混在一起。
+
+### 生图候选
+
+推荐先用 FLUX.1-schnell。
+
+原因：
+
+- 适合快速生成角色头像、半身像、背景。
+- Modal 官方有 Flux on H100 示例。
+- `schnell` 步数少，适合按需生成。
+
+使用原则：
+
+- 不在每轮对话里调用。
+- 只在角色资产生成、重绘、创建自定义角色时调用。
+- 生成后缓存到本地或 Modal Volume，Gradio 直接读缓存图。
+
+## Modal 服务拆分
+
+建议拆成多个 Modal app 或多个 class，避免一个容器装所有模型。
+
+### 1. `modal_llm.py`
+
+用途：
+
+- 角色对话。
+- 图片理解。
+- 输出 SSE 事件流。
+
+候选模型：
+
+- 省资源路线：`google/gemma-4-E4B-it`
+- 主推路线：`google/gemma-4-12B-it`
+- 高质量路线：`google/gemma-4-26B-A4B-it`
+
+接口：
+
+```http
+POST /persona/events
+Accept: text/event-stream
+```
+
+输出：
+
+```text
+data: {"type":"stage","expression":"thinking","motion":"look_at_user"}
+
+data: {"type":"voice","style":"soft","speed":0.92,"energy":0.45}
+
+data: {"type":"text_delta","text":"嗯，"}
+
+data: {"type":"sentence_end"}
+
+data: {"type":"done"}
+```
+
+### 2. `modal_tts.py`
+
+用途：
+
+- 分句 TTS。
+- 返回 WAV/MP3 bytes。
+- 可选支持流式音频。
+
+候选模型：
+
+- 默认：Chatterbox Multilingual。
+- fallback：Kokoro-82M。
+- 实验：Dia / CSM。
+
+接口：
+
+```http
+POST /tts
+```
+
+输入：
+
+```json
+{
+  "text": "我在听。",
+  "voice_id": "star_knight_soft",
+  "emotion": "concerned",
+  "speed": 0.92,
+  "energy": 0.45
+}
+```
+
+输出：
+
+- `audio/wav` bytes
+- 或 JSON 包含临时文件 URL
+
+### 3. `modal_image.py`
+
+用途：
+
+- 生成内置角色图。
+- 重绘角色头像。
+- 自定义角色资产生成。
+
+候选模型：
+
+- FLUX.1-schnell
+- SDXL fallback
+
+接口：
+
+```http
+POST /image/character
+```
+
+## 省额度策略
+
+### 模型路由
+
+默认不要所有请求都打最大模型。
+
+建议路由：
+
+```text
+纯文字日常聊天 -> E4B 或 12B
+图片输入 -> Gemma 4 12B / E4B / 26B A4B
+音频输入实验 -> Gemma 4 12B 或 E4B
+中等成本角色回复 -> Gemma 4 12B
+高质量角色回复 / 最终 demo -> 26B A4B
+TTS -> Chatterbox 或 Kokoro
+生图 -> 用户明确点击才调用
+```
+
+### 冷启动和缓存
+
+必须使用 Modal Volume 缓存 Hugging Face 权重：
+
+```text
+/root/.cache/huggingface -> huggingface-cache volume
+/root/.cache/vllm -> vllm-cache volume
+```
+
+服务参数建议：
+
+- 开发期 `scaledown_window=60-180s`
+- demo 录制期 `scaledown_window=5-15min`
+- 公开 demo 期只让主 vLLM LLM 使用 `min_containers=1`，不要把 TTS、生图一起常驻
+- 大模型用固定 revision，避免模型仓库更新导致不可复现
+- 不要在 Gradio 启动时预热所有模型
+- 只预热当前选择的角色和当前模型
+
+主 vLLM 常驻开关：
+
+```powershell
+python scripts/set_modal_vllm_autoscaler.py on
+python scripts/set_modal_vllm_autoscaler.py off
+```
+
+如果希望部署配置本身保持常驻，部署前设置：
+
+```powershell
+$env:VC_VLLM_MIN_CONTAINERS="1"
+$env:VC_VLLM_BUFFER_CONTAINERS="0"
+$env:VC_VLLM_SCALEDOWN_WINDOW="1200"
+modal deploy modal_apps/modal_vllm_gemma.py
+```
+
+`scaledown_window` 只能减少短时间空闲后的冷启动；真正避免从零启动要使用 `min_containers=1`。这会让 GPU 24 小时计费。
+
+### 一周常驻成本
+
+按 Modal 2026-06-14 公开 GPU 价格，7 天是 168 小时：
+
+| GPU | 约每小时 | 约 7 天 |
+| --- | ---: | ---: |
+| T4 | $0.5904 | $99.19 |
+| L4 | $0.7992 | $134.27 |
+| A10 | $1.1016 | $185.07 |
+| L40S | $1.9512 | $327.80 |
+| A100-40GB | $2.0988 | $352.60 |
+| A100-80GB | $2.4984 | $419.73 |
+| H100 | $3.9492 | $663.47 |
+
+这些是 GPU-only 估算，CPU、内存、区域倍率、非抢占、Volume 存储等另计。当前已验证的 `google/gemma-4-12B-it` vLLM 路线使用 L40S，因此 7 天常驻只算 GPU 也超过 $240；$240 约能覆盖 L40S 123 小时。A10 一周 GPU-only 约 $185，但当前 12B vLLM 没有在 A10 上验证，显存余量风险较高。
+
+## 当前 Modal 实测
+
+2026-06-11 已在 `verno / veronicaulises0` Modal workspace 测试 `google/gemma-4-12B-it` + `L40S`：
+
+- 首次运行：包含镜像构建和首次权重缓存，客户端总耗时约 149.1s。
+- 缓存后运行：客户端总耗时约 33.7s；模型加载约 10.3s；生成 100 tokens 用时约 7.84s，约 12.75 tokens/s。
+- 显存峰值：约 22.34 GB。
+
+详细记录见 `BENCHMARK_RESULTS.md`。
+
+vLLM 稳定版已尝试 `google/gemma-4-12B-it`，当前不可用。`0.21.0` 和 PyPI 最新稳定版 `0.22.1` 都会把模型解析为 `TransformersMultiModalForCausalLM`，提示没有 vLLM 原生实现并 fallback 到 Transformers，随后在 profile run 出现 shape mismatch。
+
+截至 2026-06-12，Gemma 4 Unified 的可用 vLLM 路线是 main/nightly，而不是 PyPI 稳定版。当前已在 Modal L40S 上跑通 `vllm==0.22.1rc1.dev468+gfbc3a1907.cu129`，vLLM 日志解析架构为 `Gemma4UnifiedForConditionalGeneration`，并成功通过 OpenAI-compatible `/v1/chat/completions` 生成中文回复。
+
+当前持久部署：
+
+```text
+https://veronicaulises0--virtual-characters-vllm-gemma-serve.modal.run
+```
+
+部署注意：
+
+- 当前部署设置 `VC_SKIP_HF_SECRET=1`，没有把 `hf-token` 挂载到 nightly vLLM 环境。
+- 能启动是因为 `vc-hf-cache` Modal Volume 中已有 `google/gemma-4-12B-it` 权重缓存。
+- 如果清空 Volume 或迁移 workspace，需要先预缓存权重，或者明确批准 nightly 环境挂载 `hf-token`。
+- 正式 endpoint 冷启动约 3 分钟；warm 后短中文回复实测约 10-16 tok/s。
+
+短期策略：
+
+- demo 主线可以切到当前 vLLM nightly endpoint，但要保留 Transformers Modal 服务作为 fallback。
+- 如果继续追 vLLM 速度，优先优化当前 nightly endpoint 的冷启动、warmup 和 `--enforce-eager` 策略。
+- 不要再浪费额度反复测试 `vllm==0.22.1` + `google/gemma-4-12B-it` 这一组合。
+
+nightly 部署命令：
+
+```powershell
+$env:PYTHONIOENCODING="utf-8"
+$env:PYTHONUTF8="1"
+$env:VC_SKIP_HF_SECRET="1"
+$env:VC_VLLM_MODEL="google/gemma-4-12B-it"
+$env:VC_VLLM_PACKAGE="vllm==0.22.1rc1.dev468+gfbc3a1907.cu129"
+$env:VC_VLLM_EXTRA_INDEX_URL="https://wheels.vllm.ai/nightly/cu129"
+$env:VC_VLLM_UV_EXTRA_OPTIONS="--index-strategy unsafe-best-match"
+$env:VC_VLLM_PRE="1"
+$env:VC_VLLM_GPU="L40S"
+$env:VC_VLLM_FAST_BOOT="1"
+.venv\Scripts\modal.exe deploy modal_apps/modal_vllm_gemma.py
+```
+
+TTS 已测试 Chatterbox 分句流式：底层不是音频 token 流式，但可以按句合成、按句播放。warm 后每句约 2-3 秒，足够做 demo。
+
+### 并发
+
+TTS 可以允许较高并发；LLM 需要保守。
+
+建议初始值：
+
+```text
+LLM: max_inputs 4-16，按模型和 GPU 调
+TTS: max_inputs 4-10
+Image: max_inputs 1-2
+```
+
+### GPU 选择
+
+初始建议：
+
+- Chatterbox TTS：A10G / L4 起步。
+- Kokoro：CPU / L4 / T4 均可试。
+- Gemma 4 E4B：L4 / A10 / L40S 起步实测。
+- Gemma 4 12B：L40S / A100 起步更稳，量化后可再评估更低规格。
+- Gemma 4 26B A4B：A100 / H100 / H200 更稳，Modal 官方 vLLM 示例用了 H200。
+- FLUX.1-schnell：H100 最快，但开发期可以不常驻，按需运行。
+
+## 流式协议与 Modal
+
+Modal 支持 FastAPI `StreamingResponse`。因此推荐 Modal 端直接输出 SSE：
+
+```python
+from fastapi.responses import StreamingResponse
+
+def event_stream():
+    yield b'data: {"type":"stage","expression":"thinking"}\n\n'
+    yield b'data: {"type":"text_delta","text":"嗯，"}\n\n'
+    yield b'data: {"type":"done"}\n\n'
+
+return StreamingResponse(event_stream(), media_type="text/event-stream")
+```
+
+注意：
+
+- 不要要求模型原生输出完美 NDJSON。
+- 后端可以先发初始 stage/voice 事件，再转发模型 token。
+- Gradio 端消费 SSE，转换成组件多次 `yield`。
+- 调试时可以把 SSE payload 保存成 NDJSON 文件。
+
+## Modal Secret
+
+需要的 secret：
+
+- `hf-token`：默认 Hugging Face token secret，用于下载 gated 或大模型权重。
+- 可选 `modal-proxy-auth`：如果部署私有 endpoint。
+
+如果 Modal 里已经有别的 Secret 名称，可以在运行或部署前设置：
+
+```powershell
+$env:VC_HF_SECRET_NAME="your-secret-name"
+```
+
+如果只是做 health smoke test，且还没有创建 HF Secret，可以临时设置：
+
+```powershell
+$env:VC_SKIP_HF_SECRET="1"
+python scripts/check_modal_connectivity.py --mode remote-methods
+```
+
+这个开关默认只适合检查 Modal 容器启动。例外是当前 vLLM nightly + Gemma 4 路线：为了避免把 `hf-token` 暴露给 nightly 依赖栈，可以在确认 `vc-hf-cache` Volume 已经有完整权重缓存后使用 `VC_SKIP_HF_SECRET=1` 部署。常规稳定依赖栈仍建议创建 `hf-token`，并在 Hugging Face 上接受相关模型的访问条件。
+
+注意不要把 token 写进仓库。
+
+## 开发顺序
+
+### 第一步：TTS endpoint
+
+先做 Chatterbox 或 Kokoro，因为它最容易让 demo 有角色存在感。
+
+产物：
+
+- `modal_tts.py`
+- `/tts` endpoint
+- Gradio 调用 TTS 并播放音频
+
+### 第二步：LLM event endpoint
+
+先用 mock 事件流，再接 Gemma。
+
+产物：
+
+- `modal_llm.py`
+- `/persona/events` SSE endpoint
+- Gradio 能显示 text_delta、stage、voice、skill
+
+### 第三步：图像输入
+
+先用上传图片，不做实时摄像头。
+
+产物：
+
+- 图片传到 LLM/VLM endpoint
+- 生成 `vision_note`
+- 角色基于 `vision_note` 回复
+
+### 第四步：生图
+
+按需生成角色头像。
+
+产物：
+
+- `modal_image.py`
+- `/image/character`
+- 缓存生成结果
+
+## 参考链接
+
+- Modal vLLM / Gemma 示例: https://modal.com/docs/examples/vllm_inference
+- Modal streaming endpoints: https://modal.com/docs/guide/streaming-endpoints
+- Modal GPU: https://modal.com/docs/guide/gpu
+- Modal Volumes: https://modal.com/docs/guide/volumes
+- Modal Chatterbox TTS: https://modal.com/docs/examples/chatterbox_tts
+- Modal Flux: https://modal.com/docs/examples/flux
+- Gemma 4 12B IT: https://huggingface.co/google/gemma-4-12B-it
+- Gemma 4 26B A4B: https://huggingface.co/google/gemma-4-26B-A4B-it
+- Gemma 4 E4B: https://huggingface.co/google/gemma-4-E4B-it
+- vLLM PyPI: https://pypi.org/project/vllm/
+- vLLM supported models latest docs: https://docs.vllm.ai/en/latest/models/supported_models/
+- vLLM nightly wheels: https://docs.vllm.ai/en/latest/contributing/ci/nightly_builds/
+- Kokoro-82M: https://huggingface.co/hexgrad/Kokoro-82M
+- Chatterbox: https://huggingface.co/ResembleAI/chatterbox
+- Dia-1.6B: https://huggingface.co/nari-labs/Dia-1.6B
+- Sesame CSM-1B: https://huggingface.co/sesame/csm-1b

PROJECT_DESIGN.md

@@ -0,0 +1,67 @@
+# 虚拟角色项目总览
+
+## 当前结论
+
+这个项目的主线是 **现有角色驱动的多模态虚拟人格系统**。
+
+用户第一眼看到的应该是可选角色，而不是角色创建器。用户选中角色后，系统进入对话、语音、视觉理解和角色舞台联动体验。角色创建、生图、资料提取、prompt 组装和 skill 配置都是后台能力。
+
+核心体验：
+
+```text
+选择角色 -> 文本/语音/图片/摄像头输入 -> 模型流式输出回复、情绪、动作和语音参数 -> TTS/角色舞台同步响应
+```
+
+## 文档结构
+
+- [RESEARCH_NOTES.md](RESEARCH_NOTES.md)：调研信息、参考项目、产品判断、风险分析。
+- [DEVELOPMENT_GUIDE.md](DEVELOPMENT_GUIDE.md)：后续开发必须遵循的架构、文件结构、流式协议、Gradio 事件设计和 MVP 范围。
+- [MODAL_DEPLOYMENT.md](MODAL_DEPLOYMENT.md)：Modal 上的模型部署、调用方式、模型候选和省额度策略。
+
+## 关键产品原则
+
+1. 现有角色优先  
+   MVP 第一屏是角色选择。自定义角色和角色生成放在高级入口。
+
+2. 情绪由模型输出  
+   不靠用户按钮硬切情绪。模型每轮回复要输出表情、动作、语气、skill 等控制信息。
+
+3. 不等完整 JSON 才开始动  
+   对话输出使用事件流协议。模型可以先输出 `stage` / `emotion` / `voice` 事件，让 Live2D 或 2.5D 舞台先变化，再流式输出文本和音频。
+
+4. 生图是资产生成模块  
+   生图用于内置角色头像、半身像、背景图、自定义角色重绘，不在每轮聊天里触发。
+
+5. 视觉模型要绑定角色人格  
+   摄像头或上传图片不是普通看图问答，而是“当前角色如何看见并回应这件事”。
+
+6. 公开 demo 要原创化  
+   本地探索可以参考 Amadeus、流萤等目标体验。公开 HF Space 建议使用原创化角色，避免直接使用商业角色名、图像、台词、声音或完整官方设定。
+
+## MVP 目标
+
+第一版要证明“角色存在感”，不是证明所有模型都最强。
+
+必做：
+
+- 至少 3 个内置角色。
+- 文字聊天。
+- 模型流式输出：回复文本、情绪、动作、voice 参数、skill。
+- TTS 播放。
+- 角色舞台根据模型事件实时变化。
+- 上传图片后，角色以自身人格评论。
+- 调试面板展示事件流和模型结构化输出。
+
+可选：
+
+- 摄像头拍照分析。
+- 生图重绘角色头像。
+- Live2D Web 模型加载。
+
+暂缓：
+
+- 全实时视频对话。
+- 复杂长期记忆。
+- 声音克隆。
+- 商业角色原样复刻。
+- 单图自动 rig 成 Live2D。

README.md

@@ -1,13 +1,158 @@
 ---
 title: Virtual Characters
-emoji: 💻
-colorFrom: green
-colorTo: red
+emoji: 🎭
+colorFrom: blue
+colorTo: pink
 sdk: gradio
-sdk_version: 6.18.0
-python_version: '3.13'
+sdk_version: 6.17.3
 app_file: app.py
-pinned: false
+hf_oauth: true
+tags:
+  - build-small-hackathon
+  - small-models
+  - virtual-character
+  - multimodal
+  - tts
+  - modal
+  - gradio
+  - "track:backyard"
+  - "sponsor:modal"
+  - "achievement:offbrand"
+  - "achievement:fieldnotes"
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Virtual Characters
+
+Virtual Characters is a small-model, multimodal companion demo for the Build Small Hackathon. The current public experience focuses on one original character, **星萤**, with a live stage, expression switching, image-aware chat, and optional TTS playback.
+
+The app is built as a Hugging Face Gradio Space. Heavy inference runs on Modal endpoints, while the Space handles UI state, character cards, model status, OAuth-backed workshop persistence, and the stage renderer.
+
+## Why It Fits Build Small
+
+- **All active models are under 32B parameters.** The main chat endpoint is configured around a 12B-class Gemma model served by vLLM on Modal. The TTS path uses lightweight speech models such as Chatterbox/Kokoro-class voices. The image-generation spike and workshop path evaluate Qwen-Image/FLUX-style models as optional asset-generation services, also below the 32B ceiling.
+- **No 70B+ or giant hosted assistant is used as the core runtime.** The project is designed around smaller specialized services: chat, voice, image generation, matting, and stage control.
+- **Original/off-brand character design.** 星萤 is an original sci-fi communication-room character, not a clone of a commercial character.
+- **Field notes included.** The repo keeps benchmark notes and implementation notes for Modal cold starts, warm latency, TTS, image generation, and character-pack feasibility.
+
+## What You Can Try
+
+- Chat with 星萤 through text and image uploads.
+- Watch the stage switch expressions and motions from model output tags.
+- Generate playable TTS replies when the Modal TTS endpoint is available.
+- Open the `角色工坊` tab to draft/import Tavern-style character cards and test the asset-generation workflow.
+- Check model status cards for LLM, TTS, and image generation. If a Modal endpoint is asleep, the UI tells users to wait for cold start/model loading instead of failing silently.
+
+## Runtime Architecture
+
+```text
+Hugging Face Space (Gradio)
+  ├─ chat UI, stage renderer, role card UI
+  ├─ HF OAuth login for workshop save/resume
+  ├─ model status checks
+  └─ Modal endpoints
+       ├─ vLLM chat: 12B-class Gemma endpoint
+       ├─ TTS: Chatterbox/Kokoro-class voices
+       └─ image generation spike/workshop: Qwen-Image / FLUX candidates
+```
+
+## Model Notes
+
+The current configured stack is intentionally small-model oriented:
+
+| Capability | Model / Service | Size Policy |
+| --- | --- | --- |
+| Dialogue | `google/gemma-4-12B-it` served through Modal vLLM | 12B-class, below 32B |
+| TTS | Chatterbox/Kokoro-class Modal services | lightweight speech models, below 32B |
+| Character image spike | `Qwen/Qwen-Image`, `Qwen/Qwen-Image-Edit`, `FLUX.1-schnell` candidates | optional asset-generation services, below 32B target |
+| Background removal | `rembg` CPU matting path | local utility model, below 32B |
+
+The app exposes status cards because Modal endpoints can sleep. A sleeping endpoint is expected during demos; click refresh or retry after cold start completes.
+
+## Project Structure
+
+- `app.py`: Gradio UI, tabs, chat, workshop wiring, and model status controls.
+- `src/character_registry.py`: built-in character registry. The public demo currently ships only 星萤.
+- `src/stage_driver.py`: HTML/CSS stage renderer and expression/motion asset selection.
+- `src/dialogue_engine.py`: vLLM/OpenAI-compatible streaming, stage tag parsing, and TTS event handling.
+- `src/character_workshop.py`: Tavern JSON/form draft import, HF-login scoped save/resume, generation packaging, and install flow.
+- `src/model_status.py`: LLM/TTS/image-generation health checks.
+- `modal_apps/`: Modal deployment scripts for chat, TTS, and image-generation spikes.
+- `CHARACTER_GENERATION_SPIKE.md`: risk validation report for the character-generation pipeline.
+- `BENCHMARK_RESULTS.md`: Modal latency and deployment notes.
+
+## Local Development
+
+```powershell
+python -m pip install -r requirements.txt
+.\scripts\restart_gradio_background.ps1
+```
+
+Default local URL:
+
+```text
+http://127.0.0.1:7864
+```
+
+The restart script launches Gradio in the background and prints the PID, URL, stdout log path, stderr log path, LLM endpoint, and TTS endpoint.
+
+Mock mode avoids remote Modal calls:
+
+```powershell
+.\scripts\start_gradio_background.ps1 -Mock
+```
+
+Override endpoints when needed:
+
+```powershell
+.\scripts\start_gradio_background.ps1 -VllmUrl "https://your-vllm-endpoint.modal.run"
+.\scripts\restart_gradio_background.ps1 -TtsUrl "https://your-tts-endpoint.modal.run"
+```
+
+## Character Assets
+
+The public build includes one built-in character:
+
+```text
+assets/characters/star/
+assets/backgrounds/communication_room.png
+```
+
+Supported expression slots:
+
+```text
+idle, listening, thinking, worried, smile, happy
+```
+
+Motion-specific assets:
+
+```text
+assets/characters/star/talk.png
+assets/characters/star/focus.png
+```
+
+When the model emits `motion=talk` or `motion=focus`, `src/stage_driver.py` uses the dedicated action sprite. Other motions fall back to the current expression image.
+
+## Character Workshop
+
+The workshop is deliberately separated from the chat tab. Users can:
+
+1. Import a Tavern-style JSON card or fill a form.
+2. Generate four independent main-visual candidates.
+3. Select one candidate.
+4. Generate eight expression/action slots and one background.
+5. Run background removal and package assets for the stage driver.
+6. Install the generated character locally into the runtime registry.
+
+On Hugging Face Spaces, generation and install actions require HF OAuth login so each user's runs can be saved and resumed separately.
+
+## Modal Character Generation Spike
+
+The image-generation flow is still marked as an MVP/workshop path, not the core dependency for chatting. The spike scripts can be run separately:
+
+```powershell
+python scripts/run_character_generation_spike.py list-models
+python scripts/run_character_generation_spike.py modal-health
+python scripts/run_character_generation_spike.py modal-probe --candidate qwen_image --batch-size 4 --confirm-gpu
+```
+
+For full notes, see `CHARACTER_GENERATION_SPIKE.md`.

RESEARCH_NOTES.md

@@ -0,0 +1,135 @@
+# 调研与思考记录
+
+## 参考对象
+
+### Amadeus 类虚拟人格
+
+《Steins;Gate 0》里的 Amadeus 不是普通 chatbot。它的关键点是：
+
+- 角色人格来自某个人的记忆和人格数据。
+- 用户通过手机式通讯界面与角色交流。
+- 体验重点是“持续存在的人格容器”，而不是通用问答工具。
+
+对本项目的启发：
+
+- UI 可以借鉴通讯窗口、视频通话窗口、角色状态灯。
+- 角色需要身份、关系感、记忆边界和情绪连续性。
+- 角色不应该每轮都像第一次见用户。
+
+### Open-LLM-VTuber
+
+Open-LLM-VTuber 是当前最接近本项目系统形态的参考。它把 LLM、ASR、TTS、视觉感知、Live2D avatar、情绪映射、角色自定义、聊天记录持久化等模块组织在一起。
+
+可借鉴点：
+
+- 后端输出情绪，前端映射到 Live2D 表情。
+- 支持摄像头、屏幕录制、截图，让 AI 角色获得视觉感知。
+- 角色不是单 prompt，而是一组配置、模型、交互通道和表现层。
+
+### VTube Studio API
+
+VTube Studio 说明成熟 2.5D 角色系统通常不是“生成一段视频”，而是把外部信号映射到角色参数：
+
+- 通过 WebSocket 触发 hotkey。
+- 控制模型、表情、动作。
+- 输入 face tracking 数据。
+- 修改部分 ArtMesh 颜色。
+
+对本项目的启发：AI 输出应该是 `expression`、`motion`、`parameter` 这类控制事件，而不是一整段不可交互的视频。
+
+### pixi-live2d-display
+
+pixi-live2d-display 是 Web 端 Live2D 展示参考。它适合放在 `gr.HTML` 里作为浏览器端角色舞台方案。
+
+适用场景：
+
+- 已有公开授权 Live2D 模型。
+- 后端输出表情和动作事件。
+- 前端把事件映射到 Live2D motion/expression/parameter。
+
+### AnimateAnyone / Hallo
+
+这类项目证明单图驱动角色动画或音频驱动人像动画是可行方向，但它们更像后期增强模块：
+
+- 生成成本高。
+- 延迟不适合第一版交互。
+- 更适合生成短视频片段，不适合低延迟角色陪伴。
+
+## 内置角色策略
+
+### 本地探索角色
+
+本地探索可以直接参考：
+
+- Amadeus / 牧濑红莉栖风格。
+- 流萤风格。
+- 其他你喜欢的游戏或动画角色。
+
+目的不是公开复刻，而是快速评估角色还原感、语气、情绪输出和舞台表现。
+
+### 公开提交角色
+
+公开 HF Space 建议原创化：
+
+- `Amadeus-like Memory Girl`：记忆人格、理性、研究员、通讯界面感。
+- `Firefly-inspired Star Knight`：柔弱外表和战斗身份反差，科幻装甲，守护欲。
+- `Lab Assistant`：偏理性吐槽型。
+- `Mischief Mascot`：更轻松、有趣，适合 Thousand Token Wood。
+
+原因：直接使用商业角色名、官方图像、官方声音、官方台词和完整剧情设定会带来 IP 风险。
+
+## 生图模块判断
+
+生图应该是后台资产生成能力，而不是每轮对话都调用。
+
+适合场景：
+
+- 内置角色头像、半身像、背景图生成。
+- 用户点击“重绘角色”。
+- 自定义角色创建时，把用户上传图或描述转成原创视觉资产。
+
+推荐方向：
+
+- `FLUX.1-schnell`：速度快，许可证友好，适合快速生成角色图。
+- `SDXL`：生态成熟，动漫风格资源多，适合后续做 LoRA / ControlNet / IP-Adapter。
+- 角色一致性增强：后续再看 IP-Adapter、InstantID、PuLID、角色 LoRA。
+
+不建议：
+
+- 每轮聊天都生图。
+- 直接复刻商业角色图。
+- 把生图作为主体验阻塞对话。
+
+## 摄像头与视觉模型判断
+
+视觉模型可以成为差异点，但第一版要克制。
+
+可做场景：
+
+1. 角色看见你  
+   用户用摄像头拍照或低频抽帧，VLM 判断用户是否在镜头前、大致情绪、场景氛围。角色以自身人格回应。
+
+2. 角色看见物品  
+   用户把书、玩偶、手办、饮料等拿给摄像头看，角色进行 persona 化评论。
+
+3. 角色看见图片或截图  
+   用户上传截图，角色不是做通用图像问答，而是用自己的身份和情绪解读。
+
+MVP 建议：先做上传图片和手动拍照分析。实时流摄像头会增加队列、延迟和成本压力。
+
+## 参考资料
+
+- Steins;Gate 0 / Amadeus 设定概览: https://en.wikipedia.org/wiki/Steins%3BGate_0
+- Open-LLM-VTuber: https://github.com/Open-LLM-VTuber/Open-LLM-VTuber
+- VTube Studio API: https://github.com/DenchiSoft/VTubeStudio
+- pixi-live2d-display: https://github.com/guansss/pixi-live2d-display
+- Live2D 概念: https://en.wikipedia.org/wiki/Live2D
+- AnimateAnyone: https://github.com/HumanAIGC/AnimateAnyone
+- Hallo: https://github.com/fudan-generative-vision/hallo
+- Gradio Image / webcam: https://www.gradio.app/docs/gradio/image
+- Gradio streaming inputs: https://www.gradio.app/guides/streaming-inputs
+- Gradio streaming outputs: https://www.gradio.app/guides/streaming-outputs
+- Hugging Face Inference Providers: https://huggingface.co/docs/inference-providers/index
+- FLUX.1-schnell: https://huggingface.co/black-forest-labs/FLUX.1-schnell
+- SDXL: https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0
+

app.py

@@ -0,0 +1,1877 @@
+from __future__ import annotations
+
+import base64
+import html
+import mimetypes
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+import gradio as gr
+
+from src.character_registry import (
+    character_display_name,
+    format_character_card_markdown,
+    get_character,
+    get_character_packages,
+)
+from src.character_workshop import (
+    LOGIN_REQUIRED_MESSAGE,
+    create_draft_from_form,
+    create_draft_from_tavern_json,
+    create_initial_state,
+    ensure_user_workshop_run,
+    generate_background,
+    generate_expression_pack,
+    generate_main_candidates,
+    get_current_user,
+    install_character_package,
+    list_user_workshop_runs,
+    load_workshop_run,
+    matte_and_package_assets,
+    record_workshop_event,
+    render_packaged_stage_preview,
+    require_login_for_generation,
+    select_main_candidate,
+    summarize_workshop_stats,
+)
+from src.dialogue_engine import stream_reply
+from src.model_status import (
+    check_all_statuses,
+    check_image_generation_status,
+    initial_model_statuses,
+    llm_loading_status,
+    statuses_json,
+    statuses_markdown,
+    statuses_with_llm_status,
+    warm_llm_model,
+)
+from src.stage_driver import render_character_stage
+
+
+ROOT = Path(__file__).resolve().parent
+
+APP_CSS = """
+:root,
+body {
+  color-scheme: light;
+}
+
+.gradio-container {
+  background:
+    radial-gradient(circle at 10% 8%, rgba(103, 232, 249, .22), transparent 28%),
+    radial-gradient(circle at 82% 0%, rgba(251, 191, 36, .20), transparent 26%),
+    linear-gradient(135deg, #eef7f8 0%, #f8f4ec 46%, #f4eef2 100%);
+  color: #172033;
+}
+
+#vc-root {
+  max-width: 1500px;
+  margin: 0 auto;
+}
+
+.vc-topbar {
+  align-items: stretch;
+  flex-wrap: wrap;
+}
+
+.vc-status-wrap {
+  min-width: min(760px, 100%);
+}
+
+.vc-status-actions {
+  justify-content: center;
+  gap: 8px;
+}
+
+.vc-status-actions button {
+  width: 100%;
+  min-height: 38px;
+}
+
+.vc-model-action {
+  border: 1px solid rgba(212, 212, 216, .13);
+  border-radius: 8px;
+  background: rgba(18, 20, 24, .66);
+  padding: 10px 12px;
+}
+
+.vc-model-action p {
+  margin: 0;
+  color: rgba(244, 244, 245, .82);
+  font-size: 13px;
+  line-height: 1.45;
+}
+
+.vc-tabs {
+  margin-top: 8px;
+}
+
+.vc-panel {
+  border: 1px solid rgba(212, 212, 216, .13);
+  border-radius: 8px;
+  background: rgba(18, 20, 24, .82);
+  box-shadow: 0 18px 52px rgba(0, 0, 0, .24);
+  backdrop-filter: blur(18px);
+  padding: 12px;
+}
+
+.vc-panel .label-wrap,
+.vc-input-dock .label-wrap {
+  color: rgba(228, 228, 231, .82);
+}
+
+.vc-card-head {
+  display: grid;
+  grid-template-columns: 72px 1fr;
+  gap: 12px;
+  align-items: center;
+  padding: 4px 0 12px;
+  border-bottom: 1px solid rgba(212, 212, 216, .12);
+  margin-bottom: 12px;
+}
+
+.vc-card-head img {
+  width: 72px;
+  height: 72px;
+  object-fit: cover;
+  border-radius: 8px;
+  background: #09090b;
+  border: 1px solid rgba(103, 232, 249, .30);
+  box-shadow: 0 0 26px rgba(103, 232, 249, .14);
+}
+
+.vc-card-title {
+  display: flex;
+  flex-direction: column;
+  gap: 7px;
+}
+
+.vc-card-title strong {
+  font-size: 18px;
+  letter-spacing: 0;
+  color: #f4f4f5;
+}
+
+.vc-tags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+}
+
+.vc-tags span {
+  border: 1px solid rgba(103, 232, 249, .24);
+  background: rgba(8, 145, 178, .13);
+  color: #a5f3fc;
+  border-radius: 999px;
+  padding: 2px 8px;
+  font-size: 12px;
+  line-height: 18px;
+}
+
+.vc-character-card {
+  max-height: 67vh;
+  overflow: auto;
+  padding-right: 4px;
+}
+
+.vc-character-card h3 {
+  display: none;
+}
+
+.vc-character-card p,
+.vc-character-card li,
+.vc-character-card blockquote {
+  font-size: 13px;
+  line-height: 1.62;
+}
+
+.vc-character-card strong {
+  color: #fbbf24;
+}
+
+.vc-character-card blockquote {
+  border-left: 3px solid #fb7185;
+  background: rgba(251, 113, 133, .08);
+  margin: 6px 0 12px;
+  padding: 8px 10px;
+}
+
+#character-stage {
+  min-height: 560px;
+}
+
+#character-stage > div {
+  min-height: 560px;
+}
+
+.vc-stage2 {
+  height: min(72vh, 680px);
+  min-height: 560px;
+  position: relative;
+  overflow: hidden;
+  border-radius: 8px;
+  background:
+    radial-gradient(circle at 74% 18%, rgba(103, 232, 249, .18), transparent 32%),
+    linear-gradient(145deg, var(--bg), #09090b 74%);
+  background-size: auto, auto;
+  background-position: center, center;
+  color: #eef2ff;
+  font-family: Inter, "Microsoft YaHei", system-ui, sans-serif;
+  isolation: isolate;
+}
+
+.vc-stage2::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background:
+    linear-gradient(90deg, rgba(255,255,255,.07) 1px, transparent 1px),
+    linear-gradient(0deg, rgba(255,255,255,.05) 1px, transparent 1px);
+  background-size: 72px 72px;
+  mask-image: linear-gradient(180deg, transparent, #000 18%, #000 72%, transparent);
+  opacity: .08;
+  transform: perspective(700px) rotateX(58deg) translateY(140px) scale(1.4);
+  transform-origin: 50% 100%;
+  z-index: 1;
+}
+
+.vc-stage2::after {
+  content: "";
+  position: absolute;
+  inset: auto 0 0 0;
+  height: 38%;
+  background: linear-gradient(0deg, rgba(5, 10, 18, .62), rgba(5, 10, 18, .01));
+  z-index: 1;
+  pointer-events: none;
+}
+
+.vc-stage-top {
+  position: absolute;
+  z-index: 4;
+  left: 18px;
+  right: 18px;
+  top: 16px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  font-size: 13px;
+  color: #f8fafc;
+  pointer-events: none;
+}
+
+.vc-bg {
+  position: absolute;
+  z-index: 0;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  opacity: .86;
+  filter: saturate(.95) brightness(.86);
+}
+
+.vc-name {
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
+  font-weight: 700;
+  letter-spacing: 0;
+  min-height: 32px;
+  max-width: min(58%, 280px);
+  padding: 6px 12px;
+  border: 1px solid rgba(103, 232, 249, .42);
+  border-radius: 999px;
+  background: linear-gradient(135deg, rgba(7, 15, 25, .82), rgba(15, 23, 42, .66));
+  color: #f8fafc;
+  box-shadow: 0 10px 28px rgba(2, 6, 23, .32), inset 0 1px 0 rgba(255, 255, 255, .10);
+  text-shadow: 0 1px 8px rgba(0, 0, 0, .72);
+  backdrop-filter: blur(12px);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.vc-name::before {
+  content: "";
+  width: 10px;
+  height: 10px;
+  border-radius: 999px;
+  background: var(--accent);
+  box-shadow: 0 0 18px var(--accent);
+}
+
+.vc-status {
+  min-height: 32px;
+  max-width: min(42%, 240px);
+  padding: 6px 12px;
+  border: 1px solid rgba(251, 191, 36, .44);
+  border-radius: 999px;
+  background: linear-gradient(135deg, rgba(24, 16, 10, .82), rgba(63, 40, 12, .60));
+  color: #fff7ed;
+  box-shadow: 0 10px 28px rgba(2, 6, 23, .30), inset 0 1px 0 rgba(255, 255, 255, .10);
+  text-shadow: 0 1px 8px rgba(0, 0, 0, .74);
+  backdrop-filter: blur(12px);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.vc-spotlight {
+  position: absolute;
+  z-index: 1;
+  left: 50%;
+  top: 8%;
+  width: 420px;
+  height: 460px;
+  transform: translateX(-50%);
+  border-radius: 999px;
+  background: radial-gradient(circle, rgba(103, 232, 249, .28), transparent 68%);
+  filter: blur(10px);
+  opacity: var(--talk-glow);
+  animation: vc2-pulse 3.2s ease-in-out infinite;
+}
+
+.vc-portrait-wrap {
+  position: absolute;
+  z-index: 3;
+  left: 50%;
+  bottom: 10px;
+  width: min(76%, 470px);
+  height: calc(100% - 66px);
+  display: flex;
+  align-items: flex-end;
+  justify-content: center;
+  transform: translateX(-50%) scale(var(--focus));
+  transform-origin: 50% 92%;
+  filter: drop-shadow(0 34px 42px rgba(0, 0, 0, .46));
+  animation: vc2-breathe 4.6s ease-in-out infinite;
+}
+
+.vc-portrait {
+  display: block;
+  width: auto;
+  max-width: 100%;
+  max-height: 100%;
+  height: auto;
+  object-fit: contain;
+  user-select: none;
+  pointer-events: none;
+}
+
+.vc-ground {
+  position: absolute;
+  z-index: 2;
+  left: 50%;
+  bottom: 12px;
+  width: 390px;
+  height: 42px;
+  transform: translateX(-50%);
+  border-radius: 999px;
+  background: radial-gradient(ellipse, rgba(0, 0, 0, .46), transparent 70%);
+  filter: blur(3px);
+}
+
+.vc-motion-talk .vc-portrait-wrap {
+  animation: vc2-talk 1.15s ease-in-out infinite;
+}
+
+.vc-motion-focus .vc-portrait-wrap,
+.vc-motion-look .vc-portrait-wrap {
+  animation: vc2-focus 2.8s ease-in-out infinite;
+}
+
+.vc-motion-sway .vc-portrait-wrap {
+  animation: vc2-sway 4s ease-in-out infinite;
+}
+
+.vc-motion-blink .vc-portrait-wrap {
+  animation: vc2-blink 3.4s ease-in-out infinite;
+}
+
+@keyframes vc2-breathe {
+  0%, 100% { transform: translateX(-50%) translateY(0) scale(var(--focus)); }
+  50% { transform: translateX(-50%) translateY(-7px) scale(calc(var(--focus) + .012)); }
+}
+
+@keyframes vc2-talk {
+  0%, 100% { transform: translateX(-50%) translateY(0) scale(var(--focus)); filter: brightness(1); }
+  42% { transform: translateX(-50%) translateY(-8px) scale(calc(var(--focus) + .015)); filter: brightness(1.06); }
+  70% { transform: translateX(-50%) translateY(-3px) scale(calc(var(--focus) + .006)); }
+}
+
+@keyframes vc2-focus {
+  0%, 100% { transform: translateX(-50%) translateY(0) rotate(-.4deg) scale(var(--focus)); }
+  50% { transform: translateX(-50%) translateY(-6px) rotate(.7deg) scale(calc(var(--focus) + .01)); }
+}
+
+@keyframes vc2-sway {
+  0%, 100% { transform: translateX(-50%) rotate(-1deg) scale(var(--focus)); }
+  50% { transform: translateX(-50%) rotate(1.2deg) translateY(-5px) scale(calc(var(--focus) + .01)); }
+}
+
+@keyframes vc2-blink {
+  0%, 100% { transform: translateX(-50%) translateY(0) scale(var(--focus)); opacity: 1; }
+  48% { transform: translateX(-50%) translateY(-4px) scale(var(--focus)); opacity: .98; }
+  52% { transform: translateX(-50%) translateY(-4px) scale(1.006); opacity: .94; }
+}
+
+@keyframes vc2-pulse {
+  0%, 100% { opacity: var(--talk-glow); transform: translateX(-50%) scale(.98); }
+  50% { opacity: calc(var(--talk-glow) + .08); transform: translateX(-50%) scale(1.04); }
+}
+
+.vc-output #component-0,
+.vc-output textarea,
+.vc-output .wrap {
+  background: rgba(9, 9, 11, .42);
+}
+
+.vc-model-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 10px;
+}
+
+.vc-workshop-grid {
+  display: grid;
+  gap: 12px;
+}
+
+.vc-workshop-status p {
+  margin: 0;
+  color: rgba(228, 228, 231, .78);
+  font-size: 13px;
+}
+
+.vc-workshop-shell {
+  position: relative;
+  isolation: isolate;
+}
+
+.gradio-container .wrap.full,
+.gradio-container .wrap.minimal,
+.gradio-container .wrap.center.full,
+.gradio-container .wrap.default.full,
+.gradio-container .wrap.default.minimal {
+  opacity: 0 !important;
+  background: transparent !important;
+  pointer-events: none !important;
+}
+
+.vc-model-pill {
+  min-height: 84px;
+  border: 1px solid rgba(212, 212, 216, .14);
+  border-radius: 8px;
+  background: rgba(24, 24, 27, .72);
+  padding: 10px 12px;
+  display: grid;
+  gap: 4px;
+  position: relative;
+  overflow: hidden;
+}
+
+.vc-model-pill::before {
+  content: "";
+  position: absolute;
+  left: 0;
+  top: 0;
+  bottom: 0;
+  width: 4px;
+  background: #71717a;
+}
+
+.vc-model-pill b {
+  font-size: 13px;
+  color: #f4f4f5;
+}
+
+.vc-model-pill span {
+  font-size: 13px;
+  color: #e4e4e7;
+}
+
+.vc-model-pill small {
+  font-size: 11px;
+  color: rgba(212, 212, 216, .62);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.vc-model-pill em {
+  font-style: normal;
+  font-size: 12px;
+  color: rgba(228, 228, 231, .74);
+}
+
+.vc-model-ready::before {
+  background: #22c55e;
+  box-shadow: 0 0 16px rgba(34, 197, 94, .46);
+}
+
+.vc-model-loading::before,
+.vc-model-sleeping::before,
+.vc-model-unknown::before {
+  background: #f59e0b;
+  box-shadow: 0 0 16px rgba(245, 158, 11, .42);
+}
+
+.vc-model-error::before {
+  background: #fb7185;
+  box-shadow: 0 0 16px rgba(251, 113, 133, .42);
+}
+
+.vc-model-local::before {
+  background: #67e8f9;
+  box-shadow: 0 0 16px rgba(103, 232, 249, .42);
+}
+
+.vc-model-unconfigured::before {
+  background: #71717a;
+}
+
+.vc-input-dock {
+  margin-top: 12px;
+  border: 1px solid rgba(103, 232, 249, .20);
+  border-radius: 8px;
+  background: rgba(229, 231, 235, .96);
+  box-shadow: 0 -18px 60px rgba(0, 0, 0, .28);
+  padding: 12px;
+  color: #111827;
+}
+
+#vc-message {
+  border-radius: 8px;
+  background: #f8fafc !important;
+  color: #111827 !important;
+  border: 1px solid rgba(8, 145, 178, .28);
+}
+
+#vc-message,
+#vc-message * {
+  color: #111827 !important;
+}
+
+#vc-message textarea,
+#vc-message input,
+#vc-message [contenteditable="true"] {
+  background: #f8fafc !important;
+  color: #111827 !important;
+  caret-color: #0891b2 !important;
+}
+
+#vc-message textarea::placeholder,
+#vc-message input::placeholder {
+  color: #64748b !important;
+}
+
+#vc-message button {
+  background: rgba(8, 145, 178, .10) !important;
+  border-color: rgba(8, 145, 178, .24) !important;
+  color: #0f172a !important;
+}
+
+#vc-message svg {
+  color: #0f172a !important;
+  stroke: currentColor !important;
+}
+
+#voice-output {
+  min-height: 72px;
+}
+
+.vc-audio-status p {
+  margin: 0;
+  color: rgba(228, 228, 231, .76);
+  font-size: 13px;
+}
+
+@media (max-width: 980px) {
+  .vc-stage-col {
+    order: 1;
+  }
+
+  .vc-left {
+    order: 2;
+  }
+
+  .vc-right {
+    order: 3;
+  }
+
+  .vc-status-wrap,
+  .vc-status-actions {
+    min-width: 100% !important;
+  }
+
+  .vc-model-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .vc-character-card {
+    max-height: none;
+  }
+
+  #character-stage,
+  #character-stage > div {
+    min-height: 480px;
+  }
+}
+
+.gradio-container {
+  color-scheme: light;
+  --vc-page-text: #172033;
+  --vc-page-muted: #526173;
+  --vc-page-bg:
+    radial-gradient(circle at 10% 8%, rgba(103, 232, 249, .22), transparent 28%),
+    radial-gradient(circle at 82% 0%, rgba(251, 191, 36, .20), transparent 26%),
+    linear-gradient(135deg, #eef7f8 0%, #f8f4ec 46%, #f4eef2 100%);
+  --vc-panel-bg: rgba(255, 255, 255, .86);
+  --vc-panel-border: rgba(15, 23, 42, .13);
+  --vc-panel-shadow: 0 18px 45px rgba(30, 41, 59, .14);
+  --vc-card-strong: #a16207;
+  --vc-tag-bg: rgba(8, 145, 178, .10);
+  --vc-tag-text: #0e7490;
+  --vc-pill-bg: rgba(255, 255, 255, .84);
+  --vc-pill-text: #172033;
+  --vc-pill-muted: #64748b;
+  --vc-input-bg: rgba(255, 255, 255, .92);
+  --vc-input-text: #172033;
+  --vc-input-muted: #526173;
+  --vc-chat-bg: rgba(255, 255, 255, .78);
+  background: var(--vc-page-bg) !important;
+  color: var(--vc-page-text) !important;
+}
+
+.gradio-container:has(#vc-mode-night) {
+  color-scheme: dark;
+  --vc-page-text: #e5e7eb;
+  --vc-page-muted: rgba(228, 228, 231, .72);
+  --vc-page-bg:
+    radial-gradient(circle at 12% 14%, rgba(103, 232, 249, .12), transparent 30%),
+    radial-gradient(circle at 82% 8%, rgba(251, 191, 36, .10), transparent 28%),
+    linear-gradient(135deg, rgba(8, 11, 16, .98), rgba(15, 16, 18, .98) 48%, rgba(20, 12, 17, .98));
+  --vc-panel-bg: rgba(18, 20, 24, .82);
+  --vc-panel-border: rgba(212, 212, 216, .13);
+  --vc-panel-shadow: 0 18px 52px rgba(0, 0, 0, .24);
+  --vc-card-strong: #fbbf24;
+  --vc-tag-bg: rgba(8, 145, 178, .13);
+  --vc-tag-text: #a5f3fc;
+  --vc-pill-bg: rgba(24, 24, 27, .72);
+  --vc-pill-text: #f4f4f5;
+  --vc-pill-muted: rgba(212, 212, 216, .62);
+  --vc-input-bg: rgba(229, 231, 235, .96);
+  --vc-input-text: #111827;
+  --vc-input-muted: #475569;
+  --vc-chat-bg: rgba(9, 9, 11, .42);
+}
+
+.vc-panel {
+  background: var(--vc-panel-bg) !important;
+  border-color: var(--vc-panel-border) !important;
+  box-shadow: var(--vc-panel-shadow) !important;
+  color: var(--vc-page-text) !important;
+}
+
+.vc-input-dock {
+  background: var(--vc-input-bg) !important;
+  border-color: var(--vc-panel-border) !important;
+  box-shadow: var(--vc-panel-shadow) !important;
+  color: var(--vc-input-text) !important;
+}
+
+.vc-panel *,
+.vc-character-card,
+.vc-character-card p,
+.vc-character-card li,
+.vc-character-card blockquote,
+.vc-card-title small {
+  color: var(--vc-page-text);
+}
+
+.vc-panel .label-wrap {
+  color: var(--vc-page-muted) !important;
+}
+
+.vc-input-dock .label-wrap {
+  color: var(--vc-input-muted) !important;
+}
+
+.vc-card-head {
+  border-bottom-color: var(--vc-panel-border) !important;
+}
+
+.vc-card-title strong {
+  color: var(--vc-page-text) !important;
+}
+
+.vc-tags span {
+  background: var(--vc-tag-bg) !important;
+  color: var(--vc-tag-text) !important;
+  border-color: rgba(8, 145, 178, .22) !important;
+}
+
+.vc-character-card strong {
+  color: var(--vc-card-strong) !important;
+}
+
+.vc-character-card blockquote {
+  color: var(--vc-page-text) !important;
+  background: rgba(251, 113, 133, .09) !important;
+}
+
+.vc-model-pill {
+  background: var(--vc-pill-bg) !important;
+  border-color: var(--vc-panel-border) !important;
+}
+
+.vc-model-pill b,
+.vc-model-pill span {
+  color: var(--vc-pill-text) !important;
+}
+
+.vc-model-pill small,
+.vc-model-pill em {
+  color: var(--vc-pill-muted) !important;
+}
+
+.vc-output textarea,
+.vc-output .wrap,
+.vc-output [data-testid="chatbot"] {
+  background: var(--vc-chat-bg) !important;
+  color: var(--vc-page-text) !important;
+}
+
+.vc-audio-status p {
+  color: var(--vc-page-muted) !important;
+}
+
+.vc-input-dock {
+  background: var(--vc-input-bg) !important;
+}
+
+.gradio-container:not(:has(#vc-mode-night)) .vc-stage2 {
+  box-shadow: 0 24px 64px rgba(15, 23, 42, .20);
+}
+
+.gradio-container:not(:has(#vc-mode-night)) .vc-bg {
+  opacity: .94;
+  filter: saturate(1.03) brightness(1.04);
+}
+
+.gradio-container:not(:has(#vc-mode-night)) .vc-stage2::after {
+  background: linear-gradient(0deg, rgba(15, 23, 42, .36), rgba(15, 23, 42, .01));
+}
+
+.vc-appearance-mode label {
+  color: var(--vc-page-text) !important;
+}
+
+.gradio-container:not(:has(#vc-mode-night)) .vc-appearance-mode,
+.gradio-container:not(:has(#vc-mode-night)) .vc-appearance-mode *,
+.gradio-container:not(:has(#vc-mode-night)) input,
+.gradio-container:not(:has(#vc-mode-night)) textarea,
+.gradio-container:not(:has(#vc-mode-night)) select,
+.gradio-container:not(:has(#vc-mode-night)) button {
+  color: #172033 !important;
+}
+
+.gradio-container:not(:has(#vc-mode-night)) input,
+.gradio-container:not(:has(#vc-mode-night)) textarea,
+.gradio-container:not(:has(#vc-mode-night)) select,
+.gradio-container:not(:has(#vc-mode-night)) .wrap,
+.gradio-container:not(:has(#vc-mode-night)) .container {
+  background-color: rgba(255, 255, 255, .88) !important;
+  border-color: rgba(15, 23, 42, .12) !important;
+}
+
+.gradio-container:not(:has(#vc-mode-night)) button {
+  background: rgba(255, 255, 255, .82) !important;
+  border-color: rgba(8, 145, 178, .22) !important;
+}
+
+.gradio-container:not(:has(#vc-mode-night)) button.primary,
+.gradio-container:not(:has(#vc-mode-night)) #vc-message button:last-child {
+  background: linear-gradient(135deg, #0891b2, #0f766e) !important;
+  color: #ffffff !important;
+}
+
+.gradio-container:has(#vc-mode-night) .vc-appearance-mode,
+.gradio-container:has(#vc-mode-night) .vc-appearance-mode *,
+.gradio-container:has(#vc-mode-night) .vc-panel input,
+.gradio-container:has(#vc-mode-night) .vc-panel textarea,
+.gradio-container:has(#vc-mode-night) .vc-panel select {
+  color: #e5e7eb !important;
+}
+"""
+
+
+VOICE_STYLE_CHOICES = [
+    ("跟随角色", "neutral"),
+    ("温柔", "soft"),
+    ("坚定", "firm"),
+    ("开心", "happy"),
+    ("担心", "concerned"),
+    ("俏皮", "playful"),
+]
+
+APPEARANCE_CHOICES = [("晨光舱", "day"), ("夜航舱", "night")]
+
+
+def _theme() -> gr.Theme:
+    return gr.themes.Default(primary_hue="cyan", secondary_hue="amber", neutral_hue="zinc")
+
+
+def _appearance_marker(mode: str) -> str:
+    marker_id = "vc-mode-night" if mode == "night" else "vc-mode-day"
+    return f'<span id="{marker_id}" aria-hidden="true" style="display:none"></span>'
+
+
+def _character_choices() -> list[tuple[str, str]]:
+    return [
+        (character_display_name(character), character_id)
+        for character_id, character in get_character_packages().items()
+    ]
+
+
+def _voice_choices(character: dict) -> list[tuple[str, str]]:
+    choices = character.get("voice_options") or []
+    if choices:
+        return [(str(label), str(value)) for label, value in choices]
+    voice = character.get("voice", {})
+    return [(voice.get("voice_label") or voice.get("voice_id") or "默认音色", voice.get("voice_id") or "default")]
+
+
+def _initial_state(character_id: str) -> dict:
+    character = get_character(character_id)
+    return {
+        "character_id": character_id,
+        "stage": {"expression": "idle", "motion": "breathe", "intensity": 0.35},
+        "events": [],
+        "last_vision_note": None,
+        "character": character,
+        "voice": _default_voice_state(character, enabled=True),
+    }
+
+
+def _default_voice_state(character: dict, enabled: bool) -> dict[str, Any]:
+    voice = character.get("voice", {})
+    return {
+        "enabled": enabled,
+        "voice_id": voice.get("voice_id", "default"),
+        "style": voice.get("default_style", "neutral"),
+        "emotion": voice.get("default_style", "neutral"),
+        "speed": _pace_to_speed(voice.get("pace", "normal")),
+        "energy": float(voice.get("energy", 0.5)),
+        "audio_prompt_path": voice.get("audio_prompt_path"),
+    }
+
+
+def _pace_to_speed(pace: str) -> float:
+    return {"slow": 0.92, "normal": 1.0, "fast": 1.08}.get(str(pace), 1.0)
+
+
+def _opening_history(character: dict) -> list[dict[str, str]]:
+    first_mes = str(character.get("first_mes") or "").strip()
+    if not first_mes:
+        return []
+    return [{"role": "assistant", "content": first_mes}]
+
+
+def _history_for_model(history: list[dict], character: dict) -> list[dict]:
+    history = list(history or [])
+    first_mes = str(character.get("first_mes") or "").strip()
+    if history and history[0].get("role") == "assistant" and str(history[0].get("content") or "").strip() == first_mes:
+        return history[1:]
+    return history
+
+
+def _character_header_html(character: dict) -> str:
+    tags = "".join(f"<span>{html.escape(str(tag))}</span>" for tag in character.get("tags", [])[:6])
+    avatar_uri = _avatar_uri(character)
+    name = html.escape(character_display_name(character))
+    summary = html.escape(character.get("summary", ""))
+    return f"""
+<div class="vc-card-head">
+  <img src="{avatar_uri}" alt="{name}" />
+  <div class="vc-card-title">
+    <strong>{name}</strong>
+    <div class="vc-tags">{tags}</div>
+    <small>{summary}</small>
+  </div>
+</div>
+"""
+
+
+def _avatar_uri(character: dict) -> str:
+    avatar = character.get("visual", {}).get("avatar", "star")
+    for candidate in (
+        ROOT / "assets" / "characters" / avatar / "idle.png",
+        ROOT / "assets" / "characters" / "star" / "idle.png",
+    ):
+        if candidate.exists():
+            encoded = base64.b64encode(candidate.read_bytes()).decode("ascii")
+            return f"data:image/png;base64,{encoded}"
+    return ""
+
+
+def switch_character(character_id: str):
+    state = _initial_state(character_id)
+    character = state["character"]
+    voice = state["voice"]
+    return (
+        _character_header_html(character),
+        format_character_card_markdown(character),
+        render_character_stage(character, state["stage"]),
+        state,
+        _opening_history(character),
+        {"events": []},
+        gr.update(choices=_voice_choices(character), value=voice["voice_id"]),
+        gr.update(value=voice["style"]),
+        gr.update(value=voice["speed"]),
+        gr.update(value=voice["energy"]),
+        gr.update(value=True),
+        "等待新的语音回复。",
+        None,
+    )
+
+
+def refresh_model_status():
+    statuses = check_all_statuses()
+    return statuses_markdown(statuses), statuses_json(statuses)
+
+
+def refresh_model_status_both():
+    statuses = check_all_statuses()
+    html_status = statuses_markdown(statuses)
+    note = _model_action_note(statuses)
+    return html_status, html_status, statuses_json(statuses), note, note
+
+
+def refresh_workshop_status_only():
+    return statuses_markdown(check_all_statuses())
+
+
+def start_main_model():
+    starting_status = llm_loading_status()
+    statuses = statuses_with_llm_status(starting_status)
+    html_status = statuses_markdown(statuses)
+    note = "主模型启动请求已发出。首次加载可能需要 1-3 分钟；这个操作只预热当前服务，不会把 GPU 常驻。"
+    yield html_status, html_status, statuses_json(statuses), note, note
+
+    result = warm_llm_model()
+    statuses = statuses_with_llm_status(result)
+    html_status = statuses_markdown(statuses)
+    note = _model_action_note(statuses, warmup=True)
+    yield html_status, html_status, statuses_json(statuses), note, note
+
+
+def _initial_model_action_note() -> str:
+    return "主模型按需启动。首次对话前可先启动模型；启动完成后几分钟内对话会更快。"
+
+
+def _model_action_note(statuses: list, *, warmup: bool = False) -> str:
+    llm = next((status for status in statuses if status.kind == "llm"), None)
+    if not llm:
+        return _initial_model_action_note()
+    if llm.state == "ready":
+        prefix = "主模型已启动。" if warmup else "主模型可用。"
+        return f"{prefix} 当前请求延迟约 {llm.latency_s:.1f}s。" if llm.latency_s is not None else prefix
+    if llm.state == "loading":
+        return llm.message or "主模型正在启动；稍后刷新状态。"
+    if llm.state == "sleeping":
+        return "主模型已休眠；可以点击启动主模型，或直接发送消息等待冷启动。"
+    if llm.state == "mock":
+        return "当前使用本地 mock，对话不会等待 Modal 模型。"
+    if llm.state == "unconfigured":
+        return "主模型 endpoint 未配置。"
+    return llm.message or "主模型状态异常，请刷新状态或检查 endpoint。"
+
+
+def _hf_oauth_available() -> bool:
+    if os.environ.get("SPACE_ID") or os.environ.get("HF_TOKEN"):
+        return True
+    try:
+        from huggingface_hub import get_token
+
+        return bool(get_token())
+    except Exception:
+        return False
+
+
+def workshop_login_status(profile: gr.OAuthProfile | None = None) -> str:
+    user = get_current_user(profile)
+    if user.authenticated:
+        return f"已登录 Hugging Face：{user.display_name}（@{user.username}）。生成进度会保存到你的任务列表。"
+    return "未登录。可以先填写或导入角色；点击生成、打包、安装前需要使用 Hugging Face 登录。"
+
+
+def workshop_refresh_runs(profile: gr.OAuthProfile | None = None):
+    user = get_current_user(profile)
+    choices = list_user_workshop_runs(user)
+    value = choices[0][1] if choices else None
+    return (
+        workshop_login_status(profile),
+        gr.update(choices=choices, value=value),
+        summarize_workshop_stats(),
+    )
+
+
+def workshop_load_selected_run(run_dir: str | None, profile: gr.OAuthProfile | None = None):
+    try:
+        user = get_current_user(profile)
+        choices = list_user_workshop_runs(user)
+        selected = run_dir or (choices[0][1] if choices else None)
+        if not selected:
+            return (*_empty_workshop_outputs("没有可恢复的角色生成任务。"), gr.update(choices=choices, value=None), summarize_workshop_stats())
+        state = load_workshop_run(selected, user=user)
+        return (*_workshop_state_outputs(state, "已加载历史任务，可以从中断位置继续。"), gr.update(choices=choices, value=selected), summarize_workshop_stats())
+    except Exception as exc:
+        user = get_current_user(profile)
+        return (*_empty_workshop_outputs(f"加载任务失败：{exc}"), gr.update(choices=list_user_workshop_runs(user), value=run_dir), summarize_workshop_stats())
+
+
+def workshop_load_recent_run(profile: gr.OAuthProfile | None = None):
+    return workshop_load_selected_run(None, profile)
+
+
+def _workshop_state_outputs(state: dict, message: str):
+    draft = state.get("draft") or {}
+    expression_paths = [
+        state.get("expression_assets", {}).get(slot)
+        for slot in ("idle", "listening", "thinking", "worried", "smile", "happy", "talk", "focus")
+        if state.get("expression_assets", {}).get(slot)
+    ]
+    package_dir = Path(state.get("package_dir") or Path(state.get("run_dir") or "") / "package")
+    grid_path = package_dir / "generated" / "asset_grid.png"
+    preview_html = ""
+    if grid_path.exists():
+        try:
+            preview_html = render_packaged_stage_preview(state)
+        except Exception:
+            preview_html = ""
+    selected = state.get("selected_candidate_index")
+    selected_label = f"当前选择：{selected}" if selected is not None else "当前选择：无。"
+    return (
+        message,
+        format_character_card_markdown(draft) if draft else "",
+        state,
+        state.get("main_candidates") or [],
+        selected if selected is not None else 0,
+        selected_label,
+        expression_paths,
+        state.get("background_asset"),
+        str(grid_path) if grid_path.exists() else None,
+        preview_html,
+    )
+
+
+def _empty_workshop_outputs(message: str):
+    return (message, "", {}, [], 0, "当前选择：无。", [], None, None, "")
+
+
+def _workshop_run_dropdown_update(profile: gr.OAuthProfile | None, state: dict | None = None):
+    user = get_current_user(profile)
+    choices = list_user_workshop_runs(user)
+    value = (state or {}).get("run_dir")
+    if not value and choices:
+        value = choices[0][1]
+    return gr.update(choices=choices, value=value)
+
+
+def workshop_create_from_form(
+    display_name: str,
+    description: str,
+    personality: str,
+    scenario: str,
+    first_mes: str,
+    tags: str,
+):
+    try:
+        draft = create_draft_from_form(
+            display_name=display_name,
+            description=description,
+            personality=personality,
+            scenario=scenario,
+            first_mes=first_mes,
+            tags=tags,
+        )
+        workshop_state = create_initial_state(draft, persist=False)
+        return (
+            "草案已创建，可以生成主视觉候选。",
+            format_character_card_markdown(draft),
+            workshop_state,
+            [],
+            0,
+            "当前选择：尚未生成候选。",
+            [],
+            None,
+            None,
+            "",
+        )
+    except Exception as exc:
+        return (f"创建草案失败：{exc}", "", {}, [], 0, "当前选择：无。", [], None, None, "")
+
+
+def workshop_import_tavern(file):
+    try:
+        draft = create_draft_from_tavern_json(file)
+        workshop_state = create_initial_state(draft, persist=False)
+        return (
+            "Tavern JSON 已导入，可以生成主视觉候选。",
+            format_character_card_markdown(draft),
+            workshop_state,
+            [],
+            0,
+            "当前选择：尚未生成候选。",
+            [],
+            None,
+            None,
+            "",
+        )
+    except Exception as exc:
+        return (f"导入失败：{exc}", "", {}, [], 0, "当前选择：无。", [], None, None, "")
+
+
+def _require_workshop_model_ready() -> str | None:
+    status = check_image_generation_status()
+    if status.state == "ready":
+        return None
+    return status.message or "Modal 图像生成服务可能已休眠或正在冷启动，请等待容器启动和模型载入后重试。"
+
+
+def workshop_generate_main_candidates(workshop_state: dict | None, profile: gr.OAuthProfile | None = None):
+    started = time.perf_counter()
+    user = get_current_user(profile)
+    try:
+        user = require_login_for_generation(profile)
+    except ValueError as exc:
+        record_workshop_event(user, "generate_main_candidates", {"stage": "auth_required", "success": False, "failure_reason": str(exc)})
+        return str(exc), gr.update(), workshop_state or {}, "当前选择：无。", _workshop_run_dropdown_update(profile, workshop_state), summarize_workshop_stats()
+    wait_message = _require_workshop_model_ready()
+    if wait_message:
+        record_workshop_event(user, "generate_main_candidates", {"stage": "modal_wait", "success": False, "failure_reason": wait_message, "modal_state": "not_ready"})
+        return wait_message, gr.update(), workshop_state or {}, "当前选择：无。", _workshop_run_dropdown_update(profile, workshop_state), summarize_workshop_stats()
+    try:
+        workshop_state = ensure_user_workshop_run(workshop_state or {}, user)
+        workshop_state = generate_main_candidates(workshop_state)
+        paths = workshop_state.get("main_candidates") or []
+        record_workshop_event(
+            user,
+            "generate_main_candidates",
+            {
+                "stage": "main_candidates",
+                "character_id": workshop_state.get("character_id"),
+                "duration_seconds": round(time.perf_counter() - started, 3),
+                "success": True,
+                "image_count": len(paths),
+            },
+        )
+        return "主视觉候选已生成。请选择其中一张。", paths, workshop_state, "当前选择：0", _workshop_run_dropdown_update(profile, workshop_state), summarize_workshop_stats()
+    except Exception as exc:
+        record_workshop_event(user, "generate_main_candidates", {"stage": "main_candidates", "success": False, "failure_reason": str(exc), "duration_seconds": round(time.perf_counter() - started, 3)})
+        return f"主视觉生成失败：{exc}", gr.update(), workshop_state or {}, "当前选择：无。", _workshop_run_dropdown_update(profile, workshop_state), summarize_workshop_stats()
+
+
+def workshop_select_candidate(workshop_state: dict | None, evt: gr.SelectData):
+    try:
+        index = int(evt.index if evt is not None else 0)
+        workshop_state = select_main_candidate(workshop_state or {}, index)
+        return workshop_state, f"当前选择：{index}"
+    except Exception as exc:
+        return workshop_state or {}, f"选择失败：{exc}"
+
+
+def workshop_generate_assets(workshop_state: dict | None, profile: gr.OAuthProfile | None = None):
+    started = time.perf_counter()
+    user = get_current_user(profile)
+    try:
+        user = require_login_for_generation(profile)
+    except ValueError as exc:
+        record_workshop_event(user, "generate_expression_pack", {"stage": "auth_required", "success": False, "failure_reason": str(exc)})
+        return str(exc), gr.update(), None, workshop_state or {}, _workshop_run_dropdown_update(profile, workshop_state), summarize_workshop_stats()
+    wait_message = _require_workshop_model_ready()
+    if wait_message:
+        record_workshop_event(user, "generate_expression_pack", {"stage": "modal_wait", "success": False, "failure_reason": wait_message, "modal_state": "not_ready"})
+        return wait_message, gr.update(), None, workshop_state or {}, _workshop_run_dropdown_update(profile, workshop_state), summarize_workshop_stats()
+    try:
+        workshop_state = ensure_user_workshop_run(workshop_state or {}, user)
+        if len(workshop_state.get("main_candidates") or []) < 4:
+            return "请先生成 4 张主视觉候选，再继续生成 8 表情和背景。", gr.update(), None, workshop_state, _workshop_run_dropdown_update(profile, workshop_state), summarize_workshop_stats()
+        workshop_state = generate_expression_pack(workshop_state)
+        workshop_state = generate_background(workshop_state)
+        expression_paths = [workshop_state["expression_assets"][slot] for slot in ("idle", "listening", "thinking", "worried", "smile", "happy", "talk", "focus")]
+        record_workshop_event(
+            user,
+            "generate_expression_pack",
+            {
+                "stage": "assets_ready",
+                "character_id": workshop_state.get("character_id"),
+                "duration_seconds": round(time.perf_counter() - started, 3),
+                "success": True,
+                "image_count": len(expression_paths) + (1 if workshop_state.get("background_asset") else 0),
+            },
+        )
+        return "8 表情和背景已生成，可以开始去背景并打包。", expression_paths, workshop_state.get("background_asset"), workshop_state, _workshop_run_dropdown_update(profile, workshop_state), summarize_workshop_stats()
+    except Exception as exc:
+        record_workshop_event(user, "generate_expression_pack", {"stage": "assets_ready", "success": False, "failure_reason": str(exc), "duration_seconds": round(time.perf_counter() - started, 3)})
+        return f"表情或背景生成失败：{exc}", gr.update(), None, workshop_state or {}, _workshop_run_dropdown_update(profile, workshop_state), summarize_workshop_stats()
+
+
+def workshop_package_assets(workshop_state: dict | None, profile: gr.OAuthProfile | None = None):
+    started = time.perf_counter()
+    user = get_current_user(profile)
+    try:
+        user = require_login_for_generation(profile)
+    except ValueError as exc:
+        record_workshop_event(user, "package_assets", {"stage": "auth_required", "success": False, "failure_reason": str(exc)})
+        return str(exc), None, "", workshop_state or {}, _workshop_run_dropdown_update(profile, workshop_state), summarize_workshop_stats()
+    try:
+        workshop_state = ensure_user_workshop_run(workshop_state or {}, user)
+        workshop_state = matte_and_package_assets(workshop_state)
+        package_dir = Path(workshop_state["package_dir"])
+        grid_path = package_dir / "generated" / "asset_grid.png"
+        preview_html = render_packaged_stage_preview(workshop_state)
+        record_workshop_event(user, "package_assets", {"stage": "packaged", "character_id": workshop_state.get("character_id"), "duration_seconds": round(time.perf_counter() - started, 3), "success": True})
+        return "角色资产已打包，可预览后安装。", str(grid_path), preview_html, workshop_state, _workshop_run_dropdown_update(profile, workshop_state), summarize_workshop_stats()
+    except Exception as exc:
+        record_workshop_event(user, "package_assets", {"stage": "packaged", "success": False, "failure_reason": str(exc), "duration_seconds": round(time.perf_counter() - started, 3)})
+        return f"打包失败：{exc}", None, "", workshop_state or {}, _workshop_run_dropdown_update(profile, workshop_state), summarize_workshop_stats()
+
+
+def workshop_install_character(workshop_state: dict | None, profile: gr.OAuthProfile | None = None):
+    started = time.perf_counter()
+    user = get_current_user(profile)
+    try:
+        user = require_login_for_generation(profile)
+    except ValueError as exc:
+        record_workshop_event(user, "install_character", {"stage": "auth_required", "success": False, "failure_reason": str(exc)})
+        return (
+            str(exc),
+            gr.update(choices=_character_choices()),
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            workshop_state or {},
+            _workshop_run_dropdown_update(profile, workshop_state),
+            summarize_workshop_stats(),
+        )
+    try:
+        workshop_state = ensure_user_workshop_run(workshop_state or {}, user)
+        workshop_state = install_character_package(workshop_state)
+        character_id = workshop_state["installed_character_id"]
+        switch_values = switch_character(character_id)
+        record_workshop_event(user, "install_character", {"stage": "installed", "character_id": character_id, "duration_seconds": round(time.perf_counter() - started, 3), "success": True})
+        return (
+            f"角色已安装：{character_id}",
+            gr.update(choices=_character_choices(), value=character_id),
+            *switch_values,
+            workshop_state,
+            _workshop_run_dropdown_update(profile, workshop_state),
+            summarize_workshop_stats(),
+        )
+    except Exception as exc:
+        record_workshop_event(user, "install_character", {"stage": "installed", "success": False, "failure_reason": str(exc), "duration_seconds": round(time.perf_counter() - started, 3)})
+        return (
+            f"安装失败：{exc}",
+            gr.update(choices=_character_choices()),
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            workshop_state or {},
+            _workshop_run_dropdown_update(profile, workshop_state),
+            summarize_workshop_stats(),
+        )
+
+
+def _parse_message(message: Any) -> tuple[str, dict[str, list[dict[str, Any]]], str]:
+    if message is None:
+        return "", {"images": []}, ""
+    if isinstance(message, str):
+        text = message.strip()
+        return text, {"images": []}, text
+
+    text = str(message.get("text") or "").strip() if isinstance(message, dict) else ""
+    files = message.get("files") if isinstance(message, dict) else []
+    media_inputs: dict[str, list[dict[str, Any]]] = {"images": []}
+
+    for item in files or []:
+        parsed = _parse_file_item(item)
+        if not parsed:
+            continue
+        if parsed["kind"] == "image":
+            media_inputs["images"].append(parsed)
+
+    if not text:
+        if media_inputs["images"]:
+            text = "请看这张图片，并用你的角色视角回应。"
+
+    attachment_labels = []
+    if media_inputs["images"]:
+        attachment_labels.append(f"{len(media_inputs['images'])} 张图片")
+    display_text = text
+    if attachment_labels:
+        display_text = f"{text}\n\n（已附加：{'，'.join(attachment_labels)}）"
+    return text, media_inputs, display_text
+
+
+def _parse_file_item(item: Any) -> dict[str, Any] | None:
+    if isinstance(item, str):
+        path = item
+        mime_type = mimetypes.guess_type(path)[0] or ""
+        name = Path(path).name
+    elif isinstance(item, dict):
+        path = item.get("path") or item.get("name") or item.get("orig_name")
+        mime_type = item.get("mime_type") or mimetypes.guess_type(str(path or ""))[0] or ""
+        name = item.get("orig_name") or item.get("name") or Path(str(path or "")).name
+    else:
+        path = getattr(item, "path", None) or getattr(item, "name", None)
+        mime_type = getattr(item, "mime_type", None) or mimetypes.guess_type(str(path or ""))[0] or ""
+        name = getattr(item, "orig_name", None) or Path(str(path or "")).name
+
+    if not path:
+        return None
+    suffix = Path(str(path)).suffix.lower()
+    if mime_type.startswith("image/") or suffix in {".png", ".jpg", ".jpeg", ".webp", ".gif"}:
+        kind = "image"
+    else:
+        return None
+    return {"kind": kind, "path": str(path), "mime_type": mime_type, "name": str(name)}
+
+
+def chat(
+    message: Any,
+    history: list[dict] | None,
+    state: dict | None,
+    voice_id: str,
+    voice_style: str,
+    voice_speed: float,
+    voice_energy: float,
+    voice_enabled: bool,
+):
+    if not state:
+        state = _initial_state("star_knight")
+
+    character = state.get("character") or get_character(state.get("character_id", "star_knight"))
+    user_text, media_inputs, display_text = _parse_message(message)
+    history = list(history or [])
+    if not user_text and not media_inputs["images"]:
+        yield history, render_character_stage(character, state["stage"]), None, "等待输入。", _debug_state(state), state
+        return
+
+    voice_state = {
+        **_default_voice_state(character, enabled=voice_enabled),
+        "voice_id": voice_id,
+        "style": voice_style,
+        "emotion": voice_style,
+        "speed": float(voice_speed or 1.0),
+        "energy": float(voice_energy or 0.5),
+        "enabled": bool(voice_enabled),
+    }
+    state["voice"] = voice_state
+    state["last_vision_note"] = _media_note(media_inputs)
+
+    model_history = _history_for_model(history, character)
+    history = history + [{"role": "user", "content": display_text}, {"role": "assistant", "content": _assistant_wait_message()}]
+    partial = ""
+    audio_value = None
+    audio_status = _initial_audio_status(voice_state)
+    yield (
+        history,
+        render_character_stage(character, state["stage"]),
+        audio_value,
+        audio_status,
+        _debug_state(state),
+        state,
+    )
+
+    for event in stream_reply(
+        user_text=user_text,
+        history=model_history,
+        state=state,
+        media_inputs=media_inputs,
+        voice_state=voice_state,
+    ):
+        state.setdefault("events", []).append(event)
+        state["events"] = state["events"][-100:]
+
+        if event["type"] == "stage":
+            state["stage"] = {**state.get("stage", {}), **event}
+        elif event["type"] == "text_delta":
+            partial += event.get("text", "")
+            history[-1]["content"] = partial
+        elif event["type"] == "audio":
+            audio_value = event.get("path")
+            audio_status = "语音回复���生成，可点击播放器收听。"
+        elif event["type"] == "error":
+            audio_status = event.get("message", audio_status)
+
+        yield (
+            history,
+            render_character_stage(character, state["stage"]),
+            audio_value,
+            audio_status,
+            _debug_state(state),
+            state,
+        )
+
+    if not audio_value:
+        audio_status = _final_audio_status(voice_state)
+        yield history, render_character_stage(character, state["stage"]), audio_value, audio_status, _debug_state(state), state
+
+
+def _media_note(media_inputs: dict[str, list[dict[str, Any]]]) -> str | None:
+    parts = []
+    if media_inputs.get("images"):
+        parts.append(f"用户本轮附加了 {len(media_inputs['images'])} 张图片。")
+    return " ".join(parts) if parts else None
+
+
+def _initial_audio_status(voice_state: dict[str, Any]) -> str:
+    if not voice_state.get("enabled", True):
+        return "语音生成已关闭。"
+    if not os.environ.get("VC_MODAL_TTS_URL"):
+        if _local_tts_service_exists():
+            return "TTS endpoint 未绑定；modal_apps/modal_tts.py 已存在，部署后设置 VC_MODAL_TTS_URL 即可生成语音。"
+        return "语音模型未配置。"
+    return "正在等待语音回复。"
+
+
+def _final_audio_status(voice_state: dict[str, Any]) -> str:
+    if not voice_state.get("enabled", True):
+        return "语音生成已关闭。"
+    if not os.environ.get("VC_MODAL_TTS_URL"):
+        if _local_tts_service_exists():
+            return "TTS endpoint 未绑定；modal_apps/modal_tts.py 已存在，部署后设置 VC_MODAL_TTS_URL 即可生成语音。"
+        return "语音模型未配置。"
+    return "本轮没有生成可播放语音。"
+
+
+def _assistant_wait_message() -> str:
+    if os.environ.get("VC_USE_MOCK") == "1":
+        return "正在生成回复..."
+    return "正在连接主模型。如果服务刚休眠，会先完成冷启动和权重加载。"
+
+
+def _local_tts_service_exists() -> bool:
+    return (ROOT / "modal_apps" / "modal_tts.py").exists()
+
+
+def _debug_state(state: dict) -> dict[str, Any]:
+    return {
+        "character_id": state.get("character_id"),
+        "stage": state.get("stage"),
+        "voice": state.get("voice"),
+        "last_vision_note": state.get("last_vision_note"),
+        "events": state.get("events", [])[-25:],
+    }
+
+
+def build_demo() -> gr.Blocks:
+    default_id = "star_knight"
+    default_state = _initial_state(default_id)
+    default_character = default_state["character"]
+    default_voice = default_state["voice"]
+
+    with gr.Blocks(title="Virtual Characters", elem_id="vc-root") as demo:
+        state = gr.State(default_state)
+        workshop_state = gr.State({})
+        appearance_marker = gr.HTML(value=_appearance_marker("day"), visible=True)
+
+        with gr.Tabs(elem_classes=["vc-tabs"]):
+            with gr.Tab("对话"):
+                with gr.Row(elem_classes=["vc-topbar"]):
+                    with gr.Column(scale=1, min_width=320, elem_classes=["vc-status-wrap"]):
+                        model_status = gr.HTML(value=statuses_markdown(initial_model_statuses()), elem_classes=["vc-panel"])
+                    with gr.Column(scale=0, min_width=240, elem_classes=["vc-status-actions"]):
+                        appearance_mode = gr.Radio(
+                            choices=APPEARANCE_CHOICES,
+                            value="day",
+                            label="视觉模式",
+                            elem_classes=["vc-appearance-mode"],
+                        )
+                        start_model = gr.Button("启动主模型", variant="primary")
+                        refresh_status = gr.Button("刷新模型状态", variant="secondary")
+                        model_action_status = gr.Markdown(value=_initial_model_action_note(), elem_classes=["vc-model-action"])
+
+                with gr.Row(equal_height=True):
+                    with gr.Column(scale=1, min_width=300, elem_classes=["vc-panel", "vc-left"]):
+                        character_select = gr.Radio(
+                            choices=_character_choices(),
+                            value=default_id,
+                            label="角色",
+                        )
+                        character_header = gr.HTML(value=_character_header_html(default_character))
+                        character_card = gr.Markdown(
+                            value=format_character_card_markdown(default_character),
+                            elem_classes=["vc-character-card"],
+                        )
+
+                    with gr.Column(scale=3, min_width=430, elem_classes=["vc-stage-col"]):
+                        stage = gr.HTML(
+                            value=render_character_stage(default_character, default_state["stage"]),
+                            elem_id="character-stage",
+                        )
+                        with gr.Row(elem_classes=["vc-input-dock"]):
+                            message_input = gr.MultimodalTextbox(
+                                label="输入",
+                                placeholder="输入文字，也可以附加图片...",
+                                sources=["upload"],
+                                file_types=["image"],
+                                file_count="multiple",
+                                submit_btn="发送",
+                                stop_btn=True,
+                                elem_id="vc-message",
+                            )
+
+                    with gr.Column(scale=1, min_width=340, elem_classes=["vc-panel", "vc-output", "vc-right"]):
+                        chatbot = gr.Chatbot(
+                            label="输出",
+                            value=_opening_history(default_character),
+                            height=430,
+                        )
+                        audio = gr.Audio(label="语音回复", autoplay=False, interactive=False, elem_id="voice-output")
+                        audio_status = gr.Markdown(value="等待新的语音回复。", elem_classes=["vc-audio-status"])
+
+                        with gr.Accordion("语音控制", open=False):
+                            voice_enabled = gr.Checkbox(value=True, label="生成语音回复")
+                            voice_id = gr.Dropdown(
+                                choices=_voice_choices(default_character),
+                                value=default_voice["voice_id"],
+                                label="音色",
+                            )
+                            voice_style = gr.Dropdown(
+                                choices=VOICE_STYLE_CHOICES,
+                                value=default_voice["style"],
+                                label="语气",
+                            )
+                            voice_speed = gr.Slider(0.75, 1.25, value=default_voice["speed"], step=0.01, label="语速")
+                            voice_energy = gr.Slider(0.2, 1.0, value=default_voice["energy"], step=0.05, label="表现力")
+
+                with gr.Accordion("事件与状态调试", open=False):
+                    with gr.Row():
+                        debug = gr.JSON(value={"events": []}, label="事件流")
+                        debug_models = gr.JSON(value=statuses_json(initial_model_statuses()), label="模型状态")
+                        debug_workshop_stats = gr.JSON(value=summarize_workshop_stats(), label="角色工坊统计")
+
+            with gr.Tab("角色工坊"):
+                with gr.Column(elem_id="vc-workshop-shell", elem_classes=["vc-workshop-shell"]):
+                    with gr.Row(elem_classes=["vc-topbar"]):
+                        with gr.Column(scale=1, min_width=320, elem_classes=["vc-status-wrap"]):
+                            workshop_model_status = gr.HTML(value=statuses_markdown(initial_model_statuses()), elem_classes=["vc-panel"])
+                        with gr.Column(scale=0, min_width=240, elem_classes=["vc-status-actions"]):
+                            if _hf_oauth_available():
+                                workshop_login = gr.LoginButton("使用 Hugging Face 登录")
+                            else:
+                                workshop_login = None
+                                gr.Markdown(
+                                    "本地 OAuth 预演需要先运行 `hf auth login` 或设置 `HF_TOKEN`，重启后这里会出现“使用 Hugging Face 登录”按钮；Space 上用户会直接点击按钮登录。",
+                                    elem_classes=["vc-model-action"],
+                                )
+                            workshop_start_model = gr.Button("启动主模型", variant="primary")
+                            workshop_refresh_status = gr.Button("刷新模型状态", variant="secondary")
+                            workshop_model_action_status = gr.Markdown(value=_initial_model_action_note(), elem_classes=["vc-model-action"])
+                    with gr.Row(equal_height=True):
+                        with gr.Column(scale=1, min_width=360, elem_classes=["vc-panel", "vc-workshop-grid"]):
+                            workshop_user_status = gr.Markdown(value=workshop_login_status(), elem_classes=["vc-workshop-status"])
+                        with gr.Column(scale=2, min_width=460, elem_classes=["vc-panel", "vc-workshop-grid"]):
+                            workshop_run_choice = gr.Dropdown(
+                                choices=list_user_workshop_runs(get_current_user(None)),
+                                value=None,
+                                label="我的生成任务",
+                                interactive=True,
+                            )
+                            with gr.Row():
+                                refresh_workshop_runs = gr.Button("刷新任务列表", variant="secondary")
+                                load_workshop_run_button = gr.Button("加载任务继续", variant="secondary")
+                                load_recent_workshop_run = gr.Button("加载最近任务", variant="secondary")
+
+                    with gr.Row(equal_height=True):
+                        with gr.Column(scale=1, min_width=360, elem_classes=["vc-panel", "vc-workshop-grid"]):
+                            workshop_status = gr.Markdown(value="先导入 Tavern JSON，或手填角色设定创建草案。", elem_classes=["vc-workshop-status"])
+                            tavern_file = gr.File(label="Tavern JSON 角色卡", file_types=[".json"])
+                            import_tavern = gr.Button("导入 Tavern JSON", variant="secondary")
+                            gr.Markdown("### 手填角色设定")
+                            workshop_name = gr.Textbox(label="角色名", value="星核")
+                            workshop_description = gr.Textbox(label="描述", lines=4, value="一名银白短发、青绿色眼睛的原创科幻通讯员。")
+                            workshop_personality = gr.Textbox(label="性格", lines=3, value="冷静、温柔、边界清晰")
+                            workshop_scenario = gr.Textbox(label="场景", lines=3, value="用户正在通过虚拟通讯端与角色对话。")
+                            workshop_first_mes = gr.Textbox(label="开场白", lines=2, value="我在。现在频道很稳定。")
+                            workshop_tags = gr.Textbox(label="标签", value="原创, 科幻, 通讯端")
+                            create_draft = gr.Button("创建草案", variant="primary")
+                            workshop_draft_card = gr.Markdown(value="", elem_classes=["vc-character-card"])
+
+                        with gr.Column(scale=2, min_width=460, elem_classes=["vc-panel", "vc-workshop-grid"]):
+                            with gr.Row():
+                                generate_candidates = gr.Button("生成 4 张主视觉候选", variant="primary")
+                                generate_assets = gr.Button("生成 8 表情和背景", variant="secondary")
+                            selected_candidate_index = gr.Number(value=0, visible=False)
+                            selected_candidate_label = gr.Markdown(value="当前选择：无。", elem_classes=["vc-workshop-status"])
+                            main_gallery = gr.Gallery(label="主视觉候选", columns=4, height=260, object_fit="contain")
+                            expression_gallery = gr.Gallery(label="8 表情/动作独立图片", columns=4, height=360, object_fit="contain")
+                            background_preview = gr.Image(label="背景图", type="filepath", height=180)
+
+                        with gr.Column(scale=1, min_width=360, elem_classes=["vc-panel", "vc-workshop-grid"]):
+                            package_assets = gr.Button("去背景并打包预览", variant="secondary")
+                            package_grid = gr.Image(label="资产包网格", type="filepath", height=300)
+                            package_stage_preview = gr.HTML(value="")
+                            install_character = gr.Button("安装并切换到新角色", variant="primary")
+
+        refresh_status.click(
+            refresh_model_status_both,
+            outputs=[model_status, workshop_model_status, debug_models, model_action_status, workshop_model_action_status],
+            show_progress="hidden",
+        )
+        start_model.click(
+            start_main_model,
+            outputs=[model_status, workshop_model_status, debug_models, model_action_status, workshop_model_action_status],
+            show_progress="minimal",
+        )
+        workshop_refresh_status.click(
+            refresh_model_status_both,
+            outputs=[model_status, workshop_model_status, debug_models, model_action_status, workshop_model_action_status],
+            show_progress="hidden",
+        )
+        workshop_start_model.click(
+            start_main_model,
+            outputs=[model_status, workshop_model_status, debug_models, model_action_status, workshop_model_action_status],
+            show_progress="minimal",
+        )
+        if workshop_login is not None:
+            workshop_login.click(
+                workshop_refresh_runs,
+                outputs=[workshop_user_status, workshop_run_choice, debug_workshop_stats],
+                show_progress="hidden",
+            )
+        refresh_workshop_runs.click(
+            workshop_refresh_runs,
+            outputs=[workshop_user_status, workshop_run_choice, debug_workshop_stats],
+            show_progress="hidden",
+        )
+        load_workshop_run_button.click(
+            workshop_load_selected_run,
+            inputs=[workshop_run_choice],
+            outputs=[
+                workshop_status,
+                workshop_draft_card,
+                workshop_state,
+                main_gallery,
+                selected_candidate_index,
+                selected_candidate_label,
+                expression_gallery,
+                background_preview,
+                package_grid,
+                package_stage_preview,
+                workshop_run_choice,
+                debug_workshop_stats,
+            ],
+            show_progress="minimal",
+        )
+        load_recent_workshop_run.click(
+            workshop_load_recent_run,
+            outputs=[
+                workshop_status,
+                workshop_draft_card,
+                workshop_state,
+                main_gallery,
+                selected_candidate_index,
+                selected_candidate_label,
+                expression_gallery,
+                background_preview,
+                package_grid,
+                package_stage_preview,
+                workshop_run_choice,
+                debug_workshop_stats,
+            ],
+            show_progress="minimal",
+        )
+        appearance_mode.change(
+            _appearance_marker,
+            inputs=[appearance_mode],
+            outputs=[appearance_marker],
+            show_progress="hidden",
+        )
+        character_select.change(
+            switch_character,
+            inputs=[character_select],
+            outputs=[
+                character_header,
+                character_card,
+                stage,
+                state,
+                chatbot,
+                debug,
+                voice_id,
+                voice_style,
+                voice_speed,
+                voice_energy,
+                voice_enabled,
+                audio_status,
+                audio,
+            ],
+            show_progress="hidden",
+        )
+        message_input.submit(
+            chat,
+            inputs=[
+                message_input,
+                chatbot,
+                state,
+                voice_id,
+                voice_style,
+                voice_speed,
+                voice_energy,
+                voice_enabled,
+            ],
+            outputs=[chatbot, stage, audio, audio_status, debug, state],
+            show_progress="hidden",
+        ).then(lambda: None, outputs=[message_input], show_progress="hidden")
+        create_draft.click(
+            workshop_create_from_form,
+            inputs=[
+                workshop_name,
+                workshop_description,
+                workshop_personality,
+                workshop_scenario,
+                workshop_first_mes,
+                workshop_tags,
+            ],
+            outputs=[
+                workshop_status,
+                workshop_draft_card,
+                workshop_state,
+                main_gallery,
+                selected_candidate_index,
+                selected_candidate_label,
+                expression_gallery,
+                background_preview,
+                package_grid,
+                package_stage_preview,
+            ],
+            show_progress="hidden",
+        )
+        import_tavern.click(
+            workshop_import_tavern,
+            inputs=[tavern_file],
+            outputs=[
+                workshop_status,
+                workshop_draft_card,
+                workshop_state,
+                main_gallery,
+                selected_candidate_index,
+                selected_candidate_label,
+                expression_gallery,
+                background_preview,
+                package_grid,
+                package_stage_preview,
+            ],
+            show_progress="hidden",
+        )
+        generate_candidates.click(
+            workshop_generate_main_candidates,
+            inputs=[workshop_state],
+            outputs=[workshop_status, main_gallery, workshop_state, selected_candidate_label, workshop_run_choice, debug_workshop_stats],
+            show_progress="full",
+            show_progress_on=main_gallery,
+            concurrency_limit=1,
+            concurrency_id="character_workshop_generation",
+        )
+        main_gallery.select(
+            workshop_select_candidate,
+            inputs=[workshop_state],
+            outputs=[workshop_state, selected_candidate_label],
+            show_progress="hidden",
+        )
+        generate_assets.click(
+            workshop_generate_assets,
+            inputs=[workshop_state],
+            outputs=[workshop_status, expression_gallery, background_preview, workshop_state, workshop_run_choice, debug_workshop_stats],
+            show_progress="full",
+            show_progress_on=[expression_gallery, background_preview],
+            concurrency_limit=1,
+            concurrency_id="character_workshop_generation",
+        )
+        package_assets.click(
+            workshop_package_assets,
+            inputs=[workshop_state],
+            outputs=[workshop_status, package_grid, package_stage_preview, workshop_state, workshop_run_choice, debug_workshop_stats],
+            show_progress="full",
+            show_progress_on=[package_grid, package_stage_preview],
+            concurrency_limit=1,
+            concurrency_id="character_workshop_generation",
+        )
+        install_character.click(
+            workshop_install_character,
+            inputs=[workshop_state],
+            outputs=[
+                workshop_status,
+                character_select,
+                character_header,
+                character_card,
+                stage,
+                state,
+                chatbot,
+                debug,
+                voice_id,
+                voice_style,
+                voice_speed,
+                voice_energy,
+                voice_enabled,
+                audio_status,
+                audio,
+                workshop_state,
+                workshop_run_choice,
+                debug_workshop_stats,
+            ],
+            show_progress="minimal",
+            concurrency_limit=1,
+            concurrency_id="character_workshop_generation",
+        )
+    return demo
+
+
+def launch_app(*, prevent_thread_lock: bool = False):
+    demo = build_demo().queue()
+    demo.launch(
+        theme=_theme(),
+        css=APP_CSS,
+        server_name=os.environ.get("VC_GRADIO_SERVER_NAME", "127.0.0.1"),
+        server_port=int(os.environ.get("VC_GRADIO_PORT", "7861")),
+        prevent_thread_lock=prevent_thread_lock,
+    )
+    return demo
+
+
+def _keep_alive_until_interrupt(demo) -> None:
+    try:
+        while True:
+            time.sleep(3600)
+    except KeyboardInterrupt:
+        demo.close()
+
+
+if __name__ == "__main__":
+    _keep_alive_until_interrupt(launch_app(prevent_thread_lock=True))

demo_modal_stack.py

@@ -0,0 +1,121 @@
+import re
+import tempfile
+import time
+from pathlib import Path
+
+import gradio as gr
+
+from modal_apps.modal_llm import PersonaLLM
+from modal_apps.modal_tts import CharacterTTS
+from src.character_registry import CHARACTER_PACKAGES, get_character
+from src.stage_driver import render_character_stage
+
+
+APP_CSS = """
+#modal-demo-stage iframe, #modal-demo-stage { min-height: 460px; }
+"""
+
+
+def _character_choices() -> list[tuple[str, str]]:
+    return [(character["display_name"], character_id) for character_id, character in CHARACTER_PACKAGES.items()]
+
+
+def _split_sentences(text: str) -> list[str]:
+    return [part.strip() for part in re.split(r"(?<=[。！？!?；;])\\s*", text) if part.strip()] or [text.strip()]
+
+
+def _write_wav(audio: bytes, prefix: str = "vc_tts_") -> str:
+    handle = tempfile.NamedTemporaryFile(prefix=prefix, suffix=".wav", delete=False)
+    handle.write(audio)
+    handle.close()
+    return handle.name
+
+
+def chat_once(message: str, history: list[dict], character_id: str, tts_enabled: bool):
+    if not message.strip():
+        yield history, None, {"status": "empty"}
+        return
+
+    character = get_character(character_id)
+    history = history + [{"role": "user", "content": message}, {"role": "assistant", "content": "Modal LLM 正在生成..."}]
+    yield history, None, {"status": "llm_generating"}
+
+    started = time.perf_counter()
+    llm_result = PersonaLLM().generate_text.remote(
+        user_text=message,
+        character=character,
+        max_new_tokens=120,
+    )
+    reply = llm_result["text"]
+    history[-1]["content"] = reply
+    debug = {
+        "status": "llm_done",
+        "llm_remote_s": llm_result.get("remote_s"),
+        "llm_output_tokens": llm_result.get("output_tokens"),
+        "client_elapsed_s": round(time.perf_counter() - started, 3),
+    }
+    yield history, None, debug
+
+    if not tts_enabled:
+        return
+
+    for index, sentence in enumerate(_split_sentences(reply), start=1):
+        if not sentence:
+            continue
+        debug = {**debug, "status": "tts_generating", "tts_sentence_index": index, "tts_sentence": sentence}
+        yield history, None, debug
+        tts_started = time.perf_counter()
+        audio = CharacterTTS().synthesize.remote(text=sentence, emotion="neutral")
+        audio_path = _write_wav(audio)
+        debug = {
+            **debug,
+            "status": "tts_chunk_done",
+            "tts_sentence_index": index,
+            "tts_remote_client_s": round(time.perf_counter() - tts_started, 3),
+            "audio_path": audio_path,
+        }
+        yield history, audio_path, debug
+
+
+def switch_character(character_id: str):
+    character = get_character(character_id)
+    stage = {"expression": "idle", "motion": "breathe", "intensity": 0.35}
+    return character["summary"], render_character_stage(character, stage)
+
+
+def build_demo() -> gr.Blocks:
+    default_id = "memory_girl"
+    default_character = get_character(default_id)
+    default_stage = {"expression": "idle", "motion": "breathe", "intensity": 0.35}
+
+    with gr.Blocks(title="Modal Virtual Character Smoke Demo") as demo:
+        with gr.Row():
+            with gr.Column(scale=1, min_width=260):
+                character_select = gr.Radio(_character_choices(), value=default_id, label="角色")
+                character_summary = gr.Markdown(default_character["summary"])
+                tts_enabled = gr.Checkbox(value=True, label="启用 Chatterbox TTS")
+            with gr.Column(scale=2, min_width=360):
+                stage = gr.HTML(
+                    render_character_stage(default_character, default_stage),
+                    elem_id="modal-demo-stage",
+                    min_height=460,
+                )
+            with gr.Column(scale=2, min_width=360):
+                chatbot = gr.Chatbot(label="Modal 对话", height=380)
+                message = gr.Textbox(label="输入", lines=2, submit_btn=True)
+                audio = gr.Audio(label="分句语音", autoplay=True)
+
+        debug = gr.JSON(label="调试")
+
+        character_select.change(switch_character, inputs=[character_select], outputs=[character_summary, stage])
+        message.submit(
+            chat_once,
+            inputs=[message, chatbot, character_select, tts_enabled],
+            outputs=[chatbot, audio, debug],
+        ).then(lambda: "", outputs=[message])
+
+    return demo
+
+
+if __name__ == "__main__":
+    build_demo().queue().launch(css=APP_CSS, server_name="127.0.0.1", server_port=7862)

modal_apps/README.md

@@ -0,0 +1,208 @@
+# Modal apps
+
+These files define separate Modal deployments for the virtual character project.
+
+## Setup
+
+```powershell
+python -m pip install -r requirements.txt
+modal setup
+modal secret create hf-token HF_TOKEN=hf_xxx
+```
+
+You must also accept gated model licenses on Hugging Face before Modal can download those weights.
+
+If your Modal Secret uses a different name, set it before running checks or deploys:
+
+```powershell
+$env:VC_HF_SECRET_NAME="your-secret-name"
+```
+
+## First checks
+
+Run remote method health checks:
+
+```powershell
+modal run modal_apps/modal_ping.py
+modal run modal_apps/modal_hf_check.py
+python scripts/check_modal_connectivity.py --mode remote-methods
+```
+
+`modal_ping.py` is CPU-only and only checks login/connectivity. `modal_hf_check.py` is also CPU-only and checks whether Modal can read `hf-token` and query the selected Hugging Face model metadata without downloading weights. The health checks in `check_modal_connectivity.py` start the service containers but do not load model weights. Actual generation tests will load models and consume GPU credits.
+
+Benchmark Gemma on Modal:
+
+```powershell
+$env:VC_BENCH_MODEL="google/gemma-4-12B-it"
+$env:VC_BENCH_GPU="L40S"
+modal run modal_apps/modal_gemma_benchmark.py --max-new-tokens 64
+```
+
+Benchmark Gemma through vLLM:
+
+```powershell
+$env:VC_VLLM_MODEL="google/gemma-4-12B-it"
+$env:VC_VLLM_VERSION="0.22.1"
+$env:VC_VLLM_GPU="L40S"
+$env:VC_VLLM_FAST_BOOT="1"
+modal run modal_apps/modal_vllm_gemma.py --max-tokens 128
+```
+
+Note: `vllm==0.22.1` is the latest PyPI stable release checked on 2026-06-12, but it still does not run `google/gemma-4-12B-it` correctly in our Modal test. For Gemma 4 12B, use this only as a regression check.
+
+Benchmark Gemma through vLLM nightly:
+
+```powershell
+$env:PYTHONIOENCODING="utf-8"
+$env:PYTHONUTF8="1"
+$env:VC_SKIP_HF_SECRET="1"
+$env:VC_VLLM_MODEL="google/gemma-4-12B-it"
+$env:VC_VLLM_PACKAGE="vllm==0.22.1rc1.dev468+gfbc3a1907.cu129"
+$env:VC_VLLM_EXTRA_INDEX_URL="https://wheels.vllm.ai/nightly/cu129"
+$env:VC_VLLM_UV_EXTRA_OPTIONS="--index-strategy unsafe-best-match"
+$env:VC_VLLM_PRE="1"
+$env:VC_VLLM_GPU="L40S"
+$env:VC_VLLM_FAST_BOOT="1"
+modal run modal_apps/modal_vllm_gemma.py --max-tokens 128
+```
+
+Deploy the working vLLM nightly endpoint:
+
+```powershell
+$env:PYTHONIOENCODING="utf-8"
+$env:PYTHONUTF8="1"
+$env:VC_SKIP_HF_SECRET="1"
+$env:VC_VLLM_MODEL="google/gemma-4-12B-it"
+$env:VC_VLLM_PACKAGE="vllm==0.22.1rc1.dev468+gfbc3a1907.cu129"
+$env:VC_VLLM_EXTRA_INDEX_URL="https://wheels.vllm.ai/nightly/cu129"
+$env:VC_VLLM_UV_EXTRA_OPTIONS="--index-strategy unsafe-best-match"
+$env:VC_VLLM_PRE="1"
+$env:VC_VLLM_GPU="L40S"
+$env:VC_VLLM_FAST_BOOT="1"
+modal deploy modal_apps/modal_vllm_gemma.py
+```
+
+Keep the deployed vLLM endpoint warm:
+
+```powershell
+python scripts/set_modal_vllm_autoscaler.py on
+```
+
+This updates the deployed `serve` function to `min_containers=1`, `buffer_containers=0`, and `scaledown_window=1200`. It takes effect without rebuilding the image, but Modal resets this override on the next deploy.
+
+To make warm residency part of the deployment configuration, set these before `modal deploy`:
+
+```powershell
+$env:VC_VLLM_MIN_CONTAINERS="1"
+$env:VC_VLLM_BUFFER_CONTAINERS="0"
+$env:VC_VLLM_SCALEDOWN_WINDOW="1200"
+modal deploy modal_apps/modal_vllm_gemma.py
+```
+
+Turn warm residency off when the demo window is over:
+
+```powershell
+python scripts/set_modal_vllm_autoscaler.py off
+```
+
+Current deployed endpoint:
+
+```text
+https://veronicaulises0--virtual-characters-vllm-gemma-serve.modal.run
+```
+
+This deployment intentionally skips mounting `hf-token` into the nightly vLLM runtime. It depends on the `vc-hf-cache` Modal Volume already containing `google/gemma-4-12B-it`.
+
+To avoid building every service image at once, check one service at a time:
+
+```powershell
+python scripts/check_modal_connectivity.py --mode remote-methods --service llm
+python scripts/check_modal_connectivity.py --mode remote-methods --service tts
+python scripts/check_modal_connectivity.py --mode remote-methods --service image
+```
+
+## Character generation spike
+
+The automated character-generation spike is intentionally isolated from the Gradio UI and the deployed image endpoint.
+
+Safe checks:
+
+```powershell
+python scripts/run_character_generation_spike.py list-models
+python scripts/run_character_generation_spike.py modal-health
+```
+
+`modal-health` starts the Modal app but does not load model weights. Generation probes load weights and consume GPU credits, so the CLI requires `--confirm-gpu`:
+
+```powershell
+python scripts/run_character_generation_spike.py modal-probe --candidate flux_schnell --batch-size 1 --confirm-gpu
+python scripts/run_character_generation_spike.py modal-benchmark --candidates flux_schnell qwen_image --confirm-gpu
+python scripts/run_character_generation_spike.py modal-benchmark --candidates qwen_image_edit --init-image path\to\reference.png --include-expressions --confirm-gpu
+python scripts/run_character_generation_spike.py modal-benchmark --candidates qwen_controlnet_union --control-image path\to\pose.png --include-expressions --confirm-gpu
+```
+
+Candidates:
+
+- `flux_schnell`: speed baseline using `black-forest-labs/FLUX.1-schnell`.
+- `qwen_image`: Chinese prompt and high-quality text-to-image candidate using `Qwen/Qwen-Image`.
+- `qwen_image_edit`: expression/edit candidate using `Qwen/Qwen-Image-Edit`.
+- `qwen_controlnet_union`: pose/canny/depth action candidate using `InstantX/Qwen-Image-ControlNet-Union`.
+- `instantid_sdxl`: tracked as identity-preserving candidate, but disabled until the face-analysis/model download path is pinned.
+
+The spike image installs diffusers from GitHub because the Qwen Image and ControlNet pipelines require recent upstream support. If a model is gated or not cached, make sure the `hf-token` secret has accepted the Hugging Face model terms.
+
+If `hf-token` is not created yet and you only want to verify Modal container startup, use:
+
+```powershell
+$env:VC_SKIP_HF_SECRET="1"
+python scripts/check_modal_connectivity.py --mode remote-methods
+```
+
+Only deploy with `VC_SKIP_HF_SECRET=1` when the selected model is public or the required weights are already cached in the mounted Modal Volume. The working vLLM Gemma 4 deployment uses this cache-based route to avoid exposing `hf-token` to a nightly dependency stack.
+
+Deploy services:
+
+```powershell
+modal deploy modal_apps/modal_llm.py
+modal deploy modal_apps/modal_tts.py
+modal deploy modal_apps/modal_image.py
+```
+
+Then set endpoint URLs from Modal output:
+
+```powershell
+$env:VC_MODAL_LLM_URL="https://...modal.run/persona_events"
+$env:VC_MODAL_TTS_URL="https://...modal.run/tts"
+$env:VC_MODAL_IMAGE_URL="https://...modal.run/character_image"
+python scripts/check_modal_connectivity.py --mode endpoints
+```
+
+## Cost defaults
+
+- vLLM LLM: `google/gemma-4-12B-it`, GPU `L40S`, scaledown 5 min unless `VC_VLLM_MIN_CONTAINERS=1`.
+- Transformers LLM fallback: `google/gemma-4-12B-it`, GPU `L40S`, scaledown 3 min.
+- TTS: Chatterbox, GPU `A10G`, scaledown 3 min.
+- Image: FLUX.1-schnell, GPU `H100`, scaledown 1 min.
+
+Modal public GPU prices checked on 2026-06-14:
+
+| GPU | Approx hourly | Approx 7 days |
+| --- | ---: | ---: |
+| T4 | $0.5904 | $99.19 |
+| L4 | $0.7992 | $134.27 |
+| A10 | $1.1016 | $185.07 |
+| L40S | $1.9512 | $327.80 |
+| A100-40GB | $2.0988 | $352.60 |
+| A100-80GB | $2.4984 | $419.73 |
+| H100 | $3.9492 | $663.47 |
+
+These numbers are GPU-only. CPU, memory, regional multipliers, non-preemptible execution, and storage can add extra cost. With a $240 budget, one L40S can stay warm for about 123 hours, so a full 7-day L40S warm deployment is over budget. A10 fits the 7-day GPU-only budget, but the current Gemma 4 12B vLLM deployment is validated on L40S and should not be moved to A10 without a separate benchmark.
+
+Override with env vars before deploy:
+
+```powershell
+$env:VC_LLM_MODEL="google/gemma-4-E4B-it"
+$env:VC_LLM_GPU="A10"
+$env:VC_TTS_BACKEND="kokoro"
+$env:VC_IMAGE_GPU="L40S"
+```

requirements.txt

@@ -0,0 +1,6 @@
+gradio[oauth]>=6.0.0
+httpx>=0.28.0
+modal>=1.0.0
+pillow>=10.0.0
+python-dotenv>=1.0.1
+rembg[cpu]>=2.0.67

src/character_spike/__init__.py

@@ -0,0 +1,2 @@
+"""Risk-validation helpers for automated character generation."""
+

src/character_spike/assets.py

@@ -0,0 +1,447 @@
+from __future__ import annotations
+
+import json
+import math
+import random
+import time
+from collections import deque
+from pathlib import Path
+from typing import Any
+
+from PIL import Image, ImageDraw, ImageFilter, ImageFont
+
+from src.character_spike.schema import CANONICAL_STAGE_SIZE, EXPRESSIONS, default_character_package
+
+
+def create_asset_package_from_probe_outputs(
+    *,
+    source_run_dir: str | Path,
+    candidate_id: str,
+    character_id: str,
+    display_name: str,
+    output_root: str | Path,
+    seed: int = 42,
+    remove_background: bool = True,
+) -> dict[str, Any]:
+    started = time.perf_counter()
+    source = Path(source_run_dir)
+    out_root = Path(output_root)
+    run_dir = out_root / character_id
+    character_dir = run_dir / "assets" / "characters" / character_id
+    background_dir = run_dir / "assets" / "backgrounds"
+    generated_dir = run_dir / "generated"
+    character_dir.mkdir(parents=True, exist_ok=True)
+    background_dir.mkdir(parents=True, exist_ok=True)
+    generated_dir.mkdir(parents=True, exist_ok=True)
+
+    package = default_character_package(character_id, display_name)
+    package["metadata"]["source"] = "probe_asset_package"
+    package["metadata"]["source_run_dir"] = str(source)
+    package["metadata"]["candidate_id"] = candidate_id
+    package_path = run_dir / "characters" / f"{character_id}.json"
+    package_path.parent.mkdir(parents=True, exist_ok=True)
+    package_path.write_text(json.dumps(package, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+    assets: list[dict[str, Any]] = []
+    missing_slots: list[str] = []
+    for expression in EXPRESSIONS:
+        source_path = source / "generated" / candidate_id / f"expression_{expression}" / "00.png"
+        if not source_path.exists():
+            source_path = source / "generated" / candidate_id / "expression_idle" / "00.png"
+            missing_slots.append(expression)
+        target_path = character_dir / f"{expression}.png"
+        image = Image.open(source_path).convert("RGBA")
+        processed = remove_flat_background(image) if remove_background else image
+        normalized = normalize_to_stage_canvas(processed)
+        normalized.save(target_path)
+        assets.append(
+            {
+                "slot": expression,
+                "path": str(target_path.relative_to(run_dir)),
+                "source_path": str(source_path),
+                "bytes": target_path.stat().st_size,
+                "source": f"probe:{candidate_id}",
+                "usable": expression not in missing_slots,
+                "manual_score": None,
+            }
+        )
+
+    background_path = background_dir / f"{character_id}_spike_background.png"
+    _draw_mock_background(display_name, random.Random(seed)).save(background_path)
+    grid_path = generated_dir / "asset_grid.png"
+    make_thumbnail_grid([character_dir / f"{slot}.png" for slot in EXPRESSIONS], grid_path)
+
+    manifest = {
+        "schema_version": 1,
+        "run_type": "probe_asset_package",
+        "character_id": character_id,
+        "display_name": display_name,
+        "seed": seed,
+        "created_at_unix": int(time.time()),
+        "duration_seconds": round(time.perf_counter() - started, 3),
+        "paths": {
+            "run_dir": str(run_dir),
+            "character_package": str(package_path.relative_to(run_dir)),
+            "character_assets": str(character_dir.relative_to(run_dir)),
+            "background": str(background_path.relative_to(run_dir)),
+            "thumbnail_grid": str(grid_path.relative_to(run_dir)),
+        },
+        "assets": assets,
+        "model_results": [],
+        "qa": {
+            "usable_assets": len([asset for asset in assets if asset["usable"]]),
+            "total_assets": len(EXPRESSIONS),
+            "needs_manual_review": missing_slots,
+            "notes": [
+                "Packaged from Modal probe outputs.",
+                "Background removal uses a simple flat-background alpha pass; manual QA is still required."
+                if remove_background
+                else "Background was intentionally preserved as a no-matting fallback.",
+            ],
+        },
+    }
+    manifest_path = generated_dir / "manifest.json"
+    manifest["paths"]["manifest"] = str(manifest_path.relative_to(run_dir))
+    manifest_path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    write_report(manifest, generated_dir / "report.md")
+    return manifest
+
+
+def create_mock_asset_package(
+    *,
+    character_id: str,
+    display_name: str,
+    output_root: str | Path,
+    seed: int = 42,
+) -> dict[str, Any]:
+    started = time.perf_counter()
+    rng = random.Random(seed)
+    out_root = Path(output_root)
+    run_dir = out_root / character_id
+    character_dir = run_dir / "assets" / "characters" / character_id
+    background_dir = run_dir / "assets" / "backgrounds"
+    generated_dir = run_dir / "generated"
+    character_dir.mkdir(parents=True, exist_ok=True)
+    background_dir.mkdir(parents=True, exist_ok=True)
+    generated_dir.mkdir(parents=True, exist_ok=True)
+
+    package = default_character_package(character_id, display_name)
+    package["metadata"]["source"] = "mock_asset_package"
+    package_path = run_dir / "characters" / f"{character_id}.json"
+    package_path.parent.mkdir(parents=True, exist_ok=True)
+    package_path.write_text(json.dumps(package, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+    assets: list[dict[str, Any]] = []
+    for index, expression in enumerate(EXPRESSIONS):
+        path = character_dir / f"{expression}.png"
+        image = _draw_mock_character(display_name, expression, index, rng)
+        normalized = normalize_to_stage_canvas(image)
+        normalized.save(path)
+        assets.append(
+            {
+                "slot": expression,
+                "path": str(path.relative_to(run_dir)),
+                "bytes": path.stat().st_size,
+                "source": "mock_pillow",
+                "usable": True,
+                "manual_score": None,
+            }
+        )
+
+    background_path = background_dir / f"{character_id}_spike_background.png"
+    _draw_mock_background(display_name, rng).save(background_path)
+    grid_path = generated_dir / "asset_grid.png"
+    make_thumbnail_grid([character_dir / f"{slot}.png" for slot in EXPRESSIONS], grid_path)
+
+    manifest = {
+        "schema_version": 1,
+        "run_type": "mock_asset_package",
+        "character_id": character_id,
+        "display_name": display_name,
+        "seed": seed,
+        "created_at_unix": int(time.time()),
+        "duration_seconds": round(time.perf_counter() - started, 3),
+        "paths": {
+            "run_dir": str(run_dir),
+            "character_package": str(package_path.relative_to(run_dir)),
+            "character_assets": str(character_dir.relative_to(run_dir)),
+            "background": str(background_path.relative_to(run_dir)),
+            "thumbnail_grid": str(grid_path.relative_to(run_dir)),
+        },
+        "assets": assets,
+        "model_results": [],
+        "qa": {
+            "usable_assets": len(assets),
+            "total_assets": len(EXPRESSIONS),
+            "needs_manual_review": [],
+            "notes": ["Mock assets validate packaging, postprocessing, manifest, and reporting without GPU cost."],
+        },
+    }
+    manifest_path = generated_dir / "manifest.json"
+    manifest["paths"]["manifest"] = str(manifest_path.relative_to(run_dir))
+    manifest_path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    write_report(manifest, generated_dir / "report.md")
+    return manifest
+
+
+def normalize_to_stage_canvas(image: Image.Image, size: tuple[int, int] = CANONICAL_STAGE_SIZE) -> Image.Image:
+    image = image.convert("RGBA")
+    alpha = image.getchannel("A")
+    bbox = alpha.getbbox()
+    if bbox is None:
+        return Image.new("RGBA", size, (0, 0, 0, 0))
+
+    crop = image.crop(bbox)
+    max_width = int(size[0] * 0.82)
+    max_height = int(size[1] * 0.92)
+    scale = min(max_width / crop.width, max_height / crop.height)
+    new_size = (max(1, round(crop.width * scale)), max(1, round(crop.height * scale)))
+    crop = crop.resize(new_size, Image.Resampling.LANCZOS)
+    canvas = Image.new("RGBA", size, (0, 0, 0, 0))
+    x = (size[0] - new_size[0]) // 2
+    y = size[1] - new_size[1] - 24
+    canvas.alpha_composite(crop, (x, y))
+    return canvas
+
+
+def remove_flat_background(
+    image: Image.Image,
+    *,
+    tolerance: int = 42,
+    feather_radius: float = 1.25,
+) -> Image.Image:
+    image = image.convert("RGBA")
+    width, height = image.size
+    sample_points = [
+        (0, 0),
+        (width - 1, 0),
+        (0, height - 1),
+        (width - 1, height - 1),
+        (width // 2, 0),
+        (width // 2, height - 1),
+    ]
+    pixels = image.load()
+    samples = [pixels[x, y][:3] for x, y in sample_points]
+    background = tuple(round(sum(channel) / len(samples)) for channel in zip(*samples))
+
+    source_pixels = image.load()
+    visited = bytearray(width * height)
+    queue: deque[tuple[int, int]] = deque()
+
+    def is_background(x: int, y: int) -> bool:
+        rgb = source_pixels[x, y][:3]
+        distance = max(abs(rgb[index] - background[index]) for index in range(3))
+        return distance <= tolerance
+
+    def push(x: int, y: int) -> None:
+        index = y * width + x
+        if visited[index] or not is_background(x, y):
+            return
+        visited[index] = 1
+        queue.append((x, y))
+
+    for x in range(width):
+        push(x, 0)
+        push(x, height - 1)
+    for y in range(height):
+        push(0, y)
+        push(width - 1, y)
+
+    while queue:
+        x, y = queue.popleft()
+        if x > 0:
+            push(x - 1, y)
+        if x < width - 1:
+            push(x + 1, y)
+        if y > 0:
+            push(x, y - 1)
+        if y < height - 1:
+            push(x, y + 1)
+
+    alpha = Image.new("L", image.size, 255)
+    alpha_pixels = alpha.load()
+    for y in range(height):
+        row = y * width
+        for x in range(width):
+            if visited[row + x]:
+                alpha_pixels[x, y] = 0
+    if feather_radius > 0:
+        alpha = alpha.filter(ImageFilter.GaussianBlur(feather_radius))
+    image.putalpha(alpha)
+    return image
+
+
+def make_thumbnail_grid(paths: list[Path], output_path: str | Path, thumb_size: tuple[int, int] = (180, 240)) -> Path:
+    output = Path(output_path)
+    cols = 4
+    rows = math.ceil(len(paths) / cols)
+    grid = Image.new("RGB", (cols * thumb_size[0], rows * (thumb_size[1] + 26)), (17, 24, 39))
+    draw = ImageDraw.Draw(grid)
+    font = _font(16)
+    for index, path in enumerate(paths):
+        row, col = divmod(index, cols)
+        x = col * thumb_size[0]
+        y = row * (thumb_size[1] + 26)
+        image = Image.open(path).convert("RGBA")
+        image.thumbnail(thumb_size, Image.Resampling.LANCZOS)
+        cell = Image.new("RGBA", thumb_size, (15, 23, 42, 255))
+        px = (thumb_size[0] - image.width) // 2
+        py = (thumb_size[1] - image.height) // 2
+        cell.alpha_composite(image, (px, py))
+        grid.paste(cell.convert("RGB"), (x, y))
+        draw.text((x + 8, y + thumb_size[1] + 4), path.stem, fill=(226, 232, 240), font=font)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    grid.save(output)
+    return output
+
+
+def write_report(manifest: dict[str, Any], path: str | Path) -> Path:
+    output = Path(path)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    report = render_report_markdown(manifest)
+    output.write_text(report, encoding="utf-8")
+    return output
+
+
+def render_report_markdown(manifest: dict[str, Any]) -> str:
+    qa = manifest.get("qa", {})
+    model_results = manifest.get("model_results") or []
+    assets = manifest.get("assets") or []
+    lines = [
+        f"# Character Generation Spike Report: {manifest.get('display_name', manifest.get('character_id', 'unknown'))}",
+        "",
+        "## Run",
+        "",
+        f"- Character ID: `{manifest.get('character_id')}`",
+        f"- Run type: `{manifest.get('run_type')}`",
+        f"- Duration: `{manifest.get('duration_seconds')}` seconds",
+        f"- Seed: `{manifest.get('seed')}`",
+        "",
+        "## Asset QA",
+        "",
+        f"- Usable assets: `{qa.get('usable_assets', 0)}/{qa.get('total_assets', len(assets))}`",
+        f"- Needs manual review: `{len(qa.get('needs_manual_review') or [])}`",
+    ]
+    for note in qa.get("notes") or []:
+        lines.append(f"- Note: {note}")
+    lines.extend(["", "## Model Results", ""])
+    if model_results:
+        lines.append("| Candidate | Mode | Cold/Warm | Images | Seconds | GPU | Status |")
+        lines.append("| --- | --- | --- | ---: | ---: | --- | --- |")
+        for result in model_results:
+            lines.append(
+                "| {candidate} | {mode} | {temperature} | {images} | {seconds} | {gpu} | {status} |".format(
+                    candidate=result.get("candidate_id", ""),
+                    mode=result.get("mode", ""),
+                    temperature="cold" if result.get("loaded_before") is False else "warm",
+                    images=result.get("image_count", 0),
+                    seconds=result.get("duration_seconds", ""),
+                    gpu=result.get("gpu", ""),
+                    status=result.get("status", ""),
+                )
+            )
+    else:
+        lines.append("No remote model probes recorded yet.")
+
+    lines.extend(["", "## Assets", ""])
+    for asset in assets:
+        lines.append(f"- `{asset.get('slot')}`: `{asset.get('path')}` ({asset.get('bytes')} bytes)")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _draw_mock_character(display_name: str, expression: str, index: int, rng: random.Random) -> Image.Image:
+    width, height = CANONICAL_STAGE_SIZE
+    image = Image.new("RGBA", (width, height), (0, 0, 0, 0))
+    draw = ImageDraw.Draw(image)
+    accent = _palette(index)
+    skin = (255, 216, 204, 255)
+    coat = (31 + rng.randrange(20), 41 + rng.randrange(20), 55 + rng.randrange(30), 255)
+    hair = (190 + rng.randrange(45), 230 + rng.randrange(20), 245 + rng.randrange(10), 255)
+
+    draw.ellipse((265, 970, 635, 1060), fill=(0, 0, 0, 72))
+    draw.polygon([(250, 1080), (345, 660), (555, 660), (650, 1080)], fill=coat)
+    draw.polygon([(345, 670), (450, 850), (555, 670), (595, 1080), (305, 1080)], fill=(12, 18, 31, 255))
+    draw.rounded_rectangle((395, 600, 505, 730), radius=36, fill=(239, 184, 170, 255))
+    draw.ellipse((255, 170, 645, 640), fill=skin)
+    draw.ellipse((210, 95, 690, 520), fill=hair)
+    draw.pieslice((210, 110, 690, 650), 185, 355, fill=(120, 190, 210, 255))
+    draw.polygon([(300, 250), (370, 100), (420, 340)], fill=hair)
+    draw.polygon([(430, 230), (510, 80), (540, 345)], fill=hair)
+    draw.polygon([(535, 260), (610, 150), (625, 390)], fill=hair)
+    draw.rounded_rectangle((385, 795, 515, 835), radius=18, fill=accent)
+
+    _draw_expression(draw, expression, accent)
+    font = _font(28)
+    small = _font(22)
+    draw.text((34, 34), display_name, fill=(238, 242, 255, 220), font=font)
+    draw.text((34, 72), expression, fill=accent, font=small)
+    return image
+
+
+def _draw_expression(draw: ImageDraw.ImageDraw, expression: str, accent: tuple[int, int, int, int]) -> None:
+    eye = (15, 23, 42, 255)
+    if expression in {"smile", "happy"}:
+        draw.arc((325, 385, 410, 445), 200, 340, fill=eye, width=8)
+        draw.arc((490, 385, 575, 445), 200, 340, fill=eye, width=8)
+        draw.arc((405, 505, 495, 570), 15, 165, fill=(159, 18, 57, 255), width=8)
+    else:
+        draw.ellipse((330, 380, 405, 455), fill=(248, 250, 252, 255))
+        draw.ellipse((495, 380, 570, 455), fill=(248, 250, 252, 255))
+        draw.ellipse((356, 398, 388, 438), fill=accent)
+        draw.ellipse((521, 398, 553, 438), fill=accent)
+        draw.ellipse((366, 410, 382, 433), fill=eye)
+        draw.ellipse((531, 410, 547, 433), fill=eye)
+        if expression == "worried":
+            draw.arc((410, 525, 490, 580), 200, 340, fill=(159, 18, 57, 255), width=8)
+        else:
+            draw.arc((410, 505, 490, 552), 25, 155, fill=(159, 18, 57, 255), width=7)
+    if expression == "thinking":
+        draw.line((315, 350, 405, 360), fill=eye, width=7)
+        draw.line((495, 360, 585, 350), fill=eye, width=7)
+    elif expression == "worried":
+        draw.line((315, 365, 405, 340), fill=eye, width=7)
+        draw.line((495, 340, 585, 365), fill=eye, width=7)
+    else:
+        draw.line((320, 360, 405, 350), fill=eye, width=7)
+        draw.line((495, 350, 580, 360), fill=eye, width=7)
+
+
+def _draw_mock_background(display_name: str, rng: random.Random) -> Image.Image:
+    width, height = 1600, 900
+    image = Image.new("RGB", (width, height), (12, 18, 31))
+    draw = ImageDraw.Draw(image)
+    for y in range(height):
+        shade = int(20 + 40 * y / height)
+        draw.line((0, y, width, y), fill=(10, 16 + shade // 4, 26 + shade))
+    for _ in range(70):
+        x = rng.randrange(width)
+        y = rng.randrange(height)
+        radius = rng.randrange(1, 4)
+        draw.ellipse((x, y, x + radius, y + radius), fill=(148, 163, 184))
+    for x in range(0, width, 120):
+        draw.line((x, 0, x + 320, height), fill=(255, 255, 255, 16), width=1)
+    font = _font(44)
+    draw.text((56, 56), f"{display_name} / spike background", fill=(226, 232, 240), font=font)
+    return image
+
+
+def _palette(index: int) -> tuple[int, int, int, int]:
+    colors = [
+        (103, 232, 249, 255),
+        (125, 211, 252, 255),
+        (250, 204, 21, 255),
+        (244, 114, 182, 255),
+        (167, 243, 208, 255),
+        (196, 181, 253, 255),
+        (251, 146, 60, 255),
+        (129, 140, 248, 255),
+    ]
+    return colors[index % len(colors)]
+
+
+def _font(size: int) -> ImageFont.ImageFont:
+    try:
+        return ImageFont.truetype("arial.ttf", size)
+    except OSError:
+        return ImageFont.load_default()

src/character_spike/schema.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+EXPRESSIONS = ["idle", "listening", "thinking", "worried", "smile", "happy", "talk", "focus"]
+CANONICAL_STAGE_SIZE = (900, 1200)
+WARM_FOUR_IMAGE_LIMIT_SECONDS = 60.0
+EIGHT_ASSET_LIMIT_SECONDS = 180.0
+MIN_USABLE_ASSET_COUNT = 6
+
+
+@dataclass(frozen=True)
+class ModelCandidate:
+    id: str
+    label: str
+    family: str
+    model_id: str
+    mode: str
+    default_steps: int
+    default_gpu: str
+    implemented: bool
+    notes: str
+
+
+MODEL_CANDIDATES: tuple[ModelCandidate, ...] = (
+    ModelCandidate(
+        id="flux_schnell",
+        label="FLUX.1-schnell",
+        family="flux",
+        model_id="black-forest-labs/FLUX.1-schnell",
+        mode="text_to_image_speed_baseline",
+        default_steps=4,
+        default_gpu="H100",
+        implemented=True,
+        notes="Speed baseline for main visual candidates.",
+    ),
+    ModelCandidate(
+        id="qwen_image",
+        label="Qwen-Image",
+        family="qwen_image",
+        model_id="Qwen/Qwen-Image",
+        mode="text_to_image_quality_candidate",
+        default_steps=50,
+        default_gpu="H100",
+        implemented=True,
+        notes="Quality and Chinese prompt candidate; likely slower than FLUX.",
+    ),
+    ModelCandidate(
+        id="qwen_image_edit",
+        label="Qwen-Image-Edit",
+        family="qwen_image_edit",
+        model_id="Qwen/Qwen-Image-Edit",
+        mode="instruction_image_edit",
+        default_steps=50,
+        default_gpu="H100",
+        implemented=True,
+        notes="Expression and local edit candidate based on a reference image.",
+    ),
+    ModelCandidate(
+        id="qwen_controlnet_union",
+        label="Qwen-Image-ControlNet-Union",
+        family="qwen_controlnet",
+        model_id="InstantX/Qwen-Image-ControlNet-Union",
+        mode="pose_canny_depth_control",
+        default_steps=30,
+        default_gpu="H100",
+        implemented=True,
+        notes="Structure control candidate for action poses.",
+    ),
+    ModelCandidate(
+        id="instantid_sdxl",
+        label="InstantID SDXL",
+        family="instantid",
+        model_id="InstantX/InstantID",
+        mode="identity_preserving_candidate",
+        default_steps=30,
+        default_gpu="H100",
+        implemented=False,
+        notes="Tracked as identity-preserving candidate; remote runner is intentionally not enabled until antelopev2/model download path is decided.",
+    ),
+)
+
+
+def candidate_by_id(candidate_id: str) -> ModelCandidate:
+    for candidate in MODEL_CANDIDATES:
+        if candidate.id == candidate_id:
+            return candidate
+    known = ", ".join(candidate.id for candidate in MODEL_CANDIDATES)
+    raise ValueError(f"unknown model candidate: {candidate_id}; expected one of {known}")
+
+
+def slugify_identifier(value: str, fallback: str = "character") -> str:
+    normalized = value.strip().lower()
+    normalized = re.sub(r"[^a-z0-9_\-\u4e00-\u9fff]+", "_", normalized)
+    normalized = re.sub(r"_+", "_", normalized).strip("_-")
+    return normalized or fallback
+
+
+def project_root() -> Path:
+    return Path(__file__).resolve().parents[2]
+
+
+def default_character_package(character_id: str, display_name: str) -> dict[str, Any]:
+    return {
+        "id": character_id,
+        "name": display_name,
+        "display_name": display_name,
+        "summary": "自动化角色生成风险验证用原创角色草案。",
+        "description": f"{display_name} 是用于验证多表情虚拟角色生成流水线的原创角色。",
+        "personality": "冷静、温柔、有清晰边界。",
+        "scenario": "用户正在通过虚拟角色实验台与角色进行对话和视觉资产测试。",
+        "first_mes": "我在。现在可以开始验证角色生成流程。",
+        "alternate_greetings": ["测试频道已接入。", "角色资产验证准备完成。"],
+        "mes_example": "",
+        "creator_notes": "由自动化角色生成 spike 创建；用于技术验证，不代表最终角色设定。",
+        "tags": ["生成测试", "原创角色", "技术验证"],
+        "profile": {
+            "identity": "自动化角色生成风险验证用原创虚拟角色",
+            "core_traits": ["冷静", "温柔", "边界清晰"],
+            "relationship_to_user": "把用户当成共同验证系统的协作者",
+            "boundaries": ["不声称自己是商业 IP 角色", "不复述商业 IP 官方设定"],
+        },
+        "dialogue_style": {
+            "tone": "自然、简短、清晰",
+            "sentence_shape": "中短句",
+            "catchphrases": ["我在。"],
+        },
+        "skills": ["daily_chat", "style_guard"],
+        "voice": {"voice_id": "default", "pace": "normal", "energy": 0.5},
+        "visual": {
+            "accent": "#67e8f9",
+            "background": "#111827",
+            "background_image": f"{character_id}_spike_background",
+            "avatar": character_id,
+        },
+        "metadata": {"source": "character_generation_spike"},
+    }
+

src/character_spike/tavern_import.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from src.character_spike.schema import default_character_package, slugify_identifier
+
+
+def load_tavern_json(path: str | Path) -> dict[str, Any]:
+    raw = Path(path).read_text(encoding="utf-8-sig")
+    parsed = json.loads(raw)
+    if not isinstance(parsed, dict):
+        raise ValueError("Tavern card JSON must be an object")
+    return parsed
+
+
+def convert_tavern_card(card: dict[str, Any], forced_id: str | None = None) -> dict[str, Any]:
+    data = card.get("data") if isinstance(card.get("data"), dict) else card
+    name = str(data.get("name") or data.get("char_name") or data.get("display_name") or "Imported Character").strip()
+    character_id = slugify_identifier(forced_id or name, fallback="imported_character")
+    package = default_character_package(character_id, name)
+
+    description = _text(data.get("description") or data.get("desc"))
+    personality = _text(data.get("personality"))
+    scenario = _text(data.get("scenario"))
+    first_mes = _text(data.get("first_mes") or data.get("first_message"))
+    mes_example = _text(data.get("mes_example") or data.get("example_dialogue"))
+    creator_notes = _text(data.get("creator_notes") or data.get("creatorcomment"))
+    alternate_greetings = _list_of_text(data.get("alternate_greetings") or data.get("alternate_greeting"))
+    tags = _list_of_text(data.get("tags") or data.get("tag") or [])
+
+    if description:
+        package["description"] = description
+        package["summary"] = _summary_from_text(description)
+        package["profile"]["identity"] = _first_nonempty_line(description)
+    if personality:
+        package["personality"] = personality
+        package["profile"]["core_traits"] = _traits_from_personality(personality)
+    if scenario:
+        package["scenario"] = scenario
+        package["profile"]["relationship_to_user"] = _first_nonempty_line(scenario)
+    if first_mes:
+        package["first_mes"] = first_mes
+    if mes_example:
+        package["mes_example"] = mes_example
+    if creator_notes:
+        package["creator_notes"] = creator_notes
+    if alternate_greetings:
+        package["alternate_greetings"] = alternate_greetings
+    if tags:
+        package["tags"] = tags
+
+    character_book = _extract_character_book(card, data)
+    package["metadata"] = {
+        "source": "tavern_json",
+        "spec": card.get("spec"),
+        "spec_version": card.get("spec_version") or data.get("spec_version"),
+        "creator": data.get("creator"),
+        "character_version": data.get("character_version"),
+        "raw_extensions": data.get("extensions") if isinstance(data.get("extensions"), dict) else {},
+        "character_book": character_book,
+    }
+    package["visual"]["avatar"] = character_id
+    package["visual"]["background_image"] = f"{character_id}_spike_background"
+    return package
+
+
+def write_character_draft(package: dict[str, Any], output_dir: str | Path) -> Path:
+    out_dir = Path(output_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    path = out_dir / f"{package['id']}.json"
+    path.write_text(json.dumps(package, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    return path
+
+
+def _text(value: Any) -> str:
+    return str(value or "").strip()
+
+
+def _list_of_text(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [item.strip() for item in value.splitlines() if item.strip()]
+    if isinstance(value, list):
+        return [str(item).strip() for item in value if str(item).strip()]
+    return []
+
+
+def _summary_from_text(text: str, limit: int = 120) -> str:
+    compact = " ".join(text.split())
+    if len(compact) <= limit:
+        return compact
+    return compact[: limit - 1].rstrip() + "…"
+
+
+def _first_nonempty_line(text: str) -> str:
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped:
+            return stripped
+    return text.strip()
+
+
+def _traits_from_personality(personality: str) -> list[str]:
+    separators = ["、", "，", ",", ";", "；", "\n"]
+    values = [personality]
+    for separator in separators:
+        next_values: list[str] = []
+        for value in values:
+            next_values.extend(value.split(separator))
+        values = next_values
+    traits = [item.strip() for item in values if item.strip()]
+    return traits[:8] or ["自然", "清晰"]
+
+
+def _extract_character_book(card: dict[str, Any], data: dict[str, Any]) -> dict[str, Any] | None:
+    for source in (data, card):
+        for key in ("character_book", "world_info", "lorebook"):
+            value = source.get(key)
+            if isinstance(value, dict):
+                return value
+    extensions = data.get("extensions")
+    if isinstance(extensions, dict):
+        for key in ("character_book", "world_info", "lorebook"):
+            value = extensions.get(key)
+            if isinstance(value, dict):
+                return value
+    return None
+

tests/test_character_spike.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import json
+import unittest
+from pathlib import Path
+
+from scripts.run_character_generation_spike import _evaluate_gate
+from src.character_spike.assets import create_mock_asset_package
+from src.character_spike.schema import EXPRESSIONS, MODEL_CANDIDATES, candidate_by_id
+from src.character_spike.tavern_import import convert_tavern_card, load_tavern_json, write_character_draft
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+TMP_ROOT = PROJECT_ROOT / ".tmp" / "tests"
+
+
+class CharacterSpikeTests(unittest.TestCase):
+    def test_candidate_registry_tracks_required_models(self) -> None:
+        ids = {candidate.id for candidate in MODEL_CANDIDATES}
+        self.assertIn("flux_schnell", ids)
+        self.assertIn("qwen_image", ids)
+        self.assertIn("qwen_image_edit", ids)
+        self.assertIn("qwen_controlnet_union", ids)
+        self.assertIn("instantid_sdxl", ids)
+        self.assertFalse(candidate_by_id("instantid_sdxl").implemented)
+
+    def test_tavern_json_import_maps_fields_to_draft_package(self) -> None:
+        card = {
+            "spec": "chara_card_v2",
+            "spec_version": "2.0",
+            "data": {
+                "name": "测试角色",
+                "description": "一名用于导入验证的角色。\n第二行会被保留。",
+                "personality": "冷静、敏锐，温柔",
+                "scenario": "用户正在测试角色卡导入。",
+                "first_mes": "你好，我已经导入完成。",
+                "alternate_greetings": ["备用开场 A", "备用开场 B"],
+                "creator_notes": "只用于测试。",
+                "tags": ["测试", "导入"],
+                "character_book": {"entries": [{"keys": ["地点"], "content": "测试空间"}]},
+            },
+        }
+
+        package = convert_tavern_card(card)
+
+        self.assertEqual(package["display_name"], "测试角色")
+        self.assertEqual(package["first_mes"], "你好，我已经导入完成。")
+        self.assertEqual(package["alternate_greetings"], ["备用开场 A", "备用开场 B"])
+        self.assertEqual(package["profile"]["core_traits"][:3], ["冷静", "敏锐", "温柔"])
+        self.assertEqual(package["metadata"]["spec"], "chara_card_v2")
+        self.assertEqual(package["metadata"]["character_book"]["entries"][0]["content"], "测试空间")
+
+    def test_load_and_write_tavern_draft(self) -> None:
+        root = TMP_ROOT / "tavern_draft"
+        root.mkdir(parents=True, exist_ok=True)
+        source = root / "card.json"
+        source.write_text(json.dumps({"name": "Plain Card", "first_mes": "Hi"}), encoding="utf-8")
+
+        package = convert_tavern_card(load_tavern_json(source), forced_id="plain_card")
+        path = write_character_draft(package, root / "characters")
+
+        self.assertTrue(path.exists())
+        parsed = json.loads(path.read_text(encoding="utf-8"))
+        self.assertEqual(parsed["id"], "plain_card")
+        self.assertEqual(parsed["first_mes"], "Hi")
+
+    def test_mock_asset_package_creates_manifest_grid_and_assets(self) -> None:
+        output_root = TMP_ROOT / "mock_assets"
+        output_root.mkdir(parents=True, exist_ok=True)
+        manifest = create_mock_asset_package(
+            character_id="spike_test",
+            display_name="星核",
+            output_root=output_root,
+            seed=7,
+        )
+        run_dir = Path(manifest["paths"]["run_dir"])
+
+        self.assertEqual(len(manifest["assets"]), len(EXPRESSIONS))
+        self.assertTrue((run_dir / "generated" / "manifest.json").exists())
+        self.assertTrue((run_dir / "generated" / "report.md").exists())
+        self.assertTrue((run_dir / "generated" / "asset_grid.png").exists())
+        for expression in EXPRESSIONS:
+            self.assertTrue((run_dir / "assets" / "characters" / "spike_test" / f"{expression}.png").exists())
+
+    def test_gate_requires_timing_and_usable_assets(self) -> None:
+        manifest = {
+            "assets": [{"usable": True} for _ in range(6)],
+            "model_results": [
+                {
+                    "benchmark_case": "warm_four",
+                    "status": "ok",
+                    "loaded_before": True,
+                    "duration_seconds": 55.0,
+                },
+                {
+                    "benchmark_case": "eight_expression_total",
+                    "status": "ok",
+                    "duration_seconds": 170.0,
+                },
+            ],
+        }
+        gate = _evaluate_gate(manifest)
+        self.assertTrue(gate["ready_for_character_workshop"])
+
+        manifest["model_results"][1]["duration_seconds"] = 240.0
+        gate = _evaluate_gate(manifest)
+        self.assertFalse(gate["ready_for_character_workshop"])
+        self.assertIn("导入角色卡", gate["fallback_recommendation"])
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_character_workshop.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+import io
+import json
+import os
+import unittest
+import uuid
+from pathlib import Path
+
+from PIL import Image, ImageDraw
+
+import src.character_workshop as workshop
+from src.character_registry import load_user_character_packages
+from src.model_status import ModelStatus, statuses_markdown
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+TMP_ROOT = PROJECT_ROOT / ".tmp" / "workshop_tests"
+
+
+class CharacterWorkshopTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.test_root = TMP_ROOT / f"{self._testMethodName}_{uuid.uuid4().hex}"
+        self.test_root.mkdir(parents=True, exist_ok=True)
+        self.old_roots = (
+            workshop.WORKSHOP_ROOT,
+            workshop.INSTALLED_CHARACTER_ROOT,
+            workshop.INSTALLED_BACKGROUND_ROOT,
+            workshop.INSTALLED_CHARACTER_JSON_ROOT,
+        )
+        self.old_data_root = os.environ.get("VC_DATA_ROOT")
+        workshop.WORKSHOP_ROOT = self.test_root / "generated"
+        workshop.INSTALLED_CHARACTER_ROOT = self.test_root / "installed" / "assets" / "characters"
+        workshop.INSTALLED_BACKGROUND_ROOT = self.test_root / "installed" / "assets" / "backgrounds"
+        workshop.INSTALLED_CHARACTER_JSON_ROOT = self.test_root / "installed" / "characters"
+        os.environ["VC_DATA_ROOT"] = str(self.test_root / "data")
+        workshop.set_remote_probe_for_tests(self._fake_probe)
+        self.probe_calls = []
+
+    def tearDown(self) -> None:
+        (
+            workshop.WORKSHOP_ROOT,
+            workshop.INSTALLED_CHARACTER_ROOT,
+            workshop.INSTALLED_BACKGROUND_ROOT,
+            workshop.INSTALLED_CHARACTER_JSON_ROOT,
+        ) = self.old_roots
+        if self.old_data_root is None:
+            os.environ.pop("VC_DATA_ROOT", None)
+        else:
+            os.environ["VC_DATA_ROOT"] = self.old_data_root
+        workshop.set_remote_probe_for_tests(None)
+
+    def test_form_to_installable_character_package(self) -> None:
+        draft = workshop.create_draft_from_form(
+            display_name="工坊角色",
+            description="银白短发的原创角色。",
+            personality="冷静、温柔",
+            scenario="通讯端测试。",
+            first_mes="我在。",
+            tags="测试,工坊",
+        )
+        state = workshop.create_initial_state(draft)
+        state = workshop.generate_main_candidates(state)
+        self.assertEqual(len(state["main_candidates"]), 4)
+
+        state = workshop.select_main_candidate(state, 2)
+        self.assertEqual(state["selected_candidate_index"], 2)
+
+        state = workshop.generate_expression_pack(state)
+        self.assertEqual(set(state["expression_assets"]), set(workshop.EXPRESSIONS))
+
+        state = workshop.generate_background(state)
+        self.assertTrue(Path(state["background_asset"]).exists())
+
+        state = workshop.matte_and_package_assets(state, mode="fallback")
+        package_dir = Path(state["package_dir"])
+        self.assertTrue((package_dir / "generated" / "asset_grid.png").exists())
+        self.assertTrue((package_dir / "generated" / "stage_smoke.html").exists())
+
+        state = workshop.install_character_package(state)
+        character_id = state["installed_character_id"]
+        self.assertTrue((workshop.INSTALLED_CHARACTER_JSON_ROOT / f"{character_id}.json").exists())
+        self.assertTrue((workshop.INSTALLED_BACKGROUND_ROOT / f"{character_id}_background.png").exists())
+        for expression in workshop.EXPRESSIONS:
+            self.assertTrue((workshop.INSTALLED_CHARACTER_ROOT / character_id / f"{expression}.png").exists())
+
+    def test_user_character_loader_reads_installed_json(self) -> None:
+        root = TMP_ROOT / "registry"
+        root.mkdir(parents=True, exist_ok=True)
+        path = root / "loaded_character.json"
+        path.write_text(json.dumps({"id": "loaded_character", "display_name": "已加载角色"}), encoding="utf-8")
+
+        packages = load_user_character_packages(root)
+
+        self.assertEqual(packages["loaded_character"]["display_name"], "已加载角色")
+
+    def test_image_generation_status_markdown(self) -> None:
+        html = statuses_markdown(
+            [
+                ModelStatus(
+                    "image_generation",
+                    "sleeping",
+                    "已休眠",
+                    url="modal_apps/modal_character_spike.py",
+                    message="Modal 图像生成服务可能已休眠或正在冷启动，请等待容器启动和模型载入后重试。",
+                )
+            ]
+        )
+
+        self.assertIn("Image Generation", html)
+        self.assertIn("等待容器启动", html)
+
+    def test_logged_in_runs_are_user_scoped_and_loadable(self) -> None:
+        alice = workshop.get_current_user(_Profile("alice", "Alice"))
+        bob = workshop.get_current_user(_Profile("bob", "Bob"))
+
+        alice_state = workshop.create_initial_state(
+            workshop.create_draft_from_form(
+                display_name="Alice 角色",
+                description="测试。",
+                personality="冷静",
+                scenario="测试。",
+                first_mes="你好。",
+            ),
+            user=alice,
+        )
+        bob_state = workshop.create_initial_state(
+            workshop.create_draft_from_form(
+                display_name="Bob 角色",
+                description="测试。",
+                personality="冷静",
+                scenario="测试。",
+                first_mes="你好。",
+            ),
+            user=bob,
+        )
+
+        alice_runs = workshop.list_user_workshop_runs(alice)
+        bob_runs = workshop.list_user_workshop_runs(bob)
+
+        self.assertEqual(len(alice_runs), 1)
+        self.assertEqual(len(bob_runs), 1)
+        self.assertIn("Alice 角色", alice_runs[0][0])
+        self.assertIn("Bob 角色", bob_runs[0][0])
+        self.assertNotEqual(alice_state["run_dir"], bob_state["run_dir"])
+        loaded = workshop.load_workshop_run(alice_runs[0][1], user=alice)
+        self.assertEqual(loaded["character_id"], alice_state["character_id"])
+        with self.assertRaises(ValueError):
+            workshop.load_workshop_run(alice_runs[0][1], user=bob)
+
+    def test_resume_main_candidates_from_manifest(self) -> None:
+        user = workshop.get_current_user(_Profile("alice", "Alice"))
+        state = workshop.create_initial_state(
+            workshop.create_draft_from_form(
+                display_name="恢复角色",
+                description="测试。",
+                personality="冷静",
+                scenario="测试。",
+                first_mes="你好。",
+            ),
+            user=user,
+        )
+        state = workshop.generate_main_candidates(state)
+
+        loaded = workshop.load_workshop_run(state["run_dir"], user=user)
+
+        self.assertEqual(len(loaded["main_candidates"]), 4)
+        self.assertEqual(loaded["selected_candidate_index"], 0)
+
+    def test_partial_expression_pack_only_generates_missing_slots(self) -> None:
+        user = workshop.get_current_user(_Profile("alice", "Alice"))
+        state = workshop.create_initial_state(
+            workshop.create_draft_from_form(
+                display_name="续跑角色",
+                description="测试。",
+                personality="冷静",
+                scenario="测试。",
+                first_mes="你好。",
+            ),
+            user=user,
+        )
+        run_dir = Path(state["run_dir"])
+        idle_dir = run_dir / "expressions_raw" / "idle"
+        idle_dir.mkdir(parents=True, exist_ok=True)
+        idle_path = idle_dir / "00.png"
+        idle_path.write_bytes(_png_bytes(0))
+        manifest = json.loads((run_dir / "manifest.json").read_text(encoding="utf-8"))
+        manifest["expression_assets_raw"] = {"idle": str(idle_path.relative_to(run_dir))}
+        (run_dir / "manifest.json").write_text(json.dumps(manifest, ensure_ascii=False), encoding="utf-8")
+
+        self.probe_calls.clear()
+        state = workshop.load_workshop_run(run_dir, user=user)
+        state = workshop.generate_expression_pack(state)
+
+        self.assertEqual(set(state["expression_assets"]), set(workshop.EXPRESSIONS))
+        self.assertEqual(len(self.probe_calls), len(workshop.EXPRESSIONS) - 1)
+
+    def test_stats_event_summary(self) -> None:
+        user = workshop.get_current_user(_Profile("alice", "Alice"))
+
+        workshop.record_workshop_event(user, "generate_main_candidates", {"stage": "main_candidates", "success": True, "duration_seconds": 1.2, "character_id": "x"})
+        workshop.record_workshop_event(user, "generate_expression_pack", {"stage": "assets_ready", "success": False, "failure_reason": "boom", "character_id": "x"})
+        summary = workshop.summarize_workshop_stats()
+
+        self.assertEqual(summary["events"], 2)
+        self.assertEqual(summary["users"], 1)
+        self.assertEqual(summary["failures_by_stage"]["assets_ready"], 1)
+
+    def _fake_probe(self, **kwargs):
+        self.probe_calls.append(dict(kwargs))
+        batch_size = int(kwargs.get("batch_size", 1))
+        images = [_png_bytes(index) for index in range(batch_size)]
+        return {
+            "candidate_id": kwargs.get("candidate_id", "qwen_image"),
+            "status": "ok",
+            "image_count": batch_size,
+            "duration_seconds": 0.01,
+            "seed": kwargs.get("seed"),
+            "images": images,
+        }
+
+
+def _png_bytes(index: int) -> bytes:
+    image = Image.new("RGB", (256, 384), (238, 246, 248))
+    draw = ImageDraw.Draw(image)
+    accent = [(45, 212, 191), (96, 165, 250), (244, 114, 182), (250, 204, 21)][index % 4]
+    draw.ellipse((76, 36, 180, 150), fill=(245, 222, 214))
+    draw.rectangle((84, 150, 172, 330), fill=(35, 45, 60))
+    draw.rectangle((112, 166, 144, 310), fill=accent)
+    buffer = io.BytesIO()
+    image.save(buffer, format="PNG")
+    return buffer.getvalue()
+
+
+class _Profile:
+    def __init__(self, username: str, name: str):
+        self.username = username
+        self.name = name
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_dialogue_engine.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+from src import dialogue_engine
+
+
+class DialogueEngineMultimodalTests(unittest.TestCase):
+    def test_build_user_content_adds_image_url(self):
+        with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as handle:
+            handle.write(b"\x89PNG\r\n\x1a\n")
+            image_path = Path(handle.name)
+
+        try:
+            content = dialogue_engine._build_user_content(
+                "看一下这张图",
+                {"images": [{"path": str(image_path)}]},
+            )
+        finally:
+            image_path.unlink(missing_ok=True)
+
+        self.assertIsInstance(content, list)
+        self.assertEqual(content[0], {"type": "text", "text": "看一下这张图"})
+        self.assertEqual(content[1]["type"], "image_url")
+        self.assertTrue(content[1]["image_url"]["url"].startswith("data:image/png;base64,"))
+
+    def test_build_user_content_ignores_audio_attachment(self):
+        content = dialogue_engine._build_user_content(
+            "继续文字对话",
+            {"images": [], "audio": [{"path": "ignored.wav"}]},
+        )
+
+        self.assertEqual(content, [{"type": "text", "text": "继续文字对话"}])
+
+    def test_vllm_failure_returns_regular_error_without_audio_fallback(self):
+        class FailingClient:
+            def __init__(self, *args, **kwargs):
+                pass
+
+            def __enter__(self):
+                return self
+
+            def __exit__(self, *args):
+                return False
+
+            def stream(self, *args, **kwargs):
+                raise RuntimeError("400 Bad Request")
+
+        with patch.dict("os.environ", {"VC_VLLM_RETRIES": "1"}, clear=False):
+            with patch("httpx.Client", FailingClient):
+                events = list(
+                    dialogue_engine._stream_vllm_reply(
+                        "https://example.test",
+                        "你好",
+                        [],
+                        {"character": {"voice": {}}},
+                        {"images": []},
+                        {"enabled": False},
+                    )
+                )
+
+        errors = [event["message"] for event in events if event.get("type") == "error"]
+        self.assertTrue(any("Modal vLLM 调用失败" in message for message in errors))
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_model_status.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import os
+import unittest
+
+from src.model_status import ModelStatus, statuses_with_llm_status, warm_llm_model
+
+
+class ModelStatusTests(unittest.TestCase):
+    def test_warm_llm_model_skips_remote_when_mock_enabled(self) -> None:
+        old_value = os.environ.get("VC_USE_MOCK")
+        os.environ["VC_USE_MOCK"] = "1"
+        try:
+            status = warm_llm_model(timeout_s=0.01)
+        finally:
+            if old_value is None:
+                os.environ.pop("VC_USE_MOCK", None)
+            else:
+                os.environ["VC_USE_MOCK"] = old_value
+
+        self.assertEqual(status.kind, "llm")
+        self.assertEqual(status.state, "mock")
+        self.assertIn("mock", status.message.lower())
+
+    def test_statuses_with_llm_status_replaces_initial_llm_row(self) -> None:
+        llm_status = ModelStatus("llm", "loading", "载入中", message="正在启动主模型")
+
+        statuses = statuses_with_llm_status(llm_status)
+
+        self.assertGreaterEqual(len(statuses), 1)
+        self.assertEqual(statuses[0], llm_status)
+        self.assertEqual(statuses[0].message, "正在启动主模型")
+
+
+if __name__ == "__main__":
+    unittest.main()