foldseek-structural-search

前置条件

1. uv：阅读 uv 技能，并按照其中的设置说明操作，确保已安装 uv 且其位于 PATH 中。
2. 用户通知：如果工作区根目录中尚不存在 .licenses/foldseek_structural_search_LICENSE.txt，则 (1) 显著提醒用户查看 https://search.foldseek.com/search 和 https://github.com/steineggerlab/foldseek 上的条款，然后 (2) 创建该文件，记录通知文本和时间戳。

目标

将用户提供的 3D 蛋白质结构文件（.cif、.mmcif 或 .pdb）提交到 Foldseek Web 服务 API，以查找结构相似的蛋白质。报告排名靠前的结构命中结果，解读关键比对指标，总结推断出的蛋白质功能，将 Markdown 格式的表格保存到 .md 文件，并将完整的详细结果保存到本地 JSON 文件。

核心规则

• 文件要求：此工具绝对无法按序列、名称或登录 ID 搜索。它严格要求提供 .pdb、.cif 或 .mmcif 文件路径。
• 严格验证：绝不绕过输入验证或数据库允许列表检查。
• 不要解析 JSON：完全依赖生成的 .md 文件撰写即时摘要。JSON 仅用于后续的专用工具。
• 不要解析原始数据：不要尝试自行解析或读取原始 3D 坐标；始终将文件传递给脚本处理。
• 通知：如果使用了此技能，确保在输出中提及。

说明

1. 严格验证输入： 确认用户明确提供了工作区中 .cif、.mmcif 或 .pdb 文件的有效路径。
   • 如果用户提供的是蛋白质名称、氨基酸序列或登录号（例如 UniProt ID），但没有已下载的结构文件，立即停止。不要运行脚本。
   • 告知用户 Foldseek 需要实际的 3D 坐标文件，并建议先下载结构（例如使用 AlphaFold 获取工具）。
2. 数据库验证： 检查用户是否指定了要搜索的数据库。
   • 允许的列表： afdb50、afdb-swissprot、pdb100、BFVD、mgnify_esm30、cath50、gmgcl_id、bfmd、afdb-proteome。
   • 如果用户请求的数据库不在此列表中，立即停止。不要运行脚本。告知用户该数据库不受支持，并提供允许的数据库列表。
3. 生成文件名： 根据输入文件生成描述性输出文件名，分别用于 JSON 数据和 Markdown 表格（例如，proteinA_foldseek_results.json 和 proteinA_foldseek_results.md）。
4. 根据用户的请求执行 Python 脚本，并将标准输出重定向到生成的 .md 文件：
   • 默认（未指定数据库）： uv run scripts/search.py <path-to-file> -o <generated-filename.json> > <generated-filename.md>
   • 自定义（指定了有效数据库）： uv run scripts/search.py <path-to-file> -o <generated-filename.json> --databases <db1,db2,db3> > <generated-filename.md>
5. 脚本会查询数据库、保存完整的 JSON 负载，并将 Markdown 格式的表格写入指定的 .md 文件。
6. 读取结果： 打开并仔细阅读新生成的 .md 文件，查看 Markdown 表格。
7. 解读指标： 为用户总结 3 至 5 个具有明确注释的最佳结构匹配。报告时，使用以下特定字段评估匹配质量：
   • Prob（概率）： 接近 1.0（100%）的值表示该折叠是真正结构同源体的置信度极高。
   • Q-Cov（查询覆盖率）： 较高的百分比表示匹配覆盖了查询蛋白质整体结构的大部分，而不只是一个小的局部基序。
   • E-value 和 Seq Identity： 使用这些指标提供额外的进化背景信息。
8. 进行功能分析： 分析所报告匹配项 Target ID 列中嵌入的文本描述。
   • 明确报告最佳结构同源体的具体蛋白质名称和功能。
   • 综合概述所有同源体中不同功能、结构域或蛋白质家族的整体多样性（例如：“大多数命中项是门户蛋白，但也有一组明显的病毒衣壳匹配项……”）。
9. 明确告知用户新创建的两个文件（.json 和 .md）及其所在位置，以便后续分析步骤直接使用。

* 如果 API 返回错误或文件缺失，请明确告知用户

并要求他们核实文件路径。