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 索引员人工标注的 publicationtype 才是权威依据。仅当 efetch 返回为空(发表 PMCID > DOI) ↓ publicationtype 解析 (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](https://github.com/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 |  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 类问题速览

| questiontype | 优先 grade | 主调 skill | |--------------|----------|-----------| | therapy | A-B | pubmed-eutils.pubmedclinicalqueries(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.pubmedclinical_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 缺失 | 文献 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): 初始版本

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: EthanYoQ
• Source: EthanYoQ/Skill-hub
• License: MIT

Install and usage instructions live in the source repository linked above.