# 软件设计说明书（兼操作手册） --- ## 文档封面信息 | 项目 | 内容 | | ------ | ------------- | | 软件全称 | 岁月留书 | | 英文名称 | Life Echo | | 文档名称 | 《岁月留书》软件设计说明书 | | 文档版本 | 1.0 | | 对应软件版本 | 1.0 | | 著作权人 | 上海华嘎科技有限公司 | | 编写单位 | 上海华嘎科技有限公司 | | 编写日期 | 2026年5月12日 | --- ## 第 1 章 引言 ### 1.1 编写目的 本说明书描述「岁月留书（Life Echo）」一体化软件系统在代码仓库层面的组成结构、总体架构、主要功能规格、核心业务流程、开发与测试状况以及典型环境下的安装与运维使用方法。 ### 1.2 适用范围 本说明书适用于以下组成部分的整体说明： 1. **后端 API 服务**：路径 `api/`，基于 FastAPI，对外提供 REST API、WebSocket 实时对话能力及静态资源挂载。 2. **客户端应用**：路径 `app-expo/`，基于 Expo Router 与 React Native，面向终端用户提供登录、对话、回忆录浏览与导出相关交互界面。 3. **内部评测前端**：路径 `app-eval-web/`，基于 Vite，用于开发与回归评测场景（一般不纳入终端用户交付镜像，与内部评测 API 配合使用）。 4. **工程与运维文档**：路径 `docs/`，存放与本项目相关的运维、设计备忘等资料；本说明书为其中面向著作权登记的汇总文档。 ### 1.3 术语与缩写 | 术语 | 含义 | | ------------------ | ----------------------------------------------------- | | JWT | JSON Web Token，访问令牌与刷新令牌组合的认证机制 | | WebSocket | 全双工通信协议，本项目中用于实时语音与文本对话管线 | | ASR | Automatic Speech Recognition，语音转文字 | | TTS | Text-To-Speech，文字转语音 | | LLM | Large Language Model，大语言模型；后端通过适配层调用兼容 OpenAI API 的服务 | | Agent | 基于 LangChain 组织的对话与回忆录编排逻辑单元 | | ChatOrchestrator | 实时对话编排入口，负责将用户输入路由至画像采集或访谈对话等分支 | | MemoirOrchestrator | 回忆录正文流水线编排入口，负责分段调度抽取、分类与各 Specialist Agent | | Celery | Python 异步分布式任务队列，用于回忆录 Phase 处理、记忆压实、嵌入调度等后台作业 | | Phase1 / Phase2 | 回忆录批量处理阶段的工程称谓：Phase1 侧重批次准备与派发，Phase2 按类别执行故事管线 | | Redis | 内存数据结构存储，用作会话缓存与队列协调等 | | PostgreSQL | 关系型数据库；会话消息等持久化真源存放于此 | | pgvector | PostgreSQL 扩展，用于向量检索相关的记忆块存储与检索 | | Alembic | 数据库 Schema 迁移工具；本项目禁止手写 DDL 绕过迁移脚本 | --- ## 第 2 章 系统概述 ### 2.1 建设目标与业务边界 本软件面向「口述回忆录」类产品形态，建设目标包括： 1. **实时智能访谈**：通过 WebSocket 维持长连接，在移动端采集用户语音或文本输入，经 ASR（若语音）形成可处理文本，再由 LLM 驱动的 Agent 结合传记结构与历史记忆检索结果生成引导性回复。 2. **结构化回忆录生成**：将多轮对话中的有效叙事内容抽取、归类，按章节与阅读片段组织为可阅读的「回忆录」文稿，并支持章节级素材与图像任务（工程上区分为正文配图与章节封面等管线）。 3. **可导出成品**：服务端将回忆录内容排版并生成 PDF 等可供用户留存与分享的文档形式（具体能力以当前 `features/memoir` 与相关服务实现为准）。 4. **账户、套餐与商业化支撑**：提供用户注册登录、套餐（Plan）、配额（Quota）、订单与支付（含微信、支付宝等适配）等能力，保证多租户下的资源可控与可审计。 ### 2.2 非功能需求概要 | 类别 | 要求说明 | | ----- | ----------------------------------------------------------------- | | 实时性 | WebSocket 连接内消息顺序稳定；首轮「边播 TTS 边出字」模式下，服务端按协议先推送音频再推送对应文本分段 | | 安全 | REST 接口使用 JWT；WebSocket 连接通过 Query 携带 `access_token` 校验身份 | | 可运维 | 健康检查路由 `/health`；请求追踪依赖中间件注入 request id；日志采用统一结构化封装 | | 可扩展 | 外部厂商能力集中在 `adapters`，业务仅依赖 `ports` 协议，便于替换 ASR/TTS/LLM/短信/对象存储等实现 | | 数据一致性 | 会话消息以数据库表 `conversation_messages` 为权威存储，Redis 承担缓存与加速读取职责 | ### 2.3 系统边界图（逻辑） 客户端（Expo 应用或评测前端）仅与本后端 HTTP/WebSocket 交互；后端再访问 PostgreSQL、Redis，并向 Celery Worker 投递异步任务；外部云服务包括 LLM、ASR、TTS、短信、对象存储及支付网关等，经由适配层调用。 --- ## 第 3 章 总体设计与运行环境 ### 3.1 Monorepo 目录组成 仓库根目录主要包含： ``` life-echo/ ├── api/ # 后端（FastAPI，Python，uv + Alembic + Celery） ├── app-expo/ # 移动端（Expo Router + React Native） ├── app-eval-web/ # 内部评测 Web（Vite） ├── docs/ # 设计与运维文档（含本说明书） ├── package.json # 根级脚本聚合（如 husky、子项目脚本转发） └── README.md # 项目总览 ``` ### 3.2 后端进程形态 1. **主 API 进程**：模块入口 `api/app/main.py` 创建 FastAPI 应用 `app`，挂载各业务 Router，注册 WebSocket 路径 `/ws/conversation/{conversation_id}`，并在启动阶段执行 Alembic 迁移、Redis 连接、ASR 就绪检查、微信支付客户端预初始化等。 2. **内部评测 API 进程**（可选隔离部署）：模块入口 `api/app/internal_main.py` 创建 `internal_app`，挂载 `evaluation` 相关路由，用于回归评测与会话对比，默认与主 API 进程分离以降低评测对线上入口的影响。 3. **Celery Worker**：消费 memoir 处理、记忆压实、嵌入调度、记忆富化等任务队列；具体队列名与路由以 `tasks` 包及环境变量为准。 ### 3.3 客户端组成 `app-expo` 采用文件式路由，源码主目录为 `src/app/`，典型路由分组包括： | 路由分组 | 相对路径示例 | 用途说明 | | ------- | --------------------------------------------------------------------------------------------------- | ------------------------- | | 认证 | `(auth)/login.tsx`、`register.tsx`、`reset-password.tsx` | 登录、注册、重置密码 | | 主导航 Tab | `(tabs)/index.tsx`、`memoir.tsx`、`profile.tsx` | 首页、回忆录、个人中心 | | 对话与内容 | `(main)/conversation/[id].tsx`、`chapter/[id].tsx` | 单会话对话页、章节阅读 | | 设置与合规 | `(main)/personal-info.tsx`、`export-data.tsx`、`delete-data.tsx`、`faq.tsx`、`feedback.tsx`、`about.tsx` | 个人信息、导入导出与删除数据、常见问题、反馈、关于 | | 法律文档 | `legal/[type].tsx` | 法律类展示页 | ### 3.4 开发与运行依赖（摘要） 后端建议环境：Python 3.10 及以上；依赖与锁文件由 `uv` 管理（`api/pyproject.toml` 与 `api/uv.lock`）。数据库使用 PostgreSQL；缓存与消息代理使用 Redis。容器编排可使用 `docker-compose` 系列文件（以 `api/` 目录下实际文件名为准）。 移动端使用 Node.js 生态执行 `npm install` 与 `npx expo start` 等命令。内部评测前端在 `app-eval-web/` 目录使用 Vite 开发服务器。 ### 3.5 内部评测前端（app-eval-web） `app-eval-web` 为研发与质量保障使用的单页应用工程，默认仅监听本机开发端口（常见为 `5174`，以 Vite 控制台输出为准）。其通过 HTTP 调用 `internal_app` 暴露的评测 REST API，前缀固定为 `/internal/api/evaluation`（见 `api/app/internal_main.py` 中的 `include_router` 配置）。该前端**不作为**终端用户应用商店交付物的一部分描述，仅在说明「Monorepo 完整组成」时列出。 --- ## 第 4 章 软件结构说明 ### 4.1 后端分层架构 后端严格按功能域拆分，并遵守「路由不写业务 SQL、服务不直连三方 SDK」的边界约定： | 层次 | 目录 | 职责 | | ---- | --------------------------- | -------------------------------------------------------------- | | 接口层 | `app/features/*/router.py` | 定义 REST 或协议入口，注入服务依赖，返回 Pydantic 模型 | | 业务层 | `app/features/*/service.py` | 业务规则、事务边界、编排对多个 repo 与端口的调用 | | 持久层 | `app/features/*/repo.py` | 数据库增删查改，不在此层随意 `commit`（由上层统一事务策略） | | 领域模型 | `app/features/*/models.py` | SQLAlchemy ORM 模型 | | 端口 | `app/ports/` | 协议（Protocol），描述 ASR、TTS、LLM、短信等能力 | | 适配器 | `app/adapters/` | 具体厂商实现，如 DeepSeek、腾讯、OpenAI Whisper 等 | | 智能体 | `app/agents/` | LangChain Agent 及 `ChatOrchestrator`、`MemoirOrchestrator` 等编排类 | | 核心设施 | `app/core/` | 配置、数据库引擎、Redis、安全、日志、中间件、异常处理等 | | 任务 | `api/tasks/` | Celery 应用与任务定义入口 | ### 4.2 功能域与源码对应关系 以下功能域均位于 `api/app/features/` 下，各自通常包含 `router`、`service`、`repo`（按需）、`schemas`、`deps` 等文件： | 域 | 目录 | 主要职责 | | --- | --------------- | ---------------------------------------------------- | | 认证 | `auth/` | 注册、登录、短信验证码、JWT 签发与校验、头像预设等 | | 用户 | `user/` | 用户资料、反馈等对外接口 | | 对话 | `conversation/` | REST 会话管理、WebSocket 管线、`ChatOrchestrator` 调用、历史与额度守护 | | 记忆 | `memory/` | 记忆块写入、向量检索、富化管道、压实服务、嵌入调度与对外查询接口 | | 回忆录 | `memoir/` | 章节与阅读素材、PDF 服务、叙事安全、口述规范化、章节封面与正文图像任务、状态服务等 | | 故事 | `story/` | 与篇章素材、同步写入、配图意图等相关的服务与仓储（与回忆录流水线协同） | | 套餐 | `plan/` | 套餐目录与订购相关能力 | | 配额 | `quota/` | 配额检查与扣减策略，供对话、回忆录、支付等场景注入使用 | | 支付 | `payment/` | 订单、微信与支付宝等支付通道封装 | | 任务 | `tasks/` | 任务状态查询等对前端的任务进度暴露 | | 内容 | `content/` | TTS 等内容相关接口 | | 资源 | `asset/` | 资源存取相关仓储与模型 | | 评测 | `evaluation/` | 内部评测数据模型、打分、会话目录、回放、对比摘要等（由 `internal_main` 挂载） | ### 4.3 WebSocket 协议文件 工程在 `api/app/features/conversation/ws/protocol.md` 中维护 WebSocket 文本协议说明，包括连接 URL 形态、客户端到服务端与服务端到客户端的消息类型枚举、心跳与重连语义等，与实现代码共同构成可审查的契约说明。 --- ## 第 5 章 功能规格说明 本章按业务域给出可测试的规格化描述：目标、典型输入、处理要点、输出与约束。 ### 5.1 认证与用户（auth / user） **目标**：为全站提供可信身份，支撑受保护 REST 与 WebSocket。 **典型输入**：手机号与密码注册、登录；短信验证码发送与校验；刷新令牌请求。 **处理要点**：密码经安全哈希存储；签发短期访问令牌与长期刷新令牌；对外 schema 校验在 Pydantic 层完成。 **输出**：令牌对、用户基础资料、错误码与错误信息遵循 `app/core/errors.py` 约定的统一错误响应结构（含 `error_code`、`message`、`request_id`）。 **约束**：成功业务响应可为直接模型或字典，不必统一包装信封；敏感环境变量不得写入代码库。 ### 5.2 对话与实时管线（conversation） **目标**：维持长连接会话，完成「语音或文本 →（可选 ASR）→ Agent 推理 →（可选 TTS）→ 客户端展示」闭环。 **典型输入**：`TEXT`、`AUDIO_SEGMENT`、`AUDIO_MESSAGE`、`TRANSCRIBE_ONLY`、`TTS_REQUEST`、`TTS_CANCEL`、`END_CONVERSATION`、心跳等，详见 `protocol.md`。 **处理要点**：连接 URL 为 `/ws/conversation/{conversation_id}?token={jwt_access_token}`；编排由 `ChatOrchestrator` 将用户消息路由到画像分支或访谈分支；会话真源写入 `conversation_messages`，Redis 用于加速与缓存；额度由 `quota` 相关守护在管线中发挥作用。 **输出**：`TRANSCRIPT`、`AGENT_RESPONSE` 分段、`TTS_AUDIO`、`MEMOIR_UPDATE`、`ERROR` 等下行消息。 **约束**：同一连接内消息顺序稳定；若本轮开启服务端 TTS，则每一助手分段先 `TTS_AUDIO` 再对应 `AGENT_RESPONSE`。 ### 5.3 记忆与检索（memory） **目标**：将对话中可复用的事实与摘要以向量块形式持久化，支持后续会话与回忆录生成时的语义检索。 **典型输入**：会话轮次文本、用户标识、检索 query、富化开关相关配置。 **处理要点**：写入与切块、嵌入、可选 LLM 富化、定时压实（compaction）等由服务与 Celery 任务协同；异步与同步路径行为可能不同，工程文档中建议以 `docs/memory-retrieval.md`（若存在）等行为矩阵为准。 **输出**：检索到的记忆证据、供提示词注入的结构化片段、必要的追踪信息（若开启）。 **约束**：配置项如 `CHAT_MEMORY_RETRIEVAL_ENABLED`、`MEMORY_COMPACTION_ENABLED` 等由 `app/core/config.py` 集中管理，调参需结合运行环境与负载。 ### 5.4 回忆录与 PDF（memoir） **目标**：将多轮叙事整理为结构化章节与阅读体验，并生成可导出的文档与配图。 **典型输入**：会话 id、回忆录 id、章节 id、导出请求、图像生成相关任务参数。 **处理要点**：`MemoirOrchestrator` 负责分段编排；Phase1 批次准备后 `process_memoir_phase1` 等 Celery 任务派发 Phase2，按类别进入 `run_story_pipeline_for_category_batch`；图像方面区分正文图 `generate_story_image` 与章节封面 `generate_chapter_cover` enqueue 逻辑；PDF 由 `pdf_service` 等模块调用排版引擎完成。 **输出**：章节文本、阅读片段、PDF 文件流或 URL、任务状态更新、经由 WebSocket 的 `MEMOIR_UPDATE` 通知。 **约束**：涉及对象存储 URI 时需经预签名或受控网关访问；长篇生成依赖队列与超时配置。 ### 5.5 故事与素材（story） **目标**：承接回忆录流水线中篇章级写入与配图意图抽取等职责，与 `memoir` 域协同。 **典型输入**：批量单元规划结果、叙事路由 Agent 输出、图像意图字段。 **处理要点**：仓储与服务分层保持与全局架构一致；同步写入路径需考虑与数据库事务的一致性。 **输出**：持久化的故事单元记录、下游图像任务触发条件。 ### 5.6 套餐与配额（plan / quota） **目标**：定义可售卖套餐与用户使用限额，避免超卖与滥用。 **典型输入**：套餐 id、用户当前订阅状态、对话轮次或回忆录导出等资源计量事件。 **处理要点**：`QuotaService` 供会话与回忆录等模块注入调用；不得在功能模块内硬编码配额 SQL。 **输出**：允许或拒绝决策、剩余额度字段（若接口暴露）。 ### 5.7 支付与订单（payment） **目标**：完成下单、渠道拉起、回调处理与订单状态推进。 **典型输入**：支付方式枚举、订单金额、回调报文。 **处理要点**：微信与支付宝客户端由适配层封装；支付失败与幂等处理在服务层体现。 **输出**：支付参数包、订单状态、错误码。 ### 5.8 任务进度（tasks） **目标**：向前端暴露长时间运行任务的状态，改善用户对回忆录生成等操作的感知。 **典型输入**：任务 id 或业务关联键。 **处理要点**：与 `task_tracker` 等核心组件协作（若启用）。 **输出**：状态枚举、进度百分比或步骤文案。 ### 5.9 内容与朗读（content） **目标**：提供与朗读相关的服务端能力配合对话气泡交互。 **典型输入**：文本分段、音色参数（若支持）。 **处理要点**：与 TTS 适配层衔接；必要时写入缓存或以 URL 形式下发。 ### 5.10 内部评测（evaluation） **目标**：支持离线或半离线环境下的会话回放、评分与对比报告生成，服务于研发质量保障。 **典型输入**：评测会话导入数据、评测脚本、评分 Rubric 版本。 **处理要点**：评测 HTTP API 运行在 `internal_app`；浏览器界面由 `app-eval-web` 调用上述 API。 **输出**：评测轨迹、对比摘要、门禁报告（gate report）等结构化结果。 --- ## 第 6 章 核心业务流程与设计说明 ### 6.1 逻辑分层与依赖关系 ```mermaid flowchart TB subgraph clients [Clients] ExpoApp[app-expo] EvalWeb[app-eval-web] end subgraph backend [api FastAPI] Router[features routers] Service[services] Repo[repos] Agents[agents] Ports[ports] Adapters[adapters] end subgraph infra [Infrastructure] PG[(PostgreSQL)] Redis[(Redis)] Celery[Celery workers] end ExpoApp --> Router EvalWeb --> Router Router --> Service Service --> Repo Service --> Agents Service --> Ports Ports --> Adapters Repo --> PG Service --> Redis Service --> Celery ``` ### 6.2 访问令牌认证与刷新（REST 概要） ```mermaid sequenceDiagram participant C as Client participant A as auth_router participant S as AuthService participant DB as PostgreSQL C->>A: POST login credentials A->>S: validate_and_issue_tokens S->>DB: verify user password hash DB-->>S: user row S-->>A: access_token refresh_token A-->>C: 200 JSON tokens C->>A: GET protected with Authorization Bearer A->>S: verify access_token S-->>A: user context A-->>C: 200 protected resource C->>A: POST refresh with refresh_token A->>S: rotate if valid S-->>A: new token pair A-->>C: 200 new tokens ``` ### 6.3 WebSocket 对话主路径（概要） ```mermaid stateDiagram-v2 [*] --> Connected: JWT valid connect Connected --> Transcribing: AUDIO or AUDIO_SEGMENT Transcribing --> AgentThink: TRANSCRIPT ready Connected --> AgentThink: TEXT input AgentThink --> StreamingReply: ChatOrchestrator yields StreamingReply --> Connected: segments sent optional TTS Connected --> Ending: END_CONVERSATION Ending --> [*] Connected --> Connected: PING PONG heartbeat ``` ### 6.4 回忆录异步流水线（概要） ```mermaid flowchart LR subgraph realtime [Realtime path] WS[WebSocket pipeline] CO[ChatOrchestrator] DB1[(conversation_messages)] end subgraph batch [Batch path] MO[MemoirOrchestrator] P1[Phase1 Celery] P2[Phase2 by category] PDF[PDF service] IMG[Image tasks] end WS --> CO CO --> DB1 DB1 --> MO MO --> P1 P1 --> P2 P2 --> PDF P2 --> IMG ``` ### 6.5 记忆写入、富化与压实（概念） 用户经对话产生的新素材经 `memory` 域服务切块与嵌入后进入 PostgreSQL/pgvector；可选富化任务进入独立 Celery 队列（如 `memory_idle`）；压实任务按配置周期合并或清理旧块，以降低检索噪声与存储膨胀。详细行为以环境变量开关与代码内服务实现为准。 --- ## 第 7 章 接口与数据概要 ### 7.1 REST 与 WebSocket 入口形态 主应用 `app` 注册的路由前缀以各 `router` 定义为准；OpenAPI 文档在 `settings.enable_docs` 为真时可通过 `/docs` 与 `/redoc` 访问。WebSocket 固定路径模板为 `/ws/conversation/{conversation_id}`，鉴权参数为 Query 中的 `token`。 内部评测应用 `internal_app` 的评测相关接口前缀参见 `internal_main` 中的说明（例如 `/internal/api/evaluation/` 一类路径，以实际路由定义为准）。 ### 7.2 统一错误响应 业务错误返回 JSON 结构包含字段：`error_code`、`message`、`request_id`，由全局异常处理器注册，保证客户端可程序化解析。 ### 7.3 数据库与迁移 业务表模型分散于各 `features/*/models.py`，并在 `app/main.py` 中间接 import 以聚合到 `Base.metadata`。一切结构变更必须通过 `api/alembic` 版本脚本完成。应用启动时可在 `run_alembic_upgrade_at_startup` 中自动执行 `upgrade head`，生产可配置失败即退出。 ### 7.4 核心实体（语义级） | 实体 | 语义 | | ---------------------- | ---------------------------- | | User | 注册用户、凭据哈希、画像字段 | | Conversation / Session | 对话容器，关联多条消息 | | ConversationMessage | 单条用户或助手消息，WebSocket 与历史查询的真源 | | Memoir / Chapter | 回忆录与章节树；阅读片段与导出依赖其内容 | | MemoryChunk | 向量检索用的记忆块 | | Order / Payment | 订单与支付流水 | | Plan / Quota | 套餐定义与用户使用额度 | --- ## 第 8 章 开发状况与测试结果说明 ### 8.1 当前实现状态（与仓库说明对齐） 下列能力在根目录 `README.md` 中标记为已实现或持续演进，著作权文档在此做技术化转述： 1. 用户注册与登录（手机号与密码）。 2. 基于 JWT 的访问令牌与刷新令牌机制。 3. 基于 WebSocket 的实时语音与文本对话。 4. AI 引导访谈与画像采集分支（由 `ChatOrchestrator` 路由）。 5. 语音识别与语音合成适配（具体厂商由配置与适配器决定）。 6. 对话内容向章节与回忆录结构的整理与异步处理。 7. 回忆录章节管理与 PDF 导出能力。 8. Android 端本地数据能力（Room 等，详见客户端工程）。 9. 离线数据同步相关能力（详见客户端工程）。 10. 用户套餐与订单支付相关能力。 11. 常见问题与反馈入口（用户域接口与客户端页面）。 标记为规划或进行中的能力（如更多传记模板、章节编辑深化、多语言等）以仓库 `README.md` 最新描述为准，本说明书不将其表述为已完成交付。 ### 8.2 测试策略与自动化范围 后端测试以 `pytest` 为主，辅以 `httpx.AsyncClient` 与 `ASGITransport` 进行异步 HTTP 场景测试。项目规则强调： 1. 测试应服务真实业务场景，避免仅为覆盖率堆砌无断言价值的用例。 2. 优先覆盖核心用户路径、鉴权与配额、幂等性与关键持久化状态。 3. 不优先测试第三方库自身行为或脆弱实现细节。 4. 测试应用 `dependency_overrides` 替换数据库与外部依赖，避免直接 import 生产入口带来的环境副作用。 典型可自动化部分包括：注册登录与刷新链路、受保护资源访问、主要 CRUD 与失败分支。依赖真实 ASR、TTS、LLM、短信、支付沙箱的全链路测试多在手工或独立 E2E 环境执行。 ### 8.3 测试结果表述方式建议 在向登记机关提交「测试结果」材料时，可将以下内容整理为附录表格或截图说明： 1. 本地或 CI 执行 `uv run pytest` 的命令、通过用例数量与跳过用例原因。 2. 关键模块的覆盖率报告（若政策允许附带 `pytest-cov` 摘要）。 3. 手工测试用例清单：WebSocket 多轮对话、回忆录生成端到端、支付回调联调（若适用）。 本说明书不嵌入具体 CI 截图，以免与仓库演进不同步；导出 PDF 前由实施者替换为当期报告。 --- ## 第 9 章 安装、配置与使用方法 ### 9.1 获取源代码 通过版本控制系统克隆 `life-echo` 仓库，检查 out 的分支与标签与本次登记版本一致。 ### 9.2 后端本地开发（推荐路径） 在 `api/` 目录： 1. 安装 `uv` 并执行 `uv sync --dev` 安装运行与开发依赖。 2. 复制环境变量模板为 `.env`，按 `api/README.md` 填入数据库 URL、Redis URL、JWT 密钥、LLM 与 ASR 相关 Key 等。 3. 使用 `docker compose -f docker-compose.dev.yml up -d` 或项目提供的一键脚本启动 PostgreSQL 与 Redis。 4. 执行 `uv run alembic upgrade head`（若未依赖启动时自动迁移）。 5. 执行 `uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000` 或通过 `./dev-up.sh` 拉起 API 与 Celery。 环境变量优先级与 LLM 提供商选择逻辑以 `api/README.md` 与 `app/core/config.py` 为准。 ### 9.3 内部评测入口 在 `api/` 目录执行 `uv run uvicorn app.internal_main:internal_app --host 0.0.0.0 --port 7999`（端口以实际环境变量为准）。在另一终端于 `app-eval-web/` 执行 `npm install` 与 `npm run dev`，通过浏览器访问 Vite 提示的本地地址操作评测台。 ### 9.4 移动端使用 在 `app-expo/` 目录执行 `npm install` 与 `npx expo start`，按 Expo CLI 提示在模拟器或真机打开应用。将 API 基础地址指向已启动的后端（含合法 TLS 或开发环境豁免配置），完成登录后即可使用对话与回忆录功能。具体网络权限与麦克风权限以各平台 `app.json` / 插件配置为准。 ### 9.5 生产部署注意 1. `SECRET_KEY` 与所有第三方密钥必须来自安全存储。 2. CORS `allow_origins` 在生产应收敛为前端真实域名，而非通配。 3. 建议将 `ALEMBIC_STARTUP_FAIL_FAST` 设为严格模式以避免实例在错误 Schema 下带病运行。 4. Celery Worker 与 Beat 应与 API 分离进程或容器，并为 `memory_idle` 等专用队列配置合理并发。 ### 9.6 日志与排错 业务代码使用 `app.core.logging.get_logger(__name__)` 取得 logger，便于按 request id 关联。出现 4xx/5xx 时优先检查错误体中的 `request_id` 与服务端日志同一时间窗口。