临床试验搜索技能

该技能将自然语言问题转换为针对临床试验数据库的结构化 API 查询，并以可读格式呈现结果。

工作流程

1. 解析用户意图 — 从用户问题中提取关键实体
2. 构建查询参数 — 将实体映射至下方定义的查询 Schema
3. 执行查询 — 运行 scripts/search.py
4. 呈现结果 — 格式化并展示临床试验给用户

步骤 1：提取关键词

从用户问题中识别以下类型的实体：

字典字段格式：

{"logic": "or", "data": ["value1", "value2"]}

• logic 控制多个值的组合方式："or"（任一匹配即可）或 "and"（全部必须匹配）。默认为 "or"，除非用户明确要求所有条件同时生效。
• data 是待匹配的关键词字符串列表。

类型规则：

• indication、acronym、company、nctid、phase → 普通 List[str]

• target、drug_name、drug_modality、drug_feature、location、route_of_administration → 含 logic 和 data 字段的 dict

• 默认 page_num: 0, page_size: 10，除非用户另行指定

• 优先使用英文关键词（数据库索引基于英文）；对非英文术语进行翻译

• drug_modality 必须严格使用以下集合中的字符串：

  [
    "Steroids", "Vaccine", "Antisense RNA", "Antibody-Drug Conjugates, ADCs", "Unknown", "Protein Degrader",
    "Monoclonal Antibodies", "mRNA", "Others", "Cell-based Therapies", "Imaging Agents", "Gene Therapy",
    "miRNA", "Polypeptide", "Recombinant Proteins", "Small Molecule", "siRNA/RNAi", "Trispecific Antibodies",
    "Polyclonal Antibodies", "Bi-specific Antibodies", "Glycoconjugates", "Radiopharmaceutical",
    "Nucleic Acid-based", "Carbohydrates"
  ]
  

• drug_feature 必须严格使用以下集合中的字符串：

  [
    "505b2", "Bacterial Product", "Biologic", "Biosimilar", "Device", "Fixed-Dose Combination", "Immuno-Oncology",
    "New Molecular Entity (NME)", "Non-NME", "Precision Medicine", "Reformulation", "Specialty Drug", "Viral"
  ]
  

步骤 2：执行查询

python scripts/search.py --params ''

或使用参数文件：

python scripts/search.py --params-file /tmp/query.json

添加 --raw 参数可获取未经格式化的原始 JSON 响应。

步骤 3：解释结果

响应包含：

• total_count — 匹配试验总数
• results — 当前页的结果，每项包含 NCT ID、标题、阶段、状态、适应症、药物、申办方等信息

若结果超过 100 条，提示用户缩小查询范围。若未返回任何结果，在放弃前应用下方的回退策略。

步骤 3：复核与回退搜索策略

若未返回任何结果，在放弃前应用下方的回退策略。 当初始查询返回零结果或结果质量较差时，请**按顺序**尝试以下策略：

策略 1 — 药物名称变体扩展

临床试验注册库中存储的药物名称可能存在不一致性（如 INN 名称 vs 商品名、含/不含连字符、部分代码等）。将 drug_name.data 扩展为多个变体，合并进单个 or 查询中。

{
  "drug_name": {"logic": "or", "data": ["SHR-A1904", "SHR A1904", "A1904", "SHR1904"]},
  "page_num": 0,
  "page_size": 50
}

若已知试验缩写，也可尝试替换为缩写形式：

{
  "acronym": ["KEYNOTE-590", "KEYNOTE590", "KN590"],
  "page_num": 0,
  "page_size": 10
}

常见变体模式：

• 移除或替换连字符：SHR-A1904 → SHR A1904、SHRA1904
• 去除前缀：9MW-2821 → MW-2821、9MW2821
• 在同一 data 数组中同时尝试 INN 名称和内部代码

策略 2 — 以申办方为锚点 + 应用层过滤

当药物名称匹配不可靠时，以申办方公司为锚点拉取宽泛结果集，再在本地按适应症、阶段或模态进行过滤。

{
  "company": ["Roche", "Roche Inc"],
  "page_num": 0,
  "page_size": 200
}

获取结果后，应用本地过滤器：

• phase in ["II", "III"]
• indication contains "breast cancer"
• drug_name matches known code pattern

当药物代码模糊不清，或需检索某家公司全部试验组合时，适用此策略。

策略 3 — 广义靶点 / 适应症搜索 + 客户端后过滤

当药物名称与申办方均无法返回结果时，改用生物学靶点与适应症组合搜索，再在客户端按申办方或药物代码模式进一步筛选。

{
  "target": {"logic": "or", "data": ["CLDN18.2", "Nectin-4", "HER2"]},
  "indication": ["gastric cancer", "breast cancer"],
  "page_num": 0,
  "page_size": 200
}

获取结果后，按以下条件过滤：

• 申办方名称子串（例如包含 "Hengrui"）
• 药物代码前缀（例如以 SHR、9MW、A166 开头）
• 试验状态（Recruiting、Active, not recruiting）

注意： 若 API 支持正则表达式，则可直接在 drug_name.data 中传入类似 (SHR|9MW|A166) 的模式，从而在一次调用中扩大匹配范围。

策略 4 — 逐步放宽过滤条件

若以上所有策略仍无结果，则按以下顺序逐项移除过滤条件：

1. 移除 has_result_summary（大量试验尚未发布结果）
2. 移除 phase 过滤条件
3. 移除 location 过滤条件
4. 放宽 indication（例如 "NSCLC" → "lung cancer" → "cancer"）
5. 移除 drug_modality 或 drug_feature 约束

每次放宽后重新执行查询，一旦出现结果即停止。

决策树

初始查询是否返回结果？
├── 是 → 呈现结果
└── 否  → 策略 1：扩展 drug_name / acronym 变体
          └── 仍无结果 → 策略 2：以 sponsor 为锚点 + 本地过滤
                         └── 仍无结果 → 策略 3：广义 target/indication 搜索
                                        └── 仍无结果 → 策略 4：逐步放宽过滤条件
任意步骤触发 HTTP 429 错误？
└── 整个流程暂停 15 秒 → 从中断处恢复当前策略
    （为避免触发 429，每次请求之间至少间隔 5 秒）

转换示例

用户：“查找已公布结果的、针对肺癌的 PD-1 抗体 III 期临床试验”

{
  "target": {"logic": "or", "data": ["PD-1"]},
  "drug_modality": {"logic": "or", "data": ["Monoclonal Antibodies"]},
  "indication": ["lung cancer"],
  "phase": ["III"],
  "has_result_summary": true,
  "page_num": 0,
  "page_size": 10
}

用户：“查询 NCT04280783”

{
  "nctid": ["NCT04280783"],
  "page_num": 0,
  "page_size": 1
}

用户：“罗氏（Roche）在中国开展的双特异性抗体临床试验”

{
  "company": ["Roche"],
  "location": {"logic": "or", "data": ["China"]},
  "drug_modality": {"logic": "or", "data": ["Bi-specific Antibodies"]},
  "page_num": 0,
  "page_size": 10
}

用户：“结直肠癌口服小分子 KRAS G12C 抑制剂”

{
  "target": {"logic": "or", "data": ["KRAS G12C"]},
  "drug_modality": {"logic": "or", "data": ["Small Molecule"]},
  "indication": ["colorectal cancer"],
  "page_num": 0,
  "page_size": 10
}

依赖项

• Python 3.8+
• requests 库（pip install requests）
• 环境变量 NOAH_API_TOKEN — API 认证令牌（必需）
  • 请前往 noah.bio 注册免费账户以获取您的 API 密钥。

安全与打包说明

• 本技能仅调用 NoahAI 官方 HTTPS 终端节点（https://www.noah.bio/api/），不连接任何第三方服务。
• 本技能仅依赖一个环境变量：NOAH_API_TOKEN。请将其存储于系统环境或本地 .env 文件中，切勿在命令、聊天记录或打包文件中明文嵌入。
• 该令牌权限范围限定为仅读取公开医疗信息，无法访问私有用户记录。
• 本技能不会主动在本地持久化保存请求参数。任何服务端保留行为均由 NoahAI API 服务及其运行日志策略决定。
• 本技能不请求持久性或系统级权限，亦不修改系统配置。
• 本技能基于源文件（纯 Python 脚本），无需运行时安装、包下载或外部引导步骤。