# 童肾营养师·风险预警 Agent —— Mock MCP Server

> **团队编号**：NFYY038　|　**项目**：南方医科大学南方医院「童肾营养师」多智能体辅助决策系统
> **子智能体**：风险预警 Agent（复赛演示版）

本仓库是「童肾营养师」多智能体系统中**风险预警 Agent** 的自定义 MCP（Model Context Protocol）服务实现。它解决复赛阶段**无法接入真实 HIS / LIS、无法通过小程序真实推送**的约束，用**模拟数据 + 确定性硬规则引擎 + 北向报文/MQ 模拟**，完整复现「风险研判 → 等级判定 → 结构化报文推送 → 临床处置 SOP」的预警能力。

---

## 1. 它能做什么

| 能力 | 说明 |
|---|---|
| 南向 Mock·LIS 趋势 | `fetch_patient_biochemical_trends` 模拟调用院内 LIS，返回近 3 个月生化趋势、本次结果、变化百分比、身高/体重 Z 评分序列 |
| 硬规则引擎 | `evaluate_risk_rules` 把**全部阈值与涨幅计算下沉为确定性 Python 代码**，杜绝 8B 小模型算术幻觉 |
| 北向报文 + MQ 模拟 | `trigger_warning_event` 生成 `CKD-ALERT/1.0` 结构化报文，模拟抛出至消息队列并透传医生工作站 / 家长端微信小程序，返回投递回执 |
| 临床处置 SOP | `get_clinical_sop` 查询每条规则的主诊医生 / 护理 / 家长三视图处置建议与循证依据 |

**内置 5 个 MCP 工具**、**15 例虚构患儿**（覆盖 normal / abnormal / boundary / exception 四类场景）、**13 条硬规则**。

---

## 2. 架构与数据流

```
医生「研判指令输入」
        │
        ▼
┌──────────────────────────────────────────────────────────┐
│ 风险预警 Agent（8B 模型，仅组织自然语言）                  │
│   1. list_mock_patients            → 选定患儿              │
│   2. fetch_patient_biochemical_trends (南向 Mock①/LIS)    │
│   3. evaluate_risk_rules          → 硬规则引擎判定等级    │
│   4. trigger_warning_event        (北向 Mock②/推送+MQ)    │
│   5. get_clinical_sop             → 处置 SOP              │
└──────────────────────────────────────────────────────────┘
        │ 结构化 JSON 报文 (CKD-ALERT/1.0)
        ▼
┌──────────────────────────────────────────────────────────┐
│ 北向接口 / 消息队列（模拟 ⇒ 上线替换为 Kafka / 企微网关） │
│   topic: ckd.alert.pediatric                              │
└──────────────────────────────────────────────────────────┘
        │ 透传
        ▼
   医生工作站待办卡片  /  家长端微信小程序订阅消息
```

**硬规则（防幻觉红线）示例**：肌酐较基线涨幅 ≥50% → L1 一级 AKI；血钾 >5.5 mmol/L → L1 高钾危急；白蛋白 <35 g/L 且体重 Z 连续下降 → L2 PEW。完整 13 条见 `src/nfyy_ckd_risk_warning/rules.py` 与 `knowledge/`。

---

## 3. 安装与运行

### 方式一：PyPI / uvx（魔搭 MCP 广场部署用）
```bash
# 以 stdio 方式拉起服务（魔搭/Nexent 自定义 MCP 即如此调用）
uvx nfyy-ckd-risk-warning-mcp
```
> 服务配置 JSON（魔搭 MCP 广场「自定义创建-可托管部署」填法）：
> ```json
> { "mcpServers": { "nfyy038-risk-warning": { "command": "uvx", "args": ["nfyy-ckd-risk-warning-mcp"] } } }
> ```

### 方式二：源码安装（开发 / 评测）
```bash
python -m venv .venv && source .venv/bin/activate
pip install -e .
nfyy-ckd-risk-warning-mcp            # 等价于 python -m nfyy_ckd_risk_warning
```

### 本地 SDK 调用（不依赖 MCP 传输，便于单测/演示）
```python
from nfyy_ckd_risk_warning import server
# 输入今日生化报告 API 新结果，引擎自动对比上一次历史结果并重新研判
out = server.trigger_warning_event("C_8808", today_creatinine=165, today_potassium=5.8, today_albumin=33)
# out["reassessment"] -> 历史 L3 → 本次 L1 对照；out["payload"] / out["markdown"] -> 报文与 SOP
```

---

## 4. 复赛 Demo 演示要点

复赛无真实北向接口时，用「**研判指令输入** + 今日生化报告 API 模拟** 触发即可证明预警能力：

> 请对患儿 C_8808 进行风险研判。今日生化报告 API 回传：血肌酐 165 μmol/L，血钾 5.8 mmol/L，血清白蛋白 33 g/L。
> （患儿上一次历史结果：肌酐 95、血钾 5.4、白蛋白 43；历史系统判定 L3。）

Agent 经 `fetch（历史记录） → trigger（输入今日新报告，引擎自动对比上一次结果并重新研判）` 两步，输出：
1. **重新研判对照**：历史系统判定 L3 → 本次基于新数据重新研判 L1（肌酐 95→165 +73.7%≥50% → R-01；血钾 5.8>5.5 → R-02；白蛋白 33<35 且体重 Z 连降 → R-04），明确标注「历史等级被新数据推翻」；
2. **推送 JSON 报文**（`CKD-ALERT/1.0` 契约，含等级、命中规则、复查、循证）；
3. **临床处置 SOP**（Markdown：主诊医生 / 护理 / 家长 / 饮食红线 / 复查）；
4. **一句话结论摘要**（模型组织，附免责声明）。

> 说明：模拟数据 = 患儿历史记录；今日新血检结果（生化报告 API 模拟）是**重新研判的驱动方**——新数据优先、不沿用历史等级。本工具**不设「以系统/引擎为准」的强制纠偏**，历史系统判定仅作对比展示，最终等级由「今日新数据 + 上一次历史基线」的硬规则计算决定。

---

## 5. 目录结构

```
nfyy038-ckd-risk-warning-mcp/
├── src/nfyy_ckd_risk_warning/
│   ├── data/patients.json        # 15 例模拟患儿数据集（虚构）
│   ├── rules.py                  # 硬规则引擎（13 条）
│   ├── sop.py                    # 临床处置 SOP 文案库 + 循证
│   ├── store.py                  # 模拟 LIS/HIS 南向数据访问层
│   ├── payload.py                # 北向报文 + 消息队列模拟 + Markdown 渲染
│   ├── server.py                 # FastMCP Server（5 个工具）
│   ├── __main__.py / __init__.py
├── scripts/                      # 数据生成 / 测评集生成 / stdio 冒烟
├── prompts/                     # 系统提示词（四模块模板）
├── knowledge/                    # 知识库 SOP 简化版（iData RAG 挂载参考）
├── datasets/                     # 模拟数据集 + 测评数据集 + 数据/测评说明
├── docs/                         # 部署/接入/Demo/材料清单
├── tests/test_engine.py          # 确定性测试套件（15 例全通过）
└── pyproject.toml                # PyPI 发布配置（包名 nfyy-ckd-risk-warning-mcp）
```

---

## 6. 测试

```bash
pip install -e .
python tests/test_engine.py       # 4 项全部通过：15 例预期等级+规则、报文/MQ 契约
python scripts/_smoke_stdio.py    # MCP stdio 握手：暴露 5 个工具
```

---

## 7. 免责声明

本项目及全部数据均为**虚构合成数据**，仅用于「南方医科大学南方医院智能体创新大赛」复赛演示，**不可用于任何真实临床决策**。所有处方级用药调整须由主诊医生决定。