Metadata-Version: 2.4
Name: campus-paper-fetch
Version: 0.2.0
Summary: 校园网论文全文自动搜索与下载（OA + 出版社直连 + CARSI/aTrust 机构访问兜底）
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: playwright>=1.45
Requires-Dist: pypdf>=4.0
Requires-Dist: mcp<2,>=1.2
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Dynamic: license-file

# campus-paper-fetch

校园网论文全文自动搜索与下载工具：给定 DOI / 论文链接 / 关键词，自动尝试

1. **开放获取（OA）**：OpenAlex / Unpaywall / Crossref 找合法 OA PDF（纯 API，最快）
2. **出版社直连**：校园网 IP 授权环境下，用真实 Chrome 持久会话抓出版社 PDF 路由（解决 Cloudflare 与登录态问题）
3. **Elsevier API**：配置 Key 后走官方 Article Retrieval API
4. **机构访问兜底**：校外时通过 CARSI（华侨大学）或 aTrust 零信任门户登录后复用会话

所有下载均做 `%PDF-` 文件头 + 大小 + 页数校验，HTML 登录页/验证码页不会被误存为 PDF。

## GitHub

仓库：`https://github.com/houwei302-code/campus-paper-fetch`

```bash
git clone https://github.com/houwei302-code/campus-paper-fetch.git
cd campus-paper-fetch && uv venv && uv pip install -e .
```

完整搭建过程与踩坑记录见 [docs/BUILD-NOTES.md](docs/BUILD-NOTES.md)。

## 安装

```bash
cd ~/campus-paper-fetch
uv venv
uv pip install -e .
```

## 浏览器说明（为什么用独立 profile + 推荐 cdp 模式）

Chrome 151+ 出于安全限制，禁止对默认主 profile 开启远程调试端口
（`DevTools remote debugging requires a non-default data directory`），
因此工具使用**独立的持久化 Chrome profile**（`~/.campus-paper-fetch/browser-profile/`）：

- 校园网环境：IP 即授权，无需任何登录，直接可下
- 校外环境：在该 profile 里一次性完成 CARSI 登录（`login-carsi`），会话长期保留
- 你的主 Chrome 完全不受影响，二者互不干扰

### 两种浏览器模式

| 模式 | 说明 | 结论 |
|---|---|---|
| `persistent`（默认） | Playwright `launch_persistent_context` 拉起 Chrome，带自动化标志 + STEALTH_JS 注入 | ⚠️ 自动化指纹可被 Cloudflare 识别 → 反复人机验证、cf_clearance 不落地（2026-08 实测踩坑） |
| `cdp`（**推荐**） | 附加到"真人启动"的 Chrome（`--remote-debugging-port=9222`），无自动化标志、真实指纹 | ✅ Cloudflare 基本不拦；即使弹验证，人过了就真的过 |

当前配置已切到 `cdp`（`config set browser_mode cdp`）。**cdp 模式的前置条件**：先启动带调试端口的真人 Chrome——

```bash
scripts/start-browser.sh
# 幂等：已在运行则直接提示；等待 CDP 就绪后即可用工具
```

> 从 PyPI 安装（无 `scripts/` 目录）时的等价手动命令：
> ```bash
> "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
>   --user-data-dir="$HOME/.campus-paper-fetch/browser-profile" \
>   --remote-debugging-port=9222 --no-first-run --no-default-browser-check &
> ```

> 提示：macOS 下从 DSH 沙箱里直接拉 Chrome 会因沙箱初始化失败而崩溃（`sandbox initialization failed`），
> 请从**普通终端 / Codex / CC** 运行脚本，或在 DSH 中需要更高权限。

## 首次配置

```bash
campus-paper-fetch config set email you@hqu.edu.cn
campus-paper-fetch config set output_dir ~/Downloads/campus-papers
# 可选：Elsevier API Key（dev.elsevier.com 免费申请）
campus-paper-fetch config set elsevier_api_key xxxx
# 排除出版社（默认已排除 MDPI）
campus-paper-fetch config set exclude_publishers mdpi
```

## CLI 用法

```bash
# 解析 DOI 元数据
campus-paper-fetch resolve 10.1016/j.engstruct.2023.116000

# 下载单篇 / 多篇
campus-paper-fetch download 10.1016/j.engstruct.2023.116000 10.3390/buildings13082072

# 批量（每行一个 DOI 或链接）
campus-paper-fetch batch doi_list.txt --json-lines

# 关键词搜索（OpenAlex），可选直接下载
campus-paper-fetch search "UHPC steel composite box girder flexural" --limit 10 --download

# 机构登录（校外兜底）
campus-paper-fetch login-carsi --publisher springer
campus-paper-fetch login-atrust
campus-paper-fetch status
```

## MCP

```bash
campus-paper-fetch-mcp
```

注册到 Codex：

```toml
[mcp_servers.campus-paper-fetch]
command = "uv"
args = ["run", "--project", "/Users/houwei/campus-paper-fetch", "campus-paper-fetch-mcp"]
```

## 三端接入（DSH / Codex / Claude Code）

配置与凭证（`~/.campus-paper-fetch/config.json` + 浏览器 profile）三端共享，规则一致：

- **Codex**：新会话自动注册 `mcp__campus-paper-fetch__*` 10 个工具；或说"下载这篇论文"走
  `campus-paper-fetch` skill；CLI 兜底同下。
- **Claude Code (CC)**：MCP 注册见 `~/.claude.json`；或加载 `campus-paper-fetch` skill。
- **DSH**：不加载 MCP，用 CLI / skill 形态（`uv run --project ~/campus-paper-fetch campus-paper-fetch ...`），
  能力相同。

**任何一端使用前**（cdp 模式前置）：

```bash
~/campus-paper-fetch/scripts/start-browser.sh
```

CLI 兜底四连：

```bash
cd ~/campus-paper-fetch
uv run campus-paper-fetch download 10.1016/j.engstruct.2019.109716
uv run campus-paper-fetch batch doi_list.txt
uv run campus-paper-fetch search "UHPC composite box girder" --limit 10 --download
uv run campus-paper-fetch config set email you@hqu.edu.cn
```

## 修复记录

### 2026-08-23：解决 Cloudflare 反复人机验证 + ScienceDirect 下不到 PDF

两个根因，四处改动（`git log`/`git diff` 可查）：

1. **Cloudflare 指纹识别（persistent 模式）**：Playwright 启动的 Chrome 带自动化标志 + STEALTH_JS
   注入，`cf_clearance` 与指纹不匹配 → 反复验证不跳转。→ **改用 cdp 模式**附加真人 Chrome，
   `config set browser_mode cdp`。
2. **ScienceDirect 是 React SPA**：View PDF 链接延迟渲染，`domcontentloaded` 时不在 DOM 里，
   提取为空 → 从未点击。→ `fetch_sciencedirect_pdf` 提取前 `wait_for_selector` 等链接出现（30s）。
3. `get_context` cdp 分支 `set_accept_downloads(True)`：防 attachment 型下载事件丢失。
4. 等待循环**优先跟随 PDF 标签页**（`pdf.sciencedirectassets` / `pdfft` / `viewer`），
   避免被 newtab/文章页干扰；`finally` 关闭原文章页 + PDF 查看器页；
   `batch_download` 收尾自动清理本次新开标签页（`close_idle_pages`，不影响用户手动开的标签）。

## 安全与边界

- 账号密码、MFA、验证码一律由用户本人在可见浏览器中完成，工具不保存任何凭证
- 不绕过付费墙、不接 Sci-Hub/镜像站；仅整合 OA、出版社授权、机构订阅三条合法路径
- 机构直连下载默认串行并带间隔，避免触发出版社限流/风控
- 检测到人机验证页立即停止并报告，不尝试绕过
- 独立 profile 模式下绝不关闭你的主 Chrome
- 可按出版社排除（默认排除 MDPI）
