litreview

文献综述 — 学术领域导览

可移植性： 只要能访问出站 HTTPS，就能在任何环境中使用——默认搜索通道使用免费的免密钥 API（PubMed E-utilities + OpenAlex，无需账号、密钥或 MCP）。生成文档需要 Node.js 和 docx 包；在 CLI 中还需要 bash_tool。可在 Claude Code CLI 中原生使用，也可在 Claude.ai 中配合 Code Execution 使用。

生成一份入门指南——不是一篇完整的文献综述，而是一份导览文档，帮助刚进入陌生领域的研究人员满怀信心地开始阅读和检索。想想一位熟悉该领域、乐于助人的同事会在咖啡闲聊时告诉你什么。

搜索通道

通道	适用时机	方式
免费通道（默认）	始终可用；无需密钥、套餐或 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. 检索 → PMID：https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term=<urlencoded-query>&retmode=json&retmax=20&sort=relevance — 读取 esearchresult.idlist（PMID）和 esearchresult.count。
2. PMID → 元数据：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（免密钥；添加 &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 个查询。
• 重试策略。 失败时 → 等待 3 秒 → 重试一次 → 记录。连续失败 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 句话陈述研究问题。越具体越好——“与医生相比，大模型在临床推理任务上的表现如何？”胜过“医学中的 AI”。模糊的问题会产生模糊的综述。

提问原因： 探索性搜索取决于精确的术语。模糊的问题会产生结果稀少的探索性搜索，无法据此形成有用的框架拆解。

拒绝含糊表述。 如果用户的问题过于宽泛，用示例追问一次。如果仍然模糊，则交付结果时明确注明：“宽泛范围概览，不是深度综述”。

Q2（取决于 Q1）— 框架提示

框架——选一个，或说“由你选择”：

1. PICO（人群 / 干预 / 对照 / 结局——适用于大多数临床问题）
2. SPIDER（样本 / 现象 / 设计 / 评估 / 研究类型——适用于社会科学 / 定性研究）
3. 分解法（问题 / 解决方案 / 评估 / 局限性——适用于技术类主题）
4. 混合框架（由你选择各框架中的组成部分）
5. 由你选择——分析 Q1 并提出建议

提问原因： PICO 是约 70% 临床问题的默认框架，但不太适用于定性研究或技术评估。提前选择框架，可以避免探索性搜索建议与问题不匹配的框架。

强制选择并提供默认选项（“由你选择”）。技能会在探索性搜索后给出自己的框架建议，供用户覆盖。启发式评估请使用 scripts/framework_recommender.py。

PICO / SPIDER / 分解法的规范，请参阅 references/framework_selection.md。

Q3（依赖 Q1）——暂定深度

暂定深度——选一项。框架拆解后再最终确认：

1. 快速浏览（5 次搜索）
2. 标准评审（10 次搜索）
3. 深入研究（20 次搜索）

提问原因： 我会问两次——现在问一次，以调整侦察搜索的侧重点；框架拆解后再问一次，以确认最终选择。暂定答案会影响优先呈现哪些子领域；最终答案则决定搜索预算分配。

强制选择。用户看过框架拆解后，会在 Phase 2 之后的检查点再次提问。

停止条件： Phase 1 之前最多提问 3 个。Phase 2 之后的检查点是独立的强制选择环节（框架表 + 子领域调整 + 深度再次确认）。

Phase 1：初步侦察

进行一次广泛的侦察搜索，梳理主题、术语和方法论差异。

• 运行通道检查（Consensus 是否可用），然后：
  • 免费通道：python scripts/free_search.py --query "<broad version of 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”、“large language model”与“GPT-style model”）
• 方法论差异（临床试验、基准评估与案例研究）
• 覆盖缺口（侦察结果中未涉及的子问题）

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]”
• “使用其他框架重新开始”

提问原因（理由）

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

等待用户回复后再进入 Phase 3。 用户未明确选择前，不得开始 Phase 3。

Phase 3：定向搜索

按顺序执行（每秒 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 篇综述文章（每个子领域 1 篇）
• 进行 4 次按年代筛选的搜索（排名前 2 的子领域，每个子领域各搜索较早和较新的研究）
• 对被引次数最高的 3 篇论文分别进行 3 次后续搜索
• 预留 3 次搜索，用于探索新兴主题（追踪值得关注的意外发现）

全程遵守每秒 1 次请求的速率限制。按顺序执行。确认收到响应后再进行下一次调用。使用 citation_tracker.py 记录每次搜索。

跨搜索情报

在所有搜索结果中使用 3 种追踪方式——第 3 阶段完成后运行 scripts/cross_search_aggregator.py --session NAME：

1. 重复命中的论文——同一篇论文出现在 3 次或更多子领域搜索中，通常说明它具有奠基性
2. 反复出现的作者——同一作者出现在多次搜索中，说明其研究团队在该领域占据主导地位；最常出现的 3-5 位作者最值得关注
3. 年度被引次数启发式判断——一篇 2023 年发表、被引 150 次的论文，价值远高于一篇 2008 年发表、被引 150 次的论文。使用 OpenAlex 的 cited_by_count 识别奠基性著作。

这些结果将用于 DOCX 的“从这里开始”“关键研究团队”和“参考文献”部分。

第 4 阶段：DOCX 研究指南

使用 Node.js + docx 库生成。共 8 个部分（完整规范见 references/docx_8_sections.md）：

1. 主题概览——一个简洁的段落（4-6 句）
2. 从这里开始——优先阅读顺序——按顺序排列 5-7 篇论文：最新且最好的综述 → 奠基性论文 → 2-3 篇前沿研究 → 研究空白/争议。每篇包括：带超链接的标题 + 作者/年份 + 1 句贡献说明 + 1 句“关注要点”
3. 领域发展历程——按时间顺序撰写叙述（1-2 个段落）+ 时间线表格（5-8 个里程碑：年份 / 里程碑 / 重要性）+ 术语演变说明
4. 子领域指南（每个子领域包含 4 个部分）
   • 4a. 研究发现（用内联引文综合概述，2-3 句）
   • 4b. 关键论文（3-5 篇带超链接的论文，附被引次数、年份和 1 句重要性说明）
   • 4c. 关键搜索词（6-10 个关键词、同义词、MeSH 术语和历史术语）
   • 4d. 布尔搜索式（2-3 条可直接粘贴使用的搜索式）
5. 关键研究团队——排名前 3-5 位的作者/团队，列出所属机构、覆盖的子领域及代表性论文链接（来自跨搜索聚合器）
6. 未解问题与研究空白——分为三类：方法学 / 人群与情境 / 概念与理论。解释每个研究空白为何重要。
7. 参考文献——按第一作者姓氏的字母顺序排列。每条都包含可点击链接：PubMed URL 或 DOI（免费来源）/“在 Consensus 中查看”（来源为 Consensus）。每条内联引文都必须对应一条参考文献。
8. 审计日志——搜索摘要表格（#、查询、筛选条件、返回论文数、状态）、数量统计区块、覆盖说明（包括使用了哪个搜索渠道：免费 / 免费 + 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 技能。

输出

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

另需：

• 聊天摘要区块：“已保存：。审计：N 次搜索 × M 篇唯一论文 / K 篇已引用。搜索渠道：<free | free+Consensus>。”
• 若用户提出要求，则在聊天中直接打印审计日志

工具

脚本	作用
scripts/free_search.py	免费、无需密钥的搜索通道——通过标准库 urllib 使用 PubMed E-utilities + OpenAlex（--query、`--source pubmed
scripts/citation_tracker.py	以 JSON 为基础的三项计数审计，存储于 ~/.litreview_sessions/<session>.json
scripts/framework_recommender.py	根据研究问题，以启发式方式推荐 PICO/SPIDER/分解法
scripts/cross_search_aggregator.py	第 3 阶段后按重复命中、反复出现的作者和年均引用量进行排序

参考资料

• references/framework_selection.md — PICO / SPIDER / 分解法规范（7 个以上来源）
• references/search_budget_allocation.md — 深度层级 + 跨搜索智能分析 + 顺序执行理由（7 个以上来源）
• references/docx_8_sections.md — 研究指南 DOCX 规范 + 技术要求（7 个以上来源）

应拒绝的反模式

• 并行执行搜索调用（任何通道）
• 跳过交互式检查点（未获用户确认就运行所有搜索）
• 用训练数据中的知识填充稀少的结果
• 无正当理由就默认采用非 PICO 框架
• 在聊天中引用并非来自本次会话搜索结果的论文
• 尝试检测 Consensus 方案层级（已删除——唯一的运行时检查是“本次会话中是否提供 Consensus MCP 工具？”）
• 将 Consensus 视为必需项（它是可选增强功能；默认使用免费通道）
• 在标准/深度预算中跳过受年代门槛限制的搜索
• 跳过跨搜索智能分析（重复命中、反复出现的作者）
• 在超链接中截断来源 URL

---

版本： 1.1.0
源规范： megaprompts/09-litreview-megaprompt.md（维护者本地草稿规范——已被 gitignore 忽略，不在公共仓库中） 构建模式： Path B（直接转换）。与 pulse 并列（研究包形态）。v1.1.0：免费的无密钥 API（PubMed + OpenAlex）成为默认搜索通道；Consensus 降为可选增强功能；根据 2026-06 newgen 审计 + ClawHub 规则 #3（不得依赖付费服务）删除了方案层级检测。