DreamWeaver/dreamweaver
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7ebdfb2582b05c80e78152c98d437aa4131f2b06
dreamweaver/docs/planning/demo-checklist.md

9.7 KiB
Raw Blame History

DreamWeaver 求职演示 Checklist

目标: 演示前用 5-10 分钟确认本地 Docker 环境、核心生成链路和讲解材料处于可展示状态。

当前演示口径（2026-05-06）: 主生成链路可作为稳定主线展示；语音共创是 Phase A Alpha，可演示回合式共创、文本降级、上传转写、观测指标和保存为 Story。管理端已能看到 ASR 维度运营摘要。外部 Registry 阻塞已通过可配置基础镜像与 npm registry 修复；当前代码 docker compose up -d --build 和 SMOKE_VOICE=1 均已通过。

1. 演示前准备

环境检查

  • 已拉取最新 main
  • backend/.env 存在，且不包含需要提交的真实密钥
  • DEBUG=true
  • ENABLE_DEMO_PROVIDERS=true
  • SECRET_KEY 已设置
  • Docker Desktop 正常运行

启动命令

docker compose up -d --build
docker compose ps

入口

2. 自动 smoke 检查

默认检查健康、登录、普通故事、绘本、图片补全和 Provider 能力分层：

./scripts/demo_smoke.sh

需要检查 TTS 音频时：

SMOKE_AUDIO=1 ./scripts/demo_smoke.sh

需要检查语音共创 Alpha 时：

SMOKE_VOICE=1 ./scripts/demo_smoke.sh

需要检查真实 OpenAI ASR Key 环境时：

SMOKE_REAL_ASR=1 ./scripts/demo_smoke.sh

需要同时检查 TTS 和语音共创时：

SMOKE_AUDIO=1 SMOKE_VOICE=1 ./scripts/demo_smoke.sh

通过标准：

  • backend health 返回 ok
  • admin-backend health 返回 ok
  • dev login 能拿到 session
  • /api/generations 能生成普通故事
  • 普通故事生成响应返回 generation_job_id，且 job 事件可查询
  • 普通故事 provider stats 返回成功率、耗时和成本字段
  • 普通故事封面 retry 后 image_status=ready
  • 故事详情页能看到生成轨迹和 Provider 调用结果
  • 故事库能看到跨故事 Provider 运营摘要
  • /api/generations 能生成绘本
  • 绘本生成响应返回 generation_job_id，且 story job history 可查询
  • 绘本 provider stats 返回成功率、耗时和成本字段
  • 绘本图片 retry 后 image_status=ready
  • 绘本阅读页能看到生成轨迹和资源重试历史
  • /admin/providers/capabilities 返回 text/image/tts/storybook/asr
  • /api/audio/{story_id}/status 能查询音频缓存状态且不触发生成
  • 如果启用 SMOKE_AUDIO=1，音频 retry 后 audio_status=ready
  • 如果启用 SMOKE_VOICE=1，语音共创会话可完成文本 fallback、上传回合、analytics 和 finalize 到 Story
  • 如果启用 SMOKE_VOICE=1，analytics 返回输入构成、语音时长、Provider 分布、ASR/TTS 成功率和低置信度确认率
  • 如果启用 SMOKE_VOICE=1，analytics 支持按 provider 和 session_status 筛选
  • 如果启用 SMOKE_REAL_ASR=1，上传回合返回 transcription_provider=openai_asr，转写文本非空
  • 如果启用 SMOKE_REAL_ASR=1，/api/voice-sessions/analytics?provider=openai_asr 能看到上传回合
  • Admin Provider analytics 在 capability=asr 下能看到语音会话数、上传回合数、ASR 成功/失败和失败原因
  • 真实 ASR 环境失败时，脚本输出包含上传响应、Voice Session 事件和 Admin ASR failure reasons
  • 验证结果已记录到 docs/planning/demo-validation-log.md

真实 ASR 环境变量最小集：

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/.env 后重启 backend/worker。若在 Admin Provider 表里改过 ASR 配置，先 curl -u admin:admin -X POST http://localhost:52800/admin/providers/reload，再重启 API 容器/进程，避免运行中缓存仍指向旧 provider。

真实 ASR 常见失败口径：

  • OPENAI_API_KEY 未配置：容器或本机 API 没读到 key。
  • HTTP 401/403：key 错误、项目权限或网关鉴权失败。
  • HTTP 429 / insufficient_quota：额度或限流问题。
  • model_not_found：VOICE_TRANSCRIPTION_MODEL 当前 key 不可用，先换回 gpt-4o-mini-transcribe。
  • 网络连接失败：检查代理、DNS、OPENAI_API_BASE 是否必须带 /v1。
  • 音频格式失败：传 REAL_ASR_AUDIO_FILE=/path/to/sample.m4a 换一段真实短音频复测。

3. 手动演示路径

路径 A: 普通故事

  1. 打开用户端。
  2. 使用本地登录。
  3. 创建普通故事：
    • 关键词：月亮船，小狐狸，学会道歉
    • 教育主题：真诚表达
  4. 进入故事详情页。
  5. 展示：
    • 标题和正文
    • 封面状态
    • 音频状态
    • 音频缓存大小与更新时间
    • 资产补全/重试入口
  6. 点击音频播放，说明音频缓存复用；必要时清理缓存后重新生成。

路径 B: 绘本

  1. 创建绘本：
    • 关键词：彩虹邮局，小刺猬，练习说谢谢
    • 教育主题：感恩表达
  2. 进入绘本阅读器。
  3. 翻页展示多页文本和插图。
  4. 刷新页面或复制 URL，说明绘本已经支持按 ID 恢复。

路径 C: Admin/Provider

  1. 打开 Admin。
  2. 说明管理端不是用户主链路，而是产品拥有者维护供应链路的辅助能力。
  3. 通过接口或页面说明：
    • Capability: text/image/tts/storybook/asr
    • Provider: 具体供应商配置
    • Adapter: API 调用实现
    • Routing Policy: 优先级/成本/延迟/轮询
  4. 切到“语音识别”能力，说明 Voice Studio 上传转写的 ASR 调用已进入管理端运营摘要，可看语音会话、上传回合、失败原因和成本归因。

路径 D: 语音共创 Alpha

  1. 打开用户端并进入“语音共创”。
  2. 创建一个新会话，先使用文本 fallback 快速演示：
    • 首轮：我想听一个小熊和星星一起找家的故事
    • 修正：不要让小熊害怕，让月亮姐姐帮它
  3. 展示每轮内容：
    • 用户表达 / 系统理解
    • 系统文字回应
    • TTS 语音回应状态
    • 最近事件和待处理提示
  4. 演示低置信度确认：说明系统会提示“本轮系统理解为”，家长可选择继续、重说或改成文本。
  5. 点击结束并保存，确认正式 Story 进入故事库。
  6. 打开生成轨迹，说明语音共创 finalize 后的封面资产补全已经接回统一 generation job。
  7. 回到 Admin 的语音识别摘要，说明 Alpha 阶段保留 demo fallback，同时为真实 ASR Provider 验收预留运营视图。

4. 3 分钟讲解结构

详细稿见 docs/planning/interview-pitch.md。现场建议背结构，不逐字背。

0:00 - 0:40 产品定位

DreamWeaver 是面向 3-8 岁亲子场景的个性化 AI 绘本与陪伴式讲述产品。它不是只生成一次性故事，而是围绕孩子档案、成长主题和故事宇宙，生成可回看、可补全、可聆听的故事体验。

0:40 - 1:30 用户闭环

用户选择孩子档案，输入主题或教育目标，生成故事或绘本。主内容先可读，封面、插图、语音作为资产补全。即使图片或音频失败，故事仍然可读，并且可以后续重试。

1:30 - 2:20 系统设计

系统收敛到统一 Generation Workflow：上下文准备、主记录保存、资产补全、状态回写和后处理。Provider 体系拆成 Capability、Provider、Adapter、Routing Policy，用户不需要理解模型供应商，只感知稳定的产品能力。

2:20 - 3:00 取舍与下一步

求职版优先稳定闭环和可解释性，不做支付、多租户和复杂监控。现在 job/event 已能查询 workflow、资产补全、provider 调用轨迹和聚合指标，统一生成已迁移到后台 worker，取消/重试队列也已打通；Voice Studio 已进入 Phase A Alpha，可演示回合式共创和保存为 Story；用户端可看跨故事运营摘要，管理端可看当前环境跨用户 Provider dashboard 和 ASR 摘要。下一步应补真实 ASR Key 环境验收、跨环境 Provider 汇聚、断点续跑和更完整监控。

5. 风险预案

风险 现场处理
网络导致 TTS 失败 说明音频是可恢复资产，不阻塞故事阅读；使用已缓存样本或跳过 TTS
图片 provider 未补全 展示 partial ready，说明主内容已可读、资产可稍后补全
图片 provider 失败 展示 degraded completed 与 retry 机制
录音或 ASR 不稳定 切到文本 fallback，说明 Alpha 阶段已保留降级路径
语音共创低置信度卡住 使用“按这个理解继续”或“改成文本输入”完成本轮
Docker Hub 拉取超时 当前 Dockerfile/Compose 支持基础镜像覆盖；本机 .env 已配置代理源，可直接 docker compose up -d --build
Docker 冷启动慢 演示前提前运行 smoke 脚本并保持容器运行
Admin 页面不适合主展示 只用 Provider 分层说明辅助讲系统设计
面试官追问生产部署 明确当前是求职版 MVP，本轮重点是产品闭环和系统边界

6. 演示完成标准

  • 面试官能在 30 秒内理解产品定位。
  • 能现场看到普通故事和绘本结果。
  • 能解释失败降级和资产重试。
  • 能解释为什么 Provider 分层是产品设计，而不是单纯技术炫技。
  • 能说明语音共创当前是 Phase A Alpha，而不是实时语音最终形态。
  • 能说明下一步计划，而不是让项目停在 demo。
Reference in New Issue View Git Blame Copy Permalink