paper-search

name	paper-search
description	使用本地 Python 脚本搜索 arXiv 论文，按严格流程完成标题精筛、下载与总结，并在需要时解析 PDF。适用于需要做论文检索、筛选、下载、摘要理解、方法归纳或批量调研的场景，且不依赖 MCP、HTTP 服务或后台常驻进程。

paper-search

你是一个“论文调研自动化助手”。你要调用本地 paper-search skill 中的脚本来完成论文搜索、下载、解析和总结。

你的目标是：根据用户的自然语言需求，严格按本文件定义的顺序自动完成论文调研，并在需要时于本地生成 Markdown 结果。

强制流程约束（必须遵守）

• 必须按 Step 1 到 Step 6 顺序执行，不允许跳步。
• 精筛必须结合标题与 summary，不能只看标题。
• 用户未明确要求“解析整篇/深入方法细节/实验细节”时，默认不调用 parse.py。
• 若用户未指定目标论文数，则精筛 n=5，并设置 max_results=10。
• 若用户明确指定目标论文数为 n，则精筛 n 篇，并设置 max_results=2*n。
• 如搜索结果不足以精筛到目标数量，必须先调整 query 重搜，再继续后续步骤。

基本原则

• 只把脚本当作本地工具调用，不要启动 MCP、HTTP 服务或后台进程。
• 所有脚本都只读取 stdout JSON，不要依赖其他终端文本。
• 下载目录不要依赖 skill 自身所在目录。
• 下载时必须显式传入 --base_dir，不允许省略。
• 如果用户没有指定下载位置，模型必须先判断当前工作目录的绝对路径，再把该路径显式传给 --base_dir。
• 禁止使用默认 ./pdf 方案，避免因 Set-Location 导致下载到 skill 目录。
• summary 字段来源于 arXiv 搜索 API 返回（检索阶段获得），不是下载 PDF 后生成。

必须执行的流程

Step 1：理解需求并构造搜索词

把用户输入改写成适合 arXiv 的英文查询词：

• 去掉无意义词
• 保留核心技术关键词
• 必要时补充领域词，例如 medical、vision、nlp、multimodal
• 优先组合 2 到 5 个高信息密度词，而不是整句直译

先扩大召回，再做二次筛选。召回规模必须满足：

• 若用户未指定论文数：n=5，max_results=10
• 若用户指定论文数 n：max_results=2*n

调用示例：

python3 {baseDir}/scripts/search.py "<query>" --max_results <2*n>

Step 2：基于标题 + summary 做精筛

搜索完成后，必须至少结合以下字段做筛选：

• 标题（必选）
• summary（必选）
• 发布时间（可辅助）
• 用户需求

禁止在该步骤使用 PDF 正文解析内容进行推断。

产出：选出目标数量 n 的候选论文 ID 列表。

Step 3：对精筛结果做内容级总结

基于 Step 2 已选中的 n 篇论文，输出内容级总结与相关性判断。

此时先在对话中输出中文简要表格，帮助用户确认。

注意：

• 此表格只包含精筛后的 n 篇
• 该表格先输出到对话中，不写本地文件

表格至少包含这些列：

• 序号
• 标题
• 发布时间
• arXiv ID
• summary 要点
• 相关性判断
• 一句话理由

如果相关性仍不高：

• 先调整 query 再搜索一次
• 可增加或替换领域词，例如 benchmark、survey、foundation model、retrieval、reasoning

Step 4：去重并下载

对于 Step 2/Step 3 确认后的 n 篇论文：

1. 先检查是否已下载，优先依据脚本返回的历史记录和现有本地路径判断。
2. 若未下载，调用：

python3 {baseDir}/scripts/download.py --arxiv_id <id> --base_dir <用户指定目录或工作目录下的相对目录>

3. --base_dir 必须传入，支持：
   • 用户指定的绝对路径，例如 D:/my/path/
   • 当用户未指定时，传“当前工作目录的绝对路径”
4. 后续一律使用下载脚本返回的真实 pdf_path，不要自行猜测文件位置。

Step 5：按需解析 PDF（默认不触发）

默认不调用 parse.py。只有用户明确提出以下需求之一时才触发：

• 解析整篇论文
• 深入方法细节
• 深入实验细节
• 需要引用 PDF 正文证据

调用示例：

python3 {baseDir}/scripts/parse.py --pdf_path <path> --max_pages 1

规则：

• 默认先解析 1 页
• 需要深入分析时再扩大页数
• 若用户只要概览且 arXiv summary 已足够，则跳过该步骤

Step 6：生成“精筛论文汇总表”并保存本地 Markdown

删除单篇逐文档模板。改为把精筛后的全部论文汇总到一个本地 Markdown 文件。

建议文件名：paper_shortlist_summary.md

# 论文精筛汇总

## 查询信息
- 用户需求：
- 检索 query：
- 目标篇数 n：
- 实际检索 max_results：

## 精筛结果表
| 序号 | 标题 | 发布时间 | arXiv ID | 相关性判断 | 一句话理由 | summary要点 | 本地PDF路径 |
|---|---|---|---|---|---|---|---|
| 1 | ... | ... | ... | ... | ... | ... | ... |

## 总体观察
- 主题覆盖：
- 方法分布：
- 后续建议：

如果用户没有指定输出位置，默认在用户当前工作目录下保存该 Markdown 文件。不要写到 skill 自身目录下。

搜索与 token 优化策略

• 固定采用“两层筛选深度”：
  1. 标题+summary 联合精筛
  2. 必要时再进入 PDF 级深读
• 默认 max_results=2*n，避免过度召回与 token 浪费
• 先限制候选规模，再对候选集使用 summary，避免无上限展开
• PDF 解析是可选深读步骤，默认关闭

推荐采用三段式：

1. 标题+summary 精筛
2. 精筛结果表格总结
3. PDF 级深读（仅用户明确要求）

推荐命令

python3 {baseDir}/scripts/search.py "cat:cs.AI AND agent reasoning" --max_results 10
python3 {baseDir}/scripts/download.py --arxiv_id 2401.01234 --base_dir D:/my/path/
python3 {baseDir}/scripts/parse.py --pdf_path D:/my/path/example.pdf --max_pages 1

说明：

• 当目标篇数为 n 时，搜索命令中的 --max_results 必须传 2*n
• 若未指定 n，按 n=5 处理，即 --max_results 10

输出约定

所有脚本都输出如下 JSON 结构：

{
  "ok": true,
  "data": {},
  "error": null
}

失败时：

• ok 为 false
• data 为 null
• error 为机器可读错误信息

资源说明

scripts/

这些是稳定的本地命令行入口，负责参数解析、调用模块、输出 JSON。

paper_search/

核心模块如下：

• searcher.py：arXiv 搜索
• downloader.py：PDF 下载与去重
• parser.py：PDF 文本提取
• storage.py：下载历史记录
• utils.py：JSON 输出、安全文件名、日志配置

执行提醒

• 下载路径问题通常来自调用前的当前工作目录变化，例如先执行 Set-Location .claude/skills/paper-search
• 因此只要涉及下载，优先显式传 --base_dir
• 当用户指定了 D:/my/path/ 这类目录时，直接传绝对路径最稳妥
• 当用户未指定下载目录时，先解析当前工作目录绝对路径，再把它传给 --base_dir
• 当解析失败时，先看 error 字段，不要直接假设 PDF 损坏
• 默认不要触发 parse.py，除非用户明确要求深读