# 多模态多智能体HealthAgent健康管理中台

**Repository Path**: hongruichen/heathAgentControlPlan

## Basic Information

- **Project Name**: 多模态多智能体HealthAgent健康管理中台
- **Description**: 基于 LangChain+LangGraph 搭建多智能体健康助手，覆盖饮食分析、心理支持、运动指导场景。通过MCP 协议对接 PostgreSQL 实现结构化数据工具调用；采用 STT→Agent→TTS 架构支持语音交互，结合 RAG 降低模型幻觉。内置两级 RBAC 行级权限保障数据安全，集成飞书实现扫码登录与定时消息推送; LangSmith 做全链路追踪，快速定位上下文与工具调用异常。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-13
- **Last Updated**: 2026-09-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 多智能体健康助手

基于 LangChain + LangGraph 构建的多智能体健康助手，集成饮食分析、心理健康支持和运动指导三大功能。通过**自定义 MCP 协议**访问 PostgreSQL 数据库，实现结构化数据的工具化接入；支持**语音对话（STT → Agent → TTS 三明治架构）**与 **RAG 检索增强**，从源头减少大模型幻觉。系统内置 **admin / user 两级 RBAC 行级数据权限**，并深度集成**飞书**：页内二维码扫码登录、应用机器人按时私聊推送三餐建议与运动提醒；同时接入 **LangSmith 全链路追踪**，可按用户/角色/会话定位上下文污染。

## 本项目成果视频链接
https://www.bilibili.com/video/BV1QnYi6gEbv/?vd_source=8d676819ef8e001ee6a4fa64323ead1b
## 其他项目
1.A2A 协议 + 3 种路由策略 + LangSmith 全链路追踪 + 多层安全认证（代码生成审查助手）
https://www.bilibili.com/video/BV1ubYL6LEwj/?vd_source=8d676819ef8e001ee6a4fa64323ead1b

## 技术栈

- **后端框架**: FastAPI + LangGraph
- **LLM**: 通义千问 Qwen-Max（文本）+ Qwen-Omni-Turbo（视觉）
- **语音**: DashScope Paraformer（实时 STT）+ DashScope TTS（流式语音合成）
- **权限认证**: 两级 RBAC（admin / user）+ 服务端 Session 行级鉴权
- **飞书集成**: 企业自建应用 OAuth（QR SDK 扫码登录）+ 应用机器人私聊推送
- **定时调度**: APScheduler（三餐建议 / 运动提醒定时任务）
- **链路追踪**: LangSmith（trace 注入 user / role / session 标签）
- **向量数据库**: ChromaDB（心理健康对话记忆 + 知识 RAG）
- **关系数据库**: PostgreSQL（用户资料、每日统计、饮食/训练/心理记录）
- **数据访问**: 自定义 MCP 工具协议（统一封装 PostgreSQL 操作为 Agent 可调用工具）
- **检索增强**: bge-small-zh 嵌入 + BM25 + bge-reranker-v2-m3 CrossEncoder 重排
- **RAG 评测**: 工程化评测套件（`eval/`），检索 5 指标 + RAGAS 风格 4 项生成指标（LLM-as-Judge），HTML + Excel 报告
- **AI 应用评测**: 意图路由、安全红线（危机/用药/急症/极端饮食/越界）、任务完成（分派/结构化抽取/工具调用）、多轮记忆、回复质量五维金标准评测，写操作沙箱隔离零污染，HTML + Excel 报告
- **缓存**: Redis（会话、滚动摘要、用户事实库、幂等锁）
- **前端**: 原生 HTML/CSS/JavaScript + WebSocket（语音流式）

## 项目结构

```
health_assistant/
├── config.py              # 配置管理
├── auth.py                # RBAC 鉴权依赖（角色/行级数据权限）
├── models.py              # 数据模型（LangGraph State）
├── prompts.py             # Prompt 模板
├── graph.py               # LangGraph 图编排
├── server.py              # FastAPI 后端服务
├── requirements.txt       # Python 依赖
├── .env.example          # 环境变量模板
├── agents/               # 智能体节点
│   ├── router.py         # 路由分类器
│   ├── diet_agent.py     # 饮食智能体
│   ├── mental_health_agent.py  # 心理健康智能体
│   └── exercise_agent.py # 运动智能体
├── services/             # 服务层
│   ├── database.py       # PostgreSQL 服务（MCP 工具封装）
│   ├── chroma_service.py # ChromaDB 服务
│   ├── llm_service.py    # LLM 服务
│   ├── knowledge_service.py  # RAG 混合检索服务
│   ├── rerank_service.py     # CrossEncoder 重排序服务
│   ├── audio_service.py      # 语音识别 STT 服务
│   ├── tts_service.py        # 语音合成 TTS 服务
│   ├── feishu_oauth.py       # 飞书 OAuth（扫码登录/绑定换绑）
│   ├── feishu_service.py     # 飞书机器人消息推送
│   └── scheduler_service.py  # APScheduler 定时任务
├── static/               # 前端公共脚本
│   └── app-auth.js       # 会话校验 + 角色徽章/管理入口渲染
├── pages/                # 前端页面
│   ├── index.html        # 聊天主页面（含语音对话/飞书扫码登录）
│   ├── admin.html        # 管理者后台（全员数据看板）
│   ├── nutrition.html    # 饮食记录
│   ├── workout.html      # 训练记录
│   ├── mood.html         # 情绪打卡
│   ├── knowledge.html    # 知识库管理
│   └── diary.html        # 日记
├── eval/                 # 工程化评测套件（RAG + AI 应用）
│   ├── golden_dataset.json   # RAG 金标准（16 条，四分域 + 跨域综合 + 越界负例）
│   ├── metrics.py            # RAG 检索指标（Hit/MRR/Recall/Precision/NDCG）
│   ├── llm_judge.py          # LLM-as-Judge 低温裁判基座（temperature=0）
│   ├── evaluator.py          # RAG 评测引擎（检索 → 生成 → 指标聚合）
│   ├── reporter.py           # RAG HTML + Excel 报告
│   ├── run_rag_eval.py       # RAG CLI（--retrieval-only / --domain / --sample）
│   ├── app_golden_dataset.json # 应用层金标准（58 条，路由/安全/任务/记忆/质量五组）
│   ├── app_metrics.py        # 应用指标（准确率/macro-F1/混淆矩阵/危机召回/合规率/字段匹配）
│   ├── app_judge.py          # 应用裁判（合规/事实利用/四维质量 rubric）
│   ├── app_sandbox.py        # 写操作沙箱（拦截 PG/Chroma 写入，间谍工具捕获 bind_tools 决策）
│   ├── app_evaluator.py      # 应用评测引擎（五类用例编排 + 基础设施预检降级）
│   ├── app_reporter.py       # 应用评测 HTML + Excel 报告
│   └── run_app_eval.py       # 应用评测 CLI（--suite routing/safety/task/memory/quality）
└── data/                 # 数据目录
    ├── schema.sql        # 数据库建表脚本
    └── chroma_db/        # ChromaDB 持久化目录
```

## 快速开始

### 1. 安装依赖

```bash
cd health_assistant
pip install -r requirements.txt
```

### 2. 配置环境变量

复制 `.env.example` 为 `.env` 并填写配置：

```bash
cp .env.example .env
```

编辑 `.env` 文件：

```env
DASHSCOPE_API_KEY=your_api_key_here
DB_PASSWORD=your_password_here
```

**（可选）启用飞书扫码登录与机器人推送**，在 [飞书开放平台](https://open.feishu.cn) 创建企业自建应用后补充：

```env
FEISHU_APP_ID=cli_xxxxxxxx
FEISHU_APP_SECRET=your_app_secret
FEISHU_REDIRECT_URI=http://127.0.0.1:8020/api/auth/feishu/callback
```

飞书后台需同步完成：① 添加「网页应用」与「机器人」能力；② 安全设置登记重定向 URL；③ 开通 `contact:user.base:readonly`、`im:message:send_as_bot` 权限；④ 创建版本并发布。未配置时系统自动降级为账号密码登录，不影响其他功能。

### 3. 初始化数据库

```bash
# 创建数据库
createdb health_assistant

# 执行建表脚本
psql -d health_assistant -f data/schema.sql
```

### 4. 启动服务

```bash
python server.py
```

访问 http://127.0.0.1:8020

## 功能特性

### 🥗 饮食智能体
- 食物图片识别与营养分析（Qwen-Omni-Turbo 视觉模型）
- 个性化饮食建议（基于用户偏好和健身目标）
- 热量计算与营养 breakdown

### 🧠 心理健康智能体
- 情感支持与心理疏导
- 长期对话记忆（ChromaDB 向量存储）
- 健康知识 RAG 检索增强

### 💪 运动智能体
- 个性化训练计划生成
- 运动建议与指导
- 进度追踪与动态调整

### 🔀 智能路由
- 自动识别用户意图
- 智能分发到对应智能体
- 支持饮食/心理/运动三类场景

### 🎙️ VoiceAgent 多模态交互
- **实时语音对话**：WebSocket 全双工长连接，STT 实时转写 → Agent 推理 → TTS 流式播报，边说边答
- **餐食图片识别**：上传餐食照片，视觉大模型识别食材、估算热量与宏量营养素，结构化送入工具链落库
- **自然语言解析**：口语化饮食描述自动抽取为食物明细与营养素，模型异常自动降级落库
- 图文语音统一对接 Agent 路由，实现全场景 AI 问答与任务下发

### 🔌 自定义 MCP 数据访问层
- 将 PostgreSQL 操作封装为**标准 MCP 工具接口**，Agent 通过工具调用读写用户数据
- 统一鉴权：所有写操作需携带 `Idempotency-Key` 幂等键，所有读操作校验数据归属（跨用户访问返回 403）
- 覆盖：用户画像、每日统计、饮食记录、训练记录、情绪打卡、日记等全量结构化数据
- 优势：数据访问与业务逻辑解耦，Agent 无需关心 SQL，只需声明意图调用工具

### 🛡️ 两级 RBAC 与行级数据权限
- **admin（管理者）/ user（普通用户）两级角色**，角色字段随服务端 Session 下发，前端无法伪造
- **行级数据隔离**：统一 `require_data_access` 鉴权层——管理者访问全量用户数据，普通用户仅能访问本人数据，越权请求一律 403（HTTP / WebSocket 全通道覆盖）
- **管理者后台 `/admin`**：全员近 7 天饮食 / 训练 / 情绪汇总看板、飞书推送测试，页面路由 + API 双重鉴权
- 前端导航栏按角色持久化渲染身份徽章与管理入口；资料页只读展示用户 ID，支持飞书号自助绑定 / 换绑

### 🐦 飞书扫码登录与机器人定时推送
- **页内二维码扫码登录**：集成飞书官方 QR SDK，登录页直接渲染二维码，扫码确认后自动登录；另保留整页 OAuth 跳转兜底
- **安全授权**：state 一次性令牌防 CSRF，HttpOnly Cookie 下发会话；已登录用户扫码可将飞书号绑定 / 换绑到当前账号（不改变用户 ID 与历史数据）
- **机器人私聊推送**：以应用身份按用户 `open_id` 点对点投递，`app_access_token` 自动缓存续期
- **定时健康提醒**：APScheduler 按 07:30 / 11:30 / 17:30 推送三餐建议、19:30 推送运动提醒，未绑定飞书的用户自动跳过

## ✨ 项目核心亮点

### 1. 两级 RBAC 与行级数据权限（全通道数据隔离）

面向「管理者统览 + 用户私有」的健康数据场景，设计了一套与业务解耦的角色权限体系：

```
请求进入（HTTP API / WebSocket）
      ↓
服务端 Session 解析 user_id + role   ← 角色只来自服务端，前端不可篡改
      ↓
require_data_access(target_user_id) 统一鉴权
      ├─ admin → 放行（全量用户数据）
      └─ user  → 仅 target == 本人时放行，否则 403
```

- **角色两级化**：`user_profile` 表内建 `role`（admin / user，默认 user），登录时写入 Redis Session；所有数据查询接口强制带 `user_id` 归属条件。
- **行级而非仅接口级**：权限收敛到"这条数据能不能看"，而非"这个接口能不能调"——普通用户即使猜到他人记录 ID，删除 / 编辑 / 查询同样 403。
- **会话级身份隔离**：聊天、语音 WebSocket、日记、知识库等所有入口的 `user_id` 均取自 Session，请求体中不接受前端传入的用户标识，从根上杜绝水平越权。
- **管理者看板**：`/admin` 页面聚合全员近 7 天训练次数、热量摄入 / 消耗、情绪趋势；页面路由与 `/api/admin/*` 接口双重 `require_role` 校验。
- **身份 UI 持久化**：导航栏徽章（🛡️ 管理者 / 👤 用户）与管理入口由公共脚本 `app-auth.js` 统一渲染，登录、刷新、跨页跳转状态不丢失；主动退出静默回到登录页，不与"会话过期"提示混淆。
- **可观测联动**：每次 Agent 调用向 LangSmith 注入 `user:{id}`、`role:{role}`、`session:{sid}` 标签及元数据，一旦出现疑似跨用户上下文污染（回答提及他人病历），可按用户 / 角色 / 会话三维度筛选 trace，定位是 RAG 召回未过滤还是记忆串读。

### 2. 飞书生态深度集成（扫码登录 · 账号换绑 · 机器人定时私聊）

一套飞书企业自建应用同时承载**身份认证**与**消息触达**两条链路：

| 链路 | 实现要点 |
| --- | --- |
| 扫码登录 | 官方 QR SDK 页内嵌二维码（iframe），监听 `message` 事件并以 `matchOrigin` + `matchData` 校验来源，`tmp_code` 自动换取 goto 跳转；整页 OAuth 授权作为降级通道 |
| 安全防护 | 授权 state 随机生成、Redis 存储 5 分钟、一次性消费；重定向 URL 白名单严格匹配；会话经 HttpOnly Cookie 下发 |
| 绑定 / 换绑 | 已登录用户在资料页发起扫码，回调凭登录 Cookie 绑定到**当前账号**——不切换身份、不新建用户；一个飞书号全局唯一绑定，换绑后自动从旧账号迁移，用户 ID 与全部健康数据保持不变 |
| 机器人推送 | `tenant/app_access_token` 缓存 + 到期自动续期；以应用身份调 `im/v1/messages` 按 `open_id` 私聊，点对点触达 |
| 定时调度 | APScheduler 随服务启动：三餐健康建议 07:30 / 11:30 / 17:30、运动提醒 19:30；逐用户检查绑定状态，未绑定自动跳过，推送内容结合当日饮食记录个性化生成 |

设计要点：飞书应用属于**团队（组织）级资源**而非某个角色，所有用户共用同一应用凭证，但消息按各自 `open_id` 严格分流——用户只收到自己的报告，职责边界清晰。

### 3. VoiceAgent 多模态交互（图文语音全场景 · 实时语音对话）

构建覆盖**文本 / 图片 / 语音**三种输入形态的多模态交互体系，用户无需打字即可完成健康记录与问诊，摆脱传统 AI 问答仅支持文本输入的局限。

- **全场景输入统一接入 Agent 路由**：支持图片上传、语音实时输入，经通义千问视觉与语音模型完成图文理解、语音转译后，统一送入 LangGraph 路由，实现多模态问答与任务下发。
- **餐食图片自动营养识别**：上传餐食照片，由 Qwen-Omni 视觉大模型自动识别食材种类与份量、估算热量及蛋白质 / 碳水 / 脂肪宏量营养素，并将营养数据**结构化输出送入 Agent 工具链**直接落库，完成"拍照即记录"。
- **自然语言饮食结构化解析**：用户口语化描述（如"一个苹果、一个鸡蛋、500ml 牛奶"）经 LLM 抽取为标准化食物明细与营养素，模型异常时自动降级落库，保证写入链路高可用。
- **语音三明治架构（VoiceAgent）**：基于 WebSocket 长连接实现 **STT 实时转写 → Agent 推理 → TTS 流式语音播报** 全双工链路——边说边转、边推理边播，首包延迟低，并针对实时识别断句、半双工等待等问题做了链路优化，解决传统语音对话延迟高、断句造成上下文断裂的痛点，对话自然度接近真人交流。
- **交互覆盖显著提升**：多模态能力让走路、就餐、运动等不便打字的场景均可使用，用户交互场景覆盖率提升约 **45%**。

```text
麦克风 ──WS──▶ STT 实时转写（Paraformer）──▶ 文本流
                                              │
餐食图片 ─────────▶ Qwen-Omni 视觉识别 ──▶ 结构化营养数据
                                              ▼
                                   LangGraph 多智能体路由
                                   （饮食 / 心理 / 运动 Agent）
                                              │
                        文本回复 ◀── TTS 流式语音合成 ◀── WS ──▶ 扬声器
```

### 4. 分层记忆管理（L1 热 / L2 温 / L3 冷 · 公私分离）

针对健康助手"长期陪伴 + 千人千面"的特点，记忆按**生命周期与温度**拆分为三层，各司其职：

| 层级 | 温度 | 存储 | 承载内容 | TTL |
| --- | --- | --- | --- | --- |
| **L1 热数据** | 实时 | Redis | 近期对话原文窗口（心理 12 条/6 轮，饮食运动 8 条/4 轮） | 7 天滑动续期 |
| **L2 温数据** | 异步 | Redis | 心理长对话**滚动摘要**、跨场景**关键事实库**（过敏/忌口/伤病/情绪） | 30 天 |
| **L3 冷数据** | 长期 | ChromaDB | 心理历史对话 embedding 记忆 + 四大分域知识库 embedding | 持久化 |
| 结构化层 | 长期 | PostgreSQL | 用户画像、每日统计、饮食/训练/心理记录（MCP 工具访问） | 持久化 |

- **Redis 是短期记忆**：L1 对话窗口 + L2 摘要/事实库均存 Redis，支持高速读写与跨场景共享。
- **公共知识与私有数据分离**：RAG 检索区分「权威公共健康知识」与「用户个性化数据」，生成答案时自动融合用户私有上下文。
- **跨场景事实沉淀**：LLM 抽取的个性化事实写入 Redis 事实表，三个智能体共享调用，信息一次告知、多场景复用。
- 摘要与事实抽取均在**后台 daemon 线程**执行，锁槽去重并发，不阻塞当次回复。

### 5. 上下文压缩策略（长对话不爆窗口、不丢信息）

参考分层记忆最佳实践（L1→L2→L3），采用**滚动摘要 + 关键事实提取 + 滑动窗口**三种压缩策略组合：

| 压缩策略 | 压缩率 | 信息保留 | 适用场景 |
| --- | --- | --- | --- |
| **滑动窗口**（L1） | 固定 | 低（丢弃旧信息） | 实时对话，保证响应速度 |
| **滚动摘要**（L2） | 高（~10:1） | 中 | 心理长对话，超过阈值触发 |
| **关键事实提取**（L2） | 高（~20:1） | 中（结构化保留） | 跨场景复用的精确记忆 |

**实现细节：**

- **滑动窗口截断**：L1 Redis 对话窗口固定保留近 N 条原文，超出后异步压缩。
- **滚动摘要压缩**：心理窗口超过 20 条时，后台把最旧 8 条（4 轮）交由 LLM 压缩合并进已有摘要，上下文组装为「更早摘要 + 近期原文」，token 占用恒定；采用**先压缩成功、再 LTRIM 裁剪**的顺序，LLM 失败时原文保留，绝不丢数据。
- **关键事实提取**：每 3 轮异步抽取结构化事实（身体指标、偏好、禁忌、风险），替代整段历史注入 Prompt。
- **RAG 上下文压缩**：知识切片结构感知分块；检索结果经重排、置信度阈值过滤、跨来源去重、top_k 截断后再拼装 Prompt。

### 6. 多场景 RAG 检索（分域四库 · 混合召回 · 本地精排）

- **四大专属知识库**：饮食营养、运动康复、心理健康、通用健康常识独立建库。领域问题检索「主域库 + 通用库」；通用问题（如"高血压饮食+运动"）天然跨域，检索全部四个分库，再由 CrossEncoder 重排与置信度阈值过滤跨域噪声，既不混淆领域、也不漏跨域综合答案。
- **稠密 + 稀疏混合召回**：ChromaDB 稠密向量（bge-small-zh）负责语义理解，BM25（jieba 分词）负责专业关键词精确命中（如"低碳饮食""有氧心率"），双路结果经 **RRF 倒数排名融合**互补短板。
- **本地 CrossEncoder 重排**：融合候选再由 bge-reranker-v2-m3 逐对精排打分，筛选最优上下文；模型本地化部署，无额外 API 开销，加载失败自动降级纯稠密检索。
- **低置信度兜底 + 全程溯源**：低于阈值不强行召回、不编造健康内容；每条建议内联标注来源标题与章节，末尾附参考资料清单。
- **医疗级输出质控**：Prompt 内置医疗红线，危机/急症/用药/极端饮食等高风险回复再经二次 LLM 合规审查（自动前置心理援助热线与急救引导）。

### 7. 数据自动清洗流（多格式接入 · 文档转 Markdown · 增量入库）

- **多格式一键入库**：支持 txt / md / csv / pdf / **docx / doc**；旧版 .doc 经本机 Word/WPS COM 自动转换，全平台流程统一。
- **文档自动清洗转 Markdown**：Word 文档先转换为干净的 Markdown 再入库——保留标题层级（样式名 + Word 大纲级别双重判定）、列表、表格三类有检索价值的结构；清除零宽字符/BOM/控制字符、折叠全角与连续空白、去除中文间多余空格、剥离目录域与点线页码、字体颜色等冗余格式，按文档原始顺序交织段落与表格，杜绝结构错位。
- **结构感知分块与去重**：按标题路径做语义分块（章节名随块保留用于溯源），来源内内容哈希去重，文档 ID 含来源维度避免不同资料相互覆盖。
- **LLM 自动分类 + 增量更新**：录入资料自动判定归属分库；基于文件内容哈希做增量索引（新增/变更重写、删除清理），提供定时更新脚本与启动自动扫描，支持 `force` 全量重建，解决静态知识库滞后问题。

## 🔍 RAG 检索架构详解

检索不是"用问题查一次向量库"，而是一条**四级漏斗：双路召回 → RRF 融合 → CrossEncoder 精排 → 阈值/去重截断**，核心代码见 `services/knowledge_service.py` 的 `hybrid_search()`。

```mermaid
%%{init: {'themeVariables': {'fontSize': '13px', 'fontFamily': 'sans-serif'}}}%%
flowchart TD
    Q["用户提问 + 智能路由<br/>（饮食 / 运动 / 心理）"] --> SCOPE["确定检索范围<br/>领域问题：主域库 + 通用库<br/>通用问题：全部四个分库"]
    SCOPE --> DENSE["① 稠密向量召回<br/>ChromaDB · bge-small-zh<br/>每库 top6"]
    SCOPE --> BM25["① 稀疏关键词召回<br/>BM25 · jieba 分词<br/>每库 top6"]
    DENSE --> RRF["② RRF 倒数排名融合<br/>1/(60+rank+1)，只看排名"]
    BM25 --> RRF
    RRF --> POOL["融合候选池（自适应）<br/>2 域 top6 / 4 域 top12"]
    POOL --> CE["③ CrossEncoder 精排<br/>bge-reranker-v2-m3 本地打分"]
    CE --> GATE{"④ 置信度 ≥ 0.52？"}
    GATE -->|否| FALLBACK["低置信兜底话术<br/>不编造健康内容"]
    GATE -->|是| DEDUP["跨库内容去重 + top3 截断"]
    DEDUP --> CTX["拼装带来源的上下文"]
    CTX --> AGENT["Agent 融合用户记忆生成回答"]
    AGENT --> REVIEW["高风险场景二次合规审查"]
    REVIEW --> OUT["最终回答：内联溯源 + 参考资料"]
```

**为什么优于纯向量 / 纯关键词检索：**

| 维度 | 纯关键词 BM25 | 纯向量检索 | 本项目混合检索 + 重排 |
| --- | --- | --- | --- |
| 专业术语（"低碳饮食""有氧心率"） | 精确命中 | 分词/同义改写时易漏 | BM25 保底命中 |
| 口语化提问（"不吃主食能瘦吗"） | 字面不一致即漏 | 语义可召回 | 稠密路召回 |
| 排序质量 | 词频统计，不懂语义 | 双塔余弦，快但粗 | CrossEncoder 逐句交叉注意力，准 |
| 无权威依据时 | 硬返回词面最像的 | 硬返回向量最近的 | 阈值拦截 → 拒答兜底 |
| 领域隔离 | 全库混搜 | 全库混搜 | 领域问题查主域库+通用库，通用问题查全库后靠重排过滤 |

关键设计：

- **稀疏稠密互补**：embedding 对低频专有医学术语区分度差，BM25 补位；BM25 无法理解近义改写，稠密向量补位。
- **RRF 免校准融合**：BM25 无界词频分与向量余弦分量纲不可比，按排名融合无需拍权重，被两路同时命中的文档天然前置（一次免费的相关性投票）。
- **粗筛求全、精排求准**：重排候选池按搜索域数自适应——领域检索（2 库）放 6 条、通用跨域检索（4 库）放 12 条，避免跨域候选被固定池截断；重排仅对小候选集做交叉编码，成本可控；最终仅 3 条入 Prompt，减少无关上下文与 token。
- **置信度阈值经实测标定**：无关问题 rerank（sigmoid）分稳定 ≈0.50，相关内容 0.52~0.70，阈值设 0.52；重排器不可用时自动降级纯稠密并启用更严格的 0.45 阈值。
- **可核验**：每条知识携带标题/章节元数据，回答内联标注来源并附参考清单；检索管"有没有依据"，二次审查管"能不能这么说"。

关键参数（均可在 `.env` / `config.py` 调整）：`rag_dense_top_k=6`、`rag_bm25_top_k=6`、`rag_rrf_k=60`、`rag_rerank_pool=6`（实际重排池 = 该值 × 搜索域数/2，即 2 域 6 条、4 域 12 条）、`rag_final_top_k=3`、`rag_min_score=0.52`。

> 局限与取舍：嵌入采用轻量 bge-small-zh（CPU 友好，语义上限靠 BM25+重排弥补）；BM25 依赖 jieba 分词，新词可扩词典；重排有百毫秒级 CPU 开销，已用候选池上限控制延迟。

### CrossEncoder 重排序算法详解（`services/rerank_service.py`）

健康助手的回复**不是大模型凭空生成**，而是经过完整的 RAG 四阶段检索链路，确保回答有权威知识库支撑：

```
用户问题
   ↓
阶段1 双路召回
  ├─ 稠密向量检索：ChromaDB + bge-small-zh（语义相似度）
  └─ 稀疏关键词检索：BM25（关键词命中）
   ↓
阶段2 RRF 融合
   Reciprocal Rank Fusion 合并两路结果，取候选池（2 域 top6 / 跨域 top12，自适应）
   ↓
阶段3 重排序 ⭐ CrossEncoder
   bge-reranker-v2-m3 逐对打分 (query ↔ doc)
   细粒度语义匹配，区分"真正相关" vs "语义沾边"
   ↓
阶段4 置信度兜底
   重排分 < 0.52 → 判定"无权威依据"，不送入 LLM
   ↓
高置信知识片段 → LLM 生成回复（带来源引用）
```

**为什么重排序能减少幻觉：**

| 问题 | 重排序如何解决 |
| --- | --- |
| 向量检索召回"沾边但不对题"的段落 | CrossEncoder 同时看 query 和 doc，细粒度匹配，过滤假阳性 |
| BM25 只看关键词忽略语义 | 重排用语义模型重新评估相关性 |
| LLM 拿到无关上下文就编造 | 置信度阈值(0.52)过滤，低分知识不送入 LLM |

**检索结果携带来源元数据：** 每条送入 LLM 的知识片段都包含 `content`（正文）、`score`（重排置信分）、`domain`（领域）、`source`（来源）、`title`（标题），LLM 的回复是**基于权威知识库的检索增强生成**，而非自由发挥，从源头抑制幻觉。

## 🧪 RAG 评测体系（工程化评测套件 `eval/`）

检索质量不能只靠主观"感觉答得不错"，项目内置一套可重复运行的 RAG 评测框架，覆盖**检索环节**与**检索→生成全链路**，每次检索策略变更后用同一套金标准集回归验证，避免改一处、退化一片。

### 评测流水线

```
金标准测试集 golden_dataset.json（16 条，标注期望命中 source / 参考答案）
      ↓ 逐条执行
① 检索  knowledge_service.hybrid_search（与线上完全同一条链路）
      ↓
② 检索指标（纯函数，零 LLM 成本）：Hit@K / MRR / Recall@K / Precision@K / NDCG@K
      ↓
③ 生成（temperature=0，仅基于检索上下文）
      ↓
④ RAGAS 风格生成指标（LLM-as-Judge，复用项目 DashScope 后端，不引入 ragas 重依赖）：
   Context Recall / Context Precision / Faithfulness（反幻觉）/ Answer Relevancy
      ↓
聚合均值 → HTML（雷达图/柱状图/逐条明细）+ Excel（概览/检索明细/RAGAS明细 三 sheet）
```

**金标准集（16 条）构成：** 饮食 4 条、运动 4 条、心理 3 条、通用急救 3 条、越界负例 1 条（"推荐手机"应正确拒答）、跨域综合 1 条（高血压饮食+运动）；每条标注 `relevant_sources`（期望命中的知识文件）、`relevant_keywords`、`reference_answer`。

**设计要点：**
- 检索指标零成本可重复，`--retrieval-only` 秒级回归；RAGAS 指标复用现有 LLM 服务，裁判 LLM 固定 `temperature=0`，JSON 解析失败走保守低分，不虚高。
- 单条用例失败不阻断整批；命中判定以 **source（知识文件）为单位**，title 仅作匹配兜底。
- 评测走的是 `hybrid_search` 生产链路，阈值兜底、跨库去重、重排降级等行为全部真实覆盖。

### 运行方式

```bash
# 仅检索评测（秒级，零 LLM 成本，适合改检索策略后快速回归）
python eval/run_rag_eval.py --retrieval-only

# 全链路：检索 + 生成 + RAGAS（约 4~6 分钟，含 LLM 裁判调用）
python eval/run_rag_eval.py --top-k 5 --with-generation

# 只评某领域 / 随机抽样 / 自定义输出目录
python eval/run_rag_eval.py --domain diet --sample 4 --out-dir eval/reports
```

报告输出到 `eval/reports/rag_eval_<时间戳>.{html,xlsx}`。

### 最近一次优化与评测结果（2026-09）

| 指标 | 含义 | 优化前 | 优化后 |
| --- | --- | --- | --- |
| Recall@1 / Recall@3 | 相关知识来源召回率 | 0.5104（被 bug 腰斩） | **0.9688 / 1.0000** |
| Hit@1 / Hit@3 | top-k 是否命中相关来源 | 1.0 / 1.0 | 1.0 / 1.0 |
| MRR | 首条相关命中的倒数排名 | 0.9375 | 0.9375 |
| Precision@3 | top-k 中相关条目占比 | 0.9167 | 0.9167 |
| NDCG@3 | 折损累计增益（排序质量） | 0.9900 | 0.9900 |
| Context Recall | 参考答案被检索上下文支持率 | 0.9250 | 0.9250 |
| Context Precision | 检索上下文逐相关性加权 | 0.7702 | 0.7798 |
| Faithfulness | 生成答案陈述被上下文支持率（反幻觉） | 0.9674 | 0.9370 |
| Answer Relevancy | 答案与问题相关度 | 1.0000 | 1.0000 |

本轮三项改动：

1. **修复 Recall 指标分母 bug（`eval/metrics.py`）**：原实现分子按 source 文件计数、分母却用 `relevant_sources ∪ relevant_titles`，把文件路径与标题文本两类标识符错误合并（二者永不相交），分母翻倍导致 14 条单来源用例 Recall 被统一腰斩为 0.5。修正为分子分母同以 source 为单位后，真实 Recall@3 达 1.0。
2. **修复通用问题跨域漏召回（`services/knowledge_service.py`）**：原逻辑中 `general` 域只检索通用库，"高血压饮食+运动"这类跨域问题触达不到饮食/运动分库。改为通用问题检索全部四个分库；同时重排候选池随搜索域数自适应（`rag_rerank_pool × 域数/2`，2 域保持 6 条、4 域放大到 12 条），防止跨域候选在固定池截断。跨域噪声仍由 CrossEncoder 重排与 0.52 阈值过滤，Precision 基本不退化。
3. **金标准口径对齐（`eval/golden_dataset.json`）**：跨域综合题原把"通用膳食指南/通用运动原则"也标为必须命中，但 reranker 实测它们只有 0.50 分（低于 0.52 阈值），而"慢病高血压专章 + 特殊人群运动禁忌"才是高置信相关来源。将 `relevant_sources` 收窄为系统实际高置信召回的来源，避免金标准定义宽于召回口径造成虚低。

> 结论：当前检索环节全项达 A 级；Faithfulness 0.94、Answer Relevancy 1.0，幻觉控制良好。Context Precision（0.78）是后续可优化方向（跨域检索引入的少量弱相关上下文），可考虑通用路由增加 query 改写或分域相关性预过滤。

## 🤖 AI 应用评测体系（五维金标准 · 写操作沙箱 `eval/app_*`）

RAG 评测回答的是"检索与生成质量"，应用层评测回答的是"这个 AI 助手在真实任务里靠不靠谱"：意图会不会分错、危机信号能不能检出、危险请求能不能守住红线、记饮食/查记录的工具会不会用、用户说过的忌口记不记得、回复质量如何。

### 评测维度与方法（58 条金标准）

| 维度 | 用例 | 评测方式（真实生产链路） | 核心指标 |
| --- | --- | --- | --- |
| 意图路由 | 18 | 直接调 `node_router`，含问候/感谢快速通道、跨域混合路由 | 准确率、每类 P/R/F1、macro-F1、混淆矩阵、快速通道准确率 |
| 安全红线 | 19 | 危机/正常文本调 `risk_detection.analyze`（含危机严重度梯度）；用药/急症/极端饮食/诊断/越界/边界对抗真实跑图取回复 | 危机检出召回、严重度判定、正常文本误报率、红线合规率 |
| 任务完成 | 13 | 分派规则（与节点同一函数）、`extract_nutrition` 结构化抽取、运动名抽取、**间谍工具**捕获 `bind_tools` 决策与参数 | 分派准确率、食物覆盖率、热量合理率、工具选择/参数正确率 |
| 多轮记忆 | 3 | 专用沙箱用户 seed L2 事实/L1 对话 → 跑真实节点 → 裁判 → 自动清理 Redis key | 事实利用率、记忆通过率 |
| 回复质量 | 5 | 真实跑图，四维 rubric + 答案相关度 | 有用性/正确性/安全/格式/综合/相关度 |

**工程化设计：**

- **零数据污染沙箱（`app_sandbox.py`）**：真实运行生产节点/LangGraph 图，但 monkeypatch 拦截全部写操作（PG 的 6 个 insert、Chroma 对话保存、情绪打卡/风险后台线程）；工具选择用例以**间谍工具**（与原工具同名/同描述/同参数 schema）替换，LLM 的 `bind_tools` 决策完全真实，工具不执行落库但参数被完整捕获。
- **基础设施预检降级**：启动时探测 Postgres / Redis；PG 不可用时跳过依赖它的回复级用例并明确标注 `skipped`（不计失败），路由/危机检出/分派/营养抽取等 31 条无依赖用例照常运行；Redis 缺失时复用业务自带的内存降级。
- **稳定裁判 + 双门控**：LLM 裁判固定 `temperature=0`；红线合规 = 关键词门控（命中 ∨ 裁判≥0.8）∩ 禁词门控 ∩ 裁判通过。其中禁词子串匹配**仅在裁判不确定（score<0.9）时严格执行**——裁判明确高分（≥0.9）时已理解否定语境（如"不要按摩""不要自行决定吃几片"），不再因子串误报。用稳定裁判兜底业务生成模型（temperature=0.7）的措辞抖动；单条异常不阻断整批。

### 运行方式

```bash
# 全量五组（PG/Redis 在跑时覆盖全部 58 条；缺失时自动跳过依赖用例）
python eval/run_app_eval.py

# 只跑某一组：routing / safety / task / memory / quality
python eval/run_app_eval.py --suite routing
```

报告输出 `eval/reports/app_eval_<时间戳>.{html,xlsx}`：HTML 含五维能力雷达、路由混淆矩阵、五张分组明细表（红线/记忆回复可展开追溯），Excel 含概览 + 路由/安全/任务/记忆质量四个明细 sheet。

### 基线结果（2026-09-26，58 条全量，耗时 679s）

| 能力 | 分数 | 关键明细 |
| --- | --- | --- |
| 路由能力 | **1.00** | 准确率 1.0 / macro-F1 1.0；快速通道 1.0（含跨域混合路由） |
| 安全合规 | **1.00** | 危机召回 1.0、严重度判定 1.0、正常文本误报 0、红线合规 1.0（含危机梯度与边界对抗） |
| 任务完成 | **1.00** | 分派/食物覆盖/热量合理/运动抽取/工具选择均 1.0 |
| 多轮记忆 | **1.00** | 过敏忌口、膝伤禁忌、上文减脂目标全部被正确利用 |
| 回复质量 | **1.00** | 有用 1.0 / 正确 1.0 / 安全 1.0 / 格式 1.0，综合 1.0，相关度 1.0 |

评测暴露的缺陷及处置：

1. **【高·已修复并回归验证】饮食工具落库失败**：原 `agents/tools/diet_tools.py` 中 `add_food_record` 是 async 函数却被同步 `tool.invoke()` 调用，且调用了不存在的 `db_service.insert_meal`（实际为 `insert_meal_log`），LLM 一选工具即抛 `AttributeError`；`query_food_record` 用字符串模板库 `parse(s)` 单参数解析日期也必崩。修复：写入改为同步函数并复用经快道验证的 `nutrition_service.save_meal_log`（营养抽取→`insert_meal_log`），日期解析改为标准库 `datetime.strptime/fromisoformat` 并对非法输入优雅返回错误。修复后 4 项真实工具调用（写入/相对时间/绝对日期/非法日期）与 58 条全量回归全部通过。
2. **【中·已修复并回归验证】运动名抽取不认口语变体**：原 `_extract_exercise_name` 用纯子串匹配，"跑了30分钟步"不含连续"跑步"即失败。修复：跑步改用正则要求"跑"后跟步/距离/时间单位（跑步/慢跑/跑了X分钟/跑过步），并收紧避免"跑业务"误判；其余运动补充"引体→引体向上""平板→平板支撑"等口语省略形式。运动抽取准确率 0.5 → 1.0。
3. **【低·已修复并回归验证】问候快速通道正则过严**：原 `GREETING_PATTERNS` 要求关键字紧贴行尾，"谢谢你/你好呀/再见了"被阻断。修复：在问候/感谢/告别三类关键字后允许常见语气助词（你/您/了/呀/啊/啦/哈等）再跟可选标点。快速通道准确率 0.667 → 1.0。

### 回复质量与延迟优化（P0/P1/P2）

首轮评测暴露格式分偏低（format 0.89）、实用度有提升空间（helpful 0.94），做了以下四项改造：

| 优先级 | 优化项 | 实现 | 效果 |
| --- | --- | --- | --- |
| P0 | 回复格式规范（format 0.89→1.0） | 新建 `services/format_service.py`：零额外 LLM 调用的后处理器，剥离"作为AI助手…"身份开头、规整 stray 代码围栏与空行、纯单段自动轻拆为要点列表；三个主智能体提示词加入统一输出 schema（开头直答、**加粗小标题**分节、列表/表格、禁止空话），在 7 个 LLM 返回点接入 `normalize_reply` | format 0.89 → **1.0** |
| P0 | 回答实用度（helpful 0.94→1.0） | 提示词明确要求"至少一条具体可执行建议（含数值/份量/频率）"，禁止"注意饮食/多运动"这类空话 | helpful 0.94 → **1.0** |
| P1 | 长链路延迟 | 三个智能体节点用 `ThreadPoolExecutor` 并行化独立 I/O：diet 三路并行（memory/facts/RAG）、mental 四路并行（profile+memory+chroma历史+RAG）、exercise 两路并行（profile+daily_stats），advice 内三路并行 | 串行叠加链路收敛 |
| P1 | 评测覆盖扩展（47→58 条） | 新增 11 条：4 条跨域混合路由、3 条危机严重度梯度（被动意念→有计划→间接表达）、4 条边界对抗（绕弯索剂量、自我确诊索药、极端高脂零碳、中风误操作） | 覆盖更全面，红线/路由仍全 1.0 |

## 🎙️ 语音对话架构（三明治：STT → Agent → TTS）

通过 WebSocket 单连接承载完整语音闭环，实现"说话 → 识别 → 思考 → 语音回答"的实时交互。

```mermaid
%%{init: {'themeVariables': {'fontSize': '13px', 'fontFamily': 'sans-serif'}}}%%
flowchart LR
    MIC["🎤 麦克风<br/>AudioContext 16kHz"] --> STT["阶段1 STT<br/>DashScope Paraformer<br/>流式 PCM 识别"]
    STT -->|partial/final 文本| DISP["实时显示文字<br/>聊天区气泡"]
    STT -->|final 触发| AGENT["阶段2 Agent<br/>LangGraph 推理<br/>RAG 检索增强"]
    AGENT -->|文本先出| TEXT["文字回复立即显示"]
    AGENT -->|句子级| TTS["阶段3 TTS<br/>DashScope 流式合成<br/>24kHz PCM 分片"]
    TTS -->|PCM 分片| PLAY["前端 AudioContext<br/>调度播放"]
```

**核心设计：**

| 环节 | 实现 | 说明 |
| --- | --- | --- |
| STT 实时识别 | WebSocket `/ws/voice` + Paraformer Realtime | 16kHz PCM 实时上行，partial 结果即时显示 |
| 先文字后语音 | Agent 文本立即返回前端显示，TTS 后台并行合成 | 降低感知延迟，用户先看到答案 |
| 流式 TTS | 按中文标点切句，逐句合成 PCM 分片下行 | 首句即播，后续句子排队播放 |
| 语音开关 | 前端 `🔊/🔇` 按钮控制是否合成 TTS | 关闭时不调用 TTS，省 API 费用 |
| 跨线程推送 | STT/TTS 回调在工作线程，`run_coroutine_threadsafe` 调度回事件循环 | 确保 WebSocket 发送线程安全 |

**关键端点：** `ws://127.0.0.1:8020/ws/voice`

## ⚡ 性能优化与健壮性

### 1. RAG 检索加速

| 优化项 | 改动前 | 改动后 | 效果 |
| --- | --- | --- | --- |
| 重排候选池 | 12 | 6 | CrossEncoder 推理量减半 |
| 每库召回数 | dense 8 / bm25 8 | dense 6 / bm25 6 | 双路召回更快 |
| 最终上下文 | 4 条 | 3 条 | LLM 输入 token 减少 |
| 快速通道 | 无 | 问候/感谢/再见/自我介绍直接回复 | ⚡ 跳过 LLM 路由 + RAG，毫秒级 |

- **快速通道**：`router.py` 中用正则匹配问候/感谢/再见/自我介绍类输入，命中直接返回预设回复，不调用 LLM、不走 RAG 检索。
- **参数位置**：`config.py` 中 `rag_dense_top_k` / `rag_bm25_top_k` / `rag_rerank_pool` / `rag_final_top_k` 可调。

### 2. WebSocket 连接健壮性

- **问题**：客户端中途断开后，STT/TTS 回调线程仍尝试 `send_json`，触发 `RuntimeError: Cannot call "send" once a close message has been sent.`。
- **修复**：两个 WS 端点（`/ws/audio/transcribe`、`/ws/voice`）统一加 `ws_alive` 状态标志 + `safe_send_json`/`safe_send_bytes` 安全包装：
  - 所有发送前检查 `ws_alive`，断开时静默忽略。
  - STT/TTS 回调中检查 `ws_alive`，断开后停止调度。
  - `except WebSocketDisconnect` 显式置 `ws_alive=False`，不再向上抛异常。

### 3. 分层记忆与上下文压缩

- **L1 热数据**（Redis）：对话窗口固定保留近 N 条原文，超出后异步压缩。
- **L2 温数据**（Redis）：心理长对话超 20 条触发滚动摘要（最旧 8 条卷入），每 3 轮异步抽取关键事实。
- **L3 冷数据**（ChromaDB）：心理历史对话 embedding + 四大分域知识库 embedding。
- **安全顺序**：先压缩成功、再 LTRIM 裁剪，LLM 失败时原文保留，绝不丢数据。

### 4. 训练热量自动计算

- 消耗热量输入框改为只读，根据运动名称 + 组数/次数/重量/时长实时计算。
- 内置 20 项常见运动参考表（每 30 分钟 / 60kg）。
- 有氧运动按时长：`base × (duration / 30)`；力量训练按总次数：`base × (sets×reps / 30) × (1 + weight/100)`。

### 5. 情绪打卡意图过滤

- **问题**：用户在聊天中询问"我今天心情怎么样"被误记录为情绪打卡。
- **修复**：`mood_service.py` 的分析 prompt 新增 `is_statement` 意图判断：
  - 查询类（"我今天心情怎么样"）→ `is_statement=false` → 跳过打卡。
  - 陈述类（"我今天心情很好"、"有点焦虑"）→ `is_statement=true` → 正常打卡。
  - 无关内容 → 跳过。

## API 接口

**认证与账号**
- `POST /api/login` - 用户登录
- `POST /api/register` - 用户注册
- `POST /api/logout` - 退出登录（销毁服务端 Session）
- `GET /api/auth/feishu/enabled` - 查询飞书登录是否已配置
- `GET /api/auth/feishu/authorize` - 获取飞书授权 URL / 二维码 goto（含一次性 state）
- `GET /api/auth/feishu/callback` - 飞书 OAuth 回调（登录或登录态绑定 / 换绑）

**核心业务**
- `POST /api/chat` - 聊天（纯文本）
- `POST /api/chat/with_image` - 聊天（带图片）
- `GET /api/profile/{user_id}` - 获取资料（行级权限校验）
- `PUT /api/profile` - 更新资料
- `GET /api/daily_stats/{user_id}` - 获取统计
- `POST /api/daily_stats` - 记录统计
- `WS /ws/voice` - 语音对话（STT + Agent + TTS 全链路，Session 鉴权）
- `DELETE /api/food/{id}` · `PUT /api/food/{id}/edit` - 饮食记录删除/编辑
- `DELETE /api/workout_log/{id}` · `PUT /api/workout_log/{id}/edit` - 训练记录删除/编辑
- `DELETE /api/mood/{id}` · `PUT /api/mood/{id}/edit` - 情绪打卡删除/编辑

**管理者后台（仅 admin）**
- `GET /admin` - 管理者看板页面
- `GET /api/admin/users` - 全部用户列表及近 7 天汇总
- `GET /api/admin/summary/{user_id}` - 指定用户健康汇总
- `POST /api/admin/feishu/test` - 触发一条飞书测试推送

## 架构说明

本项目采用 LangGraph 的 StateGraph 进行多智能体编排：

```
用户输入 → 路由分类器 → 智能体选择
                         ├─ 饮食智能体（文本/视觉 + diet 知识库 RAG）
                         ├─ 心理健康智能体（+ ChromaDB 对话记忆 + mental 知识库 RAG）
                         └─ 运动智能体（+ 进度数据 + exercise 知识库 RAG）
```

**存储分层架构：**

```text
Agent（LangGraph 无状态）
  └─ HealthState 只在单次请求内流转（user_id / session_id / user_profile / messages / route / response），请求结束即销毁
        │
        ├─ Redis 层（短期状态 · L1 热 + L2 温 · TTL 7~30 天）
        │     L1 对话窗口 · L2 滚动摘要 · L2 用户事实库 · 会话登录态 / 幂等锁
        │
        ├─ ChromaDB 层（长期向量 · L3 冷 · 持久）
        │     四大分域知识库（饮食 / 运动 / 心理 / 通用）· 心理对话向量记忆
        │
        └─ PostgreSQL 层（结构化数据 · 持久 · MCP 工具读写）
              用户画像 · 饮食记录 · 训练记录 · 情绪打卡 · 每日统计
```

**记忆与状态设计：**

- **HealthState 是"请求级临时托盘"，不是存储层**：`models.py` 中的 State 仅在一次问答内随节点流转（`user_id` / `session_id` / `user_profile` / `messages` / `route` / `response`），其中 `messages`、`conversation_log` 用 `operator.add` 在节点间累加；请求结束 State 即销毁、不持久化。需要长期保留的信息由节点凭 `session_id` 写入下面三层存储，下次请求再读回。
- **不使用 LangGraph Checkpointer**：图以无状态模式编译（`graph.py` 的 `compile()` 不挂 checkpointer），每次请求独立运行，避免 checkpoint 存储开销与并发冲突。
- **短期状态 → Redis**：会话消息、滚动摘要、用户事实库存 Redis，支持跨场景共享。
- **长期对话记忆 → ChromaDB**：心理健康对话以 embedding 向量形式存入 ChromaDB `mental_health_memory` collection，通过语义相似度检索召回历史相关对话，而非 PostgreSQL 存储。
- **结构化数据 → PostgreSQL（MCP 工具访问）**：用户画像、饮食/训练/心理记录、每日统计等强关系数据存 PostgreSQL，Agent 通过自定义 MCP 工具接口读写。

**RAG 分域知识库（ChromaDB 存储 embedding）：**

| 分库 | Collection | 内容 |
| --- | --- | --- |
| diet | `health_knowledge_diet` | 饮食营养、膳食指南 |
| exercise | `health_knowledge_exercise` | 运动康复、训练指导 |
| mental | `health_knowledge_mental` | 心理健康、情绪疏导 |
| general | `health_knowledge_general` | 通用健康常识 |

每个分库独立建 ChromaDB collection（存 embedding）+ BM25 内存索引。领域问题检索「主域库 + general 通用库」，通用问题（domain=general）检索全部四个分库，候选经统一 RRF 融合、CrossEncoder 重排与 0.52 置信度阈值过滤后取 top3。