需要人类基因组变异的临床致病性分级…

当你要查 ClinVar 中变异的临床意义、星级评审状态、提交者证据、表型/HPO、坐标或致病/良性对照列表时使用。

适用场景

解决思路

1. 若未安装 uv，阅读 uv skill 并按其 Setup 安装，确保 uv 在 PATH。
2. 若 workspace 根目录不存在 .licenses/clinvar_database_LICENSE.txt，先显著通知用户查看 https://www.ncbi.nlm.nih.gov/clinvar/ 条款，再创建该文件记录通知文本和时间戳。
3. 确保 home 目录存在 .env；若不存在则创建。
4. 若计划大量查询或遇到 429，注册免费 NCBI_API_KEY（https://www.ncbi.nlm.nih.gov/account/settings/），并用 credentials skill 的安全凭据协议检查/请求该 key，帮助用户加入 .env；该 key 可把 NCBI 限速从 3 次/秒提升到 10 次/秒。
5. 通过提供的 Python wrapper 脚本执行 ClinVar 查询：`uv run scripts/clinvar_api.py ...`，由脚本处理严格限速、重试和 XML/JSON 解析。
6. 快速开始示例：`uv run scripts/clinvar_api.py search --query "BRCA1[gene]" --output results.json`。
7. 对任何 “List all” 或全基因请求，显式设置更高的 `--retmax`（如 `1000`）以确保数据完整性；注意原文 Core Rules 称 `search` 默认 `--retmax 200`，而 Utility Scripts 称默认 `--retmax 0`（获取全部匹配），因此不要依赖默认值。
8. 优先使用 wrapper 脚本处理标准查询；若解析输出不含所需字段，可修改脚本或直接查询 NCBI E-utilities API，但原始 XML schema 复杂且随记录类型变化。
9. 若触发限速，脚本会抛出明确错误；必须用 credentials skill 的安全凭据协议检查并请求 `NCBI_API_KEY`，帮用户加入 `.env` 后重试。
10. 若使用本技能，确保在输出中提及。
11. count 用途：不获取 ID，只检查匹配变异数量，用来判断是否需要完整 `search`。
12. count 参数：`--query` 必填，NCBI Entrez 搜索查询字符串；`--output` 必填，输出 JSON 文件路径。
13. count 示例：`uv run scripts/clinvar_api.py count --query 'TP53[gene] AND "uncertain significance"[clinsig]' --output count.json`，输出 `{"total_count": <int>}`。
14. search 用途：用 NCBI Entrez 搜索语法按基因组位置、基因符号或临床属性识别变异；search 命令会自动分页，确保完整、确定地获取所有匹配结果。
15. search 示例1：获取所有匹配变异（默认行为）：`uv run scripts/clinvar_api.py search --query "BRCA1[gene]" --output results.json`。
16. search 示例2：按染色体和位置范围搜索：`uv run scripts/clinvar_api.py search --query "11[chr] AND 5225000:5226000[chrpos]" --output results.json`。
17. search 示例3：用 Entrez 语法组合条件：`uv run scripts/clinvar_api.py search --query "HBB[gene] AND pathogenic[clinsig]" --output results.json`。
18. search 示例4：限制结果为 50：`uv run scripts/clinvar_api.py search --query "TP53[gene]" --retmax 50 --output results.json`。
19. search 参数：`--query` 必填；`--retmax` 最大总变异 ID 数，默认 0 表示获取所有匹配结果，设为正整数可限制结果集；`--page_size` 每次 API 请求获取的 ID 数，默认 500，NCBI 限制最大 10000；`--output` 必填。
20. search 输出：JSON 对象，含 `total_count`（ClinVar 中匹配变异总数）、`fetched_count`（实际获取 ID 数）、`variant_ids`（ClinVar Variation ID 字符串列表）。
21. summary 用途：获取顶级临床意义标签、星级评审状态和基本表型数据，用于快速筛选变异。
22. summary 示例：`uv run scripts/clinvar_api.py summary --variant_ids 12345 67890 --output summary.json`。
23. summary 参数：`--variant_ids` 必填，一个或多个 ClinVar Variation ID；`--output` 必填。
24. summary 输出：JSON 列表，每个 summary 对象含 `variant_id`、`title`、`clinical_significance`、`review_status`、`last_evaluated`、`phenotypes`；`genes`（`{gene_id, symbol, strand}` 列表）；`variation_type`（如 single nucleotide variant、Deletion、Insertion）；`molecular_consequences`（字符串列表，如 ["missense variant", "nonsense"]）。
25. evidence 用途：获取单个变异的完整临床记录，包括自由文本临床理由、断言方法和具体提交者备注。
26. evidence 示例：`uv run scripts/clinvar_api.py evidence --variant_id 12345 --output evidence.json`。
27. evidence 参数：`--variant_id` 必填，单个 ClinVar Variation ID；`--output` 必填。
28. evidence 输出：JSON 对象，含 `variant_id`；`allele_info`（`{chromosome, position_start, position_stop, reference_allele, alternate_allele, cytogenetic_band, dbsnp_rsid}`，优先 GRCh38）；`conditions`（`{name, medgen_cui, omim_id, orphanet_id, hpo_terms}` 列表）；`functional_consequences`（`{value, sequence_ontology_id}` 列表）；`structural_variant_details`（`{outer_start, inner_start, inner_stop, outer_stop, copy_number}`，仅 CNV 有，否则 null）；`citation_references`（全局 Citations 部分引用的 PubMed ID 列表）；`submissions`（每个提交者记录含 `submitter_name`、`classification`、`curator_notes`、`assertion_criteria`、`date_last_evaluated`）。
29. Count-First 工作流（推荐）：对大型或未知结果集，先用 `count` 判断是否继续，再用 `search`（自动分页并返回 `total_count`/`fetched_count`），然后用 `summary` 筛选。
30. Count-First 第1步（可选，search 也返回 total_count）：`uv run scripts/clinvar_api.py count --query "HBB[gene] AND pathogenic[clinsig]" --output count.json`。
31. Count-First 第2步：`uv run scripts/clinvar_api.py search --query "HBB[gene] AND pathogenic[clinsig]" --output ids.json`。
32. Count-First 第3步：从 search 输出提取 `variant_ids`，运行 `uv run scripts/clinvar_api.py summary --variant_ids 12345 67890 --output summary.json`。
33. Deep Dive 工作流 search → evidence：需要某变异的完整临床图景（提交者理由、PubMed 引用、本体关联条件、等位基因坐标）时，用 `evidence`。
34. Deep Dive 示例：`uv run scripts/clinvar_api.py evidence --variant_id 12345 --output evidence.json`。
35. 稳健变异发现（三角验证）：ClinVar 元数据不一致；为满足 “List all” 请求，不要依赖单一过滤器，在单一回合内执行以下搜索并合并结果：
36. 三角验证1：按精确标签搜索，如 `"3 prime UTR variant"[molecular_consequence]`。
37. 三角验证2：按 HGVS 命名模式搜索，如 `c.*`。
38. 三角验证3：按基因组坐标范围搜索，使用 `[chrpos]`。
39. 通过 HGVS 验证编码 vs 非编码：`molecular_consequences` 单独可能含糊（如 `splice donor variant` 出现在编码和非编码上下文）；始终交叉检查 `title` 字段的 HGVS 模式。
40. HGVS 模式：`c.-…` — 5' UTR（非编码）。
41. HGVS 模式：`c.*…` — 3' UTR（非编码）。
42. HGVS 模式：`c.123+N` / `c.123-N` — 内含子（非编码）。
43. HGVS 模式：`p.Trp146Arg` 等 — 蛋白效应（编码）。
44. 判断规则：有 UTR/内含子 HGVS 且无 `p.` 注释的变异是非编码，即使有 splicing 标签；反之任何 `p.` 注释表示编码效应。
45. ClinVar 元数据参考：3' UTR 搜索字符串 `"3 prime UTR variant"[mol_consequence]`，HGVS `c.*`。
46. ClinVar 元数据参考：5' UTR 搜索字符串 `"5 prime UTR variant"[mol_consequence]`，HGVS `c.-`。
47. 要查找 “high-confidence” 变异或专家评审共识，使用 `review_status` 过滤器；这是区分单实验室断言和 panel 评审 ground truth 的最有效方式。
48. 字段选择：快速致病性标签 — 用 `summary` → `clinical_significance`。
49. 字段选择：基因符号和链 — 用 `summary` → `genes`。
50. 字段选择：变异类型（SNV、del 等） — 用 `summary` → `variation_type`。
51. 字段选择：蛋白水平效应 — 用 `summary` → `molecular_consequences`。
52. 字段选择：基因组坐标（GRCh38） — 用 `evidence` → `allele_info`。
53. 字段选择：关联条件（本体） — 用 `evidence` → `conditions`。
54. 字段选择：SO 功能后果 — 用 `evidence` → `functional_consequences`。
55. 字段选择：CNV 断点/拷贝数 — 用 `evidence` → `structural_variant_details`。
56. 字段选择：PubMed 参考 — 用 `evidence` → `citation_references`。
57. 字段选择：最后实验室评审日期 — 用两者 → `last_evaluated`。
58. 字段选择：临床医生理由 — 用 `evidence` → `submissions[].curator_notes`。
59. 获取基因组坐标（默认 HG38/GRCh38）：要得到 `<chrom>:<pos>:<ref>><alt>`（如 `chr5:70951945:G>A`），必须用 `evidence` 命令，因为 `summary` 输出没有这些细节。
60. 列出或呈现变异时，即使未明确要求，也必须始终包含 `<chrom>:<pos>:<ref>><alt>` 格式的基因组坐标；如果 summary 缺少坐标，用 `evidence` 命令或 dbSNP fallback 获取。
61. 获取坐标步骤1：`uv run scripts/clinvar_api.py evidence --variant_id <ID> --output evidence.json`。
62. 获取坐标步骤2：从 `Assembly="GRCh38"` 的 `SequenceLocation` 元素提取 VCF 属性：Chromosome `Chr`；Position `positionVCF`（或 `start`）；Ref `referenceAlleleVCF`（或 `referenceAllele`）；Alt `alternateAlleleVCF`（或 `alternateAllele`）。
63. 不精确坐标（基因范围）fallback：ClinVar 常对非编码变异返回全基因范围；若提取坐标对应基因范围而非具体位置，用 `dbsnp-database` skill 解析精确坐标。
64. dbSNP fallback 步骤1：检查 `evidence` 输出中的 `dbsnp_rsid`。
65. dbSNP fallback 步骤2：运行 `uv run scripts/dbsnp_cli.py resolve-rsid {rsid}` 获取精确 GRCh38 坐标。
66. dbSNP fallback 步骤3：用 dbSNP 的 SPDI 或 HGVS 数据格式化为 `<chrom>:<pos>:<ref>><alt>`。
67. structural variant 注意：`structural_variant_details` 字段只对拷贝数变异（CNV）填充；标准 SNV 和小 indel 该字段为 `null`，应改用 `allele_info` 的 `position_start`、`position_stop`、`reference_allele`、`alternate_allele`。
68. CNV / 大缺失注意：大拷贝数变异（CNV）常有空 `molecular_consequences`；如果变异标题提到 “del” 且坐标与目标区域重叠，即使缺少标签也相关。
69. 获取和使用 API key：可在 https://www.ncbi.nlm.nih.gov/account/settings/ 免费注册；若本技能看起来与用户请求相关，必须用 credentials skill 的安全凭据协议检查并请求该 key。
70. 最佳实践：始终用 `uv run` 执行 `python`。
71. 最佳实践：若 `jq` 不可用，立即改用 Python 单行命令处理 JSON，如 `uv run python3 -c "import json; ..."`。
72. 最佳实践：在用 `search` 前先用 `count` 了解结果集大小。
73. 最佳实践：`search` 命令默认获取所有结果，并在输出中包含 `total_count` 和 `fetched_count`；始终验证两者匹配以确认完整检索。
74. 最佳实践：Entrez 结果未排序；要按日期排序，获取所有结果后按 `last_evaluated` 本地排序。
75. 常见错误：不要自己解析 E-utilities XML — 始终使用提供的 `clinvar_api.py` 客户端，它稳健处理不可预测的 XML schema。
76. 常见错误：遇到 HTTP 429 Too Many Requests — 客户端会抛异常提示暂停；必须用 credentials skill 的安全凭据协议检查并请求 `NCBI_API_KEY`，帮用户加入 `.env` 后重试。
77. 常见错误：不要向 API 发送原始 DNA 序列 — API 期望 HGVS 命名、RS ID 或正确的 Entrez 坐标语法（如 `11[chr] AND 1234[chrpos]`），不是原始 ATCG 字符串。
78. 常见错误：对同义或非编码变异 — HGVS 命名（如 `CAPN3 AND "c.551C>T"`）比坐标搜索（`[chrpos]`）更可靠，因为许多此类 ClinVar 记录缺少精确基因组映射。
79. 常见错误：分子后果大小写敏感 — ClinVar 返回混合大小写字符串；过滤时始终使用大小写不敏感匹配（`.lower()`）。
80. 常见错误：不要把 `search` 输出解析为裸列表 — `search` 返回的是含 `total_count`、`fetched_count`、`variant_ids` 的 JSON 对象，不是裸列表。

适用边界 · 注意事项

• 不要用于查找特定变异在全球人群中的等位基因频率（改用 gnomAD）。
• 不要用于描述蛋白正常生物学功能/典型遗传模式（改用 OMIM），或预测新突变的机制效应（改用 AlphaGenome）。
• 不要用于查找患者监测计划（改用 GeneReviews），或生成/查看 3D 结构模型（改用 PDB/AlphaFold）。