临床试验数据库查询Skill：用自然语言与代码把全球临床试验数据变成可查询的结构化结果
- 一句话定位：封装 ClinicalTrials.gov 官方 API v2，让 AI 能按疾病、药物、地点、状态、阶段等条件直接检索全球临床试验，并取回结构化详情、资格标准与联系方式。
- 零认证门槛：底层为公开 API，无需申请密钥，默认返回 JSON，也可直接导出 CSV，适合研究分析、患者匹配与药物情报跟踪。
- 四种内置调用方式：
search_studies()条件搜索、get_study_details()单试验详情、search_with_all_results()自动分页、extract_study_summary()摘要提取，覆盖从“找得到”到“读得懂”的全链路。 - 有明确边界：速率限制约为每分钟 50 个请求，批量采集需配合最大分页（1000 条/页）和指数退避策略。
- 最适合三类人：临床研究协调员、医药行业情报分析人员、需要为患者寻找入组机会的医疗从业者，以及做真实世界研究的开发者。
1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？
技能中文名：临床试验数据库查询Skill 技能英文名：clinicaltrials-database 技能 ID：11979
它解决的问题很具体：ClinicalTrials.gov 是全球规模最大的临床试验注册库，由美国国家医学图书馆维护，数据权威但对非技术用户并不友好——网页端筛选维度有限、分页繁琐、结果难以批量导出。对开发者而言，虽然 API v2 是公开的，但端点规范、嵌套字段路径、分页 token、速率限制处理都需要额外查文档才能跑通。这个技能把「查什么、怎么查、怎么取字段」封装成可直接调用的能力，让 AI 助手按照自然语言指令完成检索与整理。
安装与启用思路（一键安装 AI 技能提升开发效率）：
- 安装前提：需要一个已支持技能（Skill）机制的 AI 客户端或开发环境，以及可用的 Python 3 运行环境。由于脚本通过
requests库发起 HTTP 请求，需确保该依赖已安装。具体的依赖清单与最低版本要求以官方说明为准。 - 安装入口：在技能市场或技能管理面板中，通过技能 ID
11979或英文名clinicaltrials-database定位并一键启用。具体的安装命令、仓库地址与授权方式，以官方说明为准。 - 验证是否生效：技能详情提供了自带的验证方式——进入脚本目录直接运行示例，能打印出示例查询结果即表示安装成功：
cd scientific-databases/clinicaltrials-database/scripts
python3 query_clinicaltrials.py
- 接口连通性验证：也可用一条最小请求确认网络与 API 可达：
import requests
url = "https://clinicaltrials.gov/api/v2/studies"
params = {"query.cond": "breast cancer", "filter.overallStatus": "RECRUITING", "pageSize": 10}
data = requests.get(url, params=params).json()
print(f"Found {data['totalCount']} trials")
如果能打印出匹配的试验数量，说明技能链路（脚本、网络、API）已经全部打通。
2. 该技能的主要功能和特点
- 按疾病/条件检索：使用
query.cond参数，可查询特定疾病、罕见病或共病条件下的试验，并跟踪某一诊断的试验可用性变化。 - 按干预/药物检索：使用
query.intr参数，定位测试某款药物、器械或治疗程序的试验，常用于药物开发跟踪与竞争情报分析。 - 地理范围检索：使用
query.locn参数，按城市、州或区域定位试验点，可进一步提取机构名称与站点状态，便于患者转诊和选址分析。 - 按赞助方/组织检索：使用
query.spons参数，查看某一机构主导的试验及其合作方，用于跟踪研究组合、分析资助优先级、识别合作机会。 - 按研究状态筛选：支持
RECRUITING、NOT_YET_RECRUITING、ENROLLING_BY_INVITATION、ACTIVE_NOT_RECRUITING、SUSPENDED、TERMINATED、COMPLETED、WITHDRAWN等完整状态枚举。 - 单试验详情获取：通过 NCT ID（如
NCT04852770）拉取完整研究信息，包括资格标准、年龄与性别限制、联系方式、站点列表、阶段与入组人数。 - 自动分页与批量采集：
search_with_all_results()自动翻页遍历全部结果；也可手动用page_token控制翻页节奏，单页最大 1000 条。 - CSV 导出：请求
format="csv"可直接把结果写成文件，便于导入表格或数据分析工具（注意此时返回的是字符串而非字典）。 - 摘要抽取：
extract_study_summary()一次性提取 NCT ID、标题、状态、阶段、入组人数、最后更新时间和简介，适合快速浏览与报告复用。
和普通工具比强在哪：网页检索只能人工逐条查看，难以组合多个筛选条件并批量落盘；自行写脚本则要反复查 OpenAPI 规范、处理嵌套结构与 429 限流。该技能把参数命名、字段路径、错误处理、分页逻辑都固化下来，用户只需要描述检索意图。
3. 如何使用该技能？
第 1 步：明确检索意图并选择参数维度。 先想清楚要按什么条件筛——条件（query.cond）、干预（query.intr）、地点（query.locn）、赞助方（query.spons）、状态（filter.overallStatus），这些条件可以自由组合。
第 2 步：发起条件搜索。 例如查找招募中的 2 型糖尿病试验，并按最后更新日期倒序：
from scripts.query_clinicaltrials import search_studies
results = search_studies(
condition="type 2 diabetes",
status="RECRUITING",
page_size=20,
sort="LastUpdatePostDate:desc"
)
print(f"Found {results['totalCount']} recruiting diabetes trials")
for study in results["studies"]:
protocol = study["protocolSection"]
print(protocol["identificationModule"]["nctId"], protocol["identificationModule"]["briefTitle"])
输入：疾病名、状态、每页数量、排序规则。
输出：totalCount 总命中数 + studies 列表，每条包含嵌套的 protocolSection。
第 3 步：组合多条件做精准筛选。 例如在加州查找肺癌的免疫治疗试验，再在本地按阶段二次过滤：
results = search_studies(
condition="lung cancer",
intervention="immunotherapy",
location="California",
status=["RECRUITING", "NOT_YET_RECRUITING"],
page_size=100
)
phase2_3 = [s for s in results["studies"]
if any(p in ["PHASE2", "PHASE3"]
for p in s["protocolSection"].get("designModule", {}).get("phases", []))]
第 4 步：按 NCT ID 拉取详情。 用于核查资格标准与联系方式：
from scripts.query_clinicaltrials import get_study_details
study = get_study_details("NCT04852770")
eligibility = study["protocolSection"]["eligibilityModule"]
print(eligibility.get("minimumAge"), "-", eligibility.get("maximumAge"))
print(eligibility.get("sex"))
print(eligibility.get("eligibilityCriteria"))
第 5 步：批量获取或导出。 需要全量数据时用 search_with_all_results(condition="rare disease", status="RECRUITING") 自动翻页；需要交付文件时用 format="csv" 写出 CSV。
第 6 步：生成摘要做汇报。 用 extract_study_summary() 把单条试验压缩成标题、状态、阶段、入组人数、更新时间与简介六要素。
注意事项：API 速率限制约每分钟 50 请求，批量任务请使用最大页面大小、请求间加延迟、遇到 429 状态码时等待后重试；响应字段并非全部存在，取数时统一用 .get() 安全导航。
4. 同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| 临床试验数据库查询Skill（clinicaltrials-database） | AI 技能形态的 ClinicalTrials.gov 数据访问层 | 条件/药物/地点/赞助方/状态多维检索、详情获取、自动分页、CSV 导出、摘要抽取 | 需具备 Python 环境并启用技能；底层 API 无需认证，具体安装方式以官方说明为准 | 患者匹配、研究分析、药物情报、批量数据导出 | 优势：开箱即用、字段路径与限流已封装、可与 AI 对话式调用；不足：数据源单一，仅覆盖 ClinicalTrials.gov 注册库 |
| 直接使用 ClinicalTrials.gov 网页检索 | 官方可视化检索入口 | 关键词搜索、筛选器、结果列表与详情页 | 零门槛，浏览器即可 | 临时查一两条试验、人工核对 | 优势：无需编程、界面直观；不足：多条件组合受限、难以批量导出、无法自动化 |
| 自行编写 API 调用脚本 | 基于官方 API v2 的自建方案 | 完全自定义的查询与数据结构 | 需阅读 OpenAPI 规范、处理鉴权差异、分页与错误重试 | 有特殊字段需求、需深度定制的团队 | 优势：灵活性最高；不足：开发与维护成本高，限流和嵌套结构需自己兜底 |
| 商业临床情报平台（如各类试验数据库订阅服务） | 面向企业的增值数据产品 | 跨注册库整合、人工标注、分析看板 | 通常需商务采购与账号授权，费用以官方说明为准 | 药企竞争情报、投资尽调 | 优势：数据加工深、可视化强；不足：成本高、数据更新存在滞后、灵活查询受产品限制 |
从对比可以看出，该技能的差异化在于「低成本 + 可编程 + 可对话」三者的交集：比网页检索更可批量，比自建脚本更省事，比商业平台更轻量。
5. 该技能的典型应用场景与实际体验情况
场景一：临床研究协调员为患者寻找入组机会。
痛点是个别患者符合的条件非常窄，手工在网页上反复切换筛选器很耗时。使用方式是先用 condition 锁定疾病，再叠加 location 限定城市、status="RECRUITING" 只看在招项目，最后用 get_study_details() 逐条核对 eligibilityModule 中的年龄、性别与纳入排除标准。
实际体验：上手难度低，条件→地点→状态的组合逻辑符合真实工作流；效果上能把「几十条候选」快速收敛到「个位数可核查」；注意事项是资格标准字段为 CommonMark 富文本，需要人工阅读理解，不能只靠机器判断。
场景二：医药行业分析师跟踪某款药物的研发进展。
痛点是竞品试验分散、更新频繁，靠人工巡检容易漏。使用方式是 intervention="Pembrolizumab" 配合 status=["RECRUITING","ACTIVE_NOT_RECRUITING"] 拉取在研项目，再在本地按 PHASE3 过滤，并定期以 LastUpdatePostDate:desc 排序查看新增动态。
实际体验：结果结构化程度高，NCT ID 与题目可直接进表格；效果是每周巡检从数小时压缩到几分钟；注意事项是药物名称存在同义词与拼写差异，建议用通用名多试几组关键词。
场景三：研究机构做区域试验分布分析。
使用方式是 location="New York" + condition="cancer" 拉取结果后，遍历 contactsLocationsModule.locations 提取机构、城市、州与站点状态，统计各机构承接项目数量。
实际体验：这是该技能最能体现批量优势的场景，单页 1000 条配合自动分页可快速形成数据集；注意事项是必须控制请求节奏，否则容易触发 429 限流，建议在批量采集时显式加入延迟。
场景四：开发者为内部系统搭建试验数据接口。
使用方式是把 search_studies() 与 search_with_all_results() 作为服务层函数，向上提供检索能力，向下统一处理超时、HTTP 错误与 JSON 解析异常。
实际体验：技能详情中给出的最佳实践（超时设置、raise_for_status()、RequestException 捕获、.get() 安全导航）可直接复用，减少踩坑；注意事项是不同试验的模块完整度差异较大，resultsSection 并非每条都有，需要在业务侧做空值兜底。
6. 该技能能为用户带来的价值
把检索时间从小时级压到分钟级。 过去需要人工在网页上反复切换筛选条件、逐条点开详情的流程，现在用一段十几行的查询代码即可完成，多条件组合与批量分页是纯手工方式难以企及的。
把 API 门槛降到几乎为零。 无需申请密钥、无需通读 OpenAPI 规范、无需自己设计分页与重试逻辑。参数命名（query.cond、query.intr、query.locn、query.spons、filter.overallStatus）与字段路径（protocolSection.identificationModule.nctId 等）已被固化，新手照抄示例即可跑通。
让数据真正可复用。 CSV 导出与摘要抽取把「一次性查询」变成「可归档、可对比、可二次分析」的数据资产，适合周期性巡检与趋势观察。
降低合规与信息误差风险。 数据直接来自官方注册库，避免二手转载导致的版本滞后；状态枚举与日期格式（ISO 8601）规范统一，减少口径不一致带来的判断偏差。
长期价值在于可组合。 该技能输出的结构化结果可以继续接入报表、看板或匹配算法，成为临床研究数据流水线中的一个稳定环节，而不是一次性的查询动作。
7. 常见问题 FAQ
Q1：这个技能怎么安装？需要付费吗？
在支持技能机制的 AI 客户端中，通过技能 ID 11979 或英文名 clinicaltrials-database 启用即可，具体安装命令与入口以官方说明为准。就数据源本身而言，底层 ClinicalTrials.gov API v2 是公开接口，无需认证密钥；技能本身是否收费、采用何种授权方式，同样以官方说明为准。
Q2：它和直接上 ClinicalTrials.gov 网站查有什么区别？ 网站适合临时查一两条试验；该技能适合「多条件组合 + 批量获取 + 落盘分析」。它支持按赞助方、干预措施、地理范围做程序化筛选，可自动翻页获取全部结果，还能一键导出 CSV 并抽取摘要，这些是网页端不具备的。
Q3：查询会不会被限流？大规模采集怎么办？ API 速率限制约为每分钟 50 个请求每 IP。批量任务建议：使用最大页面大小（1000 条/页）减少请求次数、请求之间加入延迟、遇到 429 状态码时等待约 60 秒后重试（指数退避），并限制最大翻页数避免任务失控。
Q4：适合哪些人使用？ 临床研究协调员与医生（为患者匹配在招试验）、医药行业分析师（跟踪药物研发与竞品情报）、科研人员（分析试验趋势与研究设计）、开发者（为内部系统接入试验数据），以及需要按地区或机构做研究组合梳理的机构管理人员。
Q5：查不到某条试验的完整信息是技能的问题吗？
大概率不是。注册库中不同试验的字段完整度本身存在差异，并非每条记录都包含结果模块或全部联系方式。使用时应统一用 .get() 做安全取值并为缺失字段设置默认值，而不是直接按固定路径访问。