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

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

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

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

### 基础检索
```bash
# 基础搜索
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 下载
```bash
# 专门的下载命令（默认 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 索引
```

### 使用脚本
```bash
# 运行文献检索脚本
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

### 查询扩展
```typescript
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
);
```

### 简单搜索
```typescript
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`);
```

### 高级搜索
```typescript
// 带过滤条件的搜索
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
```typescript
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 类型
```typescript
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 类型
```typescript
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 类型
```typescript
interface PdfDownloadOptions {
  outputDir?: string;           // 输出目录 (默认: ./downloads/pdfs)
  maxFileSize?: number;         // 最大文件大小 (默认: 50MB)
  skipExisting?: boolean;       // 跳过已存在文件 (默认: true)
  concurrency?: number;         // 并发下载数 (默认: 3)
  namingStrategy?: 'title' | 'doi' | 'id';  // 文件命名策略 (默认: title)
}
```

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

## Integration Examples

### 查询扩展 + 文献检索工作流
```typescript
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分析结合
```typescript
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 下载工作流
```typescript
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