feat(explain): 解读双模型对比

[bob798]

Summary

• 解读页面新增双模型并行对比功能（如 DeepSeek vs GLM）
• 用户可通过开关启用/关闭，默认关闭
• 主模型 + 对比模型同时请求，结果双栏展示

Context

用户希望在解读（Explain）页面中，能同时看到两个 LLM 对同一内容的解读结果（如 DeepSeek vs GLM），做横向对比。

• 交互形式：并行请求（A 方案），两模型同时调用
• 用户可通过开关控制是否启用双模型，默认关闭

设计方案

模型选择

当前 volcengine 注册表已有 deepseek-v3-250324 和 glm-4-7-251222，共用同一 API Key。
对比模型配置：

• 主模型：runtime_model.model（当前全局活跃模型）
• 对比模型：通过 MODEL_COMPARE_EXPLAIN 环境变量配置，格式 provider/model（如 volcengine/glm-4-7-251222）
• 若未配置对比模型，前端隐藏开关

改动清单

Step 1: 后端 — 支持指定模型调用

app/config.py

• 新增 get_compare_model(scene) 函数：读取 MODEL_COMPARE_<SCENE> 环境变量，返回 (provider, model_name) 或 None

app/services/model_client.py

• 新增 get_specific_client(provider, model_name) 工厂函数：按给定 provider+model 创建客户端实例
  • 复用 AnthropicClient / OpenAICompatibleClient，但允许覆盖 model

app/models/db.py — ExplanationCache 表

• 新增 model_tag 列（String, nullable=False, default=""）
• 唯一约束改为 (text_hash, kind, cefr_level, model_tag)
• 旧数据 model_tag="" 视为默认模型缓存，兼容无影响

app/services/explain_service.py

• _cache_get / _cache_set 增加 model_tag 参数
• explain_text() 增加可选 model_tag: str = "" 参数 → 非空时用 get_specific_client() 调用
• stream_sentence_explanation() 同理增加 model_tag 参数

app/routers/practice.py

• ExplainRequest 新增可选字段 model_tag: Optional[str] = None
• StreamExplainRequest 同理
• 新增 GET /practice/explain/models 接口：返回 { primary: "deepseek-v3", compare: "glm-4-7" | null }，前端据此决定是否显示开关

Step 2: 前端 — 双栏对比 UI

frontend/src/components/ExplanationModal.vue

• 新增状态：compareMode（boolean，localStorage 持久化）、compareData（同 data 结构）、compareLoading、compareError
• fetchExplanation() 改造：
  • 始终发主模型请求（不变）
  • compareMode 开启时，同时发第二个请求（model_tag=compare）
  • 用 Promise.all 并行
• Tab 栏右侧新增对比开关（小 toggle），仅在有 compare 模型时显示
• explain-box 内：
  • 单模型模式：保持现有布局不变
  • 双模型模式：上方展示模型名 tag，两栏左右排列（移动端改上下堆叠）
• 组件挂载时调一次 /practice/explain/models 缓存结果

不动的部分

• 免提模式、收藏、追问面板 — 均不变，始终基于主模型结果
• TTS 播放 — 始终播主模型内容
• IPA phonetic 本地查询 — 不涉及模型，不变

Test plan

• .env 配置 MODEL_COMPARE_EXPLAIN=volcengine/glm-4-7-251222
• 启动 uvicorn app.main:app --reload
• 解读一个单词 → 开关关闭时只看到一个结果
• 开启对比开关 → 并行出两个结果，模型名标签正确
• 句子流式解读 → 两栏各自流式渲染
• 关闭对比 → 恢复单栏
• 刷新页面 → 开关状态持久化
• 未配置 MODEL_COMPARE_EXPLAIN 时 → 开关不显示
• 回归：免提模式、收藏、追问不受影响

🤖 Generated with Claude Code

[bob798]

代码已在 main 中实现（runtime_model 热切换、model_router、get_scene_client 均已合入）。关闭过时 PR。