# paper_summary

**Repository Path**: little77/paper_summary

## Basic Information

- **Project Name**: paper_summary
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-09
- **Last Updated**: 2026-02-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 论文智能分析系统

一款基于人工智能的学术论文管理系统，可以自动从 PDF 中提取元数据，使用大语言模型（GPT-4 或 Claude）生成中文摘要，并将结果导出为 Obsidian Markdown 或 JSON 格式。

## 功能特性

- **PDF 处理**: 自动从学术论文中提取标题、作者、年份、DOI 和摘要
- **AI 摘要**: 使用 GPT-4 或 Claude 3 生成中文摘要
- **去重**: 基于 DOI 或标题防止重复论文
- **多种导出格式**: 导出为 Obsidian Markdown（含 frontmatter 和 wikilinks）或 JSON
- **可搜索存储**: 支持全文搜索的 SQLite 数据库
- **成本跟踪**: 跟踪 token 使用量和估算成本
- **错误处理**: 全面的错误代码便于调试
- **会议爬虫**: 自动爬取顶级网络安全会议（USENIX Security、CCS、NDSS、IEEE S&P）的论文
- **批量处理**: 支持目录批量处理和任务队列管理
- **缓存机制**: 智能缓存避免重复处理

## 安装

### 前置要求

- Python 3.11 或更高版本
- OpenAI API 密钥或 Anthropic API 密钥

### 使用 uv（推荐）

```bash
# 克隆仓库
git clone <repository-url>
cd paper-agent

# 安装依赖
uv sync

# 激活虚拟环境
source .venv/bin/activate  # Linux/Mac
# 或
.venv\Scripts\activate  # Windows
```

### 使用 pip

```bash
# 安装依赖
pip install -r requirements.txt

# 以开发模式安装
pip install -e .
```

### 依赖项

```
PyMuPDF>=1.23.0       # PDF 处理
openai>=1.0.0         # OpenAI API
anthropic>=0.18.0     # Anthropic API
pyyaml>=6.0.0         # YAML 解析
chromadb>=0.4.0       # 向量存储
pymupdf4llm>=0.2.9    # PDF 转 Markdown 转换
semanticscholar>=0.1.0 # Semantic Scholar API 客户端
```

### Semantic Scholar API 集成

项目集成了 Semantic Scholar API，用于搜索和获取学术论文信息。

#### 使用示例

```python
from semanticscholar import SemanticScholar

# 初始化客户端
s = SemanticScholar()

# 搜索论文
results = s.search_paper('machine learning', limit=10)

for paper in results:
    print(f"Title: {paper.title}")
    print(f"Authors: {', '.join([author.name for author in paper.authors])}")
    print(f"Year: {paper.year}")
    print(f"DOI: {paper.doi}")
    if paper.openAccessPdf:
        print(f"PDF URL: {paper.openAccessPdf.url}")
    print("---")
```

#### API 端点

- **论文搜索**: `search_paper(query, limit=10, fields=[])`
- **获取论文详情**: `get_paper(paper_id, fields=[])`
- **引用关系**: `get_paper_citations(paper_id, limit=100)`

更多详细信息请参考 [Semantic Scholar API 文档](https://api.semanticscholar.org/api-docs/)。

## 配置

### 设置 API 密钥

将您的 API 密钥设置为环境变量：

```bash
# 对于 OpenAI
export OPENAI_API_KEY="your-api-key-here"

# 对于 Anthropic
export ANTHROPIC_API_KEY="your-api-key-here"
```

在 Windows 上：

```cmd
set OPENAI_API_KEY=your-api-key-here
```

或添加到您的 shell 配置（`~/.bashrc`、`~/.zshrc` 等）：

```bash
export OPENAI_API_KEY="your-api-key-here"
```

### 检查配置

验证您的设置：

```bash
paper-agent config --list
```

输出示例：

```
Configuration:

✓ OPENAI_API_KEY: sk-... (已设置)
✗ ANTHROPIC_API_KEY: 未设置
✓ Database: papers.db (存在)
```

## 使用方法

### 处理论文

生成摘要并导出为多种格式：

```bash
paper-agent summarize --input paper.pdf --output-dir output
```

选项：
- `--input`: PDF 文件路径（必需）
- `--output-dir`: 输出目录（默认：`output`）
- `--model`: LLM 提供商 - `openai` 或 `anthropic`（默认：`openai`）

使用 Anthropic 的示例：

```bash
paper-agent summarize --input paper.pdf --model anthropic
```

输出文件：
- `{title}.md`: 带 YAML frontmatter 的 Obsidian Markdown
- `{title}.json`: 包含所有元数据的 JSON 格式

输出示例：

```
Processing PDF: paper.pdf
Generating summary using openai...
Storing metadata...
Paper stored with ID: 1
Exporting to Obsidian format...
Exporting to JSON format...

✓ 摘要完成！
  摘要: 本论文提出了一种新的深度学习方法...
  Token 使用: 1000 输入, 200 输出
  成本: $0.0420
  输出目录: output
```

### 搜索论文

搜索您的论文数据库：

```bash
# 按标题搜索（部分匹配）
paper-agent search --title "machine learning"

# 按作者搜索
paper-agent search --author "Smith"

# 按年份搜索
paper-agent search --year 2024

# 按 DOI 搜索（精确匹配）
paper-agent search --doi "10.1234/example"

# 组合搜索
paper-agent search --title "neural" --author "Zhang" --year 2023
```

### 爬取会议论文

从顶级网络安全会议（USENIX Security、CCS、NDSS、IEEE S&P）自动爬取论文：

```bash
# 爬取 USENIX Security 2024 论文
paper-agent scrape --conference usenix --year 2024

# 爬取 CCS 2023 论文并指定输出目录
paper-agent scrape --conference ccs --year 2023 --output ./papers/ccs2023/

# 爬取 NDSS 2024 论文
paper-agent scrape --conference ndss --year 2024
```

选项：
- `--conference`: 会议名称（必需）- `sp` (IEEE S&P), `usenix` (USENIX Security), `ccs` (ACM CCS), `ndss` (NDSS)
- `--year`: 会议年份（必需）
- `--output`: PDF 下载目录（默认：`./output/papers/`）
- `--config-file`: 配置文件路径

功能特性：
- 自动爬取会议论文列表和 PDF
- 元数据自动保存到 SQLite 数据库
- 支持断点续传（跳过已下载的论文）
- 可选的 arXiv 元数据增强
- 可配置的速率限制和重试策略

输出示例：

```
✓ 配置文件: config.yaml
✓ arXiv 客户端初始化成功
✓ 爬虫初始化成功: USENIX 2024

正在获取 USENIX 2024 论文列表...
✓ 找到 100 篇论文

[1/100] 正在处理: Deep Learning for Security...
  ✓ 下载成功: deep_learning_for_security.pdf
  ✓ 元数据已存储

[2/100] 正在处理: Privacy-Preserving Machine Learning...
  ✓ 下载成功: privacy_preserving_ml.pdf
  ✓ 元数据已存储

...

==================================================
爬取完成！
==================================================
总计: 100 篇论文
成功: 98 篇
跳过: 2 篇
失败: 0 篇
输出目录: ./output/papers/
```

注意事项：
- 爬虫会遵守网站的速率限制配置
- 下载的论文会自动保存元数据到数据库
- 如果下载失败，可以重新运行命令继续爬取（跳过已下载的）
- 不同会议的网站结构可能变化，爬虫可能需要更新

输出示例：

```
Found 2 paper(s):

ID: 1
  Title: Deep Learning for Computer Vision
  Authors: Zhang, Wei, Liu
  Year: 2024
  DOI: 10.1234/test
  Abstract: This paper presents a novel approach...

ID: 5
  Title: Neural Networks in Practice
  Authors: Smith, Johnson
  Year: 2024
  Abstract: We propose a practical framework...
```

### 列出所有论文

显示数据库中的所有论文：

```bash
# 列出所有论文
paper-agent list

# 限制结果数量
paper-agent list --limit 10
```

输出示例：

```
Listing 5 paper(s):

ID: 1
  Title: Deep Learning for Computer Vision
  Authors: Zhang, Wei, Liu
  Year: 2024
  DOI: 10.1234/test
  Processed: 2025-02-07T12:34:56.789012

ID: 2
  Title: Neural Networks in Practice
  ...
```

### 配置管理

查看当前配置：

```bash
paper-agent config --list
```

## 输出格式

### Obsidian Markdown 格式

生成的 Markdown 文件包含：

```markdown
---
title: Deep Learning for Computer Vision
authors: ["Zhang Wei", "Li Ming"]
year: 2024
doi: 10.1234/test
tags: ["#paper", "#machine-learning"]
---

# Deep Learning for Computer Vision

**Authors**: Zhang Wei, Li Ming
**Year**: 2024
**DOI**: 10.1234/test
tags: ["#paper", "#machine-learning"]
---

# Deep Learning for Computer Vision

**Authors**: Zhang Wei, Li Ming
**Year**: 2024
**DOI**: 10.1234/test
tags: ["#paper", "#machine-learning"]
---

## Abstract

This paper presents a novel approach to deep learning...

## Summary

本论文提出了一种新的深度学习方法，用于计算机视觉任务...

## Related Papers

[[Neural Networks in Practice]]
```

### JSON 格式

生成的 JSON 文件包含所有元数据：

```json
{
  "title": "Deep Learning for Computer Vision",
  "authors": ["Zhang Wei", "Li Ming"],
  "year": 2024,
  "doi": "10.1234/test",
  "abstract": "This paper presents a novel approach to deep learning...",
  "summary": "本论文提出了一种新的深度学习方法，用于计算机视觉任务...",
  "source": "/path/to/paper.pdf",
  "processed_at": "2025-02-07T12:34:56.789012",
  "model_used": "openai",
  "token_usage": {
    "input_tokens": 1000,
    "output_tokens": 200,
    "cost": 0.042
  }
}
```

---

## 配置文件支持

项目现在支持从配置文件读取所有 LLM 和导出相关配置项。

### 配置文件格式

支持两种格式：
- **YAML**: `.yaml` 或 `.yml`
- **JSON**: `.json`

### 配置优先级

当多个来源同时提供配置时，优先级从高到低：
1. **命令行参数**（如 `--api-key sk-xxx`）- 最高优先级
2. **配置文件**（`llm.api_key`）- 第二优先级
3. **环境变量**（如 `OPENAI_API_KEY`）- 第三优先级
4. **默认值**（代码中的硬编码）- 最低优先级

### 使用方法

#### 方法 1：通过命令行参数（最高优先级）

```bash
# 使用命令行参数指定 API Key
paper-agent summarize --input paper.pdf --api-key sk-proj-your-key

# 使用命令行参数指定配置文件
paper-agent summarize --input paper.pdf --config-file config.yaml
```

#### 方法 2：通过配置文件（第二优先级）

创建配置文件 `config.yaml`：

```yaml
llm:
  api_key: your-api-key
  api_base_url: https://your-custom-api.com/v1
  model_name: gpt-4-turbo
```

#### 方法 3：使用环境变量（第三优先级）

```bash
# 设置环境变量
export OPENAI_API_KEY=sk-proj-your-key

# 正常使用
paper-agent summarize --input paper.pdf
```

### 查看当前配置

```bash
# 查看所有配置项（优先级：命令行 > 配置文件 > 环境变量）
paper-agent config --config-file config.yaml
```

### 配置文件示例

**完整示例**：

```yaml
llm:
  api_key: sk-proj-abc123xyz
  api_base_url: https://api.openai.com/v1
  model_name: gpt-4-turbo

export:
  output_dir: ./output
```

**Azure OpenAI 示例**：

```yaml
llm:
  api_key: your-azure-openai-key
  api_base_url: https://your-resource.openai.azure.com/openai/deployments/your-deployment
  model_name: gpt-4
```

**国内 LLM 服务商示例**（兼容 OpenAI 接口）：

```yaml
llm:
  API key: your-domestic-llm-api-key
  api_base_url: https://api.domestic-llm.com/v1
  model_name: your-custom-model
```

**自定义模型示例**：

```yaml
llm:
  model_name: claude-3-opus-20240229
```

（假设 API key 已通过其他方式设置）

### JSON 格式

生成的 JSON 文件包含所有元数据：

```json
{
  "title": "Deep Learning for Computer Vision",
  "authors": ["Zhang Wei", "Li Ming"],
  "year": 2024,
  "doi": 10.1234/test,
  "abstract": "This paper presents a novel approach...",
  "summary": "本论文提出了一种新的深度学习方法...",
  "source": "/path/to/paper.pdf",
  "processed_at": "2025-02-07T12:34:56.789012",
  "model_used": "openai",
  "token_usage": {
    "input_tokens": 1000,
    "output_tokens": 200,
    "cost": 0.042
  }
}
```

### JSON Format

Generated JSON files include all metadata:

```json
{
  "title": "Deep Learning for Computer Vision",
  "authors": ["Zhang Wei", "Li Ming"],
  "year": 2024,
  "doi": "10.1234/test",
  "abstract": "This paper presents a novel approach...",
  "summary": "本论文提出了一种新的深度学习方法...",
  "source": "/path/to/paper.pdf",
  "processed_at": "2025-02-07T12:34:56.789012",
  "model_used": "openai",
  "token_usage": {
    "input_tokens": 1000,
    "output_tokens": 200,
    "cost": 0.042
  }
}
```

## 数据库

系统使用 SQLite (`papers.db`) 存储论文元数据。数据库包括：

- 索引字段：`title`、`doi`、`year`
- 基于 DOI 和标题的自动去重
- 全文搜索功能

### 数据库位置

- 默认：当前目录下的 `papers.db`
- 可通过修改 CLI 代码更改（未来增强功能）

## 故障排除

### 错误代码

系统为错误返回特定的退出代码：

| 代码 | 描述 | 解决方案 |
|------|-------------|----------|
| 0 | 成功 | - |
| 1 | 一般错误 | 检查错误消息 |
| 2 | 使用错误 | 检查命令语法 |
| 3 | PDF 损坏 | 验证 PDF 文件有效 |
| 4 | PDF 受密码保护 | 删除密码保护 |
| 5 | LLM 错误 | 检查 API 密钥和网络连接 |
| 6 | 存储错误 | 检查数据库文件权限 |

### 常见问题

#### "OPENAI_API_KEY environment variable not set"

**解决方案**: 设置您的 API 密钥：

```bash
export OPENAI_API_KEY="your-key-here"
```

#### "PDF file is corrupted or invalid"

**解决方案**：
- 验证 PDF 文件可以在 PDF 阅读器中打开
- 检查文件未受密码保护
- 尝试重新下载 PDF

#### "LLM API error"（超时/速率限制）

**解决方案**：
- 检查您的互联网连接
- 验证您有足够的 API 配额
- 系统包含自动重试逻辑（3 次尝试，指数退避）

#### "Paper already exists"（DuplicatePaperError）

**解决方案**: 这是正常行为，当尝试处理数据库中已有的论文时发生。系统防止重复。

### 性能问题

#### 大 PDF 文件处理时间过长

对于 >10MB 的 PDF：
- 文本提取通常 <60s
- 元数据提取更快
- 总处理时间取决于 LLM 响应时间

#### 数据库增长过大

数据库通常很小（KB 到 MB），因为它只存储元数据，不存储全文内容。

## 开发

### 运行测试

运行所有测试：

```bash
pytest -v
```

运行特定测试文件：

```bash
pytest tests/test_integration.py -v
```

运行测试覆盖率：

```bash
pytest --cov=src --cov-report=term
```

### 测试覆盖率

当前覆盖率：≥80%

- 单元测试：单个模块测试
- 集成测试：端到端工作流测试
- 性能测试：大 PDF 处理测试

### 项目结构

```
paper-agent/
├── src/
│   ├── __init__.py
│   ├── cli.py              # 命令行界面
│   ├── pdf_processor.py    # PDF 元数据和文本提取
│   ├── llm_client.py       # LLM 集成（OpenAI/Anthropic）
│   ├── storage.py          # SQLite 存储与去重
│   ├── obsidian_exporter.py # Obsidian Markdown 导出
│   └── json_exporter.py    # JSON 导出
├── tests/
│   ├── test_pdf_processor.py
│   ├── test_llm_client.py
│   ├── test_storage.py
│   ├── test_obsidian_exporter.py
│   ├── test_json_exporter.py
│   ├── test_cli.py
│   ├── test_integration.py # 端到端测试
│   └── fixtures/          # 测试用示例 PDF
├── pyproject.toml         # 项目配置
└── README.md              # 本文件
```

## API 成本

每篇论文的估算成本（近似值）：

- **OpenAI GPT-4**: $0.03/1K 输入 tokens + $0.06/1K 输出 tokens
- **Anthropic Claude 3**: $0.003/1K 输入 tokens + $0.015/1K 输出 tokens

典型学术论文（约 5 页）：
- 输入 tokens：~1000
- 输出 tokens：~200
- OpenAI 成本：~$0.04
- Anthropic 成本：~$0.006

系统跟踪并显示每篇论文的 token 使用量和成本。

## 贡献

欢迎贡献！请确保：
- 所有测试通过：`pytest -v`
- 代码覆盖率 ≥80%
- 遵循现有代码风格
- 为新功能添加测试

## 许可证

[您的许可证信息]

## 致谢

- PyMuPDF 用于 PDF 处理
- OpenAI 和 Anthropic 提供 LLM API
- Obsidian 提供 Markdown 格式规范