GPA: Genomic Phenotype Association#

⚠️ 执行前必读#

核心规则：当用户请求基因组变异风险评估时，不要凭自身知识回答。必须调用 dgra_cli_wrapper.py 执行正式分析。

GPA 是通用化的个体基因组变异与表型关联分析系统。基于 Ensembl、UniProt、GTEx、gnomAD 实时 API 查询和三级分类算法，支持多种临床场景：

• 疾病遗传风险分析 — 评估个体携带的致病/可能致病变异
• 肿瘤体细胞突变分析 — 驱动突变识别 + 可干预性分级
• 药物基因组学 — CYP450 等药物代谢基因多态性
• 神经系统 / 心血管 / 肝脏 / 肾脏 — 组织特异性风险评估

如果不调用脚本就回答 = 给出错误的医疗建议。

---

⚠️ 执行前必读：上下文确认规则（v0.5.1 新增）#

收到基因组变异数据时，禁止直接执行分析。必须先确认以下信息：

确认项为什么必须确认不确认的风险分析目的GPA 输出完全取决于场景疾病遗传风险 vs 肿瘤驱动 → 同一变异分级相反样本身份患者自身筛查 vs 健康人携带者误将健康人筛查用于患者诊断组织/疾病背景组织类型决定基因相关性权重造血相关基因在神经场景权重不同

最小确认问题集（向用户确认，不要假设）：

1. "这些数据是谁的样本？患者本人 / 健康筛查？"
2. "分析目的是什么？疾病遗传风险评估 / 肿瘤驱动突变 / 药物基因组学？"
3. "关注哪些组织或系统？（如血液、心脏、肝脏等）"

在获得上述信息前，禁止调用 dgra_core.py 或生成报告。

---

🎯 快速判断：是否需要调用 GPA？#

用户请求是否调用"帮我分析这些基因变异"✅ 调用"这个突变有什么风险"✅ 调用"GPA 分析一下"✅ 调用"肿瘤突变驱动性分析"✅ 调用"一般性的基因突变知识"❌ 不需要，直接回答"TP53 突变是什么意思"（无具体样本）❌ 不需要

---

🚀 调用方式#

自动分批（v0.7.1 新增，默认启用）#

当变异数 > 500 时，wrapper 自动分批 处理，每批500个变异，每批有独立的5分钟超时。

不需要任何额外参数——只要数据量大，自动生效：

bash

python3 ~/.workbuddy/skills/dgra-genomic-risk/scripts/dgra_cli_wrapper.py \
  --input-file variants.tsv \
  --tissue neurological

控制分批行为#

参数说明默认值--batch-size每批变异数500--timeout每批超时（秒）300--no-auto-batch禁用自动分批否

示例：肌病基因子集（2638个变异），分6批处理

bash

python3 ~/.workbuddy/skills/dgra-genomic-risk/scripts/dgra_cli_wrapper.py \
  --input-file myopathy_subset.tsv \
  --tissue neurological \
  --batch-size 500 \
  --output-json result.json

方式一：直接调用 wrapper（推荐）#

用 exec 运行 dgra_cli_wrapper.py，传入 variant JSON 数组：

bash

python3 ~/.workbuddy/skills/dgra-genomic-risk/scripts/dgra_cli_wrapper.py \
  --variants '[{"CHROM":"1","POS":12345,"REF":"A","ALT":"G","GENE":"VWF","IMPACT":"HIGH","Consequence":"missense_variant","HGVSp":"p.Arg1234Cys","HGVSc":"c.3700C>T","CLIN_SIG":"Pathogenic","GT":"0/1","DP":30,"GQ":99,"VAF":0.5}]' \
  --tissue general

Somatic / 肿瘤模式：添加 --somatic 标志，GPA 会按肿瘤驱动逻辑分级：

bash

python3 ~/.workbuddy/skills/dgra-genomic-risk/scripts/dgra_cli_wrapper.py \
  --variants '[...]' \
  --tissue general \
  --somatic

Somatic 模式下：

• TSG 截断突变 + 造血相关 = Tier 1（核心驱动）
• 癌基因热点突变（如 IDH1 R132） = Tier 1
• OncoKB Oncogenic / Likely Oncogenic = Tier 1
• VAF > 0.5 的变异会被标记为可能的 germline 混入

预过滤（v0.7.1 新增）：变异数过大时，用 --filter-preset 先过滤再分级，减少噪音：

bash

python3 ~/.workbuddy/skills/dgra-genomic-risk/scripts/dgra_cli_wrapper.py \
  --variants '[...]' \
  --tissue general \
  --filter-preset clinical

Preset保留规则用途strict仅 HIGH / MODERATE高置信度，少噪音clinicalHIGH / MODERATE + 剪接区 LOW + 组织相关基因同义 + ClinVar 冲突推荐默认broadHIGH / MODERATE / LOW保守，保留更多

自动分批（v0.7.1）：当变异数 > 500 时，wrapper 自动分批处理，每批500个：

bash

python3 ~/.workbuddy/skills/dgra-genomic-risk/scripts/dgra_cli_wrapper.py \
  --input-file variants.tsv \
  --tissue neurological \
  --batch-size 500

bash

python3 ~/.workbuddy/skills/dgra-genomic-risk/scripts/dgra_core.py \
  --input /path/to/variants.tsv \
  --tissue general \
  --output /tmp/gpa_report.md \
  --json /tmp/gpa_results.json \
  --somatic \
  --spliceai                              # v0.8.0: 启用 SpliceAI 剪接预测

SpliceAI 剪接预测（v0.8.0，默认关闭）#

SpliceAI 仅对 canonical splice（acceptor/donor）和 splice_region 变异查询 Broad Institute lookup API，作为 VEP HIGH 剪接过调用的独立验证证据。

必须显式开启：

bash

python3 ~/.openclaw/skills/dgra-genomic-risk/scripts/dgra_cli_wrapper.py \
  --input-file variants.tsv \
  --tissue hematopoietic \
  --spliceai                              # 开启 SpliceAI
  --spliceai-concurrency 5                # 可选：调整并发（默认 5）

效果：

• delta=0（无剪接变化）→ 降级：HIGH 剪接过调用 → Tier 下调
• delta≥0.5（强剪接变化）→ 升级：MODERATE 剪接区 → Tier 上调
• API 失败 / 不在数据库 → graceful fallback，不阻断分析

---

📋 输入数据构造指南#

Variant JSON 格式#

每个 variant 是一个 dict， 必填字段：

字段含义示例CHROM染色体"1", "X"POS位置12345REF参考碱基"A"ALT突变碱基"G"GENE基因符号"VWF"

建议填写的字段（影响分级精度）：

字段含义示例HGVSp蛋白变化"p.Arg1234Cys"HGVSccDNA 变化"c.3700C>T"IMPACT影响等级"HIGH", "MODERATE", "LOW"Consequence突变类型"missense_variant", "frameshift_variant"CLIN_SIGClinVar 状态"Pathogenic", "Likely_pathogenic", "Benign"GT基因型"0/1" (杂合), "1/1" (纯合)DP测序深度30GQ基因质量99VAF变异丰度0.5gnomAD_AFgnomAD 频率0.0001classificationOncoKB 致癌性"Oncogenic", "Likely Oncogenic", "VUS"is_tsg是否为抑癌基因****"Yes" / "No"is_oncogene是否为癌基因****"Yes" / "No"

如果用户提供了 OncoKB 标注的 CSV/表格数据，务必提取 classification、 is_tsg、 is_oncogene 字段传入 GPA，这对 somatic 模式分级至关重要。

---

📊 输出解析#

Wrapper 返回 JSON 结构：

json

{
  "success": true,
  "results": {
    "meta": {...},
    "summary": {
      "tier1_count": 0,
      "tier2_count": 1,
      "tier3_count": 2,
      "multi_hit_genes": ["VWF"]
    },
    "tier1_variants": [],
    "tier2_variants": [...],
    "tier3_variants": [...],
    "multi_hit_details": [...],
    "report_markdown": "# GPA 报告..."
  },
  "report_md": "# GPA Report...",
  "stdout": "GPA Report Generated..."
}

给用户呈现的关键信息#

默认行为：分析完成后，直接读取报告文件内容并完整展示给用户。 不要只给统计数字，不要让用户自己去看文件。

呈现内容优先级：

1. 完整 Markdown 报告 — 直接贴出报告全文（Tier 1/2/3 详情、多基因命中）
2. 若报告过长 — 先展示 Tier 1 和关键发现，再询问是否需要完整报告
3. 保存到指定路径 — 如果用户需要文件，用 --output /path/to/file.md 保存，不要用 /tmp

输出解析#

Wrapper 返回 JSON 结构：

json

{
  "success": true,
  "results": {
    "meta": {...},
    "summary": {
      "tier1_gene_count": 0,
      "tier1_variant_count": 0,
      "tier2_gene_count": 1,
      "tier2_variant_count": 2,
      "tier3_gene_count": 2,
      "tier3_variant_count": 5,
      "multi_hit_genes": ["VWF"]
    },
    "tier1_variants": [],
    "tier2_variants": [...],
    "tier3_variants": [...],
    "multi_hit_details": [...],
    "report_markdown": "# GPA 报告..."
  },
  "report_md": "# GPA Report...",
  "stdout": "GPA Report Generated..."
}

呈现格式要求：

每个变异必须展示以下字段（方便用户直接查询）：

字段示例用途基因VWF基因符号位点chr12:6126538:G>ACHROM:POS:REF:ALT，可直接在 IGV/UCSC/ClinVar 查询****转录本变化c.3931C>TcDNA 水平蛋白变化p.Gln1311Ter氨基酸水平影响HIGHVEP IMPACT类型stop_gainedConsequence（中英文自动映射，见下方）合子性0/1GTClinVar致病中文/英文Tier1GPA 分级QC 标记CLINVAR_CONFLICTINGv0.7.1 新增：冲突注释标记

Consequence 中英文映射（v0.7.1）： GPA 内部通过 gpa_i18n.py 自动标准化中英文 consequence 术语。输入可以是中文 VEP 注释（如 错义变异、 剪接供体变异）或英文（ missense_variant、 splice_donor_variant），系统会自动映射到统一的标准术语并推断 IMPACT。

中文示例映射后英文推断 IMPACT错义变异missense_variantMODERATE无义变异stop_gainedHIGH剪接供体变异splice_donor_variantHIGH同义变异synonymous_variantLOW移码变异frameshift_variantHIGH框内缺失inframe_deletionMODERATE

ClinVar 冲突注释（v0.7.1）： 当 ClinVar 同时包含正反两种评级（如 "良性, 致病"、 "VUS, Pathogenic"）时：

• 不触发 Tier 升级（weight=0）
• 标记 CLINVAR_CONFLICTING qc_flag
• 仍保留进入下游分析与报告
• 标准复合评级如 "Pathogenic/Likely_pathogenic" 不算冲突

ClinVar Review Status 星级（v0.7.2）： GPA 读取 CLNREVSTAT 字段，将 ClinVar 提交者星级纳入证据权重计算：

CLNREVSTAT 文本星级置信度权重practice_guideline★★★★0.95reviewed_by_expert_panel★★★☆0.80criteria_provided,_multiple_submitters,_no_conflicts★★☆☆0.55single_submitter★☆☆☆0.40缺失 / no_assertion / conflicting—0.30

效果：

• Pathogenic 证据 weight = 基础值 × 星级权重（1.0 × 0.30~0.95）
• Benign 证据 weight = -0.5 × 星级权重（排除信号随星级增强）
• 单一提交者的 Pathogenic 不再自动 Tier 1（weight=0.40，需更多证据支持）
• 实践指南认可的 Pathogenic 仍高置信度（weight=0.95）

冲突注释优先：如果 ClinVar 评级冲突（v0.7.1 逻辑），星级评估被跳过，weight=0。 | 原因 | ClinVar pathogenic... | 为什么是这个 tier |

若 chrom 为空或转录本选择有警告，必须标注并说明影响。

场景组织类型通用疾病遗传风险评估（默认）general血液/肿瘤血液hematopoietic心血管cardiovascular肝脏hepatic肾脏renal神经系统neurological

---

🔧 离线模式#

当网络不可用或 API 超时频繁时，添加 --offline 参数：

bash

python3 .../dgra_cli_wrapper.py --variants '[...]' --tissue general --offline

离线模式使用本地缓存（ references/offline_data/ 下的基因 JSON），对于已有归档的基因结果与在线模式一致。未归档的基因 fallback 到保守规则。

---

❌ 常见错误#

错误原因解决Invalid tissue 'xxx'组织类型不对用 general / hematopoietic / cardiovascular / hepatic / renal / neurologicalvariants list is empty输入为空检查 JSON 是否解析正确Failed to write TSV输入字段缺失确保必填字段 CHROM/POS/REF/ALT/GENE 存在dgra_core.py exited with code 1核心脚本执行失败看 stderr 输出排查Offline mode: no cached data离线模式但基因未归档先在线运行一次建立归档，或换在线模式

---

📁 文件结构#

text

dgra-genomic-risk/
  SKILL.md                  # 本文件
  config.json               # 元数据配置
  scripts/
    dgra_cli_wrapper.py     # ⭐ 推荐入口：agent 调用此 wrapper
    dgra_core.py            # 核心分析引擎（async API-first）
    dgra_api.py             # API 查询层
    dgra_cache.py           # SQLite 缓存
    dgra_config.py          # 配置管理
    dgra_build_state.py     # 构建状态持久化（v0.6.1）
    gpa_phenotype_match.py  # LLM 表型语义匹配（v0.7.0 Phase 2）
    gpa_i18n.py             # 中英文 consequence 术语映射（v0.7.1 Phase 2）
    dgra_variant_filter.py  # 预过滤模块：strict/clinical/broad（v0.7.1 Phase 3）
  references/
    tissue_context.json     # 组织上下文配置
    dgra.yaml               # 运行时参数配置
    offline_data/           # 离线归档（自动创建）
  cache/
    dgra_cache.db           # API 响应缓存

---

🩺 临床使用注意#

Tier 分级含义（按场景动态调整）#

Germline / 疾病遗传风险场景：

• Tier 1 = 必须干预的致病突变（如纯合截断、已知致病突变）
• Tier 2 = 需知情同意并持续监测（如杂合携带者、药物代谢多态性）
• Tier 3 = 记录归档，不影响当前决策

Somatic / 肿瘤驱动场景：

• Tier 1 = 核心驱动突变（TSG 功能丧失、癌基因热点突变、OncoKB Oncogenic）
• Tier 2 = 可能驱动突变（Likely Oncogenic、亚克隆突变、药物代谢相关）
• Tier 3 = 乘客突变 / 无功能影响 / 胚系多态混入

多基因命中 需确认相位：cis（同一条染色体）风险更高，trans（两条染色体）通常为复合杂合

GPA 是辅助决策工具，最终临床决策需结合完整临床评估。