literature-search

name	literature-search
description	学术文献检索助手，专为撰写 Related Work / 文献综述设计。 从 IEEE Xplore、Semantic Scholar、arXiv 检索论文，默认聚焦 IEEE 顶刊/顶会。 支持交互式需求确认、多轮多关键词搜索、BibTeX 导出、摘要收集。 触发词：查文献、搜论文、literature search、related work、文献综述、 找参考文献、搜相关工作、survey papers、search papers
allowed-tools	Read, Edit, Bash, Write, Glob, Grep, WebSearch, WebFetch, AskUserQuestion
model	opus

Literature Search — 文献检索助手

专为撰写 Related Work / 文献综述设计的学术文献检索工具。从 IEEE Xplore、Semantic Scholar、arXiv 等学术数据库检索论文，收集元数据、摘要和 BibTeX，为后续撰写文献综述提供素材。

核心能力

数据源	方法	说明
IEEE Xplore	REST API (无需密钥)	默认首选，IEEE 顶刊/顶会全覆盖
Semantic Scholar	Graph API v1	跨数据库搜索，含 TL;DR 和引用数
arXiv	Atom API	预印本，最新研究进展
Google Scholar	WebSearch 备用	补充搜索，覆盖面广

参考文件

详细参考资料按主题拆分到独立文件，按需查阅：

• IEEE 顶刊/顶会参考 — 通信、CS/AI 领域推荐期刊与会议列表
• 最终报告模版 — 总览文件与子方向文件的输出格式模版
• 使用案例 — 完整的端到端搜索案例演示
• 搜索参数说明 — search.py 所有命令行参数的详细说明

工作流程

阶段 1：交互式需求确认（必须）

在开始搜索之前，必须与用户确认以下信息。使用 AskUserQuestion 工具逐一确认：

第一轮提问（核心需求）：

向用户提出以下问题，可以一次性提出：

1. 研究主题：你要查找的具体研究主题是什么？（例如："movable antenna beamforming"、"LLM-based network optimization"）
2. 使用场景：这些文献用于什么？（例如：Related Work 的某个子节、完整综述、开题调研）
3. 期刊/会议偏好：
   • 默认 IEEE 顶刊（TWC, TCOM, TSP, JSAC, TMC, TCCN, TVT, IoT-J, WCL 等）
   • 是否需要包含会议论文（ICC, GLOBECOM, WCNC, INFOCOM 等）
   • 是否需要扩展到非 IEEE 源（arXiv, Semantic Scholar）
4. 时间范围：优先查找哪个时间段的论文？（默认近 3 年）
5. 最终精选数量：最终报告中希望保留多少篇？给出目标区间，例如：
   • Related Work 某个子节：10-15 篇
   • 完整 Related Work：20-40 篇
   • 开题调研/综述：50-80 篇
   • 默认建议：25-40 篇（搜索阶段会广泛收集，最终报告精选到目标区间）
6. 已知文献：是否已经有一些相关论文？（有助于确定搜索方向和避免重复）

根据用户回答，确定搜索策略：

• 拆解 2-5 组搜索关键词（不同角度、不同术语）
• 确定数据源优先级
• 确定筛选条件（年份、期刊、引用数等）
• 根据目标数量，预估每个子方向分配的论文名额

向用户简要展示搜索计划（含各子方向预估数量）后，确认是否开始。

阶段 2：多轮搜索执行

使用 Python 脚本执行搜索：

cd ~/.claude/skills/literature-search
python3 scripts/search.py --keywords "hybrid action deep reinforcement learning" \
  --sources ieee semantic_scholar arxiv \
  --max-results 30 \
  --time-range 3y \
  --sort relevance \
  --output-dir results

完整参数说明见 搜索参数说明。

⚠️ 关键词构造规则（踩坑经验，必读）

IEEE Xplore 的 REST 搜索对多词引号短语极其敏感——多个引号短语之间默认是 AND-of-exact-phrase 匹配， 一次塞入多个并列概念（例如 "TD3 UAV offloading" "resource allocation"）几乎必定返回 0 结果。

推荐做法（单关键词原则）：

• 每次搜索只传 1 个 2–4 词的精炼短语（--keywords "hybrid action reinforcement learning"）
• 禁止把多个并列概念拼进同一个 --keywords 调用
• 不同角度 → 发起多轮搜索，每轮 1 个关键词，最后用 --merge 合并去重

如果必须一次传多个关键词：

• 默认 --match-mode any（v2 起默认）会用 OR 连接，保持高召回
• 仅当你明确想要 AND-of-exact-phrase 的严格过滤时才用 --match-mode all
• 中文关键词：IEEE/arXiv 是英文库，先翻译成英文再搜；可以在 --round-id 中保留中英文对照便于回溯

多轮搜索策略

不要只用一组关键词！针对同一主题，从不同角度搜索：

1. 核心术语搜索：直接使用研究主题的标准术语
2. 同义词/变体搜索：使用不同表述（如 "reconfigurable intelligent surface" vs "RIS" vs "intelligent reflecting surface"）
3. 方法论搜索：从技术方法角度搜索（如 "deep reinforcement learning resource allocation"）
4. 应用场景搜索：从应用角度搜索（如 "UAV trajectory optimization"）
5. 补充搜索：如果某个子方向结果不够，追加搜索

每轮搜索结果会自动去重合并。

故障处理（Failure Recovery）

现象	诊断	行动
返回 0 篇	关键词太长/太具体/AND 过严	拆分成更短短语；或 --match-mode any；或换同义词
返回超时/连接失败	源暂时不可用	换 --sources arxiv crossref；先跑 --health 诊断
HTTP 429 / Semantic Scholar 长延时	被限流	等待 60s 后重试；或从 --sources 中临时移除 S2
结果 < 3 篇	关键词过于specific	提示 AI 换更generic的 2-3 词短语重试

搜索前先跑 health check（强烈推荐）：

python3 scripts/search.py --health

根据返回的 ok 和 latency_ms 动态调整 --sources 列表，跳过不可用源。

Google Scholar 补充搜索（当 API 搜索结果不够时）：

使用 WebSearch 工具搜索：

site:scholar.google.com "exact phrase" related topic

或搜索特定期刊：

site:ieeexplore.ieee.org "keyword" "IEEE Transactions on"

阶段 3：结果整理与最终报告生成

搜索完成后，合并所有轮次结果去重，然后进行分析整理：

1. 合并去重：python3 scripts/search.py --merge results/*_papers.json -o results
2. 读取合并后 JSON，筛选 IEEE 顶刊/顶会论文（默认保留 Early Access；仅当用户明确要求"不要 Early Access / 只要正式发表"时排除）
3. Early Access 识别启发式（IEEE REST 不返回 volume/issue，可用以下规则粗判）：
   • volume == "" 且 number == "" 且 pages 为 "1--xx" → 很可能 Early Access
   • 需要精确判断时，对候选 DOI 调用 Crossref：https://api.crossref.org/works/{doi}， 若返回的 message.volume 和 message.page 均缺失则标记为 Early Access
4. 自动初筛（当结果 > 40 篇时）：按 venue 白名单 + 年份 + citation count 过滤到目标数量
   • 优先级：IEEE 顶刊 IF > 与主题的 abstract 相关度 > 引用数 > 发表时间
5. 分类整理：根据论文内容将论文归入 Related Work 子方向
6. 生成分类映射 JSON（categories.json）并调用最终报告生成

生成最终报告

准备分类映射文件 categories.json，格式为 {"子方向名称": [DOI列表]}:

{
  "A. AIGC/LLM Inference at Edge": [
    "10.1109/TMC.2024.3415661",
    "10.1109/TWC.2024.3497923"
  ],
  "B. SAGIN Resource Management": [
    "10.1109/JSAC.2024.3459073"
  ]
}

然后生成最终报告：

python3 scripts/search.py --finalize results/merged_papers.json \
  --categories categories.json \
  --topic "Hierarchical AIGC Inference in SAGIN" \
  -o results

输出格式和模版详见 最终报告模版。

阶段 4：与用户确认结果

向用户展示最终报告后：

1. 询问是否需要补充搜索某个子方向
2. 询问是否需要排除/增加某些论文
3. 询问是否需要调整分组方式
4. 确认最终结果后，可将 BibTeX 导出到用户论文项目目录

依赖安装

pip install requests feedparser

快速参考（踩坑速查）

场景	正确做法	错误做法
多关键词搜索	1 关键词/轮，多轮 merge	一次塞 2+ 多词短语到 --keywords
中文主题	先翻译为英文，--round-id 存中英对照	直接用中文喂给 IEEE
Semantic Scholar 429	从 --sources 临时去掉	硬刷直到 timeout
结果 = 0	短语拆短 / 换同义词 / --match-mode any	直接放弃
结果 > 40 篇	venue + 年份 + citation 初筛到目标数	全部丢给用户手动筛
Early Access 判断	默认保留；需要时用 Crossref 补 volume/issue	靠肉眼看 contentType 字段
读摘要	直接读 JSON 字段（完整）	从 markdown 预览中 grep

注意事项

• IEEE Xplore 搜索使用网页 REST 端点，无需 API Key，但有速率限制，搜索间隔建议 >= 1 秒
• IEEE Xplore 默认匹配模式已改为 --match-mode any（OR 连接，高召回），AND 严格模式请显式传 --match-mode all
• Semantic Scholar API 免费层 1000 次/5min，但经常 429 限流；搜索前跑 --health 确认可用性
• arXiv API 无需密钥，但建议控制请求频率
• Crossref 可作为 DOI 元数据的权威来源，用于补全 volume/issue/pages 和识别 Early Access
• 多轮搜索时自动去重（基于 DOI → arXiv ID → 标题哈希）
• 如果某个源连接失败，会自动跳过并使用其他源
• 搜索结果保存在 results/ 目录，包含时间戳，不会覆盖历史记录
• JSON 和 Markdown 报告中的摘要都保持完整，不做截断；若只读 markdown 截取了前 N 字符，请改读 *_papers.json 的 abstract 字段
• IEEE 顶刊/顶会完整列表见 IEEE 顶刊/顶会参考