# DreamWeaver 求职版 Demo 包装

这份文档用于演示前 5 分钟快速准备，也可以作为面试官追问时的项目导航。

---

## 1. 一句话定位

DreamWeaver 是面向 3-8 岁亲子场景的个性化 AI 绘本与陪伴式讲述产品。它把孩子档案、故事宇宙、故事生成、绘本插图、语音缓存、阅读事件和成长记忆串成一个可恢复的阅读闭环。

---

## 2. 演示前检查

```bash
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`

---

## 3. 主演示路径

1. 使用本地登录进入用户端。
2. 创建普通故事，说明主内容优先可读。
3. 打开故事详情页，展示 `partial_ready`、封面补全、音频缓存状态和生成轨迹。
4. 补全封面或音频，说明资产失败不会覆盖正文。
5. 创建绘本，进入绘本阅读器。
6. 刷新页面或重新进入绘本，说明按 ID 恢复和阅读位置恢复。
7. 回到故事库，展示跨故事 Provider 运营摘要。
8. 进入 Voice Studio，演示文本 fallback / 上传语音 / 保存为 Story，说明它是 Phase A Alpha。
9. 打开管理端 Provider 摘要，切到“语音识别”，展示 ASR 调用、失败原因和语音会话/上传回合。
10. 打开孩子时间线，展示阅读事件和记忆沉淀。

---

## 4. 面试讲解锚点

- **产品判断**：求职版不追求功能越多，而是围绕亲子阅读闭环收敛。
- **AI 不确定性处理**：主内容和资产拆开，图片/音频失败不阻塞阅读。
- **Provider 产品化**：用户看到稳定能力，系统内部用 Capability / Provider / Adapter / Routing Policy 管供应链。
- **可观测性**：generation job/event 让生成过程、失败恢复和 Provider 成本可解释。
- **语音共创边界**：Voice Studio 是 Phase A Alpha，验证回合式共创、文本降级、上传转写、TTS 回复和保存为 Story，不夸大成实时语音最终形态。
- **可继续生产化**：统一生成已迁移到 worker，前端轮询、任务事件模型、取消/重试队列、管理台当前环境 dashboard 和 ASR 摘要已打通；下一步是真实 ASR 环境验收、跨环境汇聚、断点续跑和更完整监控。

---

## 5. 失败预案

| 风险 | 现场处理 |
| --- | --- |
| 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 汇聚、断点续跑、监控告警和密钥治理 |