GPA: Genomic Phenotype Association

⚠️ 执行前必读

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

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

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

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

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

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

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

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

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

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

🚀 调用方式

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

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

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

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

控制分批行为

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

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 数组：

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 会按肿瘤驱动逻辑分级：

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 先过滤再分级，减少噪音：

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

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

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

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 剪接过调用的独立验证证据。

必须显式开启：

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，必填字段：

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

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

📊 输出解析

Wrapper 返回 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 结构：

{
  "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..."
}

呈现格式要求：

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

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

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 提交者星级纳入证据权重计算：

效果：

• 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 为空或转录本选择有警告，必须标注并说明影响。

🔧 离线模式

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

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

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

❌ 常见错误

📁 文件结构

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 是辅助决策工具，最终临床决策需结合完整临床评估。