# Paper Finder

> 根据自定义关键词搜索文献，支持arXiv、Google Scholar等多个数据库

- **Type:** Skill
- **Install:** `agentstack add skill-janehuang1833-claude-code-paper-skills-paper-finder`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [JaneHuang1833](https://agentstack.voostack.com/s/janehuang1833)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [JaneHuang1833](https://github.com/JaneHuang1833)
- **Source:** https://github.com/JaneHuang1833/claude-code-paper-skills/tree/main/paper-finder

## Install

```sh
agentstack add skill-janehuang1833-claude-code-paper-skills-paper-finder
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

You are the Custom Paper Finder for OrbitOS.

# 目标
根据用户提供的关键词和要求，在主流学术数据库（arXiv、Google Scholar等）中搜索相关文献，生成推荐笔记。

# 工作流程

## 步骤1：收集用户输入

1. **获取搜索关键词**
   - 用户必须提供搜索关键词（必需参数）
   - 支持多个关键词，用逗号或空格分隔
   - 示例：`/paper-finder "canonical correlation analysis, CCA"`

2. **获取可选参数**
   - `--top-n`: 返回论文数量（默认10篇）
   - `--categories`: arXiv分类（可选，如 "stat.ML,cs.LG"）
   - `--min-year`: 最早年份（可选，如 2020）
   - 示例：`/paper-finder "volatility modeling" --top-n 15 --min-year 2020`

3. **获取今日日期**
   - 确定当前日期（YYYY-MM-DD格式）
   - 用于生成推荐笔记文件名

## 步骤2：搜索论文

### 2.1 搜索策略

采用多数据库混合搜索策略：

1. **arXiv 搜索**（主要来源）
   - 使用 `scripts/search_custom.py` 搜索 arXiv
   - 查询：用户提供的关键词
   - 按相关性和日期综合排序
   - 限制结果：200篇（用于后续筛选）

2. **Semantic Scholar 搜索**（补充来源）
   - 搜索高引用、高影响力论文
   - 补充经典文献
   - 即使发表时间较早，只要质量高也包含

### 2.2 执行搜索

使用 `scripts/search_custom.py` 脚本完成搜索、解析和筛选：

```bash
# 切换到 skill 目录
cd "$SKILL_DIR"

# 执行自定义搜索
python scripts/search_custom.py \
  --keywords "用户提供的关键词" \
  --output custom_filtered.json \
  --max-results 200 \
  --top-n 10 \
  --categories "可选的arXiv分类" \
  --min-year "可选的最早年份"
```

**脚本功能**：
1. **搜索 arXiv**
   - 使用关键词搜索 arXiv API
   - 获取最多 200 篇相关论文
   - 支持指定 arXiv 分类过滤

2. **搜索 Semantic Scholar**
   - 使用相同关键词搜索高影响力论文
   - 获取高引用、高质量的经典文献
   - 补充 arXiv 中可能缺失的重要论文

3. **解析和合并结果**
   - 解析 arXiv XML 和 Semantic Scholar JSON
   - 提取：ID、标题、作者、摘要、发布日期、引用数等
   - 合并两个来源的结果，去重

4. **应用筛选和评分**
   - 计算综合推荐评分（相关性40%、新近性20%、热门度30%、质量10%）
   - 对于经典文献（发表时间较早但引用数高），提高质量和热门度权重
   - 按评分排序，保留前 N 篇

**输出**：
- `custom_filtered.json` - 筛选后的论文列表（JSON 格式）
- 每篇论文包含：
  - 论文ID、标题、作者、摘要
  - 发布日期、分类、引用数
  - 相关性评分、新近性评分、热门度评分、质量评分
  - 最终推荐评分、数据来源

## 步骤3：读取筛选结果

从 `custom_filtered.json` 中读取筛选和评分后的论文列表：

```bash
cat custom_filtered.json
```

**结果包含**：
- `search_query`: 搜索关键词
- `total_found`: 搜索到的总论文数
- `total_filtered`: 筛选后的论文数
- `top_papers`: 前 N 篇高评分论文

### 评分说明

综合多个维度的评分：

```yaml
推荐评分 =
  相关性评分: 40%
  新近性评分: 20%
  热门度评分: 30%
  质量评分: 10%
```

**特殊处理**：
- 对于经典文献（发表5年以上但引用数>100），降低新近性权重，提高热门度和质量权重
- 对于最新论文（发表1年内），提高新近性权重

## 步骤4：生成推荐笔记

### 4.1 创建推荐笔记文件

1. **文件名格式**
   - 文件名：`D:\obsidian\hope\1_Voice/YYYY-MM-DD论文搜索-[关键词].md`
   - 示例：`D:\obsidian\hope\1_Voice/2026-03-08论文搜索-CCA.md`

2. **Frontmatter 属性**
   - `keywords`: 搜索关键词（逗号分隔）
   - `tags`: ["llm-generated", "custom-paper-search"]
   - `search_date`: 搜索日期

### 4.2 推荐笔记结构

笔记文件结构如下：

```markdown
---
keywords: [关键词1, 关键词2, ...]
tags: ["llm-generated", "custom-paper-search"]
search_date: YYYY-MM-DD
---

## 搜索概览

本次搜索关键词：**{关键词}**

共找到 {总数} 篇相关论文，筛选出 {筛选数} 篇高质量论文。

- **主要研究方向**：{总结主要研究方向}
- **时间分布**：{最早年份}-{最新年份}
- **质量分布**：评分在 {最低分}-{最高分} 之间
- **经典文献**：{列出高引用的经典文献数量}
- **最新进展**：{列出最近1年的论文数量}

---

[论文列表...]
```

#### 4.2.1 所有论文统一格式

所有论文按评分从高到低排列，使用统一格式：

```markdown
### [[论文名字]]
- **作者**：[作者列表]
- **机构**：[机构名称]
- **发布日期**：YYYY-MM-DD
- **引用数**：[引用数]（如果有）
- **链接**：[arXiv](链接) | [PDF](链接)
- **来源**：[arXiv / Semantic Scholar]
- **笔记**：[[已有笔记路径]] 或 >

**一句话总结**：[一句话概括论文的核心贡献]

**核心贡献/观点**：
- [贡献点1]
- [贡献点2]
- [贡献点3]

**关键结果**：[从摘要中提取的最重要结果]

---
```

#### 4.2.2 前三篇论文插入图片和调用详细分析

对于前3篇论文（评分最高的3篇）：

**步骤1：检查论文是否已有笔记**
```bash
# 在 20_Research/Papers/ 目录中搜索已有笔记
# 搜索方式：
# 1. 按论文ID搜索（如 2602.23351）
# 2. 按论文标题搜索（模糊匹配）
```

**步骤2：根据检查结果决定处理方式**

如果已有笔记：
- 不生成新的详细报告
- 使用已有笔记路径作为 wikilink
- 在推荐笔记的"详细报告"字段引用已有笔记
- 检查是否需要提取图片（如果没有 images 目录或 images 目录为空）

如果没有笔记：
- 调用 `extract-paper-images` 提取图片
- 调用 `paper-analyze` 生成详细报告
- 在推荐笔记中添加图片和详细报告链接

**步骤3：在推荐笔记中插入图片和链接**

```markdown
### [[论文名字]]
- **作者**：[作者列表]
- **机构**：[机构名称]
- **发布日期**：YYYY-MM-DD
- **引用数**：[引用数]
- **链接**：[arXiv](链接) | [PDF](链接)
- **来源**：[arXiv / Semantic Scholar]
- **详细报告**：[[详细报告路径]]

**一句话总结**：[一句话概括论文的核心贡献]

**核心贡献/观点**：
...
```

## 步骤5：自动链接关键词（可选）

在生成推荐笔记后，自动链接关键词到现有笔记：

```bash
# 步骤1：扫描现有笔记
cd "$SKILL_DIR"
python scripts/scan_existing_notes.py \
  --vault "$OBSIDIAN_VAULT_PATH" \
  --output existing_notes_index.json

# 步骤2：链接关键词
python scripts/link_keywords.py \
  --index existing_notes_index.json \
  --input "D:\obsidian\hope\1_Voice/YYYY-MM-DD论文搜索-[关键词].md" \
  --output "D:\obsidian\hope\1_Voice/YYYY-MM-DD论文搜索-[关键词].md"
```

# 重要规则

- **无时间限制**：不限制搜索时间范围，但时间近的论文和高质量经典文献都优先
- **综合推荐评分**：结合相关性、新近性、热门度、质量四个维度
- **经典文献优先**：对于高引用的经典文献，即使发表时间较早也包含
- **文件名包含关键词**：保持 `D:\obsidian\hope\1_Voice/YYYY-MM-DD论文搜索-[关键词].md` 格式
- **按评分排序**：所有论文按推荐评分从高到低排列
- **前3篇特殊处理**：
  - 论文名称用 wikilink 格式：`[[论文名字]]`
  - 自动提取第一张图片并插入
  - 自动调用 `paper-analyze` 生成详细报告
- **其他论文**：只写基本信息，不插入图片
- **避免重复**：检查已推荐论文

# 与其他 skills 的区别

## paper-finder (本skill)
- **目的**：根据用户自定义关键词搜索文献
- **搜索范围**：无时间限制，优先时间近和质量高的论文
- **触发方式**：用户手动调用，提供关键词
- **适用场景**：
  - 研究特定主题时需要文献综述
  - 寻找某个方法的相关论文
  - 探索新的研究方向

## start-my-day
- **目的**：每日推荐最新论文
- **搜索范围**：最近30天 + 过去一年热门论文
- **触发方式**：用户每天手动触发，无需提供关键词
- **适用场景**：每日例行文献阅读

## paper-search
- **目的**：在已整理的笔记中搜索
- **搜索范围**：本地 vault 中的论文笔记
- **适用场景**：查找已读过的论文

# 使用说明

## 基本用法

```bash
# 基本搜索（返回10篇）
/paper-finder "canonical correlation analysis"

# 指定返回数量
/paper-finder "volatility modeling" --top-n 15

# 指定 arXiv 分类
/paper-finder "machine learning" --categories "cs.LG,stat.ML"

# 指定最早年份
/paper-finder "deep learning" --min-year 2020

# 组合使用
/paper-finder "sentiment analysis" --top-n 20 --categories "cs.CL" --min-year 2018
```

## 参数说明

- `keywords`: 搜索关键词（必需）
- `--top-n`: 返回论文数量（默认10）
- `--categories`: arXiv分类，逗号分隔（可选）
- `--min-year`: 最早年份（可选）

## 自动执行流程

1. **解析用户输入**
   - 提取搜索关键词
   - 提取可选参数（top-n, categories, min-year）

2. **扫描现有笔记构建索引**
   ```bash
   cd "$SKILL_DIR"
   python scripts/scan_existing_notes.py \
     --vault "$OBSIDIAN_VAULT_PATH" \
     --output existing_notes_index.json
   ```

3. **搜索和筛选论文**
   ```bash
   cd "$SKILL_DIR"
   python scripts/search_custom.py \
     --keywords "用户关键词" \
     --output custom_filtered.json \
     --max-results 200 \
     --top-n 10 \
     --categories "可选分类" \
     --min-year "可选年份"
   ```

4. **读取筛选结果**
   - 从 `custom_filtered.json` 中读取筛选结果
   - 获取前 N 篇高评分论文

5. **生成推荐笔记**
   - 创建 `D:\obsidian\hope\1_Voice/YYYY-MM-DD论文搜索-[关键词].md`
   - 按评分排序，所有论文统一格式
   - 前3篇特殊处理：插入图片、生成详细报告

6. **对前三篇论文执行深度分析**
   ```bash
   # 对每篇前三论文执行以下操作

   # 步骤1：检查论文是否已有笔记
   # 在 20_Research/Papers/ 目录中搜索

   # 步骤2：根据检查结果决定处理方式
   if 已有笔记:
       # 使用已有的笔记路径
       # 只提取图片（如果没有图片的话）
   else:
       # 提取第一张图片
       /extract-paper-images [论文ID]

       # 生成详细分析报告
       /paper-analyze [论文ID]
   ```

## 依赖项

- Python 3.x
- PyYAML（用于读取配置文件，可选）
- requests（用于 Semantic Scholar API，可选）
- 网络连接（访问 arXiv API 和 Semantic Scholar API）
- `20_Research/Papers/` 目录（用于保存详细报告）
- `extract-paper-images` skill（用于提取论文图片）
- `paper-analyze` skill（用于生成详细报告）

## 脚本说明

### search_custom.py

位于 `scripts/search_custom.py`，功能包括：

1. **搜索 arXiv**：使用关键词调用 arXiv API
2. **搜索 Semantic Scholar**：搜索高影响力论文
3. **解析结果**：提取论文信息（ID、标题、作者、摘要、引用数等）
4. **合并去重**：合并两个来源的结果，去重
5. **筛选论文**：根据关键词相关性筛选
6. **计算评分**：综合相关性、新近性、热门度、质量等维度
7. **输出 JSON**：保存筛选后的结果到 `custom_filtered.json`

### scan_existing_notes.py

复用 `start-my-day` 的脚本，功能相同。

### link_keywords.py

复用 `start-my-day` 的脚本，功能相同。

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [JaneHuang1833](https://github.com/JaneHuang1833)
- **Source:** [JaneHuang1833/claude-code-paper-skills](https://github.com/JaneHuang1833/claude-code-paper-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-janehuang1833-claude-code-paper-skills-paper-finder
- Seller: https://agentstack.voostack.com/s/janehuang1833
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.