需要检索或下载生物分子实验 3D 结构…

适用于查询和下载 RCSB PDB 中实验测定的蛋白质、核酸、配体等生物分子 3D 结构及相关元数据。

适用场景

解决思路

1. Prerequisites: 阅读并遵循 uv skill 的 Setup 说明，确保 uv 已安装并在 PATH 中。
2. Prerequisites: 若工作区根目录不存在 `.licenses/pdb_database_LICENSE.txt`，则显著通知用户查看 https://www.rcsb.org/pages/usage-policy 的使用条款，然后创建该文件记录通知文本和时间戳。
3. Core: 始终优先使用技能提供的脚本；只有作为最后手段才用 `curl`、`urllib`、原始 HTTP 请求或其他方法访问 PDB API。脚本会自动执行所需速率限制。
4. Core: 始终将输出重定向到文件；用 `jq`、`grep` 或简短 Python 片段解析输出；不要将大型 API 响应打印到 stdout，以免截断。
5. Core: 如果使用本技能，确保在输出中提及。
6. Core: 完成使用 PDB JSON/GraphQL 查询的任务后，用清晰语言解释查询做了什么，以便用户纠正错误假设。
7. 属性搜索工作流 1：获取相关 schema 以发现可搜索属性名。结构属性：`uv run scripts/fetch_schema.py --api search_structure --output schema_structure.txt`；化学属性：`uv run scripts/fetch_schema.py --api search_chemical --output schema_chemical.txt`。
8. 属性搜索工作流 2：在 schema 中 grep 相关属性；一次只 grep 一个关键词并查看多行——相似属性很多，必须选择最符合用户意图的最佳匹配。
9. 属性搜索工作流 3：用发现的属性构造并运行 JSON 搜索查询：`uv run scripts/search_pdb.py --query '<JSON>' --return_type <RETURN_TYPE> --output results.json`；传 `--count_only` 只获取匹配条目数。
10. 选择属性时参考 PDB 概念：Entity 是结构中的唯一分子；Instance/Chain 是实体的具体拷贝（如两条相同序列蛋白链是同一 entity 不同 instance/chain）；Assembly 是生物学相关实例/链集合，可能等于、少于或多于 deposited structure；Label vs Auth 是聚合物实例标签和单体编号方案，label 更一致且脚本/API 总用 label，但用户和论文可能用 auth，必要时澄清；Chemical component 是小分子/单体，ID 匹配 `[A-Z]{1,3}`；Primary citation 是结构主要论文，优先用 `primary_citation` 属性而非 `citation`；Resolution 是结构质量常用指标（越低越好），通常优先用 `rcsb_entry_info.resolution_combined`，它考虑不同实验方法。
11. 属性搜索示例：非人类蛋白、发表在 Nature、最新优先：`uv run scripts/search_pdb.py --query '{ "type": "group", "logical_operator": "and", "nodes": [ { "type": "terminal", "service": "text", "parameters": { "operator": "exact_match", "negation": true, "value": "Homo sapiens", "attribute": "rcsb_entity_source_organism.taxonomy_lineage.name" } }, { "type": "terminal", "service": "text", "parameters": { "operator": "exact_match", "value": "Nature", "attribute": "rcsb_primary_citation.rcsb_journal_abbrev" } } ] }' --return_type entry --sort_by rcsb_accession_info.initial_release_date --sort_direction desc --page_start 0 --rows 100 --output results.json`。
12. 属性搜索示例：包含化学组分 CA（Ca2+ 离子）的结构：`uv run scripts/search_pdb.py --query '{ "type": "terminal", "service": "text_chem", "parameters": { "operator": "exact_match", "value": "CA", "attribute": "rcsb_chem_comp_container_identifiers.comp_id" } }' --return_type entry --output results.json`。
13. 属性搜索示例：含二硫键的条目数量：`uv run scripts/search_pdb.py --query '{ "type": "terminal", "service": "text", "parameters": { "operator": "exact_match", "value": "disulfide bridge", "attribute": "rcsb_polymer_struct_conn.connect_type" } }' --return_type entry --count-only --output count.json`。
14. 常用操作符：`exact_match`、`equals`、`exists`、`contains_phrase`、`contains_words`、`in`、`greater`、`less`。
15. 相似性搜索工作流：相似性搜索不需要获取 schema。
16. 相似性搜索示例：序列相似性：`uv run scripts/search_pdb.py --query '{ "query": { "type": "terminal", "service": "sequence", "parameters": { "evalue_cutoff": 1, "identity_cutoff": 0.9, "sequence_type": "protein", "value": "MTEYKLVVVGAGGVGKSALTIQLIQNHFVDEYDPTIEDSYRKQ" } }, "request_options": { "scoring_strategy": "sequence" } }' --return_type polymer_entity --output results.json`。
17. 相似性搜索示例：结构相似性：`uv run scripts/search_pdb.py --query '{ "type": "terminal", "service": "structure", "parameters": { "value": {"entry_id": "6LU7", "asym_id": "A"}, "number_of_candidates": 2000 } }' --return_type polymer_entity --output results.json`。
18. 相似性搜索示例：序列 motif 匹配：`uv run scripts/search_pdb.py --query '{ "type": "terminal", "service": "seqmotif", "parameters": { "value": "C-x(2,4)-C-x(3)-[LIVMFYWC]-x(8)-H-x(3,5)-H.", "pattern_type": "prosite", "sequence_type": "protein" } }' --return_type polymer_entity --output results.json`。
19. 相似性搜索示例：化学描述符匹配：`uv run scripts/search_pdb.py --query '{ "type": "terminal", "service": "chemical", "parameters": { "value": "InChI=1S/C8H9NO2/c1-6(10)9-7-2-4-8(11)5-3-7/h2-5,11H,1H3,(H,9,10)", "type": "descriptor", "descriptor_type": "InChI", "match_type": "graph-strict" } }' --return_type mol_definition --output results.json`。
20. 相似性搜索更多细节见 https://search.rcsb.org/#search-services。
21. 全文搜索工作流：搜索与条目关联的所有文本。示例：`uv run scripts/search_pdb.py --query '{ "type": "terminal", "service": "full_text", "parameters": { "value": "isopeptide + ( collagen | fibrinogen )" } }' --return_type entry --output results.json`。
22. 全文搜索重要规则：仅在没有更精确属性搜索可用时，作为最后手段使用 `full_text`；可考虑改用 `struct.title` 或 `rcsb_pubmed_abstract_text` 属性。
23. 文件下载工作流：下载完整 PDB 条目时使用 `download_coordinate_files.py`。在需要原子坐标、被要求提供 pdb/mmcif 文件、或非特定要求获取 PDB code 时使用。示例：`uv run scripts/download_coordinate_files.py --ids "4HHB,6BEA" --format "mmcif" --output_dir <OUTPUT_DIR>`。
24. 元数据查询工作流：只需要少量 entry/entity 元数据时，比下载完整坐标文件高效得多。
25. 元数据查询工作流 1：获取相关对象类型的 schema。例如：`uv run scripts/fetch_schema.py --api data_entry --output schema_entry.txt`。
26. 元数据查询工作流 2：在 schema 中 grep 相关字段（一次一个关键词，查看多行）。
27. 元数据查询工作流 3：构造并运行 GraphQL 元数据查询：`uv run scripts/fetch_pdb_metadata.py --query '<GraphQL>' --output results.json`。
28. 元数据查询示例：获取结构标题和实验方法：`uv run scripts/fetch_pdb_metadata.py --query '{ entries(entry_ids: ["1STP", "2JEF", "1CDG"]) { rcsb_id struct { title } exptl { method } } }' --output results.json`。
29. 元数据查询示例：获取聚合物实体分类和簇成员关系：`uv run scripts/fetch_pdb_metadata.py --query '{ polymer_entities(entity_ids:["2CPK_1","3WHM_1","2D5Z_1"]) { rcsb_id rcsb_entity_source_organism { ncbi_taxonomy_id ncbi_scientific_name } rcsb_cluster_membership { cluster_id identity } } }' --output results.json`。
30. 元数据查询示例：获取聚合物实体外部序列数据库登录号：`uv run scripts/fetch_pdb_metadata.py --query '{ entries(entry_ids:["7NHM", "5L2G"]){ polymer_entities { rcsb_id rcsb_polymer_entity_container_identifiers { reference_sequence_identifiers { database_accession database_name } } } } }' --output results.json`。

适用边界 · 注意事项

• 不要用于获取预测结构（如 AlphaFold）或非实验测定的 3D 结构；本技能面向 RCSB PDB 中的实验测定结构。
• 无法访问 RCSB PDB API/网站、无法安装 uv 或无法运行提供的脚本时，不要使用本技能。
• 不要首选全文搜索；仅当没有更精确的属性搜索可用时作为最后手段使用 full_text。