---
title: Team Paper List
emoji: 📚
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
hf_oauth: true
disable_embedding: true
---

# Team Paper List

一个供研究团队共同维护论文清单的私有 Hugging Face Docker Space。左侧可批量导入 arXiv ID；右侧是可筛选、排序、协同编辑的论文表格。每篇导入成功的论文都会把 Papers.cool 的 Kimi 摘要写入私有 Dataset，点击论文标题即可在弹窗中阅读 Markdown 摘要。

## 架构

| 组件 | 作用 |
| --- | --- |
| 私有 Docker Space | React 界面、FastAPI API、Hugging Face OAuth 登录 |
| 私有 Dataset | `index.json`、`taxonomy.json` 和 `kimi/<arxiv-id>.md` 摘要文件 |
| Papers.cool | 通过 `https://papers.cool/arxiv/kimi?paper=<arxiv-id>` 提供 Kimi 摘要 |

Space 的浏览器端从不接触 Dataset 写 token。服务端使用 `PAPERLIST_DATA_TOKEN` 将索引、标签与摘要提交到 Dataset，并以父 revision 检测多人并发写入；冲突会自动读取最新 revision 后重试。

## 首次部署到 Hugging Face

1. 确认已登录目标 Hugging Face 账号；部署脚本也可将用户名替换为 Organization slug。
2. 使用已登录的 Hugging Face CLI/API 创建两个私有仓库：

   ```bash
   python scripts/provision_hf.py --namespace YOUR_USERNAME
   ```

   默认会创建 `YOUR_USERNAME/paper-list`（Docker Space）和 `YOUR_USERNAME/paper-list-data`（Dataset）。脚本不会上传本地文件。

3. 将这个 Git 仓库推送到新建的 Space：

   ```bash
   git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/paper-list
   git push hf feature/paper-list-space:main
   ```

4. 在 Space 的 **Settings → Variables and secrets** 中设置：

   | 名称 | 类型 | 值 |
   | --- | --- | --- |
   | `PAPERLIST_DATASET_REPO` | Variable | `YOUR_USERNAME/paper-list-data` |
   | `PAPERLIST_DATA_TOKEN` | Secret | 可写入该私有 Dataset 的最小权限 token |

   不要把 `PAPERLIST_DATA_TOKEN` 放进 Git、README 或浏览器端变量。部署后，`hf_oauth: true` 会由 Hugging Face 自动注入 OAuth 相关环境变量；应用使用 Hub 提供的 FastAPI OAuth 集成处理登录、回调与会话。

5. 等待 Docker build 完成。若要让团队成员使用私有 Space，请在 Space 的 **Settings → Repository** 中把他们加入 collaborators；Dataset 可继续只由 owner 持有，因为所有数据读写均由 Space 服务端完成。首次导入会在 Dataset 中自动创建 `index.json` 与 `taxonomy.json`。

## 本地开发

后端默认采用内存存储，便于无 token 开发。设置 `PAPERLIST_DEV_USER` 后可模拟一个已登录成员：

```bash
python -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
PAPERLIST_DEV_USER=alice .venv/bin/uvicorn app.main:app --app-dir backend --reload --port 7860
```

前端开发服务器会把 `/api` 与 `/oauth` 代理到端口 7860：

```bash
cd frontend
npm ci
npm run dev
```

运行验证：

```bash
.venv/bin/python -m pytest
cd frontend && npm test && npm run build
```

## 使用说明

- **批量导入**：左侧输入框中每行放一个 arXiv ID，支持 `arXiv:...`、arXiv URL 和带版本号的 ID。已有 Ready 摘要的论文会跳过；Missing 状态再次导入会重试。
- **摘要**：Ready 的论文标题可点击，弹窗加载 Dataset 中保存的 Kimi Markdown。Missing 论文仍保留在表内，并显示原因。
- **筛选与排序**：可按上传者、载体分类、时序分类、功能分类筛选，并按上传/修改时间正反序排序。
- **协同标注**：任意登录成员都可新增、重命名、归档/恢复标签，也可多选分类和编辑备注。归档标签保留在历史论文上，但不能重新选择。
- **成员颜色**：首次上传论文的成员会分配一种稳定的浅色，整行以该颜色显示。

## 数据布局

```text
paper-list-data/
├── index.json
├── taxonomy.json
└── kimi/
    └── 2504.12369.md
```