🏥 大健康智能助手 (Smart Health Assistant)

🚀 开源版 医疗/医保 多智能体对话系统 —— 对标国内头部平台（如蚂蚁阿福、支付宝健康管家等）的 AI 健康助手落地架构。

基于 LangGraph + FastAPI + React 的完整 AI 多智能体全栈参考实现。不只是一个聊天机器人，而是深度融合了流式工具调用与结构化 UI 卡片的智能分发引擎。

• 已支持 多模态图片识别：拍照看报告、拍照问药与药品追溯码识别
• 支持 多模型配置：聊天模型可切换 ARK、OpenAI、DeepSeek、通义千问、智谱或任意 OpenAI-compatible 服务；图片模型可独立选择支持视觉输入的兼容模型
• 新增支持 RAG 知识库增强，包括常见疾病、医保政策、检验参考范围、药品用药指南等。 详见 docs/rag.md
• 新增支持 Agent Skills System，每个智能体均可动态加载模块化领域技能，无需修改 Agent 代码即可扩展能力。 详见 docs/skills.md
• 支持 开源可观测与评估：OpenTelemetry/OpenInference 链路、Jaeger 本地后端与 DeepEval 回归评估。详见 docs/observability-evals.md

📸 运行效果预览

这是一个 纯移动端（Mobile-First） 设计的项目，强烈建议使用 Chrome 手机独立模式体验。

1. 通用助手模式	2. 医保垂直大厅	3. 动态医保余额卡片
4. 近期消费明细报表	5. 月度缴费记录跟踪	6. 异地就医备案卡片
7. AI 诊室 (预问诊)	8. 医患流式问答	9. 拍报告 (报告解读)
10. 化验单指标分析	11. 药管家大厅	12. 药品知识图谱互答

✨ 核心特性

• 🧠 多智能体路由 (Multi-Agent Routing):

  • 采用总分架构。通过全局 Router Agent 实时进行意图分类，无缝调度至不同的垂直领域专家智能体。
  • 支持预问诊 (Clinic Agent)：多轮追问症状（部位、持续时间、伴随症状等），最终生成带严重等级的就诊科室建议卡片。
  • 支持医保服务 (Insurance Agent)：接入模拟医保接口，查询医保余额、消费明细、缴费记录、异地就医备案，数据通过卡片直出。
  • 支持健康问答 (Advisor Agent)：通用的医学科普与生活建议。
  • 支持药管家与报告解读：提供药品信息、相互作用查询、拍照问药，以及检查报告图片和检验指标解读。

• ⚡ 丝滑的 UI 端到端体验 (SSE + Server-Driven UI):

  • 后端接管 UI 渲染：工具调用完成后，后端不仅返回文字总结，还通过 SSE 下发 {"type": "card", "payload": ...} 事件。
  • 前端动态呈现：前端接收到事件后，实时在聊天气泡上下文中渲染出高颜值的定制卡片（如：带渐变背景、防窥探交互的医保卡片）。

• 👵 适老化无障碍设计 (Elder-Friendly Mode):

  • 一键切换长辈模式（大字体、高对比度、简化界面操作）。

• 📚 RAG 知识库增强 (Retrieval-Augmented Generation):

  • 内置混合检索引擎：BM25（精确匹配）+ 密集向量（语义检索），通过倒数排名融合（RRF）合并结果，精准命中医学术语的同时兼顾语义理解。
  • 覆盖四大领域知识库：常见疾病（高血压/糖尿病/心脏病）、医保政策（门诊/住院报销/异地就医）、检验参考范围（血常规/生化/尿常规）、药品用药指南（OTC/处方药/药物相互作用）。
  • 可插拔后端设计：嵌入模型支持 HuggingFace 本地（BAAI/bge-small-zh-v1.5，离线可用）、OpenAI API、字节 ARK API 三选一；向量库支持 Chroma / FAISS / Qdrant / pgvector 按需切换，全部通过环境变量配置。

• 🧩 可插拔技能系统 (Agent Skills System):

  • 每个智能体均可动态加载模块化领域技能，无需修改 Agent 代码即可扩展能力。
  • 内置 6 项核心技能：急症安全预检（emergency_triage）、症状严重度评分（symptom_scorer）、健康指标计算（health_calculator）、化验单解读（lab_interpreter）、慢性病风险评估（risk_assessor）、药物剂量计算（medication_calculator）。
  • 零配置自发现：新增技能只需创建子目录 + SKILL.md + skill.py，注册表启动时自动发现并挂载，按标签（clinic / advisor / report / pharmacy）分发至对应智能体。

• 🔭 开源可观测与评估 (Observability & Evals):

  • 使用 OpenInference 自动采集 LangGraph 节点、文本/视觉模型与工具调用，以标准 OTLP 输出到 Jaeger 或其他 OpenTelemetry 后端。
  • 内置匿名回归样例与严格本地评分，可选 DeepEval；医疗文本和图片默认不进入 Trace，DeepEval 遥测默认关闭。

• 🛠️ 完整全栈工程实现:

  • Backend: Python、FastAPI、LangChain、LangGraph、Uvicorn，遵循严格的类型提示和清晰的状态流转（State Graph）。
  • Frontend: React、TypeScript、TailwindCSS、Vite，针对移动端进行了像素级还原（Mobile-First）。

🏗️ 系统架构

项目的核心在于 “状态路由 + 工具卡片双向绑定”：

1. Agent State: messages, active_agent, userInfo。
2. Router Node: 识别用户意图，如果已经处于特定 Agent 的会话中，则“锁定”上下文直到用户主动退出（发送“结束/不看了”）。
3. Event Stream: 后端使用异步 Generator 透传 LangGraph 的内部运行状态（node_start, tool_start, tool_end, card）。前端依据流事件展示 Agent 执行状态与工具调用进度。
4. Lifecycle: 通过仓库内评估集复现问题、使用 OTLP Trace 定位节点，再以相同 case 验证迭代结果。

🚀 快速开始

本项目分为前端（React + TypeScript）和后端（Python FastAPI）两部分。

1. 后端服务 (Backend)

后端以 Python 编写，推荐使用 uv 进行环境管理。

cd backend

# 安装依赖项
uv sync

# 配置环境变量
cp .env.example .env
# 在 .env 中配置模型厂商、API Key 与模型名称，支持多家 OpenAI-compatible 服务

# 【首次运行】构建 RAG 知识库向量索引
# 默认使用本地 HuggingFace 嵌入模型，首次运行会自动下载约 90 MB 的模型文件
uv run python -m rag.ingest

# 启动服务 (运行于 8000 端口)
uv run uvicorn main:app --reload --port 8000

2. 前端服务 (Frontend)

前端基于 Vite 无打包构建，速度极快。

cd frontend

# 安装依赖
npm install

# 启动开发服务器 (运行于 5173 端口)
npm run dev

启动完成后，在浏览器中访问 http://localhost:5173。切换设备模拟为手机视图（iPhone 13 等）以获得最佳体感。

🛠 开发与定制

如何扩展 RAG 知识库？

1. 在 backend/rag/documents/ 目录下新建 Markdown 文件，使用 ## 章节标题 结构组织内容。
2. 重建向量索引：uv run python -m rag.ingest --rebuild

切换嵌入模型或向量库（通过环境变量）：

# 切换为 OpenAI 嵌入模型
EMBEDDING_PROVIDER=openai uv run python -m rag.ingest --rebuild

# 切换为 Qdrant 向量库（需先启动 Qdrant 服务）
VECTOR_STORE=qdrant QDRANT_URL=http://localhost:6333 uv run python -m rag.ingest --rebuild

详细说明参见 docs/rag.md。

如何为 Agent 添加新技能（Skill）？

技能是智能体的可插拔能力扩展，无需改动 Agent 代码即可增加：

1. 创建目录：mkdir backend/skills/my_skill && touch backend/skills/my_skill/__init__.py
2. 编写 SKILL.md（必填 name、description、tags frontmatter）
3. 实现 skill.py（继承 BaseSkill，定义 Pydantic I/O 和 run() 方法）
4. 启动后注册表自动发现，无需手动注册

详细说明参见 docs/skills.md。

如何监控和评估 Agent？

# 仓库根目录：启动本地 Jaeger
docker compose -f compose.observability.yml up -d

# backend/：运行匿名回归集；DeepEval 为可选依赖
cd backend
uv run python -m evals
uv run --extra eval python -m evals --provider deepeval

链路开关、隐私默认值和评估样例格式参见 docs/observability-evals.md。

如何增加一个新的 Agent？

1. 在 backend/agents 目录下新建 your_agent.py，并定义包含系统提示词和对应 tools 的 create_react_agent 实例。
2. 在 backend/agents/graph.py 中，定义一个 your_node 函数调用你创建的 agent。将它添加进图节点并连接来自路由器的 Edge。
3. 在 backend/agents/router.py 的提示词和分类器中，加入对你工具意图的理解定义。

如何增加一个前端 UI 卡片？

1. 后端调用工具后，在 main.py 的 SSE 拦截层，抓取输出并 yield { "type": "card", "payload": { "type": "your_card_type", "data": ... } }。
2. 前端 src/types/index.ts 中增加 ChatCardPayload 联合类型。
3. 在 frontend/src/components/chat/ChatCardRenderer.tsx 中编写你的 React 视图组件即可。

📜 规划与 Roadmap

• 多 Agent 路由调度核心 (LangGraph)
• 智能预问诊 & 报告科室推荐
• 基于流式卡片的医保服务面板 (对齐真实业务场景)
• 上下文环境隔离机制 (进入专科诊室 / 退出诊断)
• RAG 知识库增强：混合检索（BM25 + 密集向量）+ 可插拔嵌入模型与向量库
• 药管家 Agent（Pharmacy Agent）：药品查询、药物相互作用、OTC 推荐、附近药店
• 可插拔技能系统（Agent Skills）：6 项核心技能 + 零配置自发现注册表
• 多模态图片识别：拍照看报告、拍照问药与药品追溯码识别（可配置兼容模型）
• Agent 生命周期基础设施：OpenTelemetry/OpenInference 链路、Jaeger 与 DeepEval 回归评估
• 语音交互接入：实时 ASR 与 TTS（流式语音包反馈）

📄 开源协议

本项目采用 MIT License。你可以自由使用、修改和分发，但也请在你的项目中保留本项目的署名。

💡 鸣谢与灵感

本项目产品交互灵感来源于对医疗大健康赛道真实落地诉求的拆解，特别致敬业内优秀产品在“长辈模式”、“卡片富文本协同”领域的探索与实践。期待与开源社区一起，将这一套生产力框架推广到更多垂直泛健康场景。