文献综述

litreview
分类通用
作者Alireza Rezvani
许可MIT
评分4.90/5
使用2.3K

Litreview — 学术文献导向

> 可移植性： 只要支持出站 HTTPS 即可在任何地方运行 —— 默认搜索通道是 免费且无需密钥的 API（PubMed E-utilities + OpenAlex，无需账户，无需密钥，无需 MCP）。Consensus MCP 是一个可选的增强通道，仅在当前会话已连接时使用。生成文档需要安装带有 docx 包的 Node.js，（在 CLI 中）需要 bash_tool。原生支持 Claude Code CLI 以及开启了代码执行功能的 Claude.ai。

目标是产出一个 “启动平台” —— 不是一篇完成的文献综述，而是一份导向文档，为进入陌生领域的研究人员提供自信地开始阅读和搜索所需的一切。想象成：一位熟悉该领域的慷慨同事在喝咖啡时会告诉你的一切。

搜索通道

| 通道 | 适用时机 | 实现方式 |
|---|---|---|
| 免费通道 (默认) | 始终可用；无需密钥，无需方案，无需 MCP | 通过 scripts/free_search.py 或直接 HTTPS（见下方 URL 模板）调用 PubMed E-utilities + OpenAlex |
| Consensus 通道 (可选增强) | 仅当本会话中可用 Consensus MCP 工具时 | 在免费通道的基础上运行 Consensus 查询，以获取其综合答案卡片 |

通道检查（一次运行时检查 —— 替代所有层级检测）： 如果本会话中 没有 Consensus MCP 工具，请使用免费通道 —— 不要尝试进行层级检测，不要解析营销文案，不要询问用户的 Consensus 计划。如果 Consensus 可用，则额外运行其搜索并合并结果（通过 DOI/标题去重）。

免费通道 URL 模板（精确）

PubMed E-utilities（无需密钥；礼仪：≤3 次请求/秒）：

1. 搜索 $\rightarrow$ PMIDs: https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term=<urlencoded-query>&retmode=json&retmax=20&sort=relevance
— 读取 esearchresult.idlist (PMIDs) 和 esearchresult.count。
2. PMIDs $\rightarrow$ 元数据: https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi?db=pubmed&id=<pmid1,pmid2,...>&retmode=json
— 在 result[<pmid>] 中读取 title 和 authors[].name
pubdate、fulljournalname、articleids[]（其中 idtype: "doi" 的条目）。
3. 时段过滤：追加 &datetype=pdat&mindate=2021&maxdate=3000（近期）或 &maxdate=2015（历史）。
4. 论文 URL：https://pubmed.ncbi.nlm.nih.gov/<PMID>/。

OpenAlex（无需 API 密钥；添加 &mailto=<email> 进入礼貌池 —— 速度更快且更稳定）：

1. 搜索：https://api.openalex.org/works?search=<urlencoded-query>&per-page=20&mailto=<email>
— 在 results[] 中读取 display_name（标题）、publication_year（出版年份）、cited_by_count（被引次数）、doi、id（OpenAlex URL）、authorships[].author.display_name（作者名）、primary_location.source.display_name（发表平台）。
2. 时段过滤：&filter=from_publication_date:2021-01-01 或 &filter=to_publication_date:2015-12-31。
3. 综述文章：&filter=type:review。

OpenAlex 的 cited_by_count 是跨搜索情报层的被引次数来源（PubMed esummary 不返回次数）。

Agent 完整性规则 (Research-Pack 规范)

继承自 research-pack 规范；根据 PR #657 的跨技能一致性审计，原文锁定。

  • 来源纪律。 仅引用本会话搜索返回的论文（免费通道和/或 Consensus）。训练知识需标记为 [Not from search — model knowledge] 且不计入引用数。结果稀疏时必须明确说明，绝不能默默填充。
  • 计数纪律。 追踪三个数字：执行的搜索数 / 接收的唯一论文数（通过 DOI/标题去重）/ 引用的论文数。每篇被引论文必须拥有本会话中可检索的 URL（PubMed, DOI, OpenAlex 或 Consensus）。使用 scripts/citation_tracker.py 进行确定性计数。
  • 频率限制礼仪。 PubMed E-utilities：无密钥时 ≤3 次请求/秒。OpenAlex：通过 mailto 使用礼貌池。Consensus（若已连接）：1 次查询/秒，必须顺序执行。默认纪律：所有通道统一顺序执行，1 次查询/秒。
  • 重试策略。 失败 $\rightarrow$ 等待 3 秒 $\rightarrow$ 重试一次 $\rightarrow$ 记录日志。连续 3 次失败后：停止，提醒用户，分享已收集的内容。
  • 通道检查。 会话开始时进行一次运行时检查：Consensus MCP 工具是否可用。绝不进行层级检测。

有关顺序执行的原理及预算上限，请参阅 references/search_budget_allocation.md。

错误处理

| 故障 | 行为 |
|---|---|
| 任何通道出现频率限制 / HTTP 错误 | 等待 3 秒，重试一次，记录结果 |
| 搜索返回 0 个结果 | 明确注明；“可能是由于术语过于冷门或确实存在研究空白”；绝不默默填充 |
| 网络不可用（免费通道退出码 2） | 停止，提醒用户 —— 免费通道需要出站 HTTPS；无需检测或升级 |
| 连续 3 次失败 | 停止搜索，提醒用户，分享已收集内容，询问如何继续 |
| 子领域结果稀疏（<5 篇论文） | 在审计中标记；建议手动通过 Google Scholar / Scopus 补充 |
| 用户希望调整子领域 | 更新表格，在搜索前重新确认 |
| DOCX 验证失败 | 解包 XML，修复，重新打包 |

阶段 0：深度访谈 (3 个强制性问题，一次一个)

每个问题都附带明确的“提问原因”。停止条件：在进入阶段 1 前最多问 3 个问题。

Q1 (根源) — 研究问题的具体程度

> 请用 1-2 句话陈述研究问题。越具体越好 —— 例如“与医生相比，LLM 在临床推理任务中的表现如何？”优于“AI 在医学中的应用”。模糊的问题会导致模糊的综述。
>
> *提问原因：* 侦察搜索依赖于精确的术语。模糊的问题
避免产生无法提供有效框架分解的浅层侦察结果。

拒绝含糊。 如果用户输入过于宽泛，请在提供示例的情况下重新询问一次。如果依然模糊，则在交付时明确标注“广度导向，而非深度评审”的免责声明。

Q2（依赖于 Q1）— 框架提示

> 框架 — 请选择一项或输入“由你决定”：
>
> 1. PICO (Population / Intervention / Comparison / Outcome — 适用于大多数临床问题)
> 2. SPIDER (Sample / Phenomenon / Design / Evaluation / Research-type — 适用于社会科学/定性研究)
> 3. Decomposition (Problem / Solution / Evaluation / Limitations — 侧重技术分析)
> 4. Hybrid (由你选择组合哪些框架的组件)
> 5. 由你决定 — 我将分析 Q1 并给出建议
>
> *询问原因：* PICO 适用于约 70% 的临床问题，但并不适用于定性研究或技术评估。预先选择可避免侦察搜索建议不匹配的框架。

通过默认选项（“由你决定”）强制用户选择。技能将在侦察搜索后给出自身的框架建议，以便用户覆盖。启发式分析请使用 scripts/framework_recommender.py。

关于 PICO / SPIDER / Decomposition 的标准定义，请参阅 references/framework_selection.md。

Q3（依赖于 Q1）— 初步深度

> 初步深度 — 请选择一项。最终确认将在框架分解之后进行：
>
> 1. 快速扫描 (5 次搜索)
> 2. 标准评审 (10 次搜索)
> 3. 深度挖掘 (20 次搜索)
>
> *询问原因：* 我会询问两次 —— 现在询问是为了校准侦察搜索的重点，在框架分解后再次询问是为了最终确认。初步答案会影响优先呈现的子领域；最终答案则决定搜索预算的分配。

强制选择。在用户看到框架分解后的 Phase 2 检查点将再次询问。

停止条件： 进入 Phase 1 前最多询问 3 个问题。Phase 2 后的检查点是一个独立的确认环节（包含框架表格 + 子领域调整 + 深度重新确认）。

Phase 1: 初始侦察 (Initial Reconnaissance)

进行一次宽泛的侦察搜索，以映射主题、术语和方法论差异。

  • 执行通道检查（确认 Consensus 是否可用），然后：
- 免费通道：python scripts/free_search.py --query "<Q1 的宽泛版本>" --source both --max 20 (或使用上述 esearch/works URL 模板) - 如果 Consensus 可用，额外运行一次宽泛的 Consensus 搜索并合并结果
  • 查询词：Q1 的宽泛版本（允许术语变体；首次搜索旨在扩大覆盖面）
  • 记录：citation_tracker.py --action record_search --session NAME --query "..."
  • 记录接收数量：citation_tracker.py --action record_papers_received --session NAME --count N

为检查点综合分析：

  • 出现的主题

  • 术语变体（例如 "LLM" vs "large language model" vs "GPT-style model"）

  • 方法论差异（临床试验 vs 基准评估 vs 案例研究）

  • 覆盖缺口（侦察结果中缺失的子问题）

Phase 2: 框架选择 + 子领域生成

选择框架（基于 Q2 或根据侦察结果覆盖）：

  • PICO — 大多数临床问题（约 70% 的默认选择）

  • SPIDER — 社会科学 / 定性研究

  • Decomposition — 技术重点（问题 / 方案 / 评估 / 局限性）

  • Hybrid — 明确的跨框架映射

生成 4-5 个映射到框架组件的子领域问题。每个问题将成为 Phase 3 的定向搜索目标。

检查点 (强制选项确认环节)

Phase 2 完成后，暂停并呈现：

#

3-4 句调研总结


  • 出现的主题

  • 术语图谱

  • 证据图谱特征

框架分解表

| 框架组件 | 如何映射至本主题 | 建议探索的子领域 |
|---|---|---|
| (组件 1) | ... | 子领域 1 |
| (组件 2) | ... | 子领域 2 |
| (组件 3) | ... | 子领域 3 |
| (组件 4) | ... | 子领域 4 |
| 交叉主题 | ... | 子领域 5 |

深度确认（强制选择）

明确实际限制：使用的搜索通道（免费 / 免费+Consensus）+ 每个来源每次查询约 20 条结果的上限。

  • 快速扫描 (5 次搜索 × ~20 条结果 = 每个来源最多 ~100 篇论文)
  • 标准回顾 (10 次搜索 × ~20 = 每个来源 ~200 篇论文)
  • 深度挖掘 (20 次搜索 × ~20 = 每个来源 ~400 篇论文)

子领域强制选项

  • “看起来不错 —— 按这些子领域继续”
  • “调整：增加关于 [X] 的子领域”
  • “调整：删除 [Y] 并用 [Z] 替换”
  • “使用不同的框架重新开始”

询问原因（逻辑依据）

> 错误的框架或子领域设置会浪费搜索预算。这是修正方向的最后一个低成本时机。

在进入第三阶段前请等待用户响应。 若无明确的用户选择，拒绝启动第三阶段。

第三阶段：定向搜索

顺序执行（1 次查询/秒），按深度层级分配预算。每次搜索均在免费通道运行（free_search.py 或 URL 模板）；如果 Consensus 可用，则在其中运行相同的查询并合并结果。完整规范请参阅 references/search_budget_allocation.md。

快速扫描 (5 次搜索)

  • 5 次子领域搜索（每个子领域一次）
  • 跳过时间限制搜索 + 综述专项搜索

标准回顾 (10 次搜索)

  • 5 次子领域搜索
  • 2 次综述文章搜索（针对前 2 个子领域）："systematic review [topic]" / "meta-analysis [topic]" (OpenAlex: 添加 &filter=type:review)
  • 2 次时间限制搜索（针对最重要的子领域）：历史 (PubMed &maxdate=2015 / OpenAlex to_publication_date:2015-12-31) + 近期 (PubMed &mindate=2021 / OpenAlex from_publication_date:2021-01-01)
  • 1 次针对最高被引论文的后续搜索，使用其关键词 + 晚于其发表年份的起始日期

深度挖掘 (20 次搜索)

  • 5 次子领域搜索
  • 5 次综述文章搜索（每个子领域一次）
  • 4 次时间限制搜索（前 2 个子领域，各含旧作 + 新作）
  • 3 次针对前 3 篇最高被引论文的后续搜索
  • 3 次预留给新兴线索（追踪令人惊讶的发现）

全程遵守 1 q/sec 速率限制。顺序执行。在下一次调用前确认响应。通过 citation_tracker.py 记录每次搜索。

跨搜索情报

针对所有搜索结果运行三个追踪器 —— 在第三阶段完成后运行 scripts/cross_search_aggregator.py --session NAME：

1. 重复命中论文 —— 同一篇论文在 3 个以上子领域搜索中出现 = 可能是奠基性工作
2. 重复出现作者 —— 同一作者在多次搜索中出现 = 主导研究团队；前 3-5 名高频作者至关重要
3. 年度被引启发式算法 —— 2023 年发表且有 150 次被引 $\gg$ 2008 年发表且有 150 次被引。使用 OpenAlex 的 cited_by_count 来识别开创性工作。

这些结果将填充 DOCX 文档中的“从这里开始”、“关键研究团队”和“参考文献”部分。

第四阶段：DOCX 研究指南

通过 Node.js + docx 库生成。共 8 个章节（完整规范见 references/docx_8_sections.md）：

1. 主题概述 —— 单个精炼段落（4-6 句）
2. 从这里开始 —— 优先阅读顺序 —— 5-7 篇论文，排序如下：
最佳近期综述 $\rightarrow$ 奠基性研究 $\rightarrow$ 2-3 篇前沿研究 $\rightarrow$ 研究空白/争议。每项包含：超链接标题 + 作者/年份 + 一句话贡献 + 一句话“关注重点”。

3. 领域演进历程 — 编年史叙述（1-2 段）+ 时间线表格（5-8 个里程碑：年份 / 里程碑 / 意义）+ 术语演变说明。

4. 子领域指南（每个子领域一份，包含 4 部分）
- 4a. 研究现状（2-3 句综合论述，含行内引用）
- 4b. 核心论文（3-5 篇超链接论文，含引用数、年份、一句话重要性）
- 4c. 核心检索词（6-10 个关键词、同义词、MeSH 词、历史术语）
- 4d. 布尔检索式（2-3 个可直接复制的检索字符串）

5. 核心研究团队 — 前 3-5 位作者/团队，含所属机构、覆盖子领域、代表性论文链接（来自交叉搜索聚合器）。

6. 开放问题与空白 — 分为三类：方法论 / 人群-情境 / 概念-理论。每个空白需解释 *其重要性*。

7. 参考文献 — 按第一作者字母顺序排列。每条目包含可点击链接：PubMed URL 或 DOI（免费通道）/ “在 Consensus 中查看”（Consensus 来源）。所有行内引用必须与参考文献条目对应。

8. 审计日志 — 检索汇总表（序号、查询词、过滤器、返回论文数、状态）、计数区块、覆盖范围说明（包括使用的检索通道：free / free+Consensus）。

DOCX 技术要求

记录关键的 docx 库模式：

  • 页面：US Letter，1 英寸页边距
  • 列表：LevelFormat.BULLET（严禁使用 Unicode 符号）
  • 超链接：使用 ExternalHyperlink 且 style: "Hyperlink"，完整 URL（严禁截断）
  • 表格：双重宽度设置（columnWidths + 单元格 width），ShadingType.CLEAR
  • 保存后验证步骤（zip 完整性检查：python3 -c "import zipfile,sys; zipfile.ZipFile(sys.argv[1]).testzip()" output.docx —— 无输出即为完整 —— 然后确认所需章节均已存在）

参考 docx skill 以获取设置模式和最佳实践。

输出

code
research_guide_<topic-slug>_<YYYY-MM-DD>.docx

此外还需提供：

  • 聊天摘要块："Saved: <path>. Audit: N searches × M unique papers / K cited. Search lane: <free | free+Consensus>."

  • 若用户要求，则在行内打印审计日志。

工具链

| 脚本 | 角色 |
|---|---|
| scripts/free_search.py | 免费无密钥检索通道 —— 通过 stdlib urllib 调用 PubMed E-utilities + OpenAlex (--query, --source pubmed\|openalex\|both, --max, --json, --mailto; 离线时以状态码 2 退出并显示清晰消息) |
| scripts/citation_tracker.py | 基于 JSON 的三项计数审计，路径为 ~/.litreview_sessions/<session>.json |
| scripts/framework_recommender.py | 根据研究问题提供 PICO/SPIDER/分解法的启发式建议 |
| scripts/cross_search_aggregator.py | 第三阶段后的重复命中项 + 常现作者 + 年度引用量排名 |

参考文献

需摒弃的反模式

  • 并行化检索调用（任何通道）
  • 跳过交互式检查点（在未经用户确认的情况下运行所有检索）
  • 使用训练知识填充单薄的检索结果
  • 默认使用 n
  • 无理由使用 non-PICO 框架
  • 在对话中引用非本会话搜索结果的论文
  • 尝试进行 Consensus 方案层级检测（已删除 —— 唯一的运行时检查是“本会话是否可用 Consensus MCP 工具？”）
  • 将 Consensus 视为必须项（它是一个可选增强项；免费通道为默认设置）
  • 在标准/深度预算中跳过时代限制（era-gated）搜索
  • 跳过跨搜索情报分析（重复命中、重复出现的作者）
  • 截断超链接中的源 URL

---

版本： 1.1.0
源规范： megaprompts/09-litreview-megaprompt.md
构建模式： 路径 B（直接转换）。pulse 的同级项（研究包形态）。v1.1.0：免费无密钥 API（PubMed + OpenAlex）成为默认搜索通道；Consensus 降级为可选增强项；根据 2026-06 newgen 审计 + ClawHub 规则 #3（无付费服务依赖），删除了方案层级检测。