pengbo807/Paper-Researcher

一个论文阅读 Skill，支持 Codex 和 WorkBuddy AI，配套 Semantic Scholar MCP。它可以：

• 解释论文的方法、实验、局限和可复现性；
• 找出引用量top N的后续工作；
• 保存高引论文的引用元数据，支持后续本地过滤和重新排序；
• 从一个论文出发，执行树形结构的引用网络探索。

欢迎告诉我你希望 Paper Researcher 加入哪些新功能！ 🙌

• Codex 或 WorkBuddy AI；
• Python 3.11 或更高版本；
• uv；

由于Semantic Scholar API Key不一定能申请下来，所以本项目设计了无需API key即可运行的策略（针对可能的限流进行设计）。考虑到每一次检索完整引用扫描可能需要较长时间；MCP 会保存检查点，并在后续调用中继续未完成的扫描。

使用发布页面提供的 Git 地址克隆仓库，然后进入仓库目录：

git clone https://github.com/pengbo807/Paper-Researcher.git
cd Paper-Researcher

如果系统尚未安装 uv，按照 uv 官方安装说明 安装，并确认：

uv --version

MCP 文件使用 PEP 723 声明固定版本的 Python 依赖；首次启动时，uv 会自动创建隔离环境并安装这些依赖。

cp .codex/config.toml.example .codex/config.toml

打开 .codex/config.toml，把 cwd 改为当前仓库的绝对路径：

[mcp_servers.semantic_scholar]
command = "uv"
args = ["run", "--script", "tools/semantic_scholar_citations_mcp.py"]
cwd = "/absolute/path/to/Paper-Researcher"
env_vars = ["SEMANTIC_SCHOLAR_API_KEY"]
startup_timeout_sec = 60
tool_timeout_sec = 3600
enabled = true
required = false
default_tools_approval_mode = "auto"

打开 WorkBuddy AI 的 MCP 配置文件 ~/.workbuddy-ai/mcp.json（不存在则新建），在 mcpServers 中添加：

{
  "mcpServers": {
    "semantic_scholar": {
      "command": "uv",
      "args": ["run", "--script", "tools/semantic_scholar_citations_mcp.py"],
      "cwd": "/absolute/path/to/Paper-Researcher",
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": ""
      },
      "timeout": 3600000,
      "disabled": false
    }
  }
}

将 cwd 改为当前仓库的绝对路径。如果 mcp.json 中已有其他 MCP 配置，将 semantic_scholar 条目合并进 mcpServers 即可。

注意： 写入 mcp.json 后 MCP 不会自动生效。打开 WorkBuddy AI，在左上角找到 Connectors（自定义连接器）→ Custom connectors，找到 semantic_scholar，点击授权后该 MCP 才会启用。

如果已有 API Key，设置环境变量后在启动客户端前：

Codex：

export SEMANTIC_SCHOLAR_API_KEY="your-api-key"

WorkBuddy AI： 将 API Key 填入 mcp.json 中 env.SEMANTIC_SCHOLAR_API_KEY 字段即可。

未配置时，MCP 会使用 Semantic Scholar 的匿名访问。配置好Semantic Scholar API Key可以提高搜索速度。

用 Codex 打开仓库目录，然后新建一个任务。项目的 AGENTS.md 会引导 Codex 使用：

.agents/skills/paper-researcher/SKILL.md

.codex/config.toml 会启动配套的 Semantic Scholar MCP。如果此前已经打开过该仓库，请重新打开仓库或新建任务，使配置重新加载。

用 WorkBuddy AI 打开仓库目录。项目的 AGENTS.md 会引导 WorkBuddy AI 使用：

.workbuddy-ai/skills/paper-researcher/SKILL.md

MCP 配置生效后即可直接使用。

如果希望在其他项目中也能调用 $paper-researcher，可以把 Skill 复制到个人 Skill 目录。

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R .agents/skills/paper-researcher "${CODEX_HOME:-$HOME/.codex}/skills/paper-researcher"

也可以使用符号链接，便于仓库更新后立即生效：

ln -s "/absolute/path/to/Paper-Researcher/.agents/skills/paper-researcher" \
  "${CODEX_HOME:-$HOME/.codex}/skills/paper-researcher"

mkdir -p "$HOME/.workbuddy-ai/skills"
cp -R .workbuddy-ai/skills/paper-researcher "$HOME/.workbuddy-ai/skills/paper-researcher"

全局安装 Skill 不会自动安装 MCP。还需要把上述 MCP 配置加入个人配置；Codex 默认配置文件是 ~/.codex/config.toml，WorkBuddy AI 默认配置文件是 ~/.workbuddy-ai/mcp.json。将 cwd 设置为本仓库的绝对路径，完成后重新启动客户端。

新建一个任务并输入：

帮我找一下 Training Verifiers to Solve Math Word Problems 引用量最高的 20 篇后续论文。

正常情况下，客户端会调用 semantic_scholar_get_top_citing_papers，扫描全部引用分页，并报告：

• citation_page_request_count；
• scanned_citation_record_count；
• usable_citation_record_count；
• coverage；
• scan_complete；
• complete；
• 引用量最高的 20 篇后续论文。

第一次扫描高引论文可能耗时较长。发生持续限流或工具超时时，检查点会保留；agent会等待一段时间，然后会用相同论文和相同 Top-K 再次调用继续。

解释论文：

请解释 Training Verifiers to Solve Math Word Problems。

查找高被引后续工作：

帮我找一下 Training Verifiers to Solve Math Word Problems 引用量最高的 20 篇后续论文。

基于已保存档案继续过滤：

去掉综述和视觉相关文章之后，再给我引用量最高的 20 篇。

探索研究领域：

帮我探索 retrieval-augmented generation 领域的高影响力核心论文和重要后续工作。

当目标论文的引用量超过 1000 时，MCP 会保存实际检索到的精简引用元数据：

library/citation-searches/<论文标题>/citing-papers.sqlite3

未完成扫描的检查点保存在：

tmp/citation-checkpoints/

这些目录可能随使用持续增长，不属于 Skill 本身。删除相应论文的档案会清除本地检索记录；删除检查点会导致未完成扫描无法续传，但不会影响 Skill 和 MCP 源码。