英文文献检索助手（en-lit-search）
面向医务人员（临床医生、护士、医技、科研团队）的 PubMed 检索全自动助手。解决四件事：不会写检索式、题录没法整理、看不出研究热点、临床问题查证要快。
本包自含全部脚本：检索式构建（query_builder.py）、批量抓取（fetch_pubmed.py + _parse_lib.py）、汇总产出（build_xlsx.py，内置深度分析附表 _deep.py）、RIS 导出（jsonl_to_ris.py）。
环境依赖
python3 # 需已安装 lxml、openpyxl、requests（pip 可装）
- 网络：PubMed E-utilities（无 API key 限 3 req/s；可申请免费 NCBI API key 提速至 10 req/s）
- 深度分析附表首次运行需联网查 MeSH 树号（id.nlm.nih.gov，约 0.4 秒/词），结果缓存到
scripts/_cache/，之后秒出；离线时归「未分类」并标注，不中断
场景路由（先识别，再套默认参数）
| 场景 | 典型问法 | 默认参数 |
|---|---|---|
| S1 全院通用 | 晋升论文、课题申报查新 | Humans + English + 近 10 年 |
| S2 科研团队深度检索 | 「帮我查某药×某病的全部文献」 | 不限年份、含动物实验、强制专题子集、导出 CSV |
| S3 临床快速查证 | 「X 对 Y 是否有效？」 | 强 PICO + 限 SR/MA/RCT/指南 + 近 5 年 + 证据类型列 |
| S4 护理/教改 | 教学法效果、核心能力评价 | 按「对象-教学法-评价工具-结局」拆概念，双语摘要列 |
标准流程
第 1 步：场景识别 + PICO 拆解
把用户的中文问题拆成 P/I/C/O（+ 研究类型），逐元翻译成英文概念：
- S1/S2/S3 用标准 PICO；S4 护理教改改用「对象-教学法-评价工具-结局」
- 每个概念列出 2–4 个英文同义变体（含缩写、拼写变体）
- 把拆解结果和英文概念表给用户看一眼再继续（多数医务人员看不懂英文检索式，但能判断概念对不对）
第 2 步：MeSH 映射
python3 scripts/query_builder.py --mesh "baduanjin" "sleep quality" "nurses"
读官方词、UI、树号、入口词。判断：
- 大类概念（睡眠/运动/护士）→ 默认 Explode 扩检
- 细粒度概念（某种具体病）→
[Mesh:NoExp]收窄 - 无 MeSH 的新概念（中药名、基因名、新疗法）→
[tiab]自由词兜底 - 命中数爆炸时加副主题词（
/therapeutic use、/adverse effects等）
操作细则见 references/mesh-mapping-guide.md。
第 3 步：组配 + 校验（人工确认门，必停点）
python3 scripts/query_builder.py \
--concept 'baduanjin|aerobic exercise@Exercise' \
--concept 'nurses|nursing staff@Nurses' \
--concept 'sleep quality|sleep@Sleep Quality' \
--years 2016-2026 --humans \
--report /tmp/en_search_report.md
输出最终检索式 + Count + QueryTranslation。停下来把检索式、命中数、「扩检/缩检了哪些词」讲给用户，拿到确认才进第 4 步。命中数与 PubMed 网页不一致时，先排查引号、布尔逻辑、字段限定，不许带病往下跑。命中 >9999 时加 --segments 自动生成年份分段方案。
第 4 步：批量抓取（脚本已内嵌于本包）
# 长任务建议后台运行
python3 scripts/fetch_pubmed.py --term "<最终检索式>" --out /tmp/{检索名}.jsonl
- >9999 条：先
query_builder.py --query "..." --segments生成年份分段方案，逐段抓取后去重 - 去重后条数必须精确等于官方 Count——数据完整性硬校验
- 抓取参数与坑（并发、断点续跑、PubmedBookArticle、单元格上限）：见
references/excel-schema.md与 README
第 5 步：汇总产出
# Excel（说明/总表/统计/深度分析/专题子集）+ CSV
python3 scripts/build_xlsx.py \
--jsonl /tmp/{检索名}.jsonl --outdir <输出目录> --name "{检索名}" \
--query "<最终检索式>" --url "<PubMed 检索页>" \
--count-note "与 PubMed 网页显示一致" \
--topics topics.json # 可选，专题子集配置
# RIS（EndNote/NoteExpress 直接导入）
python3 scripts/jsonl_to_ris.py --jsonl /tmp/{检索名}.jsonl --out <输出目录>/{检索名}.ris
- 专题子集（topics.json）按研究方向写关键词组，从总表自动筛——S2 强制、S1 推荐（比让用户翻一万行有用得多）
- 字段契约：
references/excel-schema.md
第 6 步：深度分析（第 5 步已自动生成附表，--no-deep 关闭）
build_xlsx 默认产出「深度分析」附表，六区块：①疾病谱分类（MeSH C 类官方树号）②学科/专业大类 ③证据结构诊断 ④热点突现榜 ⑤研究瓶颈与局限 ⑥国家/基金/交叉矩阵/人群。运行时要做两件事：
- 填写 AI 解读区：读「五（续）瓶颈/局限素材」里自动抽取的结论/局限句（PMID+年份+原句），结合突现榜和证据结构指标，写入三条解读（热点判断/主要瓶颈/研究空白与建议），每条标注「AI 解读+日期+依据 PMIDs」
- 解读纪律：只报突现比 ≥2 的词；明确告诉用户统计表不代替阅读；结论方向（支持/反对）需读文献判断
第 7 步：S3 临床查证的附加输出
- Excel 加「证据类型」列（SR/MA→系统评价，RCT→RCT，Guideline→指南，其余→观察性）
- 证据优先过滤从第 1 层（SR/MA）逐层放宽，第 1 层 ≥ 3 条即止
- 输出 ≤ 30 条精读清单（含摘要），不做 GRADE 评级——证据强度请临床判断
输入 / 输出
- 输入：中文自然语言问题（一句话即可）；或已有英文检索式 / PMID 清单
- 输出：PICO 拆解表、MeSH 映射表、编号检索式（留档）、题录 Excel（含深度分析附表：疾病谱/学科/证据结构/热点/瓶颈+AI解读/国家基金人群）+ CSV + RIS、（S3）精读清单
红线
- 人工确认门：检索式未获用户确认，不得启动批量抓取
- 禁止浏览器抓 PubMed，一律走 E-utilities
- 去重后条数 ≠ 官方 Count = 数据事故，必须排查
- 字段缺失留空，不编造摘要、DOI、作者
- 长任务放后台执行，避免会话中断打断抓取（断点续跑依赖 JSONL 已写入的 PMID）
