Medical evidence grading

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 与具体疾病无关,移植到肺癌/糖尿病等只需:

• 确认底层 6 原子 skill 已安装(/skills 列表查看)
• 涉及罕见病时 evidence_search(rare_disease_mode=True) 自动放宽阈值(见 grade-rules.md)
• 涉及外科器械时,补充 Comparative Effectiveness Research 类型识别
• 中文医学领域加 CNKI / 万方补充检索(本 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): 初始版本