已实现功能

数字人

• 创建/编辑：形象图 + Edge-TTS 音色试听 + 人物设定（年龄/身高/体重/族裔/感情/性格）
• 创建即入 avatar_init 队列，LivePortrait 生成静音 24fps 基础视频（去眨眼、保留耸肩，速度/幅度可调）
• 列表：封面卡片、默认视频预览、重新生成、删除、任务中心跳转定位、生成中骨架屏
• 人物设定持久化为 avatars.persona JSON；编辑页右侧可勾选绑定全局知识库（N:N）

场景管理（场景 → 视频）

• 每个数字人 1-N 个场景（封面/标题/描述），每个场景 1-N 个驱动视频（描述）；创建时的 基础视频成为默认场景的默认视频（默认场景/视频不可删除）
• 场景管理页（/scenes）：表格化场景列表，可展开管理视频、批量上传（视频 + 描述）、 播放预览；播报制作与直播闲置画面都从这里选择场景 + 视频

离线视频生成（播报）

• 选数字人 + 场景/视频 + 脚本 → Edge-TTS → Wav2Lip(ONNX) 口型 → 成品 MP4 → S3 → 模态窗播放/下载
• 制作历史记录场景与视频，可查看/下载/重试（重试复用 TTS 缓存）；分阶段进度（tts/lipsync/mux）
• CodeFormer 人脸修复（口型变形改善），对比视频见仓库 docs/videos/

实时直播

• 常驻 FFmpeg 管道 + Watchdog 架构：恒定 24fps 写帧，队列空自动回退 base 动画 + 静音，播放器不转圈
• 异步 Edge-TTS → Wav2Lip 小批量出帧，多句无缝拼接；句末自动回闲置；Redis 断连静默退避
• 直播台：开/关播、字幕设置（字体/位置/边框/字号）、默认推流视频（场景 + 定时 N 秒/随机切换，持久化 live_settings）、悬浮监看、拉流地址
• 说话口型基于当前正在显示的那段场景视频（不再固定默认视频），说完从该视频衔接处继续
• Agentic 动作视频：DeepSeek 提示词注入当前场景的全部视频，回复可在句首用 <action:S3_KEY> 指定该句的动作画面（标签不出现在文字/字幕/聊天里）；观众端 直播间覆盖在画面上的 SceneSwitcher 胶囊条可随时切换活跃场景（worker 热替换闲置视频池）

观众端

• 首页导航 + 分类筛选 + 暗色模式；直播间 9:16 播放器 + 聊天（点赞、移动端胶囊样式）
• 聊天身份：游客 → 注册/登录升级（同 userId 保历史）；聊天记录持久化 + 分页
• 用户中心：身份卡、「我的消息」
• 1v1 场景切换：画面底部场景胶囊条（可横向滚动），点击切换数字人当前场景并即时生效

知识库 RAG + 长期记忆

• 知识库全局共享：Collection → 文档 Document（粘贴文本 / 上传 .txt/.pdf）， 数字人通过 avatar_knowledge 关系表 N:N 绑定（可多选、可共用）
• service-rag：zvec 全文索引 + Jieba 分词，按绑定集合强制隔离，BM25 Top-3，零模型/零下载
• LLM 链路：DeepSeek 回复注入人物设定 + 最近 10 条聊天（长期记忆）+ 命中知识 Top-3

管理与安全

• 管理员登录（Redis 会话 + HttpOnly cookie）、改用户名/密码、用户列表
• 任务中心：批量选择/删除/跳过/重试；中英双语 i18n

Telegram Mini App

• frontend/telegram（React + Vite + Tailwind + @twa-dev/sdk，:3002）： WebApp.ready() 后把 WebApp.initData POST 到 POST /api/auth/telegram
• 后端 TG_BOT_TOKEN HMAC-SHA-256 校验（24h 时效）→ 按 telegram_id upsert 身份（非游客，HttpOnly cookie）
• 启动自动注册：setWebhook（更新接收）+ setChatMenuButton（Mini App 入口）， 地址优先 TG_WEBHOOK_URL/TG_MINIAPP_URL（生产固定域名），缺失时轮询 ngrok 隧道（api-gateway / tg-app）；两者都有则跳过 ngrok
• 本地联调：ngrok.yml 双隧道 + compose ngrok 服务，NGROK_AUTHTOKEN/ TG_BOT_TOKEN/VITE_API_ORIGIN 见 .env.example

工程与性能

• 一键模型下载脚本；口型阶段约 10s/16s 视频；ONNX 线程数可调
• 多硬件路径：macOS MPS/CoreML（实测）、Linux CUDA 预留、AMD ROCm（RX 6800 XT 路径已备）