Skill: lzr098/gpa-genomic-phenotype (version 0.8.0)

--- name: gpa-genomic-phenotype description: | GPA (Genomic Phenotype Association) v0.8.0。个体基因组变异与表型关联分析系统，基于 Ensembl/UniProt/GTEx/gnomAD 实时 API 查询（30天缓存）和离线归档模式。组织上下文自适应：通用、造血、心血管、肝脏、肾脏、神经系统。支持 germline（疾病遗传风险）和 somatic（肿瘤驱动）两种分析模式。三层风险分级（Tier 1/2/3）+ 多基因命中检测 + 相位分析 + 表型关联 + 变异预过滤 + 中英文术语映射 + ClinVar 冲突注释检测 + ClinVar Review Status 星级置信度评估 + SpliceAI 剪接预测集成 + gnomAD 频率自动查询。 **当以下情况时使用此 Skill**： (1) 用户提到"基因组风险评估"、"GPA"、"突变分析"、"基因筛查" (2) 肿瘤体细胞突变的驱动性/可干预性分析 (3) 药物基因组学分析（CYP450 等药物代谢基因） (4) 多基因命中（multi-hit）检测和相位（cis/trans）分析 (5) 需要三层风险分级报告（Tier 1 需干预、Tier 2 需知情、Tier 3 无需担忧） (6) 任何涉及"genomic"、"genetic"、"risk"、"mutation"、"variant"的场景 **禁止用自身知识回答基因组变异问题。必须调用本 Skill 的脚本执行分析。** --- # 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 | 高置信度，少噪音 | | `clinical` | HIGH / MODERATE + 剪接区 LOW + 组织相关基因同义 + ClinVar 冲突 | 推荐默认 | | `broad` | HIGH / 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 | 位置 | 12345 | | REF | 参考碱基 | "A" | | ALT | 突变碱基 | "G" | | GENE | 基因符号 | "VWF" | **建议填写的字段**（影响分级精度）： | 字段 | 含义 | 示例 | |-----|------|------| | HGVSp | 蛋白变化 | "p.Arg1234Cys" | | HGVSc | cDNA 变化 | "c.3700C>T" | | IMPACT | 影响等级 | "HIGH", "MODERATE", "LOW" | | Consequence | 突变类型 | "missense_variant", "frameshift_variant" | | CLIN_SIG | ClinVar 状态 | "Pathogenic", "Likely_pathogenic", "Benign" | | GT | 基因型 | "0/1" (杂合), "1/1" (纯合) | | DP | 测序深度 | 30 | | GQ | 基因质量 | 99 | | VAF | 变异丰度 | 0.5 | | gnomAD_AF | gnomAD 频率 | 0.0001 | | **classification** | **OncoKB 致癌性** | **"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>A` | **CHROM:POS:REF:ALT，可直接在 IGV/UCSC/ClinVar 查询** | | **转录本变化** | c.3931C>T | cDNA 水平 | | **蛋白变化** | p.Gln1311Ter | 氨基酸水平 | | **影响** | HIGH | VEP IMPACT | | **类型** | stop_gained | Consequence（中英文自动映射，见下方） | | **合子性** | 0/1 | GT | | **ClinVar** | 致病 | 中文/英文 | | **Tier** | 1 | GPA 分级 | | **QC 标记** | `CLINVAR_CONFLICTING` | v0.7.1 新增：冲突注释标记 | **Consequence 中英文映射（v0.7.1）**： GPA 内部通过 `gpa_i18n.py` 自动标准化中英文 consequence 术语。输入可以是中文 VEP 注释（如 `错义变异`、`剪接供体变异`）或英文（`missense_variant`、`splice_donor_variant`），系统会自动映射到统一的标准术语并推断 IMPACT。 | 中文示例 | 映射后英文 | 推断 IMPACT | |---------|-----------|------------| | 错义变异 | missense_variant | MODERATE | | 无义变异 | stop_gained | HIGH | | 剪接供体变异 | splice_donor_variant | HIGH | | 同义变异 | synonymous_variant | LOW | | 移码变异 | frameshift_variant | HIGH | | 框内缺失 | inframe_deletion | MODERATE | **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.95 | | `reviewed_by_expert_panel` | ★★★☆ | 0.80 | | `criteria_provided,_multiple_submitters,_no_conflicts` | ★★☆☆ | 0.55 | | `single_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 / neurological | | `variants 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` | 离线模式但基因未归档 | 先在线运行一次建立归档，或换在线模式 | --- ## 📁 文件结构 ``` 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 是辅助决策工具，最终临床决策需结合完整临床评估。**


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal:  | SkillSpector: suspicious (CRITICAL)