Implement unified story generation flow

docs/planning/demo-package.md

@@ -17,16 +17,63 @@ docker compose up -d --build
 ./scripts/demo_smoke.sh
 ```
 
-需要验证语音链路时：
+需要验证故事 TTS 音频时：
 
 ```bash
 SMOKE_AUDIO=1 ./scripts/demo_smoke.sh
 ```
 
+需要验证 Voice Studio Alpha 时：
+
+```bash
+SMOKE_VOICE=1 ./scripts/demo_smoke.sh
+```
+
+需要验证真实 OpenAI ASR Key 环境时：
+
+```bash
+SMOKE_REAL_ASR=1 ./scripts/demo_smoke.sh
+```
+
+`SMOKE_REAL_ASR=1` 会自动包含 Voice Studio Alpha smoke。Docker 环境下先在 `backend/.env` 确认：
+
+```env
+ASR_PROVIDERS=["openai_asr", "demo"]
+OPENAI_API_KEY=sk-...
+OPENAI_API_BASE=
+VOICE_TRANSCRIPTION_MODE=provider
+VOICE_TRANSCRIPTION_MODEL=gpt-4o-mini-transcribe
+VOICE_TRANSCRIPTION_LANGUAGE=zh
+```
+
+改完环境变量后重启 backend/worker；如果通过 Admin Provider 表配置了 ASR，先执行 `curl -u admin:admin -X POST http://localhost:52800/admin/providers/reload`，再重启 API 容器/进程。macOS 会自动用 `say`/`afconvert` 生成短音频，其他环境可传 `REAL_ASR_AUDIO_FILE=/path/to/sample.m4a`。
+
+当 Docker Hub 网络暂时不可用时，当前 Docker 构建支持通过根 `.env` 覆盖基础镜像与 npm registry。当前机器已配置：
+
+```bash
+PYTHON_BASE_IMAGE=docker.m.daocloud.io/library/python:3.11-slim
+NODE_BASE_IMAGE=docker.1ms.run/library/node:18-alpine
+NGINX_BASE_IMAGE=docker.m.daocloud.io/library/nginx:alpine
+NPM_REGISTRY=https://registry.npmmirror.com
+```
+
+如果需要绕过 Docker、直接验证当前源码，也可以本机启动当前源码 API/admin/worker，并覆盖登录回跳地址后运行：
+
+```bash
+APP_URL=http://localhost:53000 \
+BACKEND_URL=http://localhost:53000 \
+ADMIN_BACKEND_URL=http://localhost:53800 \
+DEV_SIGNIN_URL='http://localhost:53000/auth/dev/signin?next=http://localhost:53000/auth/session' \
+SMOKE_VOICE=1 ./scripts/demo_smoke.sh
+```
+
+当前注意：2026-05-06 外部 Registry 阻塞已修复；当前代码 `docker compose up -d --build` 已通过，重建后 `SMOKE_VOICE=1` 也已通过。
+
 演示入口：
 
 - 用户端：`http://localhost:52080`
 - 本地登录：`http://localhost:52080/auth/dev/signin`
+- 语音共创：`http://localhost:52080/voice-studio`
 - 管理端：`http://localhost:52888`
 - 后端健康：`http://localhost:52000/health`
 
@@ -41,7 +88,9 @@ SMOKE_AUDIO=1 ./scripts/demo_smoke.sh
 5. 创建绘本，进入绘本阅读器。
 6. 刷新页面或重新进入绘本，说明按 ID 恢复和阅读位置恢复。
 7. 回到故事库，展示跨故事 Provider 运营摘要。
-8. 打开孩子时间线，展示阅读事件和记忆沉淀。
+8. 进入 Voice Studio，演示文本 fallback / 上传语音 / 保存为 Story，说明它是 Phase A Alpha。
+9. 打开管理端 Provider 摘要，切到“语音识别”，展示 ASR 调用、失败原因和语音会话/上传回合。
+10. 打开孩子时间线，展示阅读事件和记忆沉淀。
 
 ---
 
@@ -51,7 +100,8 @@ SMOKE_AUDIO=1 ./scripts/demo_smoke.sh
 - **AI 不确定性处理**：主内容和资产拆开，图片/音频失败不阻塞阅读。
 - **Provider 产品化**：用户看到稳定能力，系统内部用 Capability / Provider / Adapter / Routing Policy 管供应链。
 - **可观测性**：generation job/event 让生成过程、失败恢复和 Provider 成本可解释。
-- **可继续生产化**：统一生成已迁移到 worker，前端轮询、任务事件模型、取消/重试队列和管理台当前环境 dashboard 也已打通，下一步是补跨环境汇聚、断点续跑和更完整监控。
+- **语音共创边界**：Voice Studio 是 Phase A Alpha，验证回合式共创、文本降级、上传转写、TTS 回复和保存为 Story，不夸大成实时语音最终形态。
+- **可继续生产化**：统一生成已迁移到 worker，前端轮询、任务事件模型、取消/重试队列、管理台当前环境 dashboard 和 ASR 摘要已打通；下一步是真实 ASR 环境验收、跨环境汇聚、断点续跑和更完整监控。
 
 ---
 
@@ -61,6 +111,9 @@ SMOKE_AUDIO=1 ./scripts/demo_smoke.sh
 | --- | --- |
 | TTS 网络失败 | 说明音频是可恢复资产，展示缓存状态或跳过语音 |
 | 图片生成失败 | 展示 `degraded_completed` 与资源重试 |
+| 录音或 ASR 不稳定 | 切到文本 fallback，说明 Alpha 已保留降级路径 |
+| 真实 ASR Key 验收失败 | 看 smoke 输出的上传响应、Voice Session 事件和 Admin ASR failure reasons；优先排查 key 未加载、401/403、429/额度、model_not_found、`OPENAI_API_BASE` 和音频格式 |
+| Docker Hub 拉取超时 | 使用根 `.env` 的基础镜像覆盖与 npm registry 覆盖，直接重建当前 Docker 栈 |
 | Docker 冷启动慢 | 演示前先跑 smoke 并保持容器运行 |
 | Provider 追问过深 | 回到 Capability / Provider / Adapter / Routing Policy 四层解释 |
 | 生产化追问 | 说明下一步是跨环境 Provider 汇聚、断点续跑、监控告警和密钥治理 |