查询 Ensembl 基因/转录本/蛋白 ID、序列和…

需要解析 Ensembl ID、获取基因组或蛋白序列、外显子结构或变异后果预测时，通过 `scripts/ensembl_api.py` 统一查询并遵守限速。

适用场景

解决思路

1. 阅读 `uv` skill 并按其 Setup 说明安装或确认 `uv`，确保 `uv` 在 PATH 中。
2. 如果工作区根目录不存在 `.licenses/ensembl_database_LICENSE.txt`，先显著通知用户查看 https://useast.ensembl.org/index.html 和 https://github.com/Ensembl/ensembl-rest/wiki 的条款，然后创建该文件记录通知文本和时间戳。
3. 始终执行提供的 helper scripts（`scripts/ensembl_api.py`）查询数据库，不要直接访问数据库；脚本会自动处理所需限速。
4. 如果提示中物种缺失或含糊，默认使用 `--species human`（或等价默认），并向用户明确标注该默认。
5. 列出基因转录本时，除非用户明确要求所有替代异构体，只返回人类 MANE Select 转录本；其他物种返回 Canonical 转录本；若存在多个转录本且默认主转录本，向用户标注。
6. 默认组装版本为 GRCh38；请求 GRCh37 时必须加 `--assembly GRCh37`；使用非默认组装版本时向用户明确标注。
7. 输出默认写入 `/tmp` 下的临时 JSON/FASTA 文件，或用 `--output` 指定文件；脚本同时向 stdout 打印简洁摘要。
8. 使用本技能时，确保在输出中提及使用了该技能。
9. 解析基因 ID：`uv run scripts/ensembl_api.py resolve-gene TP53 --species human --output tp53.json`；若主符号未找到会自动回退解析同义词，如 `uv run scripts/ensembl_api.py resolve-gene PCL2 --output pcl2.json`。
10. 映射 ID 到外部数据库：`uv run scripts/ensembl_api.py map-id ENSG00000141510 --external-db UniProt --output uniprot_map.json`；映射转录本到 RefSeq：`uv run scripts/ensembl_api.py map-id ENST00000269305 --external-db RefSeq_mRNA --output refseq_map.json`。
11. 获取基因组序列：`uv run scripts/ensembl_api.py get-sequence 17:7661779-7687550 --species human --output seq.txt`；GRCh37 用 `uv run scripts/ensembl_api.py get-sequence chr9:21971100-21971200 --assembly GRCh37 --output seq_grch37.txt`。
12. 获取基因摘要：`uv run scripts/ensembl_api.py gene-summary ENSG00000141510 --output gene_summary.json`，得到 symbol、biotype、description、chromosomal location。
13. 列出转录本：`uv run scripts/ensembl_api.py transcripts ENSG00000141510 --only-mane --output transcripts_mane.json`；Canonical：`uv run scripts/ensembl_api.py transcripts ENSG00000141510 --only-canonical --output transcripts_canonical.json`；全部：`uv run scripts/ensembl_api.py transcripts ENSG00000141510 --output transcripts_all.json`；输出包括 Transcript Support Level (TSL)。
14. 获取 canonical TSS：`uv run scripts/ensembl_api.py canonical-tss TP53 --output tp53_tss.json` 或 `uv run scripts/ensembl_api.py canonical-tss ENSG00000141510 --output tss.json`；该命令接受 symbol 和 Ensembl ID 并自动解析，按链方向计算（`+` 链 TSS 为 `Start`，`-` 链为 `End`），直接输出单个整数坐标。
15. 获取转录本结构：`uv run scripts/ensembl_api.py transcript-structure ENST00000269305 --output structure.json`，得到外显子坐标、CDS 边界和计算的 5'/3' UTR。
16. 获取蛋白信息：`uv run scripts/ensembl_api.py protein-info ENST00000269305 --output protein_info.json`，得到 ENSP ID 和序列长度。
17. 获取蛋白序列：`uv run scripts/ensembl_api.py protein-sequence ENST00000269305 --output protein.fasta` 或 `uv run scripts/ensembl_api.py protein-sequence ENSP00000269305 --output protein_ensp.fasta`，输出氨基酸 FASTA。
18. 运行 VEP 变异后果预测：`uv run scripts/ensembl_api.py vep 9:21971147:T:C --species human --output vep.json` 或 `uv run scripts/ensembl_api.py vep rs699 --species human --output vep_rs699.json`；包含开放许可插件 AlphaMissense、Conservation、DosageSensitivity、IntAct、MaveDB、OpenTargets、LoF (Loftee)、NMD、UTRAnnotator、mutfunc、LOEUF。
19. 展示 VEP 结果时，必须把 stdout 中完整的 VEP Predictions 列表呈现给用户，不要只做摘要；该列表包含标准 VEP 预测（Consequence、Amino Acids、SIFT、PolyPhen）和开放许可插件结果（AlphaMissense、Conservation、Dosage Sensitivity、LOEUF、Loftee LoF、NMD、UTRAnnotator、Mutfunc）。如果列表很长（很多转录本），完整显示 MANE Select / canonical 转录本行，并注明完整数据在 JSON 输出中。
20. 若用户需要 stdout 未汇总的详细嵌套结构数据（如转录本 Exon 2 的精确整数坐标），先定位 JSON 文件（`--output` 指定路径或脚本打印的临时文件路径），再用 `jq` 或一次性 Python 片段提取所需数据点；文件很大时不要把整个 JSON 读入上下文。
21. 若需要脚本不支持的 API 调用（如蛋白结构域注释、组装版本间坐标映射、同源搜索、连锁不平衡、表型查找），阅读 `references/ensembl_rest_api_reference.md` 获取完整 endpoints、参数和响应字段参考。
22. 编写自定义脚本或使用替代方案时，必须遵守 Ensembl REST API 速率限制（最大 15 requests per second），并优雅处理 `429 Too Many Requests` 错误（如指数退避）。

适用边界 · 注意事项

• 不适用于未安装 `uv`、无法访问 Ensembl REST API 或无法接受 Ensembl 使用条款的环境。
• 不适用于需要临床诊断级变异致病性结论或 Ensembl REST API 未覆盖的数据与分析。
• 不适用于无法遵守 15 requests per second 限速或无法处理 `429 Too Many Requests` 的高并发批量查询。