Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@tcm-kb 我最近怕冷乏力，帮我做个中医体质测评"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
通用大模型没有中医养生这块专业能力——辨证、方剂配伍、药性禁忌是成体系的专业积累，不在通用语料里， 所以它的回答常常既错误又无据可查。本项目是一个面向中医养生咨询的垂直领域智能体： 以自建权威语料（古籍 + 现行标准，452 万字）为知识底座， 打通「问诊追问 → 检索重排 → 安全审查 → 方案生成」全链路， 并把"答错代价高"的判断从 LLM 概率链路里剥离出来。
技术栈：Python · FastAPI · LangGraph · chromadb · bge-m3 · bge-reranker-v2-m3 · DeepSeek（Function Calling）· SQLite · MCP
⚠️ 免责声明：本项目用于技术演示与健康科普。输出内容不构成医疗诊断或用药建议，出现不适请及时就医。
Related MCP server: Drug Interaction MCP Server
能力 | 说明 |
知识底座 | 32 份 / 12,053 块 / 452.9 万字中医语料向量库（古籍 + 现行标准 + 自建安全语料）；按文件指纹与提取器版本号增量入库，扩库只重算变更块 |
两段式检索 + 自反思 | 向量粗排 top-16 → 交叉编码器精排 top-4；复用精排分数当检索质量传感器，低于阈值自动改写查询重检、取历史最优（口语提问精排分 0.11 → 0.62） |
Multi-Agent 编排 | 四通道前置分流 + 五角色流水线 + 三专科专家并行扇出；安全审查持一票否决权，打回重规划上限 2 次后降级输出——异常时也不会没有方案 |
安全层（独立于 RAG） | 毒性中药 / 慢病西药冲突 / 特殊人群硬编码规则库，在 LLM 之前优先路由；危险等级五档，命中即给「能做 / 不能做 / 需先确认」判读，不看语料覆盖、也不问模型置信度 |
三层记忆 | 近期原文（保真）+ 早期纪要（压缩保量）+ 跨会话档案与长期记忆（保值）；记忆按会话作用域隔离 |
接诊档案与追问 | 规则化抽取年龄/性别/慢病/西药/在服中药食疗；缺舌象、寒热、二便等最小充分条件时强制追问，信息补齐前不给方剂级内容 |
多格式语料管线 |
|
全链路持久化 | 会话、消息、问诊状态、用户档案、长期记忆、每轮安全判读全落 SQLite，重启不丢（刷新页面安全提示仍在） |
MCP 协议化出口 | 把检索、体质判定、缺口识别、安全审查封装为 4 个标准工具 + 3 个只读资源，支持 stdio 与 HTTP 两种模式 |
可验证 | 130+ 断言的三层测试（工具逻辑 / 协议 / 部署配置）+ 12 项零 API 回归 + 42 条评估集 |
flowchart TB
subgraph L1["接入层"]
A1["Web 问答页 /"]
A2["Web 问诊页 /agent"]
A3["CLI：ask · agent · multiagent"]
A4["MCP Server（stdio / HTTP）"]
end
subgraph L2["应用层"]
B1["Multi-Agent 编排（LangGraph）"]
B2["RAG 会话：记忆 · 改写 · 自反思检索 · 生成"]
B3["安全判读层（硬规则，先于 LLM）"]
end
subgraph L3["能力层"]
C1["bge-m3 向量检索"]
C2["bge-reranker-v2-m3 交叉编码器精排"]
C3["DeepSeek 对话与 Function Calling"]
end
subgraph L4["数据层"]
D1["chromadb 向量库（12,053 块）"]
D2["SQLite：会话 · 档案 · 记忆 · 安全卡"]
D3["data/ 语料（32 份 / 452 万字）"]
end
L1 --> L2 --> L3 --> L4三个设计取向贯穿全项目：
确定性的归代码，语义的归模型——禁忌、档位、信息缺口这类"有唯一答案、答错代价高"的判断全部落在规则与代码里，LLM 只负责理解与表达。
失败要留痕——降级可以，但不能无声。所有兜底分支必须打印堆栈，否则"功能没生效"会被伪装成"这次没有风险"。
判定口径单一来源——同一语义只在一处定义（如档位由 safety/tiers.py 单点派生），避免多处实现各自漂移。
离线建库（python -m app.index）：
语料 → Unicode 归一化（清部首码位污染）→ 切块 → bge-m3 向量化 → 两阶段写入 chromadb增量策略：以文件指纹 + 提取器版本号做 manifest 比对，只重算变更文件的块；改切块逻辑时必须把
app/index.py::EXTRACTOR_VERSION +1，否则新旧块会混在同一个库里静默沿用旧向量。
在线检索（python -m app.rag / Web）：
flowchart LR
Q["用户提问"] --> C["指代改写：多轮追问还原为独立问题"]
C --> R["向量粗排 top-16"]
R --> RR["交叉编码器精排 top-4"]
RR --> J{"top1 精排分 ≥ 0.40 ?"}
J -->|是| G["生成回答 + 逐条来源标注"]
J -->|否| W["改写为中医术语检索串（口语 → 术语）"]
W --> R自反思闭环的取舍：不额外训练 critic 模型，直接复用链路里已有的精排分数当质量信号； 重检最多 2 轮并取历史最优，避免"改写本身引入了新风险"。
图结构与 python -m app.multiagent --graph 输出的边关系一一对应：
flowchart TD
S(["用户提问"]) --> RT{"router 前置分流"}
RT -->|红旗症状| UG["urgent 直接建议就医"]
RT -->|尚无体质判定| NC["need_consult 转问诊"]
RT -->|纯知识快问| FA["fast 快速问答"]
RT -->|需要方案| CO["collector 汇总事实"]
CO --> DG["diagnoser 辨证归纳"]
DG -->|信息不足| NM["need_more 强制追问"]
DG -->|红旗| UG
DG -.->|并行扇出| DE["diet_expert 食疗"]
DG -.->|并行扇出| ME["meridian_expert 经络穴位"]
DG -.->|并行扇出| MO["movement_expert 运动起居"]
DE --> PL["planner 汇总成方案"]
ME --> PL
MO --> PL
PL --> SF{"safety 安全审查"}
SF -->|通过| ED["editor 编辑定稿"]
SF -->|打回，最多 2 次| PL
SF -->|越界或跨层冲突| UG
ED --> E(["方案 + 安全卡"])
FA --> E
NM --> E
NC --> E
UG --> E前置分流是三层的：规则管安全（红旗短路，不经 LLM）→ LLM 管意图（完整流水线 / 快速问答）→ 代码管前置条件（想要方案但没测体质 → 先转问诊）。
三专科专家同一超步并发（LangGraph 条件边返回列表），扇入 planner 只跑一次，耗时约等于最慢的一个专家。
否决回环有上限：安全审查打回重规划最多 2 次，超限进降级输出——质量守门但不死锁。
防线 | 位置 | 拦什么 |
① 规则库前置路由 | 任何 LLM 调用之前 | 毒性药材、特殊人群、慢病用药冲突；命中直接给判读，模型无权改写结论 |
② 零-LLM 确定性汇总 | 主控节点 | 多专家结论合并成稿时，档位与冲突结论由代码拼装，不经过模型润色 |
③ 交付前程序化校验 | 出口 | 六模块完整性、档位一致性、引用可采信性、药名外泄守卫；有违规或红旗时一律不放行 |
危险等级五档：forbid / not_needed / confirm / conditional / ok，
判定口径是「自行食用或自行加用」，不含医师辨证处方。
Python 3.12
两个 API Key：DeepSeek（对话）、SiliconFlow（bge-m3 向量 + 重排）
可选：影印本 PDF 走 OCR 时需要 pypdfium2 + rapidocr_onnxruntime
git clone https://github.com/djp0417/tcm-rag-agent.git
cd tcm-rag-agent
conda create -n rag-agent python=3.12 -y
conda activate rag-agent
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simplecp .env.example .env # Windows: copy .env.example .env
# 编辑 .env，填入 DEEPSEEK_API_KEY / SILICONFLOW_API_KEY
python check_env.py # 验证依赖版本 + 两个 API 连通性所有入口都必须用
python -m 模块名方式运行（python app/xxx.py会 import 失败）。
python -m app.index --report-only --no-ocr # 只出《语料构成报告》，不写库、零 API 消耗
python -m app.index # 建库（影印本自动 OCR，耗时较长）
python -m app.server # Web：问答 http://127.0.0.1:7860 ；问诊 /agent
python -m app.server --port 7861 # 7860 被占时换端口（启动会先做端口预检）
python -m app.ask -q "阳虚体质有什么表现" # CLI 单次提问
python -m app.ask # CLI 交互多轮
python -m app.agent --demo # CLI 自动跑一遍完整体质辨识python -m app.multiagent --selftest # 控制流自检（秒级、零 API，先跑这个）
python -m app.multiagent --graph # 打印流程图（mermaid）
python -m app.multiagent --list # 列出可用于流水线的会话
python -m app.multiagent --conv 13 "帮我出一份完整的调理方案"变量 | 用途 | 说明 |
| 对话模型 | 必填 |
|
| 必填 |
.env 只从项目根目录读取（app/llm.py、app/embed.py、app/rerank.py 三处加载），且已被
.gitignore 排除——请勿提交或外发。除这两个 Key 外无其他必填配置。
# 零 API 回归（不发一次请求，秒级）
python -m tools.test_architecture # 架构层五条验收
python -m tools.test_precision # 精度与稳定性 55 项
python -m tools.test_safety_rules # 安全规则层（在服用判定 / 停药识别）
python -m tools.test_inquiry # 追问引擎（意图闸门 / 兜底）
python -m tools.test_memory_isolation # 记忆隔离（新会话无记忆 / 显式回忆通道）
python -m tools.test_origin_gating # 命中来源分流
python -m tools.test_mcp_tools # MCP 工具层 71 项
python -m tools.test_mcp_server # MCP 协议层 42 项（真起子进程走 JSON-RPC）
python -m tools.verify_mcp_config # MCP 部署校验 26 项（照宿主配置启动）
python -m app.multiagent --selftest # 多 Agent 控制流 A~I 共 9 段
python -m app.eval --validate # 测试集与语料一致性校验
# 真机端到端（需先起临时实例，会打真实 API）
python -m app.server --port 7862
E2E_PORT=7862 python -m tools.e2e_safety_check
E2E_PORT=7862 python -m tools.test_fresh_session
E2E_PORT=7862 python -m tools.test_plan_endpoint⚠️ "零 API" ≠ "不需要 Key"：上面这些命令不会发起任何请求，但
app/embed、app/llm在 import 期 就会构造客户端，.env没配好会直接抛Missing credentials——看起来像测试挂了，实际是环境没配。
量化评估：eval/testset.jsonl 共 42 条（域内 37 / 域外 5），覆盖体质 / 四季起居 / 素问 / 灵枢 /
难经 / 本草食养 / 抱朴子 / 千金方（OCR）/ 口语化追问 / 域外拒答十类。
python -m app.eval --validate # 先校验测试集（标注写错是评估失真的最大来源）
python -m app.eval --retrieval # 仅检索指标（含自反思对照）
python -m app.eval --full # 四项全跑，出 JSON + Markdown 报告指标 | 回答什么问题 |
金标块召回 kw_hit@4 | 这个块真的召回对了吗（书级粒度太粗，这条才是主指标） |
recall@1 / 书级 recall@4 / MRR | 命中哪本书、排在第几 |
答案忠实度 | 有没有幻觉（LLM-as-judge：每条论断能否在参考资料溯源） |
拒答正确率 | 域外该拒，域内误拒同样算失败 |
长期记忆保持率 | 第 1 轮说过的话，第 9 轮和新建会话还记得吗 |
历史基线（4345 块库）：自反思检索把 金标块召回从 81.1% 提升到 89.2%（+8.1pt）、 关键词覆盖 +8.1pt、MRR 0.887 → 0.914，域外拒答 100%。
把领域能力做成标准协议出口，让支持 MCP 的宿主（WorkBuddy / Claude Desktop / 各类 IDE 客户端）直接调用：
python -m app.mcp # stdio 模式（宿主拉起的标准方式）
python -m app.mcp --http # HTTP 模式，只绑 127.0.0.1:7863工具 | 作用 |
| 语料检索（返回带来源的片段，含自反思重检） |
| 九分法体质辨识（27 题得分 → 主体质 / 兼夹 / 调养要点） |
| 算信息缺口并给建议追问（上限 3 条） |
| 安全判读（药材 / 食材 / 西药 × 状态 → 五档结论） |
只读资源：tcm://kb/manifest（语料清单）、tcm://guide/scope（能力边界与红旗症状）、
tcm://session/{id}（会话档案）。
宿主配置示例（stdio）：
{
"mcpServers": {
"tcm-kb": {
"command": "<你的 python 绝对路径>",
"args": ["-m", "app.mcp"],
"env": {
"PYTHONPATH": "<本项目根目录的绝对路径>",
"PYTHONIOENCODING": "utf-8"
}
}
}
}两个必须注意的点（踩过的坑）：
PYTHONPATH 不能省：python -m 的 import 发生在进入包内 os.chdir 之前，光靠代码自切目录救不了"找不到包"。
stdio 模式下 stdout 是协议流：任何 print 都会污染它，宿主机报的却往往是"JSON 解析错误"，离原因很远——所以本项目日志一律走 stderr。
rag-agent-app/
├─ check_env.py # Step 0：依赖版本 + 两个 API 连通性自检
├─ app/
│ ├─ rag.py # RAG 会话：三层记忆 + 改写 + 自反思检索 + 生成
│ ├─ selfrag.py # ★ 自反思检索：精排分数驱动查询改写与重检索
│ ├─ index.py # 建库：归一化 → 切块 → 向量化 → 两阶段写入 Chroma
│ ├─ textfix.py # ★ 中文 PDF 部首码位污染归一化（数据库前必跑）
│ ├─ paths.py # ★ chroma 库路径工具（规避中文绝对路径缺陷）
│ ├─ memory.py # 三层记忆（含语义去重）
│ ├─ intake.py # 接诊层：档案抽取 / 一致性校验 / 跨轮时间线 / 信息缺口
│ ├─ inquiry.py # ★ 追问引擎：意图闸门 + 程序化兜底
│ ├─ contract.py # ★ 输出契约：模块自检 + 档位一致性 + 药名外泄守卫
│ ├─ credentials.py # 引用可采信性：剔除迷信 / 巫术性记载
│ ├─ storage.py # SQLite 七张表
│ ├─ server.py # FastAPI：会话 CRUD + 问答 SSE + 问诊 SSE + 记忆面板
│ ├─ safety/ # ★ 安全层：规则库 / 扫描器 / 五档分级引擎 / 话术层
│ ├─ agent/ # ★ 体质辨识 Agent：量表内核 / 状态机 / function calling 主循环
│ ├─ multiagent/ # ★ 多 Agent 流水线：状态 schema / 提示词 / 节点 / 确定性护栏 / 图装配
│ └─ mcp/ # ★ MCP Server：对外契约文案 / 工具纯函数 / 只读资源 / 装配
├─ tools/ # 回归脚本（不在主链路里，专门用来"证明它真的对"）
├─ web/ # 问答页与问诊页（原生 HTML/JS 单文件，无构建依赖）
├─ data/ # 知识库原文（见 data/README.md）
└─ store/ # chroma 向量库 + chat.db + OCR 缓存（均不入库）把资料放进 data/，重跑 python -m app.index 即可增量入库。
格式 | 说明 |
| 首选。带 |
| 自动识别 5 种编码（utf-8 / gbk / gb18030 / big5 / utf-8-sig） |
| 文字版直接抽取；影印本自动走 OCR（逐页断点续跑，结果磁盘缓存） |
三条纪律：
中文 PDF 入库前先做 Unicode 归一化——部分 PDF 文本层会把字形映射到 Unicode「部首区」（⼈ ≠ 人），
本项目实测曾导致 33.9% 的块检索失效、5 本古籍 100% 中招，修法是数据库前统一跑 app/textfix.py。
改了切块或归一逻辑，必须把 EXTRACTOR_VERSION +1，否则 manifest 对不上，旧被静默沿用。
入库后跑一次 python -m app.eval --validate，确认零残留。
⚠️ 语料版权：仓库不包含原书 PDF（多为现代出版物与国家标准，公开再分发有版权风险）。
data/ 里只保留 6 篇自建知识卡片作为示例，其余请自行获取——语料类别与建库方式见
data/README.md。
现象 | 处理 |
| 没激活环境，或没用 |
401 / invalid api key |
|
| 违反 chromadb 铁律：打开库必须走 |
召回内容答非所问 | 确认 |
语料里明明有这个词却搜不到 | 大概率是 PDF 部首码位污染；跑 |
| 检查 |
页面一直转圈但日志刷 200 OK | SSE 锁被客户端断开焊死（锁绝不能跨 |
端口 10048（7860 被占） | 多半是上次服务没退干净； |
阶段 0：高质量 RAG 基座（两段式检索 / 多轮改写 / 持久化 Web / 多格式语料）
阶段 1：语料补全（10 部典籍 + 影印本 OCR + 多编码兼容）
阶段 2：问诊 Agent（体质辨识状态机 + 自反思检索 + 长期记忆）
阶段 3：量化评估体系（固定测试集与判分口径）
阶段 4：Multi-Agent 协作（四通道分流 + 五角色流水线 + 三专家并行扇出，LangGraph 编排）
阶段 5：安全层（独立于 RAG 的硬规则判读 + 五档分级 + 交付前程序化校验）
阶段 6：MCP Server（4 工具 + 3 资源，stdio / HTTP 双模式）
阶段 7：知识库持续扩充（第二批权威语料入库、gold 重标注、链路级评估补全）
MIT © 丁建鹏
This server cannot be deployed
Hosted MCP for denial, prior auth, reimbursement, workflow validation, batch scoring, and feedback.
A paid remote MCP for Equibles, built to return verdicts, receipts, usage logs, and audit-ready JSON
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Hosted MCP app for guided anxiety, depression, and well-being self-checks.
