Implement unified story generation flow
This commit is contained in:
@@ -2,6 +2,8 @@
|
||||
|
||||
**目标**: 演示前用 5-10 分钟确认本地 Docker 环境、核心生成链路和讲解材料处于可展示状态。
|
||||
|
||||
**当前演示口径（2026-05-06）**: 主生成链路可作为稳定主线展示；语音共创是 Phase A Alpha，可演示回合式共创、文本降级、上传转写、观测指标和保存为 Story。管理端已能看到 ASR 维度运营摘要。外部 Registry 阻塞已通过可配置基础镜像与 npm registry 修复；当前代码 `docker compose up -d --build` 和 `SMOKE_VOICE=1` 均已通过。
|
||||
|
||||
---
|
||||
|
||||
## 1. 演示前准备
|
||||
@@ -53,6 +55,12 @@ SMOKE_AUDIO=1 ./scripts/demo_smoke.sh
|
||||
SMOKE_VOICE=1 ./scripts/demo_smoke.sh
|
||||
```
|
||||
|
||||
需要检查真实 OpenAI ASR Key 环境时：
|
||||
|
||||
```bash
|
||||
SMOKE_REAL_ASR=1 ./scripts/demo_smoke.sh
|
||||
```
|
||||
|
||||
需要同时检查 TTS 和语音共创时：
|
||||
|
||||
```bash
|
||||
@@ -81,8 +89,34 @@ SMOKE_AUDIO=1 SMOKE_VOICE=1 ./scripts/demo_smoke.sh
|
||||
- [ ] 如果启用 `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 环境变量最小集：
|
||||
|
||||
```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/.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. 手动演示路径
|
||||
@@ -121,6 +155,7 @@ SMOKE_AUDIO=1 SMOKE_VOICE=1 ./scripts/demo_smoke.sh
|
||||
- Provider: 具体供应商配置
|
||||
- Adapter: API 调用实现
|
||||
- Routing Policy: 优先级/成本/延迟/轮询
|
||||
4. 切到“语音识别”能力，说明 Voice Studio 上传转写的 ASR 调用已进入管理端运营摘要，可看语音会话、上传回合、失败原因和成本归因。
|
||||
|
||||
### 路径 D: 语音共创 Alpha
|
||||
|
||||
@@ -136,6 +171,7 @@ SMOKE_AUDIO=1 SMOKE_VOICE=1 ./scripts/demo_smoke.sh
|
||||
4. 演示低置信度确认：说明系统会提示“本轮系统理解为”，家长可选择继续、重说或改成文本。
|
||||
5. 点击结束并保存，确认正式 Story 进入故事库。
|
||||
6. 打开生成轨迹，说明语音共创 finalize 后的封面资产补全已经接回统一 generation job。
|
||||
7. 回到 Admin 的语音识别摘要，说明 Alpha 阶段保留 demo fallback，同时为真实 ASR Provider 验收预留运营视图。
|
||||
|
||||
---
|
||||
|
||||
@@ -157,7 +193,7 @@ DreamWeaver 是面向 3-8 岁亲子场景的个性化 AI 绘本与陪伴式讲
|
||||
|
||||
### 2:20 - 3:00 取舍与下一步
|
||||
|
||||
求职版优先稳定闭环和可解释性，不做支付、多租户和复杂监控。现在 job/event 已能查询 workflow、资产补全、provider 调用轨迹和聚合指标，统一生成已迁移到后台 worker，取消/重试队列也已打通；用户端可看跨故事运营摘要，管理端可看当前环境跨用户 Provider dashboard。下一步应补跨环境汇聚、断点续跑和更完整监控。
|
||||
求职版优先稳定闭环和可解释性，不做支付、多租户和复杂监控。现在 job/event 已能查询 workflow、资产补全、provider 调用轨迹和聚合指标，统一生成已迁移到后台 worker，取消/重试队列也已打通；Voice Studio 已进入 Phase A Alpha，可演示回合式共创和保存为 Story；用户端可看跨故事运营摘要，管理端可看当前环境跨用户 Provider dashboard 和 ASR 摘要。下一步应补真实 ASR Key 环境验收、跨环境 Provider 汇聚、断点续跑和更完整监控。
|
||||
|
||||
---
|
||||
|
||||
@@ -170,6 +206,7 @@ DreamWeaver 是面向 3-8 岁亲子场景的个性化 AI 绘本与陪伴式讲
|
||||
| 图片 provider 失败 | 展示 degraded completed 与 retry 机制 |
|
||||
| 录音或 ASR 不稳定 | 切到文本 fallback，说明 Alpha 阶段已保留降级路径 |
|
||||
| 语音共创低置信度卡住 | 使用“按这个理解继续”或“改成文本输入”完成本轮 |
|
||||
| Docker Hub 拉取超时 | 当前 Dockerfile/Compose 支持基础镜像覆盖；本机 `.env` 已配置代理源，可直接 `docker compose up -d --build` |
|
||||
| Docker 冷启动慢 | 演示前提前运行 smoke 脚本并保持容器运行 |
|
||||
| Admin 页面不适合主展示 | 只用 Provider 分层说明辅助讲系统设计 |
|
||||
| 面试官追问生产部署 | 明确当前是求职版 MVP，本轮重点是产品闭环和系统边界 |
|
||||
|
||||
@@ -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 汇聚、断点续跑、监控告警和密钥治理 |
|
||||
|
||||
@@ -2,6 +2,152 @@
|
||||
|
||||
这份记录用于演示前快速说明“当前本地 Docker 环境已经验证到什么程度”。新的验证记录按时间倒序追加。
|
||||
|
||||
## 2026-06-01 真实 ASR Key 环境验收入口补齐
|
||||
|
||||
- 检查当前 `openai_asr` 接线：ASR capability 已在 Provider policy 中注册，`ASR_PROVIDERS` 默认仍为 `["demo"]`；真实转写走 `openai_asr` 适配器、Provider Router 和 Voice Session 上传回合。
|
||||
- 补齐 `OPENAI_API_BASE` 到 settings 与 `openai_asr` 默认配置，兼容官方 OpenAI 留空和兼容网关 `/v1` 场景。
|
||||
- `openai_asr` 失败信息从统一“服务暂时不可用”改为保留 HTTP 状态、连接错误或异常摘要，并脱敏 `Bearer` / `sk-` token，方便区分 key、额度、模型、网关和音频格式问题。
|
||||
- `scripts/demo_smoke.sh` 新增可选 `SMOKE_REAL_ASR=1`。该开关会自动启用 `SMOKE_VOICE=1`，上传真实音频，断言 `transcription_provider=openai_asr`、转写文本非空、用户侧 analytics 可按 `provider=openai_asr` 筛选、Admin ASR analytics 能看到 `openai_asr`。
|
||||
- 默认 smoke、`SMOKE_AUDIO=1` 和 `SMOKE_VOICE=1` 行为不变；真实 ASR 路径只有显式打开时才会触发外部 OpenAI 调用。
|
||||
- 真实 ASR 音频来源：macOS 下默认用 `say` + `afconvert` 生成短 m4a；其他环境可传 `REAL_ASR_AUDIO_FILE=/path/to/sample.m4a`。
|
||||
|
||||
真实 ASR `.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
|
||||
```
|
||||
|
||||
验证命令：
|
||||
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
docker compose restart backend backend-admin worker celery-beat
|
||||
SMOKE_REAL_ASR=1 ./scripts/demo_smoke.sh
|
||||
curl -fsS -u admin:admin 'http://localhost:52800/admin/providers/analytics?days=7&capability=asr'
|
||||
```
|
||||
|
||||
若通过 Admin Provider 表改 ASR 配置，先刷新 provider cache 并重启 API 进程：
|
||||
|
||||
```bash
|
||||
curl -fsS -u admin:admin -X POST 'http://localhost:52800/admin/providers/reload'
|
||||
docker compose restart backend worker
|
||||
```
|
||||
|
||||
失败排查口径：
|
||||
|
||||
- `OPENAI_API_KEY 未配置`：容器或本机 API 没读到 key，先 `docker compose exec backend env | rg 'ASR_PROVIDERS|OPENAI|VOICE_TRANSCRIPTION'`。
|
||||
- `HTTP 401/403`：key 错误、项目权限不足或兼容网关鉴权失败。
|
||||
- `HTTP 429` / `insufficient_quota`：额度不足或触发限流。
|
||||
- `model_not_found`：`VOICE_TRANSCRIPTION_MODEL` 当前 key 不可用，先换回 `gpt-4o-mini-transcribe`。
|
||||
- `OpenAI ASR 网络连接失败`：检查代理、DNS、网关地址和 `OPENAI_API_BASE` 是否需要 `/v1`。
|
||||
- 音频格式错误或空转写：用 `REAL_ASR_AUDIO_FILE=/path/to/sample.m4a` 传一段真实短录音复测。
|
||||
|
||||
本轮本地验证：
|
||||
|
||||
- `bash -n scripts/demo_smoke.sh` 通过。
|
||||
- `backend/.venv/bin/python -m pytest backend/tests/test_provider_router.py -q` 通过，13 passed。
|
||||
- `backend/.venv/bin/python -m ruff check backend/app/core/config.py backend/app/services/provider_router.py backend/app/services/adapters/asr/openai.py backend/tests/test_provider_router.py` 通过。
|
||||
- 本轮触碰文件的 `git diff --check -- ...` 通过。
|
||||
- 全量 `git diff --check` 仍会报出既有未触碰文件 `backend/app/services/adapters/__init__.py` 与 `backend/app/services/adapters/tts/minimax.py` 的 trailing whitespace；本轮按“只改阻塞验收部分”未清理。
|
||||
- 未在当前环境执行 `SMOKE_REAL_ASR=1`，因为真实 `OPENAI_API_KEY` 不应写入仓库；该路径已作为 key 环境验收入口补齐。
|
||||
|
||||
## 2026-05-06 外部 Registry 阻塞修复与重建回归
|
||||
|
||||
- 根因分析：
|
||||
- Docker Hub 失败不是项目 Dockerfile 问题，而是当前网络到 `registry-1.docker.io` / `auth.docker.io` 的 TLS 链路不稳定；`auth.docker.io` token 请求在宿主机 `curl` 下也会 SSL timeout。
|
||||
- 绕开 Docker Hub 后，管理端前端构建又暴露第二层外部依赖问题：容器内访问 `registry.npmjs.org` 触发 `EIDLETIMEOUT`。
|
||||
- 修复方式：
|
||||
- `backend/Dockerfile`、`frontend/Dockerfile`、`admin-frontend/Dockerfile` 改为支持可覆盖基础镜像。
|
||||
- `docker-compose.yml` 新增 `PYTHON_BASE_IMAGE`、`NODE_BASE_IMAGE`、`NGINX_BASE_IMAGE`、`NPM_REGISTRY` build args，默认仍使用官方 Docker Hub / npmjs，不影响其他环境。
|
||||
- 本机 git-ignored 根 `.env` 写入代理源：`docker.m.daocloud.io`、`docker.1ms.run`、`registry.npmmirror.com`。
|
||||
- 两个前端 Dockerfile 从 `npm install` 改为 `npm ci --no-audit --no-fund`，用 lockfile 提高构建确定性。
|
||||
- `docker compose up -d --build` 已用当前代码完整重建 backend、frontend、frontend-admin 镜像并重建容器。
|
||||
- 重建后 `SMOKE_VOICE=1 ./scripts/demo_smoke.sh` 通过，生成本轮故事 ID `56/57/58`。
|
||||
- 重建后管理端 ASR analytics 验证通过：`capability=asr` 返回 `total_calls=3`、`voice_session_count=3`、`voice_turn_count=3`，并按 `demo` Provider 与 `github:dev_user_001` 聚合。
|
||||
- Docker 栈当前服务全部运行，backend、backend-admin、worker、celery-beat、frontend、frontend-admin 均为重建后容器。
|
||||
- 语音共创 PRD #48 已完成；#47/#48/#49/#50 本批 Alpha 演示质量任务收束。
|
||||
|
||||
验证命令：
|
||||
|
||||
```bash
|
||||
curl -Iv --connect-timeout 15 https://registry-1.docker.io/v2/
|
||||
curl -Iv --connect-timeout 15 'https://auth.docker.io/token?service=registry.docker.io&scope=repository:library/python:pull'
|
||||
docker compose config | rg -n "PYTHON_BASE_IMAGE|NODE_BASE_IMAGE|NGINX_BASE_IMAGE|NPM_REGISTRY"
|
||||
docker compose build backend frontend frontend-admin
|
||||
docker compose up -d --build
|
||||
SMOKE_VOICE=1 ./scripts/demo_smoke.sh
|
||||
curl -fsS -u admin:admin 'http://localhost:52800/admin/providers/analytics?days=7&capability=asr'
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
- Docker Hub 官方链路仍可不稳定，但当前项目构建不再直接依赖它的 auth 链路。
|
||||
- `docker compose up -d --build` 通过。
|
||||
- `SMOKE_VOICE=1 ./scripts/demo_smoke.sh` 通过。
|
||||
- Admin ASR analytics 手动验证通过。
|
||||
|
||||
## 2026-05-06 拉取后 ASR 管理端摘要补齐
|
||||
|
||||
- 已拉取远端 `main` 到 `0ccfd00 chore: update frontend tooling and Chinese copy`。
|
||||
- 管理端 Provider analytics 已补齐 ASR 维度：`/admin/providers/analytics?capability=asr` 会聚合 Voice Session 上传转写成功、转写失败、失败原因、ASR 成本、跨用户分布、语音会话数和上传回合数。
|
||||
- 管理端前端在语音识别筛选下将摘要卡片切换为“语音会话 / 上传回合”，避免沿用 generation job 口径。
|
||||
- 后端开发登录重定向测试已显式打开 debug，避免依赖外部环境变量导致全量测试不稳定。
|
||||
- Docker 镜像重建两次被 Docker Hub TLS handshake timeout 阻塞，失败点在 `python:3.11-slim`、`node:18-alpine`、`nginx:alpine` 元数据解析；本轮未能用当前代码重建容器。
|
||||
- 当前已启动 Docker 栈首次 `SMOKE_VOICE=1` 在登录阶段返回 502，定位为前端 Nginx 解析到旧 backend 容器 IP；重启 `frontend` 后代理恢复。
|
||||
- 当前已启动 Docker 栈下 `SMOKE_VOICE=1 ./scripts/demo_smoke.sh` 通过，覆盖故事生成、Voice Session 文本 fallback、上传回合 demo transcript hint、语音 analytics、finalize 保存 Story、绘本生成与图片补全。
|
||||
- `scripts/demo_smoke.sh` 新增 `DEV_SIGNIN_URL` 覆盖项，支持直接打本机源码 API 时把 dev 登录回跳到 `/auth/session`，避免没有 SPA 页面导致误报。
|
||||
- 当前源码本机 API/admin/worker 连接 Docker Postgres/Redis 后，`SMOKE_VOICE=1` 通过，生成本轮故事 ID `53/54/55`。
|
||||
- 本机源码 admin ASR analytics 手动验证通过：`capability=asr` 返回 `total_calls=2`、`voice_session_count=2`、`voice_turn_count=2`，并按 `demo` Provider 与 `github:dev_user_001` 聚合。
|
||||
- 技术方案已新增服务复杂度自审，列出 `voice_session_service.py`、`generation_jobs.py`、ASR service 和 Voice Studio 的拆分候选与风险信号。
|
||||
- 已按服务复杂度自审开始拆分：管理端跨用户 Provider/ASR 摘要迁移到 `backend/app/services/admin_provider_analytics.py`，`generation_jobs.py` 回到生成任务与用户侧 provider stats 边界。
|
||||
- 演示 checklist、demo package、3 分钟 pitch、PRD 和技术方案已完成口径复核：统一说明 Voice Studio 是 Phase A Alpha，ASR 摘要已进入管理端，当前源码 smoke 已通过。当时 #48 仍待当前代码镜像重建后的 Docker voice smoke。
|
||||
- 后续同日已通过 Registry 绕行修复完成 #48，见上方“外部 Registry 阻塞修复与重建回归”记录。
|
||||
|
||||
验证命令：
|
||||
|
||||
```bash
|
||||
docker compose up -d --build backend backend-admin worker celery-beat frontend-admin
|
||||
docker compose build backend frontend-admin
|
||||
DOCKER_BUILDKIT=0 docker compose build backend
|
||||
docker manifest inspect python:3.11-slim
|
||||
docker compose restart frontend
|
||||
SMOKE_VOICE=1 ./scripts/demo_smoke.sh
|
||||
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
|
||||
curl -fsS -u admin:admin 'http://localhost:53800/admin/providers/analytics?days=7&capability=asr'
|
||||
backend/.venv/bin/python -m pytest backend/tests/test_admin_providers.py -q
|
||||
backend/.venv/bin/python -m pytest backend/tests -q
|
||||
backend/.venv/bin/python -m pytest backend/tests/test_auth.py backend/tests/test_admin_providers.py -q
|
||||
backend/.venv/bin/python -m ruff check backend/app/services/generation_jobs.py backend/app/services/admin_provider_analytics.py backend/app/api/admin_providers.py backend/tests/test_admin_providers.py
|
||||
backend/.venv/bin/python -m ruff check backend/app backend/tests
|
||||
cd frontend && npm run build
|
||||
cd admin-frontend && npm run build
|
||||
git diff --check
|
||||
```
|
||||
|
||||
结果：
|
||||
|
||||
- Docker build 未完成，原因是 Docker Hub TLS handshake timeout；legacy builder 同样卡在 `FROM python:3.11-slim`，已手动终止。
|
||||
- `docker manifest inspect python:3.11-slim` 同样因 Docker Hub auth token 请求 TLS handshake timeout 失败，说明当前阻塞在 registry 访问而不是项目 Dockerfile。
|
||||
- `docker compose restart frontend` 后 `/auth/dev/signin` 经前端代理恢复 302。
|
||||
- 当前已启动 Docker 栈 `SMOKE_VOICE=1 ./scripts/demo_smoke.sh` 通过；本结果只能证明运行中栈健康，不能替代当前代码重建后的 Docker smoke。
|
||||
- 当前源码本机 API/admin/worker 下 `SMOKE_VOICE=1 ./scripts/demo_smoke.sh` 通过；当时这验证了当前代码路径，但仍不能替代镜像重建验证。后续同日已完成镜像重建验证，见上方记录。
|
||||
- 本机源码 admin ASR analytics 返回 `voice_session_count=2`、`voice_turn_count=2`，确认管理端 ASR 运营摘要字段可用。
|
||||
- 本地 demo 数据卷由历史 `create_all` 路径创建过 Voice Session 表，直接运行 `alembic upgrade head` 会因 `voice_sessions` 已存在而失败；本轮未修改数据卷版本号，后续可在演示库层面单独处理 stamp 或迁移策略。
|
||||
- `backend/tests/test_admin_providers.py` 通过，3 passed。
|
||||
- `backend/tests/test_auth.py backend/tests/test_admin_providers.py` 通过，12 passed。
|
||||
- 后端全量测试通过，119 passed。
|
||||
- 后端相关文件 ruff 检查通过；全量 `backend/app backend/tests` ruff 检查也通过。
|
||||
- 用户端 `vue-tsc && vite build` 通过。
|
||||
- 管理端 `vue-tsc && vite build` 通过。
|
||||
- `git diff --check` 通过。
|
||||
- 用户端构建仍提示 Browserslist 数据偏旧；管理端构建仍提示 `baseline-browser-mapping` 与 Browserslist 数据偏旧。本轮未处理前端依赖刷新。
|
||||
|
||||
## 2026-04-28 拉取后回归与 Voice Studio 文案收敛
|
||||
|
||||
- 已拉取远端 `main` 到 `55ca098 Add voice analytics filters and metrics` 后完成本地回归。
|
||||
|
||||
@@ -48,20 +48,22 @@ AI 生成产品最大的问题不是“能不能调模型”，而是结果不
|
||||
|
||||
我把它拆成四个概念：
|
||||
|
||||
- Capability：产品需要的 AI 能力，例如文本、图片、语音、绘本结构
|
||||
- Capability：产品需要的 AI 能力，例如文本、图片、语音合成、语音识别、绘本结构
|
||||
- Provider：某个能力下的供应商配置，例如 Gemini、OpenAI、CQTAI、MiniMax
|
||||
- Adapter：具体 API 调用实现
|
||||
- Routing Policy：如何按优先级、成本、延迟或轮询选择 Provider
|
||||
|
||||
这样用户看到的是稳定的产品能力，系统内部再决定具体调用哪个模型或供应商。
|
||||
|
||||
语音共创 Alpha 也沿用这套分层：孩子可以通过 Voice Studio 用文本降级或上传语音参与故事，系统把 ASR、对话生成和 TTS 都当成可观测能力，而不是写死在页面里。
|
||||
|
||||
---
|
||||
|
||||
## 2:35 - 3:00 当前成果和下一步
|
||||
|
||||
目前本地 Docker 可以跑通完整链路，并且有 smoke 脚本验证健康检查、登录、生成、资产重试、故事列表和 Provider 能力分层。
|
||||
目前本地 Docker 运行栈可以跑通完整链路，并且有 smoke 脚本验证健康检查、登录、生成、资产重试、故事列表、Provider 能力分层和 Voice Studio Alpha。之前镜像重建被 Docker Hub / npm registry 链路卡住，我把基础镜像和 npm registry 做成可配置后，当前代码已经完成 `docker compose up -d --build` 和重建后 voice smoke。
|
||||
|
||||
现在 generation job 已经能查询完整事件流，包括 workflow、资产补全和 provider 调用；用户端和管理端都能展示生成轨迹，也能看到 provider 成功率、耗时和成本视角。
|
||||
现在 generation job 已经能查询完整事件流，包括 workflow、资产补全和 provider 调用；用户端和管理端都能展示生成轨迹，也能看到 provider 成功率、耗时和成本视角。Voice Studio 仍定位为 Phase A Alpha：它验证回合式语音共创、文本 fallback、低置信度确认、TTS 回复和保存为正式 Story，不把它包装成实时语音最终形态。
|
||||
|
||||
我希望通过这个项目展示的是：我不只是会接 AI API，而是能把不确定的模型能力收敛成稳定、可解释、可恢复的产品体验。
|
||||
|
||||
@@ -81,6 +83,10 @@ AI 生成产品最大的问题不是“能不能调模型”，而是结果不
|
||||
|
||||
它让用户不需要理解模型供应链，只感知稳定能力；同时让产品拥有者能控制成本、失败降级和供应商切换。
|
||||
|
||||
### 语音共创现在做到什么程度？
|
||||
|
||||
它是 Phase A Alpha，已经能演示创建会话、文本 fallback、上传语音转写、系统接着讲、低置信度确认、TTS 回复、会话恢复和 finalize 保存到故事库。当前不做实时打断和全双工对话，下一步先补真实 ASR Key 环境验收。
|
||||
|
||||
### 这个项目下一步怎么上线？
|
||||
|
||||
我已经把当前轻量 job/event 模型迁移到后台 worker，并打通了前端进度轮询、取消/重试队列和管理台当前环境运营视图；下一步会补跨环境 Provider 汇聚、断点续跑和更完整监控。生产上线前还需要补真实用户鉴权配置、密钥管理和部署策略。
|
||||
我已经把当前轻量 job/event 模型迁移到后台 worker，并打通了前端进度轮询、取消/重试队列、管理台当前环境运营视图和 ASR 摘要；下一步会补真实 ASR 环境验收、跨环境 Provider 汇聚、断点续跑和更完整监控。生产上线前还需要补真实用户鉴权配置、密钥管理和部署策略。
|
||||
|
||||
@@ -13,7 +13,7 @@ DreamWeaver 当前已经具备“输入主题 -> 生成故事/绘本 -> 补全
|
||||
|
||||
这个方向的价值不在于再加一个输入方式，而在于把 DreamWeaver 从“生成结果”推进到“陪伴式创作过程”。孩子不是先写清楚需求再等待结果，而是可以像和讲故事的人对话一样，说出自己想要的角色、情节和变化，系统实时或准实时地接住这些表达，再继续讲下去。
|
||||
|
||||
本增量 PRD 最初用于把语音共创定义为一条独立、可评估、可拆阶段落地的产品路线。2026-04-24 更新后，远端 `main` 已经提前跑通 Phase A Alpha：独立 Voice Studio、语音/文本回合、低置信度确认、安全改写、TTS 回复、会话恢复、finalize 保存为 Story，以及接回统一 generation job 的资产补全与 trace。下一步不应继续扩大到 Phase B 实时化，而应先完成 Alpha 验收、真实 ASR Provider 接入、成本/观测补齐，并回到原主线的跨环境 Provider 汇聚、监控告警和断点续跑。
|
||||
本增量 PRD 最初用于把语音共创定义为一条独立、可评估、可拆阶段落地的产品路线。2026-05-06 更新后，远端 `main` 已经跑通 Phase A Alpha：独立 Voice Studio、语音/文本回合、低置信度确认、安全改写、TTS 回复、会话恢复、finalize 保存为 Story，以及接回统一 generation job 的资产补全与 trace。ASR 已纳入 Provider 能力与管理端运营摘要，当前代码镜像重建后的 Docker voice smoke 已通过；真实 Key 环境仍需补验。下一步不应继续扩大到 Phase B 实时化，而应先完成真实 ASR 环境验收，再回到原主线的跨环境 Provider 汇聚、监控告警和断点续跑。
|
||||
|
||||
---
|
||||
|
||||
@@ -31,8 +31,8 @@ DreamWeaver 当前已经具备“输入主题 -> 生成故事/绘本 -> 补全
|
||||
|
||||
### Proposed Sequencing
|
||||
|
||||
1. 先完成 Phase A Alpha 收束：回归验证、演示清单、验收矩阵和已知限制记录。
|
||||
2. 补齐真实 ASR Provider、turn 级成本/指标归因、Voice Studio smoke 路径和失败降级验收。
|
||||
1. 先完成 Phase A Alpha 收束：回归验证、演示清单、验收矩阵、服务复杂度自审和已知限制记录。
|
||||
2. 补齐真实 ASR Key 环境验收，以及 turn 级对话/TTS 成本归因。
|
||||
3. 回到生产化主线：跨环境 Provider 汇聚、监控告警、断点续跑与更细粒度任务控制。
|
||||
4. Phase A 稳定并验证产品价值后，再评估 Phase B 准实时共创。
|
||||
|
||||
@@ -386,7 +386,7 @@ DreamWeaver 的语音共创模式应当成为一种“孩子可以开口参与
|
||||
|
||||
#### 3. 新增 ASR / Dialogue Orchestrator 能力
|
||||
|
||||
当前系统已有 `text` / `image` / `tts` / `storybook` capability，但 **没有输入侧语音识别能力**。未来至少需要新增：
|
||||
初始系统已有 `text` / `image` / `tts` / `storybook` capability，但当时 **没有输入侧语音识别能力**。Phase A Alpha 已新增 `asr` capability、demo fallback 和 `openai_asr` 适配器；真实 Key 环境仍需验收。能力层仍至少包含：
|
||||
|
||||
- `asr` 或 `speech_input` capability
|
||||
- 会话级 story planner / dialogue orchestrator
|
||||
@@ -434,15 +434,16 @@ DreamWeaver 的语音共创模式应当成为一种“孩子可以开口参与
|
||||
|
||||
## Key Gaps vs Current Architecture
|
||||
|
||||
当前架构 **可以支撑语音共创方向**，但还不能直接无痛实现，主要差距有：
|
||||
初始架构 **可以支撑语音共创方向**，但不能直接无痛实现；以下差距中，Phase A Alpha 已补齐主链路，剩余重点是生产化验收：
|
||||
|
||||
1. **没有语音输入能力层**
|
||||
现在只有 TTS，没有 ASR / STT。
|
||||
1. **语音输入能力层**
|
||||
已新增 `asr` Provider capability、demo fallback 和 `openai_asr`；仍需真实 Key 环境、延迟样本和更多失败原因验收。
|
||||
|
||||
2. **没有会话态故事模型**
|
||||
现在更像“提交任务 -> 等结果”，缺少持续共创 session。
|
||||
2. **会话态故事模型**
|
||||
已新增 Voice Session/Turn/Event；后续要继续拆分服务边界，降低 turn 编排复杂度。
|
||||
|
||||
3. **没有剧情修正语义**
|
||||
3. **剧情修正语义**
|
||||
已支持基础 start / continue / correct；后续要用更多真实儿童表达样本提高覆盖。
|
||||
当前重试和取消针对 job，不针对“故事中途被改写”。
|
||||
|
||||
4. **没有低延迟链路设计**
|
||||
@@ -513,7 +514,7 @@ DreamWeaver 的语音共创模式应当成为一种“孩子可以开口参与
|
||||
| FR-008 分支剧情 | Deferred | 当前状态模型不阻断未来扩展，但未实现分叉体验 | 保持 P2，Phase A 不做 |
|
||||
| NFR-001 响应可接受 | Needs Measurement | 回合式体验已实现，但尚无 p95 指标采集 | 加入 ASR/TTS/turn 编排耗时埋点 |
|
||||
| NFR-002 儿童内容安全 | Alpha Done | 已新增用户转写安全检查、assistant 柔性改写和 `safety_flags` 事件 | 扩充安全样本和误伤回归 |
|
||||
| NFR-003 成本可观测 | Partial | generation job/provider analytics 已覆盖资产补全；voice turn 级 ASR/TTS 成本仍需细化 | 把 ASR/Dialogue/TTS 成本写入 turn/event metadata |
|
||||
| NFR-003 成本可观测 | Partial | generation job/provider analytics 已覆盖资产补全；ASR 已进入管理端 Provider 摘要；voice turn 级 Dialogue/TTS 成本仍需细化 | 把 Dialogue/TTS 成本写入 turn/event metadata |
|
||||
| NFR-004 会话可恢复 | Alpha Done | Voice Studio 支持最近会话恢复和 active session 查询 | 补刷新/切页手动验收记录 |
|
||||
| NFR-005 架构可插拔 | Alpha Done | ASR 已纳入 `asr` Provider capability，默认 demo fallback，可配置 `openai_asr` | 后续补更多 ASR provider 与管理端体验 |
|
||||
|
||||
@@ -699,4 +700,27 @@ DreamWeaver 的语音共创模式应当成为一种“孩子可以开口参与
|
||||
- 已扩展 Voice Studio 观测卡：支持转写来源和会话状态筛选，便于演示时解释 demo/fallback/真实 ASR 差异。
|
||||
- 已扩展 `SMOKE_VOICE=1`：增加 provider/status 过滤断言，避免 analytics 只验证全量路径。
|
||||
|
||||
后续仍未完成：#47 ASR Provider 管理端摘要、#48 Docker voice smoke 回归、#49 服务复杂度拆分、#50 演示口径最终复核。
|
||||
当时后续仍未完成：#47 ASR Provider 管理端摘要、#48 Docker voice smoke 回归、#49 服务复杂度拆分、#50 演示口径最终复核。2026-05-06 已补 #47/#48/#49/#50。
|
||||
|
||||
## Phase A Alpha Execution Update（2026-05-06）
|
||||
|
||||
本轮拉取远端 `main` 到 `0ccfd00 chore: update frontend tooling and Chinese copy` 后继续收束 Alpha 运营可解释性：
|
||||
|
||||
- 已完成 #47：管理端 Provider 运营摘要现在会把 Voice Session 上传转写的 ASR 成功/失败纳入 `capability=asr` 聚合。
|
||||
- 管理端摘要新增 `voice_session_count` 与 `voice_turn_count`，语音识别筛选下可直接看到语音会话数和上传回合数。
|
||||
- ASR 摘要会按转写来源聚合成功调用，按失败事件聚合错误原因，并把 ASR 成本记录计入供应商和用户维度。
|
||||
- 已补后端测试覆盖 ASR 成功、失败、成本、跨用户聚合和管理端接口响应。
|
||||
- 已完成 #48：外部 Registry 阻塞已通过可配置基础镜像与 npm registry 修复；当前代码 `docker compose up -d --build` 通过，重建后 `SMOKE_VOICE=1 ./scripts/demo_smoke.sh` 也通过。
|
||||
- 已完成 #49：技术方案新增服务复杂度自审，列出 `voice_session_service.py`、`generation_jobs.py`、ASR service 和 Voice Studio 的拆分候选、风险信号和建议顺序；并已先把管理端跨用户 Provider/ASR 摘要拆到 `admin_provider_analytics.py`。
|
||||
- 已完成 #50：演示 checklist、demo package、3 分钟 pitch、PRD 和技术方案已统一口径：Voice Studio 是 Phase A Alpha，ASR 摘要已进入管理端，当前代码 Docker 重建和 voice smoke 已完成。
|
||||
|
||||
后续仍未完成：真实 ASR Key 环境验收、turn 级 Dialogue/TTS 成本归因、跨环境 Provider 汇聚、断点续跑和更完整监控。
|
||||
|
||||
## Phase A Alpha ASR Key Validation Prep（2026-06-01）
|
||||
|
||||
- 已检查 `openai_asr` 接线：适配器通过 ASR Provider Router 被 Voice Session 上传回合调用，Provider 默认配置读取 `OPENAI_API_KEY`、可选 `OPENAI_API_BASE`、`VOICE_TRANSCRIPTION_MODEL` 和 `VOICE_TRANSCRIPTION_LANGUAGE`。
|
||||
- 已补 `SMOKE_REAL_ASR=1 ./scripts/demo_smoke.sh`，该路径会自动包含 Voice Studio smoke，上传真实音频并断言 `transcription_provider=openai_asr`、转写文本非空、用户侧 analytics 可按 `provider=openai_asr` 筛选、Admin ASR analytics 能看到 `openai_asr`。
|
||||
- 默认演示路径仍保留 demo fallback；真实 ASR 路径必须显式打开，避免没有 key 时影响普通 smoke。
|
||||
- 文档已补真实 ASR `.env`、运行命令和失败排查口径。
|
||||
|
||||
真实 Key 环境验收仍需在有可用 key 的机器执行；执行通过后再把“真实 ASR Key 环境验收”从后续项里移除。
|
||||
|
||||
54
docs/technical/environment-configuration.md
Normal file
54
docs/technical/environment-configuration.md
Normal file
@@ -0,0 +1,54 @@
|
||||
# 环境变量配置约定
|
||||
|
||||
DreamWeaver 只把 `backend/.env` 视为应用运行配置文件。根目录 `.env` 可以存在，但它只服务 Docker Compose 本身，不参与后端配置加载。
|
||||
|
||||
## 文件职责
|
||||
|
||||
| 文件 | 读取方 | 放什么 | 不放什么 |
|
||||
| --- | --- | --- | --- |
|
||||
| `backend/.env` | FastAPI、Admin API、Celery worker、Celery beat、Docker 后端服务 | `SECRET_KEY`、`DATABASE_URL`、Redis/Celery URL、Provider 列表、AI key、OAuth key、Admin 账号 | Docker 镜像源、npm registry |
|
||||
| `.env` | Docker Compose 插值 | `PYTHON_BASE_IMAGE`、`NODE_BASE_IMAGE`、`NGINX_BASE_IMAGE`、`NPM_REGISTRY` 等镜像源/registry 覆盖 | AI key、OAuth key、`SECRET_KEY`、后端运行配置 |
|
||||
| `backend/.env.example` | 人读/复制模板 | `backend/.env` 的完整示例 | 真实密钥 |
|
||||
|
||||
## 为什么不让后端读取根目录 `.env`
|
||||
|
||||
`pydantic-settings` 的相对 `env_file=".env"` 会受当前工作目录影响：在仓库根目录启动会读根 `.env`，在 `backend/` 目录启动会读 `backend/.env`。这会导致同一条启动命令在不同目录下使用不同配置。
|
||||
|
||||
当前代码在 `backend/app/core/config.py` 中固定使用绝对路径 `backend/.env`。因此后端从任意工作目录启动时都读取同一个文件。
|
||||
|
||||
## Docker 演示
|
||||
|
||||
Docker 后端服务通过 `env_file: ./backend/.env` 读取应用配置。默认容器内地址应保持为服务名：
|
||||
|
||||
```env
|
||||
DATABASE_URL=postgresql+asyncpg://dreamweaver:dreamweaver_password@db:5432/dreamweaver_db
|
||||
CELERY_BROKER_URL=redis://redis:6379/0
|
||||
CELERY_RESULT_BACKEND=redis://redis:6379/0
|
||||
REDIS_URL=redis://redis:6379/0
|
||||
```
|
||||
|
||||
Postgres 容器只接收 `docker-compose.yml` 中固定的 demo 账号和数据库名，避免把 AI/OAuth key 注入基础设施容器。后端服务读取 `backend/.env` 中的 `DATABASE_URL`。需要改 Docker demo 的数据库账号时，同时修改 `docker-compose.yml` 的 `db.environment` 和 `backend/.env` 的 `DATABASE_URL`。Docker demo 固定暴露 `52432:5432` 和 `52379:6379`，本机直跑后端时按这些宿主机端口连接。
|
||||
|
||||
## 本机直跑后端
|
||||
|
||||
本机直接运行 `uvicorn`、`celery` 或 `alembic` 时也只改 `backend/.env`，把数据库和 Redis URL 改成宿主机端口：
|
||||
|
||||
```env
|
||||
DATABASE_URL=postgresql+asyncpg://dreamweaver:dreamweaver_password@localhost:52432/dreamweaver_db
|
||||
CELERY_BROKER_URL=redis://localhost:52379/0
|
||||
CELERY_RESULT_BACKEND=redis://localhost:52379/0
|
||||
REDIS_URL=redis://localhost:52379/0
|
||||
```
|
||||
|
||||
## 检查命令
|
||||
|
||||
```bash
|
||||
# 后端实际读取哪个 env 文件
|
||||
backend/.venv/bin/python - <<'PY'
|
||||
from app.core.config import BACKEND_ENV_FILE
|
||||
print(BACKEND_ENV_FILE)
|
||||
PY
|
||||
|
||||
# Docker 后端容器实际环境，注意不要把输出贴到公共渠道
|
||||
docker compose exec backend env | sort
|
||||
```
|
||||
@@ -25,7 +25,7 @@
|
||||
- 当 `transcript_confidence` 或 `intent_confidence` 偏低时，后端优先返回确认提示，而不是直接把这一轮写进故事正文
|
||||
- 已补完整确认流：支持“按这个理解继续”“重说本轮”“改成文本输入”
|
||||
- 前端明确展示“本轮系统理解为”与“建议家长确认后再继续”提示
|
||||
- 低置信度确认链路已有后端测试覆盖，可作为下一阶段继续接 ASR 与更细确认交互的基础
|
||||
- 低置信度确认链路已有后端测试覆盖，可作为下一阶段继续验收真实 ASR Key 环境与更细确认交互的基础
|
||||
- 已新增用户转写安全检查、assistant 输出柔性改写与 `safety_flags` 事件记录
|
||||
- finalize 会生成更稳定的标题/摘要，并在条件允许时自动排队封面补全 job
|
||||
- 已新增 `voice session analytics` 聚合指标，可跟踪 turn 成功率、ASR/TTS 失败、低置信度触发、finalize 转化率、输入构成、语音时长、Provider 分布、确认率和平均置信度，并支持按转写 Provider 与会话状态筛选
|
||||
@@ -52,7 +52,7 @@ Phase A 明确不做以下内容：
|
||||
- 不做多人共创
|
||||
- 不做绘本共创主链路
|
||||
- 不做每回合即时插图生成
|
||||
- 不把 ASR / Realtime 能力立刻并入当前 admin Provider 配置面板
|
||||
- 不把 Realtime 能力立刻并入当前 admin Provider 配置面板；ASR 已作为 Alpha 运营观测能力进入 Provider 体系
|
||||
|
||||
换句话说，Phase A 是一个 **回合式 voice session MVP**，不是最终形态。
|
||||
|
||||
@@ -93,13 +93,13 @@ Phase A 明确不做以下内容：
|
||||
- `tts` Provider Router
|
||||
- 现有故事库、故事详情页和后续资产补全链路
|
||||
|
||||
### 4.2 当前明显缺失的能力
|
||||
### 4.2 初始设计时明显缺失、Alpha 已补齐的能力
|
||||
|
||||
- 语音输入识别（ASR / STT）
|
||||
- 会话级状态模型
|
||||
- “剧情修正”语义解析
|
||||
- 会话级可观测事件
|
||||
- 从 voice session 保存为正式 Story 的收束服务
|
||||
- 语音输入识别（ASR / STT）：已通过 `asr` Provider capability、demo fallback 和 `openai_asr` 适配器补齐，真实 Key 环境仍需验收。
|
||||
- 会话级状态模型：已落地 `voice_sessions / voice_turns / voice_session_events`。
|
||||
- “剧情修正”语义解析：Alpha 已支持 start / continue / correct 等回合意图。
|
||||
- 会话级可观测事件：已支持 voice session analytics、事件列表和管理端 ASR 摘要。
|
||||
- 从 voice session 保存为正式 Story 的收束服务：已支持 finalize 保存为 Story，并接回 generation job 资产补全。
|
||||
|
||||
---
|
||||
|
||||
@@ -115,7 +115,7 @@ Phase A 明确不做以下内容：
|
||||
`voice_sessions` 管过程，`stories` 管正式结果，避免把会话噪音直接污染正式故事结构。
|
||||
|
||||
4. **先复用 `text` / `tts` 主干，再决定是否拆新 capability**
|
||||
首版把复杂度压到最小，不急着把所有新能力都映射进 admin Provider 面板。
|
||||
首版把复杂度压到最小，不急着把 realtime / barge-in 等新能力映射进 admin Provider 面板。ASR 现在只作为回合式转写能力进入 Provider 体系。
|
||||
|
||||
5. **首版允许“文本可用但语音失败”降级**
|
||||
这与当前 DreamWeaver 主结果优先可读的原则一致。
|
||||
@@ -440,14 +440,29 @@ Phase A 明确不做以下内容：
|
||||
|
||||
**建议**
|
||||
|
||||
- Phase A 先接单一稳定供应商
|
||||
- 暂不并入当前 admin Provider CRUD
|
||||
- 先通过配置文件或单独 service 封装
|
||||
- Phase A 先接单一稳定供应商，并保留 demo fallback
|
||||
- 已并入当前 admin Provider CRUD 和运营摘要，但不引入 realtime 复杂配置
|
||||
- 先通过配置文件或单独 service 封装真实 Key 环境差异
|
||||
- 真实 Key 验收用 `SMOKE_REAL_ASR=1 ./scripts/demo_smoke.sh`，只在显式打开时调用外部 ASR
|
||||
|
||||
理由是：
|
||||
|
||||
- 当前 admin Provider 已扩展到 `text/image/tts/storybook/asr`
|
||||
- Phase A Alpha 已把 ASR 纳入最小 Provider 能力，但仍保留 demo fallback，避免真实转写不可用时阻塞演示
|
||||
- `openai_asr` 默认读取 `OPENAI_API_KEY`、可选 `OPENAI_API_BASE`、`VOICE_TRANSCRIPTION_MODEL` 和 `VOICE_TRANSCRIPTION_LANGUAGE`
|
||||
|
||||
真实 ASR 验收最小 `.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
|
||||
```
|
||||
|
||||
失败时优先看三处：上传接口响应、`turn_transcription_failed` 事件、Admin Provider analytics 的 `capability=asr` failure reasons。常见原因是 key 没进容器、401/403、429/额度不足、模型不可用、`OPENAI_API_BASE` 指向错误或音频格式不被接受。
|
||||
|
||||
### B. Dialogue Orchestrator
|
||||
|
||||
@@ -537,7 +552,36 @@ Phase A 就应该按 turn 记录：
|
||||
- 对话生成成本
|
||||
- TTS 成本
|
||||
|
||||
这部分后续可以汇总到新的语音共创 analytics，而不是一开始就挤进现有故事生成 dashboard。
|
||||
当前 Alpha 已把 ASR 成本和调用摘要接入管理端 Provider analytics。短期这样可以让运营视角统一看到 text/image/tts/storybook/asr；中期如果语音共创继续扩大，应把 voice session analytics 保持为主视图，把 admin Provider analytics 只作为跨能力成本与失败原因摘要。
|
||||
|
||||
### 13.3 服务复杂度自审（2026-05-06）
|
||||
|
||||
当前 Alpha 已经验证主链路，但服务边界开始接近需要拆分的程度：
|
||||
|
||||
| 模块 | 当前职责 | 复杂度信号 | 建议拆分 |
|
||||
| --- | --- | --- | --- |
|
||||
| `voice_session_service.py` | 会话 CRUD、turn 创建、意图识别、故事 patch、低置信度确认、安全改写、TTS、finalize、analytics | 文件已接近 2000 行；同步处理状态机、AI 编排和响应序列化，单次改动容易波及多条路径 | 优先拆 `voice_turn_orchestrator.py`、`voice_session_analytics.py`、`voice_session_finalizer.py` |
|
||||
| `generation_jobs.py` + `admin_provider_analytics.py` | generation job/event、任务控制、provider stats、ops summary；管理端跨用户 Provider/ASR 摘要已拆到独立 service | `generation_jobs.py` 仍偏大，但 ASR 管理端摘要已不再继续塞进 generation job 模块 | 后续继续把 `generation_jobs.py` 内部 provider telemetry helper 拆为共享小模块，保留 generation job 主流程聚焦任务状态 |
|
||||
| `voice_transcription_service.py` | ASR mode 解析与 provider router 调用 | 仍较小，但失败元数据不足，admin ASR 失败只能从事件里读 `error` | 后续补 `VoiceTranscriptionAttempt` 风格的轻量结果结构，统一 provider、latency、cost、error |
|
||||
| 前端 `VoiceStudio.vue` | 页面状态、录音上传、会话列表、turn 展示、analytics 卡片、确认/重试/finalize | 视图文件承担了太多 workflow 判断；继续加实时能力会变得难测 | 拆出 `useVoiceSessionWorkflow`、`VoiceTurnCard`、`VoiceAnalyticsPanel` |
|
||||
|
||||
建议拆分顺序：
|
||||
|
||||
1. 先拆只读 analytics：风险最低，测试可以复用现有 `test_voice_sessions.py` 与 `test_admin_providers.py`。2026-05-06 已先拆出管理端 `admin_provider_analytics.py`。
|
||||
2. 再拆 finalize：边界清晰，输入是 session，输出是 Story / generation job。
|
||||
3. 最后拆 turn orchestrator：它耦合 ASR、意图、故事 patch、安全和 TTS，应等回归矩阵更稳定后再动。
|
||||
|
||||
暂不建议在 Phase A Alpha 末尾做的大改：
|
||||
|
||||
- 不引入工作流引擎替代当前状态机。
|
||||
- 不把 voice session 直接塞进 generation job 主模型。
|
||||
- 不在 ASR 事件上新增迁移字段，除非要做精确延迟分布和供应商级 SLA。
|
||||
|
||||
触发必须拆分的信号：
|
||||
|
||||
- 单个 voice turn 改动需要同时修改 3 个以上测试文件。
|
||||
- 新增一个 analytics 字段需要读写多个无关 service。
|
||||
- Voice Studio 引入实时或准实时能力前，仍没有可复用 composable。
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user