Literature Search

Literature Search Skill

Overview

文献检索引擎，提供多源学术文献搜索与聚合能力。支持arXiv、Semantic Scholar、以及通用网络搜索，帮助用户快速找到相关领域的高质量文献资源。

Core Capabilities

1. 查询扩展 (Query Expansion) ⭐ 新功能

• 智能理解: 分析模糊的研究兴趣，识别核心主题
• 关键词生成: 生成核心词、同义词、缩写、相关术语、应用领域
• 交互式对话: 通过多轮对话逐步明确研究方向
• 结构化输出: 提供确认信息、关键词列表、追问建议

2. 多源检索

• arXiv: 预印本论文检索，获取最新研究动态
• Semantic Scholar: 学术搜索，获取引用关系和论文质量指标
• OpenAlex: 250M+ 开放学术数据，全面覆盖
• PubMed: 生物医学文献数据库
• CrossRef: DOI 元数据检索
• DBLP: 计算机科学文献
• CORE: 开放获取全文（需 API Key）
• IEEE Xplore: 工程技术文献（需 API Key）
• Google Scholar: 通过 SerpAPI（需 API Key）
• Unpaywall: OA PDF 解析器（需邮箱）
• Web Search: 扩展检索，覆盖更多资源

3. PDF 下载 ⭐ 核心功能

• 多策略解析: 直接 URL → Unpaywall → OpenAlex OA → CORE
• 开放获取优先: 自动查找 OA 版本 PDF
• 并发下载: 支持批量下载（默认 3 并发）
• 智能验证: PDF 格式验证、文件大小检查
• 元数据索引: 自动维护 metadata.json 索引
• 支持的源: arXiv (100%)、OpenAlex (OA)、CORE (OA)、Semantic Scholar (部分)

4. 智能排序

• 按引用数排序
• 按发布时间排序
• 按相关性排序

5. 信息提取

• 论文标题、作者、摘要
• 发布时间、期刊/会议
• 引用数、影响力指标

CLI Usage

查询扩展

# 单次模式 - 快速扩展查询
lit expand "我想做 AI 相关的研究"

# 保存结果到文件
lit expand "Transformer 在 NLP 中的应用" --output keywords.md

# 交互式模式 - 多轮对话明确方向
lit expand "机器学习" --interactive

基础检索

# 基础搜索
lit search "transformer attention mechanism" --limit 20

# 指定领域（自动选择最佳数据源）
lit search "CRISPR gene editing" --domain biomedical

# 指定数据源
lit search "deep learning" --source semantic_scholar,arxiv --sort citations

# 搜索并下载 PDF
lit search "attention is all you need" --download --limit 3

PDF 下载

# 专门的下载命令（默认 5 篇）
lit download "transformer" --limit 5

# 指定输出目录
lit download "attention mechanism" --output ./papers --limit 10

# 指定数据源（优先选择有 PDF 的源）
lit download "BERT" --source arxiv,openalex --limit 3

# 下载结果会保存到指定目录，并生成 metadata.json 索引

使用脚本

# 运行文献检索脚本
bun run skills/literature-search/scripts/search.ts "attention mechanism"

# 指定数据源
bun run skills/literature-search/scripts/search.ts "transformer" --source arxiv

# 限制结果数量
bun run skills/literature-search/scripts/search.ts "GPT" --limit 20

API Usage

查询扩展

import QueryExpander from './scripts/query-expander';

const expander = new QueryExpander();
await expander.initialize();

// 单次扩展
const result = await expander.expandQuery('我想做 AI 相关的研究');
console.log(expander.formatResult(result));

// 交互式扩展
const conversationHistory = [];
const result2 = await expander.interactiveExpand(
  '深度学习',
  conversationHistory
);

简单搜索

import LiteratureSearch from './scripts/search';
import { PdfDownloader } from './scripts/pdf-downloader';

const searcher = new LiteratureSearch();
await searcher.initialize();

// 搜索文献
const results = await searcher.search("transformer attention", {
  sources: ['arxiv', 'semantic_scholar'],
  limit: 10,
  sortBy: 'relevance'
});

console.log(results);

// 下载 PDF
const downloader = new PdfDownloader(
  { outputDir: './papers' },
  searcher.getRegistry()
);
const downloads = await downloader.downloadResults(results.results);
console.log(`Downloaded ${downloads.length} PDFs`);

高级搜索

// 带过滤条件的搜索
const filtered = await searcher.search("machine learning", {
  sources: ['arxiv'],
  limit: 20,
  filters: {
    yearRange: [2022, 2024],
    categories: ['cs.LG', 'cs.AI'],
    minCitations: 10
  },
  sortBy: 'citations'
});

// 按作者搜索
const byAuthor = await searcher.searchByAuthor("Yann LeCun", {
  limit: 15,
  sortBy: 'date'
});

PDF 下载 API

import { PdfDownloader } from './scripts/pdf-downloader';
import type { PdfDownloadOptions } from './scripts/types';

// 创建下载器
const options: PdfDownloadOptions = {
  outputDir: './downloads/pdfs',  // 输出目录
  maxFileSize: 50 * 1024 * 1024,  // 最大文件大小 (50MB)
  skipExisting: true,              // 跳过已存在文件
  concurrency: 3,                  // 并发数
  namingStrategy: 'title'          // 命名策略: 'title' | 'doi' | 'id'
};

const downloader = new PdfDownloader(options, searcher.getRegistry());

// 下载搜索结果
const downloads = await downloader.downloadResults(results.results);

// 下载结果
downloads.forEach(dl => {
  console.log(`Downloaded: ${dl.title}`);
  console.log(`  Path: ${dl.filePath}`);
  console.log(`  Size: ${(dl.size / 1024).toFixed(1)} KB`);
});

Output Format

QueryExpansionResult 类型

interface QueryExpansionResult {
  confirmation: {
    coreTheme?: string;          // 核心主题
    subField?: string;           // 子领域
    applicationScenario?: string; // 应用场景
    timeRange?: string;          // 时间范围
    preferredSources?: string;   // 偏好来源
  };
  keywords: Array<{
    term: string;                // 关键词
    description: string;         // 描述
    type: 'core' | 'synonym' | 'abbreviation' | 'related' | 'application';
  }>;
  followUpQuestions?: string[];  // 追问问题
  needsMoreInfo: boolean;        // 是否需要更多信息
}

SearchResult 类型

interface SearchResult {
  id: string;              // 论文唯一标识
  title: string;           // 标题
  authors: string[];       // 作者列表
  abstract: string;        // 摘要
  publishDate: string;     // 发布日期
  source: string;          // 数据源
  url: string;             // 论文链接
  pdfUrl?: string;         // PDF链接
  citations?: number;      // 引用数
  venue?: string;          // 期刊/会议
  keywords?: string[];     // 关键词
  doi?: string;            // DOI
  openAccess?: boolean;    // 是否开放获取
}

PdfDownloadOptions 类型

interface PdfDownloadOptions {
  outputDir?: string;           // 输出目录 (默认: ./downloads/pdfs)
  maxFileSize?: number;         // 最大文件大小 (默认: 50MB)
  skipExisting?: boolean;       // 跳过已存在文件 (默认: true)
  concurrency?: number;         // 并发下载数 (默认: 3)
  namingStrategy?: 'title' | 'doi' | 'id';  // 文件命名策略 (默认: title)
}

PdfDownloadResult 类型

interface PdfDownloadResult {
  filePath: string;        // 文件路径
  title: string;           // 论文标题
  source: string;          // 数据源
  size: number;            // 文件大小（字节）
  doi?: string;            // DOI
}

Integration Examples

查询扩展 + 文献检索工作流

import QueryExpander from './scripts/query-expander';
import LiteratureSearch from './scripts/search';

async function expandAndSearch(vagueQuery: string) {
  // 1. 扩展查询
  const expander = new QueryExpander();
  await expander.initialize();
  const expansion = await expander.expandQuery(vagueQuery);

  console.log('生成的关键词:', expansion.keywords.map(k => k.term));

  // 2. 使用生成的关键词搜索
  const searcher = new LiteratureSearch();
  await searcher.initialize();

  const allResults = [];
  for (const keyword of expansion.keywords.slice(0, 3)) {
    const results = await searcher.search(keyword.term, { limit: 5 });
    allResults.push(...results);
  }

  return { expansion, results: allResults };
}

// 使用示例
const result = await expandAndSearch('我想研究大语言模型');

与AI分析结合

import LiteratureSearch from './scripts/search';
import ZAI from 'z-ai-web-dev-sdk';

async function searchAndAnalyze(query: string) {
  const searcher = new LiteratureSearch();
  await searcher.initialize();

  // 搜索文献
  const results = await searcher.search(query, { limit: 5 });

  // 使用AI分析结果
  const zai = await ZAI.create();
  const summary = await zai.chat.completions.create({
    messages: [{
      role: 'user',
      content: `分析以下文献搜索结果，总结研究趋势:\n${JSON.stringify(results, null, 2)}`
    }]
  });

  return { results, analysis: summary.choices[0].message.content };
}

完整的 PDF 下载工作流

import LiteratureSearch from './scripts/search';
import { PdfDownloader } from './scripts/pdf-downloader';
import { readFileSync } from 'fs';
import { join } from 'path';

async function downloadAndIndex(query: string, outputDir: string = './papers') {
  // 1. 搜索文献（优先选择有 PDF 的源）
  const searcher = new LiteratureSearch();
  await searcher.initialize();

  const results = await searcher.search(query, {
    sources: ['arxiv', 'openalex', 'core'],  // 高 PDF 可用率的源
    limit: 20,
    sortBy: 'citations'
  });

  console.log(`Found ${results.totalResults} papers`);

  // 2. 下载 PDF
  const downloader = new PdfDownloader(
    {
      outputDir,
      skipExisting: true,
      concurrency: 3,
      namingStrategy: 'title'
    },
    searcher.getRegistry()
  );

  const downloads = await downloader.downloadResults(results.results);
  console.log(`Downloaded ${downloads.length} PDFs`);

  // 3. 读取元数据索引
  const metadataPath = join(outputDir, 'metadata.json');
  const metadata = JSON.parse(readFileSync(metadataPath, 'utf-8'));

  // 4. 生成下载报告
  console.log('\n=== Download Report ===');
  metadata.files.forEach((file: any, i: number) => {
    console.log(`${i + 1}. ${file.title}`);
    console.log(`   Authors: ${file.authors.join(', ')}`);
    console.log(`   Source: ${file.source}`);
    console.log(`   File: ${file.filePath}`);
    console.log(`   Downloaded: ${file.downloadedAt}`);
    console.log('');
  });

  return { results, downloads, metadata };
}

// 使用示例
await downloadAndIndex('transformer attention mechanism', './papers/transformers');

Best Practices

1. 使用查询扩展: 对于模糊的研究兴趣，先用 expand 命令生成具体关键词
2. 明确检索词: 使用具体的技术术语而非模糊概念
3. 组合数据源: 不同数据源覆盖不同范围的文献
4. 合理排序: 根据目的选择排序方式 (引用数/时间/相关性)
5. 缓存结果: 避免重复检索相同内容
6. 定期更新: 关注新发表论文，保持知识更新
7. 交互式模式: 不确定研究方向时使用 --interactive 模式

PDF 下载最佳实践

8. 优先选择 OA 源: arXiv、OpenAlex、CORE 提供更高的 PDF 可用率
9. 合理设置并发: 默认 3 并发，避免触发 API 限流
10. 检查 metadata.json: 下载后检查索引文件，了解下载详情
11. 仅下载 OA 论文: 本工具仅支持开放获取论文，尊重版权
12. 配置 Unpaywall: 设置 UNPAYWALL_EMAIL 环境变量提高 PDF 解析成功率
13. 文件命名策略: 使用 title 策略便于浏览，使用 doi 策略避免重名

Troubleshooting

问题：检索结果太少

• 尝试扩大检索词范围
• 增加数据源数量
• 检查拼写是否正确

问题：结果质量不高

• 使用引用数排序
• 添加时间过滤
• 指定高质量期刊/会议

问题：API限制

• 实现请求缓存
• 使用合理的请求间隔
• 合并相似请求

问题：PDF 下载失败

• 无 PDF URL: 论文可能不是开放获取，尝试其他数据源
• 下载超时: 检查网络连接，降低并发数
• 文件过大: 调整 maxFileSize 参数
• 格式验证失败: 下载的可能不是真实 PDF，检查 URL 有效性
• Unpaywall 无结果: 确保设置了 UNPAYWALL_EMAIL 环境变量

问题：PDF 可用率低

• 优先使用 arXiv: 100% PDF 可用率
• 启用 Unpaywall: 设置邮箱后可解析更多 DOI
• 使用 OpenAlex: 提供大量 OA 论文 PDF
• 避免付费源: IEEE、部分 PubMed 论文需要订阅

File Structure

skills/literature-search/
├── skill.md              # 本说明文档
├── scripts/
│   ├── search.ts         # 核心搜索脚本
│   ├── query-expander.ts # 查询扩展脚本 ⭐ 新增
│   ├── pdf-downloader.ts # PDF 下载模块 ⭐ 核心功能
│   ├── search-strategy.ts # 互补搜索策略
│   ├── types.ts          # 类型定义
│   └── adapters/         # 搜索源适配器
│       ├── base.ts       # 适配器基类
│       ├── registry.ts   # 适配器注册表
│       ├── arxiv-adapter.ts
│       ├── semantic-scholar-adapter.ts
│       ├── openalex-adapter.ts
│       ├── pubmed-adapter.ts
│       ├── crossref-adapter.ts
│       ├── dblp-adapter.ts
│       ├── ieee-adapter.ts
│       ├── core-adapter.ts
│       ├── unpaywall-adapter.ts
│       ├── google-scholar-adapter.ts
│       └── web-adapter.ts
└── examples/
    ├── basic.ts          # 基础用法示例
    └── advanced.ts       # 高级用法示例

Related Documentation

• QUERY_EXPANSION.md - 查询扩展功能详细文档