很多 agent 能搜到论文标题和摘要，但真正做文献综述时，经常会出问题：

• 只看标题就说相关
• 摘要证据很弱，却给出很强结论
• 下载不到 PDF，整个流程就停住
• 输出是巨大 JSON，人根本不想读

Paper-Reach 把这个过程拆成几个明确阶段：

1. 高召回检索候选论文
2. 基于摘要做保守初筛
3. 能下载全文就下载全文
4. 用摘要或全文做细筛
5. 输出完整版 JSON 和人能直接看的精炼版

安装：

python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
paper-reach doctor

生成示例 query：

paper-reach example-query > query.json

只做粗筛：

paper-reach screen \
  --input query.json \
  --output screen.json \
  --high-recall \
  --retrieval-limit 200

跑完整流程，并把每个阶段都输出到一个文件夹：

paper-reach run \
  --input query.json \
  --output result.json \
  --bundle-dir ./runs/demo \
  --high-recall \
  --retrieval-limit 200 \
  --workers 8

导出适合人工阅读的精简版：

paper-reach summarize \
  --input result.json \
  --output brief.json \
  --format brief \
  --top-k 20

输出目录大概长这样：

runs/demo/
├─ 00_query.json
├─ 10_screen.json
├─ 20_fetched_papers.json
├─ 30_result_full.json
├─ 40_result_brief.json
├─ 50_result_titles.json
├─ manifest.json
└─ downloads/

已经安装过的话，更新通常就是：

git pull
pip install -e .[dev]

有些学术平台需要登录状态，或者依赖机构浏览器会话。对这类平台，最实用的方式是：

浏览器登录 -> 用 Cookie-Editor 导出 Cookie -> 发给 Agent / Paper-Reach 使用

推荐流程：

• 在 Chrome 里登录目标出版社或平台
• 用 Chrome 插件 Cookie-Editor 导出 Cookie
• 把 Cookie 文件作为 --cookie-file 传给 Paper-Reach

示例：

paper-reach fetch-fulltext \
  --input query.json \
  --output review.json \
  --download-dir ./downloads \
  --cookie-file ./cookies.json

这通常比自动模拟登录或反复做人机验证更简单，也更稳定。

Cookie 处理原则：

• Cookie 留在本地
• 核心工作流不强依赖 Cookie
• Cookie 缺失或失效时，Paper-Reach 会自动回退

详情见 docs/browser-cookies.md。

Paper-Reach 不是一个重型自治研究框架，而是一个实用的文献工作流 starter repo / scaffolding。

核心设计原则：

• 搜索不难，筛选更难
  • 真正的价值在于筛得更准，而不是源更多
• 弱证据就该保持弱
  • 不能把标题相关直接说成“已确认”
• 摘要和全文是不同证据层级
  • 摘要支持有用，但全文支持更强
• 离线模式很重要
  • 必须能处理本地 PDF、metadata、DOI 列表
• JSON 优先
  • 输出要适合 agent 和脚本继续消费
• 人工复核依然重要
  • 最终应该产出人真正能看的 shortlist

• 一个给 AI Agent 复用的文献工作流
• 一个 Python CLI
• 一个适配多宿主的 skill bundle
• 一个适合 literature review / gap analysis 的 starter scaffold

• 不是一个庞大的自治 multi-agent 系统
• 不承诺每篇论文都一定能下载
• 不是一个黑盒排序器

• 高召回文献检索与 query expansion
• 保守的摘要级初筛与 explainable reasons
• PDF 可用时的全文 review
• OpenAlex 优先下载与自动回退
• profile-based ranking，支持硬门槛和加权维度
• 面向人的紧凑输出：titles 与 brief
• 面向 agent 的结构化完整 JSON 输出

下面是一个真实可用的 query：

{
  "topic": "China static population exposure assessment for disasters and infectious disease",
  "keywords": [
    "China",
    "static population",
    "gridded population",
    "census population",
    "population exposure",
    "population at risk",
    "disaster exposure",
    "hazard exposure",
    "infectious disease exposure",
    "WorldPop",
    "LandScan",
    "GPW"
  ],
  "inclusion_criteria": [
    "study area is in China",
    "uses static population data or gridded population as exposure input",
    "focuses on disaster exposure or infectious-disease exposure",
    "estimates exposed population or population at risk"
  ],
  "exclusion_criteria": [
    "study area outside China only",
    "not an exposure study",
    "generic epidemiology without exposure modeling",
    "dynamic mobility only without static population baseline"
  ],
  "year_range": [2005, 2026],
  "max_results": 200,
  "need_gap_analysis": true,
  "mode": "auto",
  "require_fulltext_for_selection": false,
  "profile": "static_population_exposure_baseline"
}

如果配置了 OPENALEX_API_KEY 或 OPENALEX_CONTENT_API_KEY，Paper-Reach 会优先尝试 OpenAlex content API：

export OPENALEX_API_KEY=your_key

下载优先级：

1. OpenAlex content API
2. open-access PDF URL
3. 落地页提取
4. cookie / header session 复用
5. 回退到摘要级 review

也就是说，OpenAlex API key 是增强项，不是硬依赖。

Paper-Reach 采用和成熟跨宿主 skill 项目类似的结构：

• 一个共享执行引擎
  • paper-reach CLI + paper_reach/
• 一个宿主无关的 skill 入口
  • SKILL.md
• 几个宿主专用的轻量 manifest
  • agents/openai.yaml
  • .claude-plugin/plugin.json
  • gemini-extension.json

这样可以把核心逻辑放在一处，同时让不同 agent 宿主都能发现和调用它。

paper-reach/
├─ README.md
├─ README_EN.md
├─ AGENTS.md
├─ SKILL.md
├─ docs/
├─ examples/
├─ skills/
├─ agents/
├─ .claude-plugin/
├─ paper_reach/
├─ scripts/
└─ tests/

• docs/install.md
• docs/usage.md
• docs/architecture.md
• docs/agent-integration.md
• docs/browser-cookies.md
• docs/publishing.md
• docs/roadmap.md

Contributions are most useful when they improve:

• screening quality
• evidence extraction
• backend extensibility
• offline usability
• agent integration

The project should stay modular, conservative, and easy to extend.