| --- |
| 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 |
| ``` |
|
|
