识礼小记的目标不是做一个开放式聊天玩具，而是把固定真实场景、AI 角色扮演、对话后评分和 RAG 话术推荐串成一个能被反复练习的沟通陪练产品。这个项目适合展示我从产品拆解、前端交互、后端分层、模型调用到测试验证的完整实现能力。
从固定场景开始，而不是开放聊天
开放聊天很容易变成泛泛而谈，用户也很难判断练习是否真的有效。因此我把首版入口收敛为固定场景：每个场景都有用户目标、关系类型、AI 角色、隐藏规则和评分重点。这样模型既有可扮演的上下文，也有可评价的目标。
这个设计让产品更像练习系统，而不是普通聊天框。用户进入练习前知道自己要面对什么情境，结束后也能看到自己在哪些表达、情绪、策略上需要改进。
- • 场景负责定义练习边界，包括关系、目标、限制和评分维度。
- • AI 角色只扮演对话对象，不向用户暴露幕后评分逻辑。
- • 复盘结果围绕可改进表达、关键转折和可复用话术组织。
端到端架构：小程序、后台、API 和模型网关
前端分为用户侧小程序和管理后台。小程序负责场景选择、流式聊天、推荐话术复制、复盘结果和历史记录；后台负责维护场景、角色和话术素材。
后端使用 FastAPI，按 auth、scene、phrase、practice、ai、rag 等模块拆分，并保持 router / service / repository / mapper 分层。这样做的好处是业务接口、模型调用、数据访问和对象转换各自有清晰边界，后续接入更多场景或模型 Provider 时不会挤在同一个入口里。
- • MySQL 保存用户、场景、会话、消息、评分和话术知识库。
- • Redis 用于支撑需要缓存或短期状态的链路。
- • Docker Compose 和部署文档用于把本地开发环境整理成可复现交付单元。
模型网关和 Prompt 边界
模型调用没有直接散落在业务代码里，而是通过 OpenAI-compatible 网关封装。网关支持普通对话、流式输出、JSON 生成、用量估算、失败 fallback 和调用日志，为后续切换 DashScope、百度或其他兼容接口留下空间。
Prompt 设计分为角色扮演和评分复盘两类。角色扮演 Prompt 强调 AI 的身份、关系和约束；评分 Prompt 强调结构化输出、评分维度和逐句分析。二者分开以后，练习过程可以保持沉浸，复盘过程则可以保持可解释。
RAG 话术推荐：让建议来自可维护素材
话术推荐没有完全依赖模型即兴生成，而是先根据场景、阶段、标签和关键词召回候选话术，再进行排序或可选重排。这样做能让推荐更贴近产品预设的沟通策略，也方便后台逐步维护话术知识库。
推荐链路会记录召回数、命中数和 fallback 原因。当用户当前语境没有足够匹配素材时，系统可以明确走降级策略，而不是假装一定找到了精准答案。
- • 场景和阶段帮助缩小候选范围。
- • 标签和关键词提供可解释的召回依据。
- • fallback 记录用于后续补充话术库和优化排序策略。
验证与公开边界
这个项目的验证重点放在 API 回归、模型 Provider 行为、评分 JSON 校验、权限隔离和模型配置异常降级上。AI 应用的不确定性无法彻底消除，但可以通过边界、日志、fallback 和测试把不确定性约束在可处理范围内。
当前网站只展示公开安全的功能、架构和职责信息。截图、演示地址、代码仓库和模型 Provider 配置都需要发布前确认，避免暴露真实配置、样例数据或不适合公开的内容。