medical-evidence-grading · 医学证据等级排序与编排层(L2)
一句话定义
对底层 6 个原子 skill 召回的医学文献做"证据金字塔排序",输出带 GRADE A/B/C/D 评级的文献集与汇总报告;同时充当智能调度器,根据问题类型(疗效/诊断/病因/预后/不良反应/预测/指南/SR)自动选择最佳原子 skill 与 PubMed Clinical Queries filter。
Iron Law(不可违反)
GRADE 评级前必须调用 pubmed-eutils.efetch_pubmed() 拿真实 publication_type。不可仅凭 title/abstract 关键词推断。
理由:title 含"randomized"未必是 RCT(可能是综述讨论 RCT);只有 NLM MeSH 索引员人工标注的 publication_type 才是权威依据。仅当 efetch 返回为空(发表 < 6 个月新文献)才允许启发式推断,且必须给 grade 加 _inferred 后缀。
完整规则见 references/grade-rules.md。
何时调用(Auto-trigger)
调用本 skill (✅):
- "评估这个临床声明的证据强度" → ✅
cross_validate_evidence(claim=...)
- "找血液 IFI 最新指南级证据" → ✅
evidence_search(query=..., target_grade='guideline_only')
- "对比这些 PMID 的 GRADE 等级" → ✅
grade_pmid_list(pmid_list=[...])
- "我要给附录 C 重新分级" → ✅
grade_pmid_list + evidence_summary
- "venetoclax AML 高质量 RCT" → ✅
evidence_search(target_grade='rct_or_above')
不调用本 skill (❌,直接调原子 skill):
- "检索 PubMed" → ❌ 直接调
pubmed-eutils
- "找 NCT 试验" → ❌ 直接调
clinical-trials-v2
- "拿全文段落" → ❌ 直接调
bioc-fulltext-fetch
- "全库批量分析" → ❌ 直接调
aact-bulk-trials
与其他 skill 协作矩阵(关键 · 编排核心)
| 协作方向 | Skill | 调用的具体函数 | 用途 |
|---|
| 上游调用方 | ifi-market-sizing-skill | (调本 skill) | 市场规模研究的"数据回补" |
| 上游调用方 | disease-market-sizing-orchestration | (调本 skill) | 调研启动阶段的高等级证据搜集 |
| 下游被调 1 | pubmed-eutils | .esearch_pubmed() / .efetch_pubmed() / .pubmed_clinical_queries() | 拿 PMID + publication_type |
| 下游被调 2 | europepmc-search | .search_articles() / .find_similar_articles() | EuropePMC + open-access 链接 |
| 下游被调 3 | clinical-trials-v2 | .search_studies() | NCT + phase + enrollment |
| 下游被调 4 | aact-bulk-trials | .bulk_disease_landscape() | 全库历史试验(罕见病/纵向) |
| 下游被调 5 | bioc-fulltext-fetch | .to_rag_chunks() | 抽样本量(只对疑似 RCT/Cohort) |
| 下游被调 6 | pubtator-entity-search | .search_by_relation() | 给文献打疾病/药物 entity tag |
| 下游接收方 | evidence-appendix-sync | (接受本 skill 输出) | 报告附录 C 同步 |
用户 / 上游 skill (ifi-market-sizing-skill, disease-market-sizing-orchestration)
│
▼
[medical-evidence-grading]
↙ ↘
BioMCP fast-path 自建 slow-path
│ │
(单次 fan-out) 并发调 6 原子 skill
↓ ↓
统一去重 (PMID > PMCID > DOI)
↓
publication_type 解析 (efetch · Iron Law)
↓
GRADE 评级 (A/B/C/D/excluded · 见 grade-rules.md)
↓
evidence-appendix-sync (报告附录 C)
BioMCP fast-path vs 自建 slow-path 双模式
Fast-path: BioMCP MCP server (优先)
genomoncology/biomcp 一次性 fan-out PubMed + EuropePMC + ClinicalTrials + PubTator。
Slow-path: 自建 fan-out (兜底)
当 BioMCP 不可用,并发调 pubmed-eutils.esearch_pubmed() + europepmc-search.search_articles() + clinical-trials-v2.search_studies(),然后 pubmed-eutils.efetch_pubmed() 拿 publication_type,可选调 bioc-fulltext-fetch.to_rag_chunks() 抽样本量。
完整检测/配置/兜底逻辑见 references/biomcp-integration.md。
性能对比:
| 模式 | 100 条文献延迟 | API 调用数 | 缓存命中后 |
|---|
| Fast-path (BioMCP) | ~3-5s | 1 | <500ms |
| Slow-path (自建) | ~15-25s | 6-10 | <500ms |
5 核心函数签名(跨平台稳定)
# ============== 1. 主入口:综合证据搜索 ==============
def evidence_search(
query: str,
target_grade: str = "all", # 'guideline_only' | 'rct_or_above' | 'all'
max_results: int = 200,
include_preprints: bool = False,
include_trials: bool = True,
date_range: str = "10years", # 'all' | '5years' | '10years' | '2020:2025'
rare_disease_mode: bool = False, # 罕见病阈值放宽,见 grade-rules.md
use_biomcp_if_available: bool = True,
) -> dict:
"""
返回 {total, by_grade, fast_path_used, cache_hit, elapsed_seconds, results: [{evidence_id, pmid, pmcid, doi, title, authors, journal, year, publication_types, sample_size, is_preprint, grade, grade_rationale, abstract, source}]}
"""
# ============== 2. 给现有 PMID 列表打分 ==============
def grade_pmid_list(
pmid_list: list[str],
fetch_fulltext_for_sample_size: bool = False,
) -> list[dict]:
"""
输入 ['38234567', ...] → 输出每条带 grade / grade_rationale 的字典。
内部:批量 pubmed-eutils.efetch_pubmed() → 解析 publication_type → 应用 grade-rules.md。
fetch_fulltext_for_sample_size=True 时,对疑似 RCT/Cohort 调 bioc-fulltext-fetch.to_rag_chunks() 抽 n。
"""
# ============== 3. 推荐检索策略 ==============
def recommend_search_strategy(
question_type: str, # 'therapy' | 'diagnosis' | 'etiology' | 'prognosis' | 'harm' | 'prediction' | 'guideline' | 'sr'
user_query: str = "",
) -> dict:
"""
返回 {clinical_queries_filter, pubmed_query_template, europepmc_query_template,
expected_grade_distribution, recommended_skill, tips[]}.
完整 8 类映射见 references/clinical-queries-mapping.md。
"""
# ============== 4. 反向证据交叉验证 ==============
def cross_validate_evidence(
claim: str, # 例: "Posaconazole 预防 IFI 比 fluconazole 更有效"
top_k: int = 10,
min_grade: str = "B",
) -> dict:
"""
NLP 拆解 claim → PICO → 反向搜索高等级证据。
返回 {claim, pico, supporting[], contradicting[], verdict, confidence}.
verdict ∈ {supported, contradicted, mixed, insufficient}.
"""
# ============== 5. 证据汇总报告 ==============
def evidence_summary(
graded_list: list[dict],
output_format: str = "markdown", # 'markdown' | 'html' | 'json'
output_path: str | None = None, # 提供则写 evidence/_summary.md
) -> str:
"""
生成等级分布表 + Top 5 grade-A 摘要表 + 关键发现 + 引用建议 + 缺口提示。
"""
Clinical Queries 8 类问题速览
| question_type | 优先 grade | 主调 skill |
|---|
| therapy | A-B | pubmed-eutils.pubmed_clinical_queries(scope='therapy/narrow') |
| diagnosis | A-C | pubmed-eutils + europepmc-search |
| etiology | B-C | pubmed-eutils |
| prognosis | B-C | pubmed-eutils |
| harm | A-C | pubmed-eutils + clinical-trials-v2 (AE 表) |
| prediction | A-B | pubmed-eutils |
| guideline | A only | pubmed-eutils.pubmed_clinical_queries(scope='guidelines') |
| sr | A only | pubmed-eutils + europepmc-search |
完整查询模板与罕见病调整见 references/clinical-queries-mapping.md。
失败模式速查 (10 条)
| 症状 | 可能原因 | 处理方式 |
|---|
| BioMCP 检测到但调用失败 | MCP server 配置存在但未启动/版本不兼容 | 静默回退 slow-path,日志告警,不阻塞 |
| BioMCP 故障 fall-back 至 slow-path 但 NCBI 也限流 | 双路连续失败 | 加 jitter 退避,3 次后切 europepmc-search 单源,grade 标 _partial |
| GRADE 自动评级 publication_type 缺失 | 文献 < 6 个月未 MeSH 索引 | 启发式推断(见 grade-rules.md),grade 加 _inferred 后缀,警告用户人工复核 |
| 样本量提取失败(efetch 摘要不含 n) | 全文不可访问 / 摘要写法不规范 | 跳过 n 校验,grade 按 publication_type 默认值,不应用 n 阈值降权 |
| 重复 PMID 跨原子 skill 未去重 | BioMCP 已去重但回退到 slow-path 未去重 | 强制 evidence_id = "PMID:" + pmid 三段优先级(PMID > PMCID > DOI)再去重 |
| 证据矛盾(同一 claim 高等级证据正反皆有) | 真实存在的临床争议 | cross_validate_evidence 返回 verdict='mixed',supporting 与 contradicting 并列展示,不强行下结论 |
| 缓存命中但 GRADE 规则更新过 | grade-rules.md 升级未 bump 版本 | grade_rule_version 字段不匹配视为 miss,自动重算并刷新缓存 |
| evidence/ 文件夹组织规范冲突 | 下游 evidence-appendix-sync 期望 grade-A/B/C/D 子目录 | 严格按 grade-A/PMID-XXX_AuthorYear.json 命名,变动需双方同步升级 |
| 同一研究多 PMID(预印本+正式版) | medRxiv → 期刊 | 优先保留期刊版,预印本标记 superseded_by |
| 中文期刊文献缺失 | NCBI 不索引部分中文期刊 | 提示用户用 CNKI / 万方补充,本 skill 不覆盖中文数据库 |
完整缓存策略见 references/cache-schema.md。
evidence/ 文件夹组织规范
下游 evidence-appendix-sync 期望本 skill 产出:
evidence/
├── grade-A/
│ ├── PMID-32786187_DiNardo-NEJM-2020.json
│ └── PMID-32786187_DiNardo-NEJM-2020_abs.txt
├── grade-B/ grade-C/ grade-D/ excluded/
├── _summary.md # evidence_summary() 产出
├── _index.csv # 全部文献索引(便于附录 C 引用)
└── _query_log.jsonl # 检索日志(可复现)
每条 *.json 含 {evidence_id, grade, grade_rationale, citation_apa, citation_chinese, metadata, abstract, fetched_at, source_chain}。
跨疾病移植清单
本 skill 与具体疾病无关,移植到肺癌/糖尿病等只需:
跨平台兼容(无锁)
| 平台 | 兼容性 | 说明 |
|---|
| Claude Code | 原生 | SKILL.md 自动加载,Skill 工具直接调用 |
| Codex (CLI) | 兼容 | 复制到 $CODEX_HOME/skills/medical-evidence-grading/,通过 skill-installer |
| Gemini CLI | 兼容 | 作为 prompt template 使用,函数签名需手工实现 |
| Cursor / Continue | 部分 | 提取 GRADE 规则表(见 grade-rules.md)作为 system prompt |
关键不变量(确保跨平台一致):
- 函数签名稳定(5 个核心函数不重命名)
- GRADE 规则用 Markdown 表格表达(任何 LLM 可解析)
- 缓存路径
~/.claude/skills/medical-evidence-grading/cache.sqlite (Path.home() 自动适配)
- BioMCP 检测三路:
~/.claude/mcp.json / ~/.codex/config.toml / BIOMCP_ENDPOINT 环境变量
References (Progressive Disclosure)
主文件保持精简;深度细节按需加载:
references/grade-rules.md — GRADE 评级完整规则表 + 降权升权信号 + 启发式推断 + 跨疾病阈值references/clinical-queries-mapping.md — Clinical Queries 8 类问题映射 + 多类型并行 + 罕见病调整 + 中国本土补充references/biomcp-integration.md — BioMCP fast-path 检测三路 + fall-back 触发条件 + slow-path 自建 fan-out + 跨平台配置references/cache-schema.md — SQLite cache 表结构 + TTL 策略 + 命中检测 + 维护命令
调用示例
# 示例 1: 找血液 IFI 最新指南
result = evidence_search(
query="invasive fungal infection prophylaxis hematology",
target_grade="guideline_only",
max_results=20,
date_range="5years",
)
# 返回 ECIL / IDSA / NCCN 等指南
# 示例 2: 给已有 PMID 列表打分
graded = grade_pmid_list(
pmid_list=["32786187", "37123456", "38234567"],
fetch_fulltext_for_sample_size=True,
)
# 示例 3: 反向验证临床声明
verdict = cross_validate_evidence(
claim="Posaconazole 预防 IFI 比 fluconazole 更有效",
top_k=10,
min_grade="B",
)
版本与依赖
- 版本: 1.1.0 (P0.2 阶段 · references 拆分版)
- GRADE 规则版本: v1.0.0 (改动需 bump,见 cache-schema.md)
- 依赖原子 skill: pubmed-eutils ≥1.0, europepmc-search ≥1.0, clinical-trials-v2 ≥2.0, aact-bulk-trials ≥1.0, bioc-fulltext-fetch ≥1.0, pubtator-entity-search ≥1.0
- 可选 MCP: biomcp (genomoncology/biomcp,推荐安装以启用 fast-path)
- 更新日志:
- v1.1.0 (2026-04-25): references/ 拆分(grade-rules / clinical-queries-mapping / biomcp-integration / cache-schema),主文件 500 → ~370 行,新增 Iron Law / Auto-trigger 5 prompt / 函数级原子 skill 引用
- v1.0.0 (2026-04-25): 初始版本