夜雨聆风在抗肿瘤治疗中，药物不良反应（ADR）具有发生率高、表现隐匿、个体差异大等特点。说明书所列的已知风险往往难以覆盖真实世界中的复杂组合，例如某类靶向药在老年女性、合并肝功能异常且正在服用华法林的患者中引发严重出血的风险，可能从未被明确记载。如何从碎片化临床数据中识别出这类「说明书未载但实际存在」的风险信号？一款轻量、可解释、开箱即用的知识图谱预警工具正为此而生。
项目概述：构建可计算、可预警、可落地的药物安全知识网络
肿瘤药物不良反应知识图谱预警系统 是一个基于知识图谱与图异常检测技术的开源医疗软件。它不依赖黑盒大模型，也不需要训练私有数据集，而是通过结构化建模「药物-不良事件-患者特征」三元关系，将药品说明书、临床指南、文献报告和真实世界数据转化为一张可查询、可分析、可预警的语义网络。
系统核心目标明确：发现说明书中未记载但图谱中高频共现的异常三元组组合，并以临床药师和肿瘤科医生能快速理解的方式生成预警卡片。整个流程闭环清晰：图谱构建 → 异常检测 → 预警生成 → 可视化呈现 → 报告导出。
该项目并非通用图谱平台，而是聚焦于肿瘤用药安全这一垂直场景，所有模块设计均围绕临床实用性展开。其输出不是抽象分数或算法指标，而是包含「严重度等级」「置信度评分」「具体临床建议」的结构化标签，直接服务于用药前评估、用药中监护与用药后复盘。
技术亮点：轻量架构下的专业算法实现
本系统在保持技术严谨性的同时，兼顾部署便捷性与使用友好性，主要体现在以下三方面：
模块化 TypeScript 架构
采用 ESM 模块规范构建，代码组织清晰，各子系统职责分明。从 loaders/ 加载图谱数据，到 engine/ 执行核心检测，再到 generators/ 和 renderers/ 分别生成预警逻辑与 HTML 页面，每一层都可通过独立入口调用。这种设计既支持 CLI 快速验证，也为未来集成进医院 HIS 或药学信息系统预留了 API 接口（详见 docs/API.md）。
LAF（Local Anomaly Factor）图异常检测引擎
区别于传统孤立森林或图神经网络等重型方案，本系统采用自研优化的 LAF 算法，专为小规模、高语义密度的医学图谱设计。其原理直观有效： - 对每个节点，统计其直接邻居数量及邻居之间的连接密度； - 若某节点邻居稀疏、且邻居之间也缺乏交互，则判定为潜在异常； - 结合 Isolation Forest 的思想，对孤立子图进行分层采样增强鲁棒性。
该算法无需大量标注样本，仅需输入符合《GRAPH_SCHEMA.md》规范的 JSON 图谱即可运行，特别适合临床数据积累尚不充分的机构起步使用。
面向临床交付的预警生成体系
预警不是简单打标，而是一套完整的信息服务链： - 依据配置文件 config/severity-thresholds.json，自动映射 LAF 分数至「严重」「高度关注」「中度关注」「一般关注」四级临床标签； - 每张 HTML 告警卡均包含可读性强的自然语言描述，例如：“吉非替尼在 EGFR 19 号外显子缺失且基线血小板计数 <100×10⁹/L 的患者中，发生间质性肺病的风险显著升高（LAF=2.83，置信度 87%）”； - 支持按严重度过滤、限制 Top-N 输出、启用图谱校验与统计摘要，确保结果可信、可控、可追溯。
应用场景：可用于多类医疗健康角色的工作流嵌入
本系统不替代医生判断，但可成为临床决策链中关键的一环辅助工具，适用于以下典型场景：
临床药师开展个体化用药监护
在审方环节，药师可批量导入患者检验指标、基因检测结果与当前用药清单，系统自动匹配图谱中对应节点，识别高风险组合并生成干预建议，提升前置风险拦截能力。
肿瘤科医生制定治疗方案时的风险预判
面对复杂共病患者（如合并糖尿病、慢性肾病、自身免疫病），医生可在拟定方案前运行检测，快速了解某药物在该亚群中的潜在 ADR 模式，辅助权衡获益与风险。
药学部门开展药物警戒与信号挖掘
利用系统 CLI 工具批量处理院内电子病历脱敏数据，定期生成 ADR 风险热力图与趋势报告，支撑季度药物安全性评价与说明书更新建议。
医学研究人员探索药物-ADR 新机制
研究者可基于 data/example-csv-import.csv 格式整理文献数据，构建自定义子图谱，验证假设路径（如“PD-1 抑制剂 + 甲状腺功能减退 → 垂体炎发生率升高”），为机制研究提供数据锚点。
使用指南：五分钟上手，零门槛启动本地预警分析
项目对环境要求极简，仅需 Node.js 18+ 与 npm 即可运行。以下是标准操作流程：
# 克隆仓库后安装依赖
npm install
# 编译 TypeScript 源码
npm run build
# 查看 CLI 工具完整帮助信息
npm run cli -- --help
# 加载内置示例图谱（含 5 种抗肿瘤药、20 余种 ADR、8 类患者特征）
npm run cli -- load --graph data/sample-graph.json
# 运行 LAF 异常检测，默认参数见 config/default-detection.json
npm run cli -- detect
# 列出当前检测出的所有预警条目（默认 Top 20）
npm run cli -- alerts
# 导出为独立 HTML 页面，含样式与交互，双击即可在浏览器打开
npm run cli -- export --format html
所有配置均可通过修改 config/ 目录下 JSON 文件调整。例如将 lafThreshold 从默认 2.0 提升至 2.5，可提高预警精度、降低误报；将 severityFilter 设为 "HIGH"，则仅输出需立即关注的高风险条目。详细参数说明与调试技巧请参阅 docs/cli-usage.md 与 docs/ALGORITHM.md。
值得一提的是，系统支持 CSV 数据导入（参考 data/example-csv-import.csv）、批量药物查询（参考 data/example-batch-drugs.json），并提供完整的图谱校验功能（启用 enableValidation 后会检查节点 ID 唯一性、关系完整性等），保障输入质量。
总结：让知识图谱真正服务于一线临床需求
当前不少医疗知识图谱项目停留在论文级演示或平台型基建阶段，而本项目反其道而行之：不做大而全的通用图谱引擎，而是深挖肿瘤药物安全这一个切口，把算法、工程与临床语言三者拧成一股绳。它用 TypeScript 实现跨平台兼容，用 LAF 算法平衡可解释性与有效性，用 HTML 告警卡打通最后一公里交付，最终呈现的不是一个技术 Demo，而是一个能放进药房电脑、能嵌入查房平板、能辅助年轻医师避开常见坑的实用工具。
其价值不在于取代专业判断，而在于把分散在文献、经验与数据库中的隐性知识，变成可检索、可排序、可行动的结构化提示。对于正在推进合理用药管理、加强肿瘤专科药学服务的医疗机构而言，这是一个值得纳入技术评估清单的轻量级开源选项。
项目当前免费开源，若您对项目有疑问、使用上的困惑或想深入交流，欢迎私信我们，或加入社群讨论。
项目地址：
https://github.com/nexorin9/adr-knowledge-graph
