pubmed-database

PubMed API

先决条件

1. uv：阅读 uv 技能，并遵循其中的设置说明，确保已安装 uv 且其位于 PATH 中。
2. 用户通知：如果工作区根目录中尚不存在 .licenses/pubmed_database_LICENSE.txt，则 (1) 显著提醒用户查看 https://pubmed.ncbi.nlm.nih.gov/disclaimer/ 和 https://www.ncbi.nlm.nih.gov/home/about/policies/ 中的条款，并始终检查该技能检索到的论文许可证是否有任何限制，然后 (2) 创建文件，记录通知文本和时间戳。
3. .env 文件：确保 .env 文件存在于主目录中。如果不存在，请创建一个。
4. NCBI_API_KEY（可选）：将 NCBI E-utilities 的速率限制从每秒 3 次请求提高到 10 次。没有此密钥也能使用该技能，但如果用户计划执行大量查询或遇到 429 错误，建议使用密钥。可在 https://www.ncbi.nlm.nih.gov/account/settings/ 免费注册密钥。如果该技能似乎与用户的请求相关，必须使用 credentials 技能中的安全凭据协议来检查并请求此密钥。
5. USER_EMAIL（可选）：向 NCBI 标识调用方（其《使用条款》建议提供）。如果该技能似乎与用户的请求相关，必须使用 credentials 技能中的安全凭据协议来检查并请求此凭据。

此技能通过 scripts/pubmed_api.py 提供对 NCBI PubMed 和 PubMed Central API 的 CLI 访问——这是一个包含 10 个功能的单一 CLI，涵盖搜索、获取、链接、全文、拼写、发现、引文匹配和缓存。

核心规则

• API 使用：始终使用提供的封装程序 scripts/pubmed_api.py，它会自动管理速率限制并防止 API 滥用。设置 NCBI_API_KEY 环境变量可将速率限制从每秒 3 次请求提高到 10 次。严禁通过其他方式查询 API（例如使用 curl、wget 或手写代码）。
• JSON 处理：使用 jq 筛选和转换 JSON 输出（如果没有 jq，则使用等效的 python 方法），以避免幻觉和上下文溢出。
• 临时文件：为避免 JSON 文件污染工作目录，请在当前目录中使用临时目录。并行运行多个 Agent 或任务时，确保每个任务使用唯一的子目录名称（例如 tmp_$TASK_ID/），以避免文件冲突。
• 通知：如果使用此技能，请确保在输出中提及，并列出生成输出时使用的所有论文 URL。

技能文件夹结构

• SKILL.md - 此文件
• scripts/pubmed_api.py - 此技能的 CLI
• references/ - 包含详细功能说明的目录
  • advanced-linking.md
  • advanced-search.md
  • bulk-workflows.md
  • citation-matching.md
  • cross-database-linking.md
  • fetch-and-resolve.md
  • search-and-discovery.md
  • utilities.md

CLI 用法

uv run scripts/pubmed_api.py <output_file> <function_name> <required_args> [--flag value ...]

• 位置参数：参数按位置传递；列表参数以逗号分隔的字符串形式传入，不带空格（例如 "35113657,31234568"）。
• 标志选项：可选参数可使用 --flag value 的形式传递，而非位置参数。
• 输出处理：成功时，JSON 会写入 output_file。出错时，进程以非零代码退出，且不会写入输出文件。

用法示例

uv run scripts/pubmed_api.py ./search_results.json search_pubmed "BRCA1" --max_results 5
cat ./search_results.json | jq '.[]' -r
uv run scripts/pubmed_api.py ./abstracts.json fetch_article_abstracts "35113657"
cat ./abstracts.json | jq '.[0].title' -r

基本操作示例

为下一次调用连接 PMIDs（最常见的链式调用模式）：

cat ./search_results.json | jq -r 'join(",")'

将摘要精简为必要字段，并截断过长的摘要：

cat ./abstracts.json | jq '[.[] | {pmid, title, snippet: (.abstract // "")[:500]}]'

按关键词筛选（可安全处理 null）：

cat ./abstracts.json | jq '[.[] | select((.title // "") | contains("Review"))]'

上下文管理与准确性

处理较大的结果集（>10 篇摘要）时：

1. 尽早筛选：先使用 jq 验证摘要中的关键词，再将完整 JSON 读入上下文。
2. 精简数据：除非另有明确指示，否则只提取 title 和 abstract 字段。作者列表和元数据会带来干扰。
3. 批量操作（N > 10）：避免逐个获取或处理 ID。API 和 History Server 专为批量检索而设计。在单轮中获取所有数据，并使用 shell 管道精简结果后再读入上下文。这样可避免耗尽轮次和上下文溢出。
4. 基于依据：如果没有找到结果，切勿使用内部知识提供具体标识符（PMID、CID、Gene ID）。准确报告工具的输出，确保结果基于当前数据库状态。
5. 结束搜索：如果要查找可能不存在的论文，将探索限制在 3–5 个高质量且多样化的搜索查询。如果这些尝试后仍没有匹配结果，就应得出没有论文符合条件的结论，而不是继续迭代——除非明确要求进行全面搜索。

函数

⚠️ 必须遵守：调用某个函数组中的任何函数前，必须先阅读该组链接的参考文件。下表仅说明每个函数的用途，而非调用方式。参数名称、参数顺序、标志和输出架构仅记录在参考文件中。**切勿根据函数名称猜测或推断参数。**如果未先阅读参考文件就调用函数，必定会导致错误调用。

搜索

• search_pubmed：查找符合自由文本或结构化 NCBI 查询的 PMID。
• global_database_discovery：统计所有 NCBI 数据库中符合查询条件的记录数量。

获取与解析

• fetch_article_abstracts：批量检索 PMID 对应的元数据和摘要。
• get_full_text_pmc：从 PMC 检索开放获取的全文。
• fetch_database_summary：将任何 NCBI 数据库中的不透明 UID 解析为易读的元数据。

跨数据库关联

• find_linked_biological_data：查找与源记录关联的其他 NCBI 数据库中的记录。
• discover_available_links：列出给定记录所有可用的 ELink linkname。

批量工作流

处理约 10 个以上 PMID时，避免逐个处理 ID。通过 cache_results_history 将它们上传到 NCBI History Server，以获取会话句柄（webenv + query_key），然后将该句柄传递给 fetch_article_abstracts 或 find_linked_biological_data，进行一次批量调用。使用 jq shell 管道精简结果后，再读入上下文。这样可避免耗尽轮次和上下文溢出。完整的工作流示例（搜索→获取、跨数据库探索、引文解析和精简数据的批量检索）请参阅参考文件。

• cache_results_history：将 PMID 上传到 NCBI History Server，以便批量检索。

实用工具

• verify_medical_spelling：搜索前检查生物医学术语的拼写。
• match_raw_citations：将不完整的书目信息解析为 PMID。