岁月时书 (Life Echo)

一个基于实时 WebSocket 长连接的智能语音对话回忆录生成系统

📖 项目简介

岁月时书 (Life Echo) 是一个创新的回忆录生成平台，通过 AI 智能对话引导用户回顾人生历程，并将口语对话自动整理为结构化的回忆录章节，最终生成精美的 PDF 电子书。

后端侧：会话轮次以 DB conversation_messages 为真源、Redis 为缓存；实时对话编排统一走 ChatOrchestrator；图像任务为 generate_story_image（正文）与 generate_chapter_cover（章节封面）。详见 api/README.md。

核心功能

• 🎙️ 实时语音对话 - 基于 WebSocket 的实时双向语音交互
• 🤖 智能访谈引导 - AI Agent 根据传记结构动态引导用户讲述人生故事
• 📝 自动内容整理 - 将口语对话自动整理为优雅的书面语章节
• 📚 结构化回忆录 - 基于传记结构自动组织章节内容
• 📄 PDF 导出 - 生成精美的回忆录 PDF 文档
• 💾 本地数据存储 - Android 端使用 Room 数据库实现离线数据管理

🏗️ 项目结构

life-echo/
├── api/                              # 后端（FastAPI，uv + Alembic）
│   ├── app/
│   │   ├── main.py                   # 对外 API 入口
│   │   ├── internal_main.py          # 内部评测 API 入口
│   │   ├── core/                     # 配置、DB、日志、Redis、LLM 调用等
│   │   ├── ports/                    # 供应商能力协议（ASR/TTS/LLM/…）
│   │   ├── adapters/                 # ports 的具体实现（腾讯、OpenAI、Whisper 等）
│   │   ├── agents/                   # 对话与回忆录编排 Agent
│   │   ├── features/                 # 按域拆分：auth、conversation、memoir、memory、evaluation…
│   │   └── tasks/                    # Celery 任务入口
│   ├── alembic/                      # 数据库迁移
│   ├── tests/                        # pytest
│   ├── main.py                       # uvicorn 兼容入口
│   └── README.md
├── app-expo/                         # 移动端（Expo Router + React Native）
├── app-eval-web/                     # 内部评测 Web（Vite，仅本机开发，不打包进预发/生产 Docker）
└── docs/                             # 设计与运维文档

🚀 快速开始

前置要求

• 后端开发：
  • Python 3.10+
  • Docker & Docker Compose（用于 PostgreSQL、Redis）
  • LLM API Key（DeepSeek 或兼容 OpenAI 的服务）

后端服务启动

详细步骤请参考 api/README.md

# 1. 进入 API 目录
cd api

# 2. 安装依赖
uv sync --dev

# 3. 配置环境变量（创建 .env 文件）
# 参考 api/README.md 中的环境变量配置说明

# 4. 启动 PostgreSQL 和 Redis
docker compose -f docker-compose.dev.yml up -d

# 5. 数据库迁移
# uv run alembic upgrade head

# 6. 启动 FastAPI 服务
uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000

# 7. 启动 Celery Worker（另一个终端）
uv run celery -A tasks.celery_app worker --loglevel=info --pool=solo

数据库 schema 迁移的正式标准是 Alembic；当前仓库已引入脚手架，api/migrations/*.sql 保留为历史/一次性 SQL 脚本，详情见 api/README.md。

后端开发工具链

后端开发环境通过 uv sync --dev 安装开发工具，当前约定如下：

• ruff：负责 lint + format
• pytest：统一测试入口
• pytest-asyncio：负责 async def 测试和异步 fixture
• pytest-cov：负责覆盖率统计
• pyright：负责类型检查，但不替代测试和 lint

常用命令详见 api/README.md。

🛠️ 技术栈

后端技术栈

技术	版本	用途
FastAPI	0.115.0	Web 框架，REST API 和 WebSocket
LangChain	0.3.7	AI Agent 框架（对话引导、内容整理）
PostgreSQL	17	关系型数据库
SQLAlchemy + Alembic	2.0.36 / 1.18+	ORM 与数据库 schema migration
Redis	7	缓存和会话存储
Celery	5.3	异步任务队列
OpenAI API	-	ASR（语音识别）、TTS（语音合成）
DeepSeek API	-	LLM（大语言模型）
ReportLab + WeasyPrint	-	PDF 生成

📚 文档导航

🔐 认证系统

系统使用 JWT（JSON Web Token）进行认证，采用访问令牌（Access Token）+ 刷新令牌（Refresh Token）机制：

• 访问令牌：有效期 2 小时，用于 API 请求认证
• 刷新令牌：有效期 30 天，用于刷新访问令牌

详细认证流程请参考 api/README.md#认证系统

🌟 功能特性

已实现功能

• ✅ 用户注册与登录（手机号 + 密码）
• ✅ JWT 认证系统（访问令牌 + 刷新令牌）
• ✅ 实时 WebSocket 语音对话
• ✅ AI 智能对话引导（基于传记结构）
• ✅ 语音识别（ASR）和语音合成（TTS）
• ✅ 对话内容自动整理为章节
• ✅ 回忆录章节管理
• ✅ PDF 导出功能
• ✅ Android 本地数据存储（Room）
• ✅ 离线数据同步
• ✅ 用户套餐与订单管理
• ✅ 常见问题（FAQ）和反馈系统

开发中功能

• 🔄 更多传记结构模板
• 🔄 图片上传与管理
• 🔄 章节编辑功能
• 🔄 多语言支持

🔒 安全注意事项

1. 环境变量安全：确保 .env 文件不被提交到版本控制
2. SECRET_KEY 安全：生产环境必须使用强随机字符串
3. CORS 配置：生产环境应限制为特定域名
4. API Key 安全：妥善保管 LLM API Key
5. 密码安全：密码使用 bcrypt 哈希存储

🤝 贡献指南

1. Fork 本项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📄 许可证

MIT License

📮 联系方式

如有问题或建议，请通过以下方式联系：

• 提交 Issue
• 发送反馈（应用内反馈功能）

---

岁月时书 - 让每一段人生故事都被温柔记录 ✨