在 NCBI dbSNP 中查询…

当需要用 NCBI dbSNP 将 rsID、基因组坐标、HGVS 字符串互相转换，或检索区域变异及相关注释信息时，使用提供的 dbsnp_cli.py 包装脚本。

适用场景

解决思路

1. 始终使用提供的 wrapper 脚本 scripts/dbsnp_cli.py 查询数据库，不要构造自定义 HTTP 或 curl 请求；脚本会自动处理限流、重试和 JSON 解析。
2. 执行命令时使用 uv run scripts/dbsnp_cli.py ... 形式，并确保 uv 已安装且在 PATH 上。
3. 如果 workspace 根目录不存在 .licenses/dbsnp_database_LICENSE.txt，先显著提醒用户查看 https://www.ncbi.nlm.nih.gov/snp/ 的条款，再创建该文件记录提醒文本和时间戳。
4. 确保 home 目录存在 .env 文件；不存在则创建。
5. NCBI_API_KEY 可选；没有 key 时限流为 3 requests/second，有 key 为 10 requests/second；如大量查询或遇到 429，建议在 https://www.ncbi.nlm.nih.gov/account/settings/ 注册免费 key。
6. 如技能与用户请求相关，必须使用 credentials skill 的安全凭据协议检查并请求 NCBI_API_KEY。
7. 若用户提供 rsID（如 rs7412、rs268），运行 get-variant。
8. 若用户提供基因组坐标 chrom pos ref alt（如 8 19962213 C T），运行 resolve-variant。
9. 若用户提供 HGVS 字符串（如 NC_000008.11:g.19962213del），运行 resolve-hgvs。
10. 若用户提供 rsID 且想要回基因组坐标，运行 resolve-rsid。
11. 若用户提供染色体区域 chrom start end，运行 search-region。
12. 不要用 search-region 查找特定变异的 rsID；如果给了 chromosome、position、reference allele、alternate allele 四个值，用 resolve-variant，它是直接的单 API 调用查找。
13. search-region 仅用于勘察一个位置范围内所有变异，会返回数百或数千条结果。
14. 所有子命令都把 JSON 写到磁盘；始终将输出保存到 /tmp/ 目录；--output 是必需参数。
15. Quick start 示例：uv run scripts/dbsnp_cli.py get-variant rs7412 --output /tmp/rs7412.json。
16. Quick start 示例：uv run scripts/dbsnp_cli.py resolve-variant 8 19962213 C T --output /tmp/resolve.json。
17. get-variant 示例：uv run scripts/dbsnp_cli.py get-variant rs268 --output /tmp/rs268.json。
18. get-variant 接受 rs268 和 268 两种形式。
19. get-variant 参数：rsid 位置参数必需；--assembly 默认 GCF_000001405.40，即 GRCh38；--full 返回完整原始 JSON；--output 默认 /tmp/dbsnp_output.json。
20. get-variant 缩写输出字段包括 refsnp_id 数字 rsID、variant_type 如 snv、ins、del、delins、genes 排序的 gene symbols、clinical_significances 临床显著性标签列表、minor_allele_frequencies 研究名称与等位基因计数和总数、placements 请求 assembly 的基因组 placements。
21. 避免在 get-variant 上使用 --full，除非确实需要；原始 payload 通常 50–500 KB，临床显著变异可能超过 1 MB。
22. 只有需要缩略输出没有的数据时才用 --full，例如跨所有转录本和蛋白 isoform 的完整 HGVS 命名、完整提交历史及提交者细节和时间戳、研究内亚群的群体等位基因频率细分、跨多个 assembly 的完整 genomic placements、显示哪些旧 rsID 合并进来的 merge history。
23. resolve-variant 示例：uv run scripts/dbsnp_cli.py resolve-variant 8 19962213 C T --output /tmp/resolve.json。
24. resolve-variant 参数：chrom 为染色体编号或 RefSeq 序列 accession；X 和 Y 必须用数字等价物 23 表示 X、24 表示 Y；pos 为 1-based 基因组位置；ref 为参考等位基因；alts 为逗号分隔的交替等位基因；--assembly 默认 GCF_000001405.40；--output 默认 /tmp/dbsnp_output.json。
25. resolve-variant 输出包含 rsids 列表。
26. resolve-rsid 示例：uv run scripts/dbsnp_cli.py resolve-rsid rs7412 --output /tmp/coords.json。
27. resolve-rsid 参数：rsid 位置参数；--assembly 默认 GCF_000001405.40；--output 默认 /tmp/dbsnp_output.json。
28. resolve-rsid 输出包含 rsid、assembly、placements。
29. resolve-hgvs 示例：uv run scripts/dbsnp_cli.py resolve-hgvs 'NC_000008.11:g.19962213del' --output /tmp/hgvs.json。
30. resolve-hgvs 参数：hgvs 位置参数；--assembly 默认 GCF_000001405.40；--output 默认 /tmp/dbsnp_output.json。
31. resolve-hgvs 输出包含 rsids 列表。
32. HGVS 字符串常包含 shell 会解释的字符，如冒号、大于号；始终用单引号包裹，如 'NC_000008.11:g.19962213del'。
33. search-region 示例：uv run scripts/dbsnp_cli.py search-region 7 117100000 117300000 --output /tmp/region.json。
34. search-region 参数：chrom 位置参数；使用 23 表示 chromosome X、24 表示 chromosome Y；start 位置参数；end 位置参数；--retmax 最大 rsIDs 数，默认 500，上限 5 000；--output 默认 /tmp/dbsnp_output.json。
35. search-region 输出包含 rsids、returned、total_available、truncated、note。
36. 当 total_available 超过返回数量时，输出包含 truncated 标记和 note，note 可能提示 Only 500 of 1423 variants returned；提高 --retmax 可获取更多，最多 5 000。
37. 工作流：从坐标识别已知变异，Step 1 用 resolve-variant 19 44908684 T C --output /tmp/step1.json，Step 2 用 get-variant <rsid_from_step1> --output /tmp/step2.json。
38. 工作流：勘察基因区域变异，Step 1 用 search-region 7 117100000 117300000 --retmax 1000 --output /tmp/region.json，Step 2 用 get-variant <rsid> --output /tmp/detail.json。
39. 工作流：将 HGVS 转成基因组坐标，Step 1 用 resolve-hgvs 'NC_000019.10:g.44908684T>C' --output /tmp/hgvs.json，Step 2 用 resolve-rsid <rsid> --output /tmp/coords.json。
40. Variation Services 端点，包括 get-variant、resolve-variant、resolve-rsid、resolve-hgvs，期望 RefSeq assembly accession；GRCh38 为 GCF_000001405.40，GRCh37 为 GCF_000001405.25。
41. search-region 始终搜索 GRCh38 位置。
42. resolve-variant 和 resolve-hgvs 会自动先试 GRCh38；如果找不到 rsIDs，再试 GRCh37 后才报告失败。
43. 发生自动 fallback 时，输出 JSON 包含 note 字段说明哪个 assembly 成功；不需要手动用不同 assembly 重试。
44. 只有需要将查找限制到某一个 assembly 时才覆盖 --assembly，例如用户坐标已知是 GRCh37。
45. 无 API key 时限流 3 requests/second；有 key 时限流 10 requests/second。
46. 如遇 HTTP 500 且消息说明断言的 reference allele 不等于参考序列：坐标位置可能有效，但提供的 ref 与请求 assembly 中该位置碱基不匹配。
47. 对 reference allele mismatch：不要机械地重试完全相同查询；检查 assembly，因为坐标是 assembly 特异的；切换 assembly：如果查询 GRCh37，改用 --assembly GCF_000001405.40；如果查询 GRCh38，改用 --assembly GCF_000001405.25。
48. 常见错误：忘记引用 HGVS 字符串；修复：用单引号包裹，如 'NC_000008.11:g.19962213del'。
49. 常见错误：给 resolve-variant 传染色体名称而不是序列 accession；修复：使用数字染色体 ID，如 8，或 RefSeq accession，如 NC_000008.11。
50. 常见错误：不需要却使用 get-variant --full；修复：缩写输出覆盖大多数场景，--full 返回 50–500 KB+ JSON。
51. 常见错误：期望 search-region 默认返回所有结果；修复：默认 --retmax 为 500，检查输出中的 total_available 看是否截断。
52. 常见错误：把 GRCh37 坐标用于 search-region；修复：search-region 始终使用 GRCh38 位置，若从 GRCh37 开始需先 lift over。
53. 常见错误：resolve-variant 或 resolve-hgvs 第一次失败时手动用不同 --assembly 重试；修复：脚本会自动先试 GRCh38 再试 GRCh37，一次调用足够。
54. 常见错误：把 X 或 Y 作为 chromosome 值传入；修复：使用数字等价物，23 表示 chromosome X，24 表示 chromosome Y；CLI 默认按数字处理染色体。
55. 如果使用了本技能，确保在输出中提及。

适用边界 · 注意事项

• 需要带提交者证据的临床致病性分类时，不要用本技能，改用 clinvar-database。
• 需要按祖先分层的精确群体等位基因频率时，不要用本技能，改用 gnomad-database。
• 需要预测新突变的功能效应或查看受变异影响的 3D 蛋白结构时，不要用本技能，改用 alphagenome-single-variant-analysis 或 alphafold-database-fetch-and-analyze / pdb-database。