tooluniverse-sequence-retrieval

生物序列检索

检索 DNA、RNA 和蛋白质序列，并正确处理消歧和跨数据库查询。

重要：工具调用中始终使用英文术语。只有在备用方案中才尝试原语言术语。使用用户的语言回复。

查询而非猜测：切勿假设登录号或序列版本。始终从 NCBI 或 ENA 检索并验证。

领域知识

序列质量层级：RefSeq（NM_/NP_ = 经整理）> RefSeq 预测序列（XM_/XP_）> GenBank（提交序列）。对于人类标准异构体，优先选择 MANE Select 转录本。检查版本号——注释会随着版本更新而改进。

工作流

Phase 0: Clarify (if needed) → Phase 1: Disambiguate Gene/Organism → Phase 2: Search & Retrieve → Phase 3: Report

---

阶段 0：澄清（必要时）

仅在以下情况提问：基因存在于多个生物体中、序列类型不明确，或菌株会影响结果。 以下情况跳过：指定了登录号、明确给出物种和基因，或请求了指定生物体的完整基因组。

---

阶段 1：基因／生物体消歧

登录号类型决策树

前缀	类型	使用方式
NC_/NM_/NR_/NP_/XM_	RefSeq	仅使用 NCBI
U*/M*/K*/X*/CP*/NZ_	GenBank	使用 NCBI 或 ENA
EMBL 格式	EMBL	优先使用 ENA

关键：切勿使用 RefSeq 登录号调用 ENA 工具——这些工具会返回 404。

身份核对清单

• 已确认生物体（学名）
• 已识别基因符号／名称
• 已确定序列类型（基因组／mRNA／蛋白质）
• 已识别登录号前缀，以便选择工具

---

阶段 2：数据检索（内部）

静默检索。不要叙述搜索过程。

# Search NCBI Nucleotide
result = tu.tools.NCBI_search_nucleotide(
    operation="search", organism=organism, gene=gene,
    strain=strain, keywords=keywords, seq_type=seq_type, limit=10
)

# Get accessions from UIDs
accessions = tu.tools.NCBI_fetch_accessions(operation="fetch_accession", uids=result["data"]["uids"])

# Retrieve sequence (FASTA or GenBank format)
sequence = tu.tools.NCBI_get_sequence(operation="fetch_sequence", accession=accession, format="fasta")

# ENA alternative (non-RefSeq accessions only)
entry = tu.tools.ena_get_entry(accession=accession)
fasta = tu.tools.ena_get_sequence_fasta(accession=accession)

备用方案链

首选	备用方案	说明
NCBI_get_sequence	ENA（若为 GenBank 格式）	NCBI 不可用
ena_get_entry	NCBI_get_sequence	ENA 不提供 RefSeq
NCBI_search_nucleotide	尝试更宽泛的关键词	无结果
NCBI_get_sequence / ena_get_sequence_fasta	dbfetch_fetch_entry (db="refseqn"/"ena_sequence")	NCBI 和 ENA 专用工具均不可用；dbfetch 镜像相同的底层记录

---

阶段 3：报告序列概况

以 序列概况报告 的形式呈现。隐藏搜索过程。包括：

1. 搜索摘要：查询内容、数据库、结果数量
2. 主要序列：登录号、类型（RefSeq/GenBank）、生物体、菌株、长度、分子类型、拓扑结构、整理级别
3. 序列预览：FASTA 的开头几行（截断显示）
4. 注释摘要：CDS/tRNA/rRNA/调控特征数量（来自 GenBank 格式）
5. 替代序列：按相关性和整理级别排序，并注明 ENA 兼容性
6. 跨数据库引用：RefSeq、GenBank、ENA/EMBL、BioProject、BioSample
7. 下载选项：FASTA（用于 BLAST／序列比对）、GenBank（用于注释）

整理级别

层级	前缀	说明
RefSeq 参考序列（最佳）	NC_, NM_, NP_	经 NCBI 整理，黄金标准
RefSeq 预测序列	XM_, XP_, XR_	通过计算预测
GenBank 已验证	各种	已提交，经过部分整理
GenBank 直接提交	各种	直接提交
第三方	TPA_	第三方注释

---

推理框架

序列质量：优先选择 RefSeq，而非 GenBank。检查版本号。定义中带有 “PREDICTED” 的序列未经实验验证。

登录号指南：RefSeq = 仅限 NCBI。GenBank = 在 ENA/EMBL 中有镜像。对于人类／模式生物，默认使用 RefSeq mRNA（NM_）；对于微生物查询，使用最完整的基因组组装版本。

跨数据库对照：同一序列可能具有不同登录号（例如，E. coli K-12 的 GenBank U00096 = RefSeq NC_000913）。如有，请始终同时报告两者。GenBank/RefSeq 之间的差异通常表示 RefSeq 整理已修正提交错误。

综合问题

1. 可用的最高质量登录号是什么？
2. 其他数据库中是否有替代登录号？
3. 注释完整度如何？
4. 序列是否来自预期的生物或菌株？
5. 哪种下载格式适合用户的下游分析？

---

错误处理

错误	响应
"No search criteria provided"	添加生物、基因或关键词
"ENA 404 error"	可能是 RefSeq；仅使用 NCBI
"No results found"	扩大搜索范围，检查拼写，尝试同义词
"Sequence too large"	说明大小，并改为提供下载链接

---

工具参考

NCBI 工具：NCBI_search_nucleotide（搜索）、NCBI_fetch_accessions（UID→登录号）、NCBI_get_sequence（检索） ENA 工具（仅限 GenBank/EMBL）：ena_get_entry（元数据）、ena_get_sequence_fasta（FASTA）、ena_get_entry_summary（摘要）

---

搜索参数参考

NCBI_search_nucleotide：operation="search"，organism（学名），gene（符号），strain，keywords，seq_type（complete_genome/mrna/refseq），limit

NCBI_get_sequence：operation="fetch_sequence"，accession，format（fasta/genbank）

---

UniProt 全生物参考蛋白质组

与上述阶段 1–3 的粒度不同：src/tooluniverse/data/uniprot_ref_tools.json 中的 UniProtRef_search_proteomes/UniProtRef_get_proteome（无需 API 密钥） 返回的是生物体级别的蛋白质组元数据——蛋白质总数、 染色体/组分明细、基因组登录号——而非单条序列。 当问题是“物种 X 的参考蛋白质组是什么，有多大”（例如，在进行 全蛋白质组分析之前，或查找要交给上述阶段 2 的正确基因组组装登录号）时， 应使用这些工具；它们不适用于获取单个基因/转录本序列。

工具	解析内容	关键输出
UniProtRef_search_proteomes	生物名称/分类 ID -> 匹配的蛋白质组 ID	id（UPXXXXXXXXX）、organism、taxon_id、proteome_type（Reference/Non Reference）、protein_count
UniProtRef_get_proteome	一个蛋白质组 ID -> 完整的生物/组装详情	organism.scientific_name/taxon_id、components[]（name、protein_count、genome_accession）、total_protein_count

实际示例链（已实时验证）：UniProtRef_search_proteomes {"query": "SARS-CoV-2"} -> 返回 3 条结果，其中包括 UP000464024（proteome_type: "Reference proteome"，17 个蛋白质），以及该生物的两个 "Non Reference proteome" 条目（分别含 5 和 10 个蛋白质）——务必检查 proteome_type，优先选择 "Reference proteome"，不要 默认第一条结果就是标准条目。将 UP000464024 传给 UniProtRef_get_proteome 后可确认 components: [{"name": "Segment", "protein_count": 17, "genome_accession": "MN908947"}]（SARS-CoV-2 的真实 参考基因组登录号），以及 total_protein_count: 17。对于人类 （UP000005640）和大肠杆菌 K-12（UP000000625）， get_proteome 也会以相同方式返回按染色体/质粒划分的组分明细。

注册表重复，已实时验证：UniProt_search_proteomes（位于 src/tooluniverse/data/uniprot_proteomes_tools.json，直接调用 rest.uniprot.org/proteomes/search）执行的搜索与上述 UniProtRef_search_proteomes 完全相同，但它是单独的较旧工具 实现。它的优势是一次调用即可返回完整的丰富记录 （BUSCO 完整度、基因组组装、各组分的蛋白质数量、完整引用列表）；而要获取这些信息， UniProtRef_search_proteomes 需要再调用一次 UniProtRef_get_proteome。 已在 organism_name: human、organism_name:escherichia coli、organism_name:mouse 上实时验证， 三者均在一次调用中返回完整的嵌套对象。如果只需 ID 或 proteomeType 进行初步筛选，任一工具均可；如果需要立即获得完整详情， 则优先使用 UniProt_search_proteomes，省去后续调用。

序列归档与聚类（UniParc、UniRef）

再来看一个与阶段 1-3 及上述蛋白质组工具不同的问题： “这个确切的序列以前是否出现过，以及对应多少个登录号？” 以及“还有哪些序列与它几乎完全相同？”

工具	回答的问题	关键参数
UniParc_search	查找某个基因/生物体/关键词对应的所有 UPI 归档条目	query（UniProt 查询语法，例如 "gene:EGFR AND organism_id:9606"）、size
UniParc_get_entry	完整序列，以及在所有数据库加载期间曾指向这个确切序列的每个 UniProt 登录号	upi
UniRef_search_clusters	查找某个基因/生物体/关键词对应的序列相似性簇	query、cluster_type（UniRef100/90/50）、size
UniRef_get_cluster	簇详情：成员数量、代表序列、共同分类群	cluster_id（例如 UniRef90_P00533）

真实示例（实时验证，EGFR/人类）：UniParc_search {"query": "gene:EGFR AND organism_id:9606", "size": 3} -> 3 个不同的 UPI 条目，每个都有不同的一组 UniProt 登录号（Q8NDU8.1、Q9BZS2.1、Q9UMG5.1），且 oldest_created 日期各不相同——UniParc 将每个独特的氨基酸序列视为一个条目，不论是由哪个 UniProt 登录号提交的，因此序列不同的异构体/片段会获得不同的 UPI，即使它们共享同一个基因名称也是如此。UniRef_get_cluster {"cluster_id": "UniRef90_P00533"} -> 一个真实的 119 成员簇，涵盖 Boreoeutheria （共同祖先分类群），其中有一个 representative_member（EGFR_HUMAN，1210 aa），包含 9 个以上合并的 UniProtKB 登录号（P00533、O00688，……）——请注意，seed_id（UPI0005F3CCCC，一个 UniParc ID）和 representative_member 不一定是同一条序列。

如果问题是“哪些 UniProt 登录号确实共享这个确切序列”（去重），请使用 UniParc；如果问题是“还有哪些序列与这个序列的相似度达到 X%”（查找跨物种的相关蛋白质，用作 MSA/系统发育分析输入，或在蛋白质组范围分析前减少冗余），请使用 UniRef。

亚细胞定位词汇（UniProt Locations）

UniProtLocations_search/UniProtLocations_get_location 可通过 ID（SL-XXXX）或自由文本搜索，查询 UniProt 的受控亚细胞定位词汇（细胞器、膜、拓扑结构、方向）。

**实际注意事项，已实时验证：**常见术语“plasma membrane”并不会显示 UniProt 对应的实际术语——UniProt 的受控词汇将该定位称为 “Cell membrane”（SL-0039），而不是“Plasma membrane”。搜索 "plasma membrane" 或 "Plasma membrane" 只会返回间接相关的结果（例如 SL-0552“Rhabdomere membrane”，其定义中恰好提到了“plasma membrane”，但它本身并不是该术语）。请搜索更宽泛、符合 UniProt 用法的术语（"membrane"、"cell"），并浏览结果，不要想当然地认为日常使用的生物学术语与 UniProt 的命名一致——这是实际的词汇不匹配，并非搜索错误。

样本元数据（EBI BioSamples）

BioSamples_search/BioSamples_search_by_filter/BioSamples_get_sample/ BioSamples_get_relationships/BioSamples_get_facets 可查询 EBI 的 6,000 多万条 样本元数据档案（生物体、组织、疾病、实验背景），这些样本支撑着测序/组学提交记录——这是 与序列本身不同的一个层面，可用于在前往 ENA/SRA 获取实际数据之前，了解“条件 X 有哪些样本”。

**已在线验证的实际注意事项：**使用多词短语（"EGFR lung adenocarcinoma"）调用 BioSamples_search 时返回了 零 条结果，而单个词 "EGFR" 则立即返回了实际结果—— 该搜索不会像搜索引擎那样默认对多个自由文本词进行 AND 匹配。请一次使用一个关键词； 或者，如果需要组合多个实际约束，请使用 BioSamples_search_by_filter（结构化的 attribute/value 配对，例如 attribute="organism", value="Homo sapiens"）。筛选前先使用 get_facets 查看实际存在的属性值会很有帮助（已在线验证：会返回 实际的分面计数，例如，宽泛文本查询有 432,302 个样本）。

生物体分类（EBI Taxonomy）

EBITaxonomy_get_by_id/get_by_scientific_name/search_by_name/suggest 可解析生物体名称/ID（NCBI Taxonomy，由 EBI 镜像）——包括谱系、 等级、分类和遗传密码。常用名（“mouse”、“fruit fly”）请使用 search_by_name；类型预填部分匹配请使用 suggest； 已知精确名称/ID 请使用 get_by_scientific_name/get_by_id。 已在线验证：Homo sapiens -> tax_id: "9606"，完整谱系字符串为 "Eukaryota; Metazoa; Chordata; ... Hominidae; Homo;"。

跨领域快速查询（BioThings Gateway）

BioThings_list_apis/BioThings_query/BioThings_get_entity/ BioThings_get_metadata 可通过一个 Elasticsearch 风格的查询接口访问约 50 个由 BioThings 托管的 API（药物相互作用、 基因—疾病文本挖掘、从 PubMed 挖掘的预测等）。在使用这个通用网关之前，可先快速检查 ToolUniverse 是否已对某项资源提供 专用覆盖（BioThings_list_apis 的 preferred_tooluniverse_tool 字段会提示是否已有功能更丰富的专用工具；如有，请优先使用该工具）。编写带字段的 BioThings_query 前，请先调用 BioThings_get_metadata，以确保字段名称正确。已在线 验证：BioThings_get_entity {"api": "mondo", "entity_id": "MONDO:0010329"} 会返回包含祖先术语的实际 MONDO 疾病本体记录；查询 ddinter API 会返回包含严重程度的实际药物相互作用配对结果。 这补充了 tooluniverse-data-integration-analysis 的多数据库证据收集工作流；如果所需资源没有现成的专用工具，它可作为快速的单次调用选项。

跨数据库 ID 解析（Bioregistry、Identifiers.org、TogoID）

三个相互重叠的注册表，用于解决“我在系统 A 中有一个 ID，它在系统 B 中对应什么”这一问题——已通过一个共享示例（人类 TP53）进行实时验证：NCBI Gene 7157 -> TogoID_convert {"ids": "7157", "source": "ncbigene", "target": "ensembl_gene"} -> 实际结果 ENSG00000141510；该 Ensembl 基因的 HGNC ID 11998 可通过 Bioregistry_resolve_reference {"prefix": "hgnc", "identifier": "11998"} 和 IdentifiersOrg_resolve {"namespace": "hgnc", "local_id": "11998"} 解析到相同的 genenames.org 记录，证实两个注册表的结果一致。

• Bioregistry（Bioregistry_resolve_reference/get_registry/get_prefix_mappings/search_registries）——包含 2600 多个前缀，为每个标识符返回多个提供方 URL（bioregistry.io、identifiers.org、n2t.net、bio2rdf，以及相关时指向 GenCC/INDRA 等资源的特定链接），还提供前缀元数据（ID 正则表达式模式、主页）。如果不知道某个数据库的确切前缀，请先使用 search_registries。
• Identifiers.org（IdentifiersOrg_resolve/get_namespace/search_namespaces/list_namespaces）——原始 MIRIAM 注册表；resolve 会返回完整的机构/提供方元数据（哪个组织托管该解析器、推荐的提供方与备用提供方），而 Bioregistry 的 default 链接不会显示这些信息。如果你需要知道某个命名空间的规范解析器由谁运营，而不只是获取 URL，请优先使用它。
• TogoID（TogoID_convert/list_datasets）——这三者中唯一真正能在 117 种数据集类型之间转换 ID 的工具（而不只是提供已有 ID 的 URL），例如每次调用都可完成 NCBI Gene -> Ensembl Gene -> UniProt -> PDB 的转换。先调用 list_datasets，获取有效的 source/target 数据集类型字符串。

当工作流需要在不同 ID 系统之间跳转，而此技能的专用工具（上文的 UniProt/UniParc/UniRef/EBI Taxonomy）无法直接连接这些系统时，可使用这组工具——例如，将变异分析技能的 Ensembl 基因 ID 转换为另一个工具所需的 NCBI Gene ID。

EBI dbfetch（一个接口，多个数据库）

dbfetch_fetch_entry（db、id、format）/ dbfetch_fetch_batch（db、逗号分隔的 ids、format）/ dbfetch_list_databases / dbfetch_list_formats——通过统一调用，按登录号从 EBI 托管的 16 个数据库（uniprotkb、pdb、embl、ena_sequence、refseqp、refseqn、ensemblgene、ensembltranscript、interpro、medline、taxonomy、uniprot、chembl、afdb、imgtligm、hgnc）中的任意一个获取原始记录；也可以通过一次 fetch_batch 请求，从同一个数据库获取多个登录号。无需 API 密钥。已进行实时验证：dbfetch_fetch_entry {"db": "uniprotkb", "id": "P04637", "format": "fasta"} 返回真实的人类 p53（P53_HUMAN）FASTA 序列；dbfetch_fetch_batch {"db": "uniprotkb", "ids": "P04637,P01308", "format": "fasta"} 在一次响应中返回 p53 和胰岛素。

何时使用此工具，而不是上文的专用工具：当你需要跨不同类型的数据库进行单次或批量获取，且不想切换各数据库专用工具/客户端时，可使用 dbfetch（例如在短暂的会话中获取 UniProt 条目、PDB 条目和 EMBL 条目）；或者当你特别需要 fetch_batch 一次调用获取多个登录号的便利性时，也可使用它。如果你需要更丰富的结构化字段（交叉引用、特征注释、整理级别的元数据），请优先使用上文的专用工具（UniProt/UniParc/ENA/NCBI）——dbfetch 返回的是数据库原生的扁平文本/FASTA/XML 文本，而不是经过解析的结构化对象。