Paper2Agent 中文使用教程

目录

1. 项目简介
2. 核心概念
3. 环境要求
4. 安装步骤
5. 基本用法
6. 进阶用法
7. 实战示例
8. 使用生成的 MCP 服务器
9. 直接连接官方托管的远程 MCP 服务器
10. 常见问题

1. 项目简介

Paper2Agent 是斯坦福大学团队发表于 Nature 的多智能体 AI 系统,它可以自动把科研论文转换成可交互的 AI 智能体,几乎不需要人工干预。

它解决的核心问题是:论文里的科学方法通常"沉睡"在 PDF 和代码仓库里,别人想复现或应用非常困难。Paper2Agent 把这些内容转换成两种可用的形态:

重要认知:这个项目是一个安装给编码智能体(Claude Code / Codex)的 skill(技能包)。真正干活的是编码智能体,Paper2Agent 给它提供了"如何转换论文"的完整工作流指令。

2. 核心概念

安装后的 skill 位于 skills/paper2agent/,内部按输入类型路由到三个子技能:

skills/paper2agent/
├── SKILL.md               # 主入口:根据输入自动路由
├── paper2skill/           # 论文 PDF → 可审阅的论文技能
├── paper2mcp/             # 代码仓库 → 经过测试的 MCP 服务器
└── paper2agent-paper/     # Paper2Agent 自己的 Nature 论文知识包(供提问)

三种输入模式:

• 只有论文 PDF(及附录、表格、图片)→ 走 paper2skill 流程
• 只有代码仓库 → 走 paper2mcp 流程
• 论文 + 代码都有 → 两个流程都跑,输出合并到:

dist/<project>-agent/
├── skill/<paper-name>/       # 论文技能
└── mcp/<repository-name>-mcp/ # MCP 服务器

3. 环境要求

开始前确认以下条件:

4. 安装步骤

方式一:让编码智能体自动安装(推荐)

直接把下面这段话发给 Claude Code 或 Codex（注意GitHub访问需要代理）:

Read https://github.com/jmiao24/Paper2Agent and install the paper2agent skill
from skills/paper2agent for this coding agent.

方式二:手动安装

第 1 步:克隆仓库

git clone https://github.com/jmiao24/Paper2Agent.git
cd Paper2Agent

第 2 步:把整个 skill 文件夹复制到宿主的个人技能目录

Claude Code:

mkdir -p "$HOME/.claude/skills/paper2agent"
cp -R skills/paper2agent/. "$HOME/.claude/skills/paper2agent/"

Codex:

mkdir -p "$HOME/.agents/skills/paper2agent"
cp -R skills/paper2agent/. "$HOME/.agents/skills/paper2agent/"

⚠️ 一定要复制整个文件夹,包括所有子目录和支撑文件(references、scripts、agents 等)。

第 3 步:重启编码智能体

在你想要工作的分析目录中启动 Claude Code 或 Codex。如果 skill 没有出现在列表里,重启一次即可。

5. 基本用法

安装完成后,在编码智能体中用一段自然语言提示词发起转换。通用模板:

Use the paper2agent skill to agentify this paper and its associated files,
alongside its code repository if available. Follow the skill instructions
for the workflow, verification, and final delivery.
​
Paper and associated files: <论文URL或本地文件>
Code repository (if available): <GitHub URL 或本地路径>
Output directory: <项目输出目录>

在 Claude Code 中也可以用斜杠命令直接调用:

/paper2agent Convert <GitHub仓库URL> into tested MCP tools in <输出目录>.

📌 Codex 用户把 /paper2agent 换成 $paper2agent。

转换结束后,智能体会交付:

• dist/<repo-name>-mcp.zip —— 可直接分发的 MCP 服务器压缩包
• 内含 USAGE.md —— 安装依赖、启动服务器、所需环境变量、支持平台的完整说明
• 验证报告 —— 实际测试过的工具清单和验证范围

6. 进阶用法

6.1 只转换论文中的特定任务或教程

大仓库(比如 Scanpy)功能太多,可以指定关注点,让转换更聚焦:

/paper2agent Convert https://github.com/scverse/scanpy into tested MCP tools in Scanpy_Agent.
Focus on the "Preprocessing and clustering" tutorial.

也可以直接给教程的 URL:

/paper2agent Convert https://github.com/scverse/scanpy into tested MCP tools in Scanpy_Agent.
Focus on https://github.com/scverse/scanpy/blob/main/docs/tutorials/basics/clustering.ipynb

6.2 需要 API Key 的仓库

不要把密钥写进提示词或代码。先通过宿主的密钥机制或进程环境变量提供凭证,然后只告诉智能体变量名:

/paper2agent Convert https://github.com/google-deepmind/alphagenome into tested MCP tools in AlphaGenome_Agent.
Read the API key from the environment variable ALPHAGENOME_API_KEY.

凭证会始终留在生成的代码、notebook、报告和交付 ZIP 之外。

6.3 纯论文模式(PDF → 论文技能)

如果只有论文 PDF、附录、表格和图片,没有代码,skill 会走 paper2skill 流程,产出如下结构的知识包:

<identifier>-paper/
├── SKILL.md
├── references/
│   ├── index.md       # 索引
│   ├── paper.md       # 正文(按章节连续)
│   └── supplement.md   # 附录
└── assets/
  ├── figure/         # 正文图
  ├── supp_figs/     # 扩展数据图、附录图
  ├── table/         # 正文表
  └── supp_table/     # 附录表

该流程内部使用 paper_bundle.py 脚本,分为五步:prepare(快照与审阅计划)→ extract(提取)→ review(逐页人工/多智能体审阅)→ build(构建)→ verify(严格校验)。校验结果分为五档:

只有前两档能通过严格校验(verify --strict 返回 0);后三档产出的技能会被标记为草稿。

6.4 中途恢复(resume)

转换是长任务,如果中断,再次调用 skill 时说明要 resume 即可,工作流状态文件(workflow-state)记录了各阶段完成标记,会从断点继续:

Use the paper2agent skill to resume the conversion in <项目目录>.

7. 实战示例

以下是 README 中的三个官方示例,可直接照抄使用。

示例 1:TISSUE —— 空间转录组不确定性分析

/paper2agent Convert https://github.com/sunericd/TISSUE into tested MCP tools in TISSUE_Agent.

生成后即可这样提问:

Calculate the 95% prediction interval for the spatial gene expression
prediction of gene Acta2 using TISSUE MCP.
​
This is my data:
Spatial count matrix: Spatial_count.txt
Spatial locations: Locations.txt
scRNA-seq count matrix: scRNA_count.txt

示例 2:Scanpy —— 单细胞数据预处理与聚类

/paper2agent Convert https://github.com/scverse/scanpy into tested MCP tools in Scanpy_Agent.
Focus on the "Preprocessing and clustering" tutorial.

生成后使用:

Use Scanpy MCP to preprocess and cluster the single-cell dataset pbmc_all.h5ad.

示例 3:AlphaGenome —— 基因组变异解读(需要 API Key)

/paper2agent Convert https://github.com/google-deepmind/alphagenome into tested MCP tools in AlphaGenome_Agent.
Read the API key from the environment variable ALPHAGENOME_API_KEY.

生成后使用:

Analyze heart gene expression data with AlphaGenome MCP to identify the causal gene
for the variant chr11:116837649:T>G, associated with Hypoalphalipoproteinemia.

8. 使用生成的 MCP 服务器

8.1 本地服务器

1. 解压交付的 ZIP,阅读其中的 USAGE.md
2. 按说明安装依赖(会注明经过测试的解释器版本、服务器入口、所需环境变量)
3. 注册到 MCP 客户端。可以直接让编码智能体代劳:Connect the generated MCP server to my coding-agent client using its USAGE.md.

8.2 验证连接

在 Claude Code 中:

claude mcp list

或在会话内输入 /mcp。连接成功后,服务器会出现在列表中。建议再发起一次真实工具调用,确认科学工作流能跑通你的输入数据。

9. 直接连接官方托管的远程 MCP 服务器

不想自己跑转换?作者在 Hugging Face 上托管了三个现成的服务器（只有示例的）:

方式一:一行命令接入 Claude Code

claude mcp add --transport http alphagenome https://Paper2Agent-alphagenome-mcp.hf.space

方式二:使用仓库自带的连接脚本

仓库提供了 scripts/connect_remote_mcp.sh,它会创建(或复用)一个分析工作区、注册服务器并自动启动 Claude:

bash scripts/connect_remote_mcp.sh \
 --working_dir ./analysis \
 --mcp_name alphagenome \
 --mcp_url https://Paper2Agent-alphagenome-mcp.hf.space

10. 常见问题

Q:安装后 /paper2agent 命令不出现?
A:重启编码智能体。确认复制的是整个 skill 文件夹(含所有子目录),且位置正确(Claude Code 为 ~/.claude/skills/paper2agent/,Codex 为 ~/.agents/skills/paper2agent/)。

Q:转换需要多久?
A:取决于仓库大小和教程数量。这是一个多阶段、多智能体的长任务,大仓库(如 Scanpy)可能需要较长时间。可以用 Focus on ... 缩小范围来加速。

Q:没有 GPU / 数据 / API key 能转换吗?
A:可以发起转换,但涉及这些资源的工具会在验证阶段受阻。skill 会如实记录哪些工具被阻塞及原因,而不是假装成功。建议先满足目标仓库的运行要求。

Q:生成的代码会不会把我的 API key 泄露到 ZIP 里?
A:不会。按 6.2 的方式通过环境变量传变量名,凭证会留在生成的代码、notebook、报告和交付 ZIP 之外。

Q:想问 Paper2Agent 这篇 Nature 论文本身的方法、结果、图表?
A:直接问编码智能体即可,skill 内置了 paper2agent-paper 知识包(含论文正文、附录、图表),专门用于回答关于 Paper2Agent 方法学的问题。

Q:交付的 ZIP 里为什么没有中间产物和审阅记录?
A:设计如此。评审与开发证据留在工作项目目录中,交付 ZIP 只含服务器运行所需文件与 USAGE.md,保证"解压即用"。

参考链接

• 项目主页:https://paper2agent.ai
• GitHub 仓库:https://github.com/jmiao24/Paper2Agent
• Nature 论文:Reimagining research papers as interactive and reliable AI agents (2026), doi: 10.1038/s41586-026-11044-y
• Claude Code MCP 文档:https://code.claude.com/docs/en/mcp
• Claude Code Skills 文档:https://code.claude.com/docs/en/skills

引用格式

@article{miao2026paper2agent,
title={Reimagining research papers as interactive and reliable {AI} agents},
author={Miao, Jiacheng and Davis, Joe R. and Zhang, Yaohui and Pritchard, Jonathan K. and Zou, James},
journal={Nature},
year={2026},
doi={10.1038/s41586-026-11044-y},
url={https://www.nature.com/articles/s41586-026-11044-y}
}