{
  "markdown": "<div align=\"center\">\n\n# 👁️ Paper-Reach\n\n给你的 AI Agent 一套严谨的文献检索与筛选工作流\n\n[![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Python 3.8%2B](https://img.shields.io/badge/python-3.8%2B-blue.svg)](pyproject.toml)\n[![GitHub Stars](https://img.shields.io/github/stars/Dai0-2/paper_reach?style=social)](https://github.com/Dai0-2/paper_reach)\n\n`Paper-Reach` 是一个面向 AI Agent 的开源 Skill + CLI，用于文献检索、摘要初筛、全文细筛、证据提取和保守排序。\n\n[快速开始](#快速开始) · [English](README_EN.md) · [支持平台](#支持平台) · [设计理念](#设计理念)\n\n</div>\n\n---\n\n## 为什么需要 Paper-Reach\n\n很多 agent 能搜到论文标题和摘要，但真正做文献综述时，经常会出问题：\n\n- 只看标题就说相关\n- 摘要证据很弱，却给出很强结论\n- 下载不到 PDF，整个流程就停住\n- 输出是巨大 JSON，人根本不想读\n\nPaper-Reach 把这个过程拆成几个明确阶段：\n\n1. 高召回检索候选论文\n2. 基于摘要做保守初筛\n3. 能下载全文就下载全文\n4. 用摘要或全文做细筛\n5. 输出完整版 JSON 和人能直接看的精炼版\n\n### 它适合什么场景\n\n| 场景 | Paper-Reach 怎么做 |\n|---|---|\n| 先拉 200-300 篇候选论文 | `screen --high-recall --retrieval-limit 200` |\n| 只想看最终标题和链接 | `summarize --format titles` |\n| 希望看到完整证据和原因 | 查看 `30_result_full.json` |\n| 下载不到全文 | 自动退回摘要级细筛，不会假装已读全文 |\n| 想让 Codex / OpenClaw 直接调用 | 使用 `SKILL.md` 和 `scripts/sync.sh` |\n\n---\n\n## 快速开始\n\n安装：\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate\npip install -e .[dev]\npaper-reach doctor\n```\n\n生成示例 query：\n\n```bash\npaper-reach example-query > query.json\n```\n\n只做粗筛：\n\n```bash\npaper-reach screen \\\n  --input query.json \\\n  --output screen.json \\\n  --high-recall \\\n  --retrieval-limit 200\n```\n\n跑完整流程，并把每个阶段都输出到一个文件夹：\n\n```bash\npaper-reach run \\\n  --input query.json \\\n  --output result.json \\\n  --bundle-dir ./runs/demo \\\n  --high-recall \\\n  --retrieval-limit 200 \\\n  --workers 8\n```\n\n导出适合人工阅读的精简版：\n\n```bash\npaper-reach summarize \\\n  --input result.json \\\n  --output brief.json \\\n  --format brief \\\n  --top-k 20\n```\n\n输出目录大概长这样：\n\n```text\nruns/demo/\n├─ 00_query.json\n├─ 10_screen.json\n├─ 20_fetched_papers.json\n├─ 30_result_full.json\n├─ 40_result_brief.json\n├─ 50_result_titles.json\n├─ manifest.json\n└─ downloads/\n```\n\n> 已经安装过的话，更新通常就是：\n>\n> ```bash\n> git pull\n> pip install -e .[dev]\n> ```\n\n---\n\n## 支持平台\n\n| 平台 | 现在可用 | 配置后更强 | 怎么开启 |\n|---|---|---|---|\n| **OpenAlex** | Metadata 检索、摘要初筛 | 官方 content API PDF 下载 | 设置 `OPENALEX_API_KEY` |\n| **arXiv** | 搜索和 metadata 检索 | PDF / 本地 review | 无需额外配置 |\n| **本地 PDF / TXT / JSON** | 离线筛选与 review | 更强的本地证据提取 | 无需额外配置 |\n| **出版社落地页** | best-effort OA 回退 | 登录态 session 复用 | 提供 cookies / headers |\n| **Codex / OpenAI 风格宿主** | Skill 发现 + CLI 调用 | bundle 安装 | `bash scripts/sync.sh` |\n| **Claude 风格宿主** | Skill 发现 + CLI 调用 | bundle 安装 | `bash scripts/sync.sh` |\n| **Gemini 风格宿主** | 已提供 extension metadata | bundle 安装 | `bash scripts/sync.sh` |\n\n### 需要 Cookie 的学术平台怎么处理\n\n有些学术平台需要登录状态，或者依赖机构浏览器会话。对这类平台，最实用的方式是：\n\n**浏览器登录 -> 用 Cookie-Editor 导出 Cookie -> 发给 Agent / Paper-Reach 使用**\n\n推荐流程：\n\n- 在 Chrome 里登录目标出版社或平台\n- 用 Chrome 插件 `Cookie-Editor` 导出 Cookie\n- 把 Cookie 文件作为 `--cookie-file` 传给 Paper-Reach\n\n示例：\n\n```bash\npaper-reach fetch-fulltext \\\n  --input query.json \\\n  --output review.json \\\n  --download-dir ./downloads \\\n  --cookie-file ./cookies.json\n```\n\n这通常比自动模拟登录或反复做人机验证更简单，也更稳定。\n\nCookie 处理原则：\n\n- Cookie 留在本地\n- 核心工作流不强依赖 Cookie\n- Cookie 缺失或失效时，Paper-Reach 会自动回退\n\n详情见 [docs/browser-cookies.md](docs/browser-cookies.md)。\n\n---\n\n## 设计理念\n\nPaper-Reach 不是一个重型自治研究框架，而是一个实用的文献工作流 starter repo / scaffolding。\n\n核心设计原则：\n\n- **搜索不难，筛选更难**\n  - 真正的价值在于筛得更准，而不是源更多\n- **弱证据就该保持弱**\n  - 不能把标题相关直接说成“已确认”\n- **摘要和全文是不同证据层级**\n  - 摘要支持有用，但全文支持更强\n- **离线模式很重要**\n  - 必须能处理本地 PDF、metadata、DOI 列表\n- **JSON 优先**\n  - 输出要适合 agent 和脚本继续消费\n- **人工复核依然重要**\n  - 最终应该产出人真正能看的 shortlist\n\n### Paper-Reach 是什么\n\n- 一个给 AI Agent 复用的文献工作流\n- 一个 Python CLI\n- 一个适配多宿主的 skill bundle\n- 一个适合 literature review / gap analysis 的 starter scaffold\n\n### Paper-Reach 不是什么\n\n- 不是一个庞大的自治 multi-agent 系统\n- 不承诺每篇论文都一定能下载\n- 不是一个黑盒排序器\n\n---\n\n## 核心能力\n\n- 高召回文献检索与 query expansion\n- 保守的摘要级初筛与 explainable reasons\n- PDF 可用时的全文 review\n- OpenAlex 优先下载与自动回退\n- profile-based ranking，支持硬门槛和加权维度\n- 面向人的紧凑输出：`titles` 与 `brief`\n- 面向 agent 的结构化完整 JSON 输出\n\n## 一个具体示例\n\n下面是一个真实可用的 query：\n\n```json\n{\n  \"topic\": \"China static population exposure assessment for disasters and infectious disease\",\n  \"keywords\": [\n    \"China\",\n    \"static population\",\n    \"gridded population\",\n    \"census population\",\n    \"population exposure\",\n    \"population at risk\",\n    \"disaster exposure\",\n    \"hazard exposure\",\n    \"infectious disease exposure\",\n    \"WorldPop\",\n    \"LandScan\",\n    \"GPW\"\n  ],\n  \"inclusion_criteria\": [\n    \"study area is in China\",\n    \"uses static population data or gridded population as exposure input\",\n    \"focuses on disaster exposure or infectious-disease exposure\",\n    \"estimates exposed population or population at risk\"\n  ],\n  \"exclusion_criteria\": [\n    \"study area outside China only\",\n    \"not an exposure study\",\n    \"generic epidemiology without exposure modeling\",\n    \"dynamic mobility only without static population baseline\"\n  ],\n  \"year_range\": [2005, 2026],\n  \"max_results\": 200,\n  \"need_gap_analysis\": true,\n  \"mode\": \"auto\",\n  \"require_fulltext_for_selection\": false,\n  \"profile\": \"static_population_exposure_baseline\"\n}\n```\n\n## OpenAlex 优先下载\n\n如果配置了 `OPENALEX_API_KEY` 或 `OPENALEX_CONTENT_API_KEY`，Paper-Reach 会优先尝试 OpenAlex content API：\n\n```bash\nexport OPENALEX_API_KEY=your_key\n```\n\n下载优先级：\n\n1. OpenAlex content API\n2. open-access PDF URL\n3. 落地页提取\n4. cookie / header session 复用\n5. 回退到摘要级 review\n\n也就是说，OpenAlex API key 是增强项，不是硬依赖。\n\n## 多宿主 Skill 支持\n\nPaper-Reach 采用和成熟跨宿主 skill 项目类似的结构：\n\n- 一个共享执行引擎\n  - `paper-reach` CLI + `paper_reach/`\n- 一个宿主无关的 skill 入口\n  - `SKILL.md`\n- 几个宿主专用的轻量 manifest\n  - `agents/openai.yaml`\n  - `.claude-plugin/plugin.json`\n  - `gemini-extension.json`\n\n这样可以把核心逻辑放在一处，同时让不同 agent 宿主都能发现和调用它。\n\n## 仓库结构\n\n```text\npaper-reach/\n├─ README.md\n├─ README_EN.md\n├─ AGENTS.md\n├─ SKILL.md\n├─ docs/\n├─ examples/\n├─ skills/\n├─ agents/\n├─ .claude-plugin/\n├─ paper_reach/\n├─ scripts/\n└─ tests/\n```\n\n## 文档\n\n- [docs/install.md](docs/install.md)\n- [docs/usage.md](docs/usage.md)\n- [docs/architecture.md](docs/architecture.md)\n- [docs/agent-integration.md](docs/agent-integration.md)\n- [docs/browser-cookies.md](docs/browser-cookies.md)\n- [docs/publishing.md](docs/publishing.md)\n- [docs/roadmap.md](docs/roadmap.md)\n\n## Contributing\n\nContributions are most useful when they improve:\n\n- screening quality\n- evidence extraction\n- backend extensibility\n- offline usability\n- agent integration\n\nThe project should stay modular, conservative, and easy to extend.\n",
  "bytes": 6331,
  "sha": "74ccf785e9d2a2d418300370fa75d44169ffe7071639990bf3665bddc9c5d6b7",
  "repo_slug": "dai0-2/paper_reach",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_dai0_2_paper_reach_383d027c/readme"
}