README.md

metadata

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 创建两个私有仓库：

   python scripts/provision_hf.py --namespace YOUR_USERNAME
   

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

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

   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 后可模拟一个已登录成员：

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：

cd frontend
npm ci
npm run dev

运行验证：

.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 论文仍保留在表内，并显示原因。
• 筛选与排序：可按上传者、载体分类、时序分类、功能分类筛选，并按上传/修改时间正反序排序。
• 协同标注：任意登录成员都可新增、重命名、归档/恢复标签，也可多选分类和编辑备注。归档标签保留在历史论文上，但不能重新选择。
• 成员颜色：首次上传论文的成员会分配一种稳定的浅色，整行以该颜色显示。

数据布局

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