Hugging Face 论文发布实战指南用 huggingface-paper-publisher 从 arXiv 索引到模型卡片引用的完整工作流【免费下载链接】skillsGive your agents the power of the Hugging Face ecosystem项目地址: https://gitcode.com/GitHub_Trending/skills7/skills导读本文围绕huggingface-paper-publisher这一 Skill 展开系统讲解如何在 Hugging Face Hub 上完成研究论文的完整生命周期管理从 arXiv 索引论文、把论文关联到模型/数据集/Space 仓库、声明与验证作者身份、管理论文在个人主页的可见性到基于四套 Markdown 模板生成专业的科研文章并转换为 HTML。读完本文你将掌握paper_manager.py的全部 CLI 命令与底层实现原理能够把论文写作 — arXiv 提交 — Hub 索引 — 仓库链接 — 引用管理这条链路一键落地。一、Skill 概览一个命令行驱动的论文发布工作台huggingface-paper-publisher是专为 AI 工程师与研究者设计的论文发布与管理工作台其核心实现是 scripts/paper_manager.py一个约 600 行、基于 argparse 的单文件 Python CLI。Skill 元信息名称与描述位于 SKILL.md 的 YAML frontmatter 中当前版本 1.0.0。它与 Hugging Face 生态的集成点可归纳为四条主线Paper Pages 论文页面Hub 上的论文索引与发现入口每条论文对应https://huggingface.co/papers/{arxiv-id}arXiv 集成通过 arXiv ID 自动索引论文并从 arXiv API 拉取标题、作者、摘要等元数据模型/数据集链接通过 README 中的 YAML 元数据把论文关联到相关仓库Hub 会自动生成arxiv:PAPER_ID标签作者身份验证认领并验证论文作者身份控制论文在个人资料页的展示。这套工具链的价值在于它把在 Hub 上建立论文可发现性这一环节变成了几条命令让论文、模型、数据集、Space 之间形成可双向跳转的引用网络而不是散落在各 README 里的孤立链接。二、环境准备与依赖管理2.1 运行前提使用uv run执行脚本。脚本头部通过PEP 723 内联依赖声明了运行环境见 paper_manager.pyuv会自动解析并创建隔离环境无需手动pip install需要 Python 3.10必须设置HF_TOKEN环境变量且为具备仓库写权限的 token用于link等写操作check、index、info等只读操作在无 token 时也可运行但脚本会给出警告。2.2 依赖清单PEP 723 头部与 SKILL.md 声明了如下依赖最低版本见 SKILL.md依赖版本要求用途huggingface_hub 0.26.0HfApi、hf_hub_download、get_token与 Hub 交互的核心pyyaml 6.0.3YAML frontmatter 解析与生成requests 2.32.5访问 Hub Paper Pages 与 arXiv APImarkdown 3.5.0Markdown 转 HTMLpython-dotenv 1.2.1加载.env文件中的HF_TOKEN需要特别说明的是源码头部paper_manager.py实际只声明了前四项markdown出现在 SKILL.md 的依赖清单中当前脚本版本尚未在导入层使用它——从源码结构看它服务于未来convert命令的 Markdown 渲染能力。2.3 Token 配置方式# 方式一环境变量 export HF_TOKENyour_token # 方式二.env 文件脚本启动时通过 load_dotenv() 自动加载 echo HF_TOKENyour_token .env脚本的 token 解析优先级为构造参数hf_token 环境变量HF_TOKENget_token()即huggingface_hub缓存的登录凭证见 paper_manager.py。2.4 路径约定所有相对路径均相对于SKILL.md所在目录即skills/huggingface-paper-publisher/。运行任何脚本前先cd到该目录或使用完整路径。三、五类核心操作全解paper_manager.py通过子命令组织功能先运行uv run scripts/paper_manager.py --help可查看全部命令每个子命令也支持独立的--help。3.1 方法一从 arXiv 索引论文index / check把一篇 arXiv 论文加入 Hub 的 Paper Pages# 索引论文 uv run scripts/paper_manager.py index \ --arxiv-id 2301.12345 # 检查论文是否已索引 uv run scripts/paper_manager.py check \ --arxiv-id 2301.12345从源码看index命令的逻辑很直白index_paper它向https://huggingface.co/papers/{arxiv-id}发送 GET 请求——若返回 200说明论文已被索引直接返回status: exists否则提示访问该 URL 以触发首次索引。也就是说索引动作本质上是访问即索引直接打开https://huggingface.co/papers/{arxiv-id}也能完成索引这正是 SKILL.md 中Direct URL Access方案的原理。check命令check_paper返回更结构化的结果{ exists: true, url: https://huggingface.co/papers/2301.12345, arxiv_id: 2301.12345, arxiv_url: https://arxiv.org/abs/2301.12345 }3.2 方法二把论文链接到模型/数据集/Spacelink为模型或数据集 README 添加论文引用这是本 Skill 使用频率最高的操作。添加到模型卡片uv run scripts/paper_manager.py link \ --repo-id username/model-name \ --repo-type model \ --arxiv-id 2301.12345添加到数据集卡片uv run scripts/paper_manager.py link \ --repo-id username/dataset-name \ --repo-type dataset \ --arxiv-id 2301.12345一次关联多篇论文--arxiv-ids逗号分隔源码中会逐条拆分后循环调用link_paper_to_repo见 main 的 link 分支uv run scripts/paper_manager.py link \ --repo-id username/model-name \ --repo-type model \ --arxiv-ids 2301.12345,2302.67890,2303.11111携带自定义引用文本uv run scripts/paper_manager.py link \ --repo-id username/model-name \ --repo-type model \ --arxiv-id 2301.12345 \ --citation $(cat citation.txt)链接的底层原理链接如何生效link_paper_to_repo源码 L119-L195的执行链路为通过hf_hub_download下载目标仓库的README.md调用_add_paper_to_readme解析/创建 YAML frontmatter并在其中插入论文引用区块通过api.upload_file以提交信息Add paper reference: arXiv:{arxiv_id}上传更新后的 README。_add_paper_to_readme源码 L197-L253的行为值得展开用正则^---\s*\n(.*?)\n---\s*\n检测 README 是否已有 YAML frontmatter若已存在且正文中已含该 arXiv ID则幂等返回不重复插入若没有 frontmatter会先补一个最小化的---\n---块新内容被包裹在!-- paper-manager:start --与!-- paper-manager:end --边界标记之间包含指向 arXiv 与 Hub Paper Pages 的双向链接以及可选的 BibTeX 引用块——这意味着后续脚本升级可以靠边界标记安全地识别并替换旧区块同时保留 README 其余内容。Hub 侧的效果链条来自 SKILL.md 的官方说明Hub 从链接中提取 arXiv ID自动为仓库打上arxiv:PAPER_ID标签用户点击标签即可跳转至 Paper PagePaper Page 反向展示所有引用该论文的模型/数据集论文可通过过滤与搜索被发现。3.3 方法三声明作者身份claim / check-authorship在 Hub 上验证并认领论文作者身份# 发起认领 uv run scripts/paper_manager.py claim \ --arxiv-id 2301.12345 \ --email your.emailinstitution.edu手动认领流程打开论文页面https://huggingface.co/papers/{arxiv-id}在作者列表中找到自己的名字点击名字并选择 Claim authorship等待管理团队审核验证。检查认领状态uv run scripts/paper_manager.py check-authorship \ --arxiv-id 2301.12345注意当前 CLI 定义 中claim与check-authorship尚未注册为独立子命令SKILL.md 中描述的是目标能力与推荐流程实际认领动作目前主要通过 Hub 网页端完成源码中PaperManager类的 token 获取与 arXiv 元数据拉取逻辑get_arxiv_info、generate_citation已为实现该能力铺平了道路。3.4 方法四管理论文可见性list-my-papers / toggle-visibility控制哪些已验证论文出现在你的公开主页# 列出我的论文 uv run scripts/paper_manager.py list-my-papers # 切换某篇论文的可见性 uv run scripts/paper_manager.py toggle-visibility \ --arxiv-id 2301.12345 \ --show true也可以在网页端完成进入账户设置 → Papers 分区为每篇论文切换 Show on profile。3.5 方法五创建科研文章create / convert使用现代模板生成基于 Markdown 的专业论文# 从模板创建 uv run scripts/paper_manager.py create \ --template standard \ --title Your Paper Title \ --output paper.md # 生成完整论文含作者与摘要 uv run scripts/paper_manager.py create \ --template modern \ --title Fine-Tuning Large Language Models with LoRA \ --authors Jane Doe, John Smith \ --abstract $(cat abstract.txt) \ --output paper.md # 转换为 HTML uv run scripts/paper_manager.py convert \ --input paper.md \ --output paper.html \ --style modern模板渲染的源码实现create_research_article源码 L255-L336从templates/目录加载模板文件然后用{{TITLE}}、{{AUTHORS}}、{{DATE}}、{{ABSTRACT}}四个占位符做替换。值得关注的安全设计frontmatter 与正文分开处理YAML 部分的占位符用_escape_yaml_value转义对反斜杠与双引号做转义后包在双引号中防止通过论文标题/作者名注入 YAML 结构正文部分的占位符用_sanitize_text净化源码 L467-L482剔除控制字符、折叠连续空白、把 Markdown 代码围栏中和为转义形式、把行首的---替换为\---从而阻断代码块逃逸与 YAML 文档分隔符注入日期自动取当前时间格式YYYY-MM-DD。四种模板的定位对比仓库的 templates/ 目录内置四套模板模板定位结构特点standard传统学术论文结构从 Introduction 到 Appendix 的八节标准结构含 Motivation/Contributions/方法论/实验/消融/讨论/结论内置结果表与超参数附录modern类 Distill 的网页友好格式自带style内联 CSS 与div布局header、abstract、key-insight、figure、experiment-details 等支持动态目录、代码高亮、交互图表、LaTeX 公式、作者单位链接arxivarXiv 期刊风格罗马数字编号章节I-VI、LaTeX 数学公式损失函数、层激活、复杂度分析、算法伪代码框、IEEE 风格三线表与参考文献编号 [1]-[6]ml-report机器学习实验报告面向实验复现Executive Summary、目标与成功标准、数据质量/分布、训练超参数表、统计显著性、错误分析、鲁棒性、部署考量、后续计划模板均包含 YAML frontmatter 骨架title、authors、date、arxiv、tagsmodern 模板额外带layout: modern字段。四、Commands Reference全命令速查# 索引论文 uv run scripts/paper_manager.py index --arxiv-id 2301.12345 # 链接到仓库 uv run scripts/paper_manager.py link \ --repo-id username/repo-name \ --repo-type model|dataset|space \ --arxiv-id 2301.12345 \ [--citation Full citation text] \ [--create-pr] # 声明作者身份 uv run scripts/paper_manager.py claim \ --arxiv-id 2301.12345 \ --email your.emailedu # 管理可见性 uv run scripts/paper_manager.py toggle-visibility \ --arxiv-id 2301.12345 \ --show true|false # 创建科研文章 uv run scripts/paper_manager.py create \ --template standard|modern|arxiv|ml-report \ --title Paper Title \ [--authors Author1, Author2] \ [--abstract Abstract text] \ [--output filename.md] # Markdown 转 HTML uv run scripts/paper_manager.py convert \ --input paper.md \ --output paper.html \ [--style modern|classic] # 检查论文状态 uv run scripts/paper_manager.py check --arxiv-id 2301.12345 # 列出我的论文 uv run scripts/paper_manager.py list-my-papers # 搜索论文 uv run scripts/paper_manager.py search --query transformer attention五、arXiv ID 规范化源码里的输入防御_clean_arxiv_id源码 L429-L454展示了这个 Skill 对用户输入的健壮性设计。它定义了两种合法 ID 模式现代格式\d{4}\.\d{4,5}(v\d)?例如2301.12345、2301.12345v2旧式格式[a-zA-Z\-]/\d{7}(v\d)?例如cs/9301111。输入清洗流程依次去除首尾空白 → 去掉arxiv:/arXiv:前缀 → 剥离https://arxiv.org/abs/或/pdf/前缀 → 去掉.pdf后缀。因此以下写法全部等价uv run scripts/paper_manager.py check --arxiv-id 2301.12345 uv run scripts/paper_manager.py check --arxiv-id arxiv:2301.12345 uv run scripts/paper_manager.py check --arxiv-id https://arxiv.org/abs/2301.12345 uv run scripts/paper_manager.py check --arxiv-id https://arxiv.org/pdf/2301.12345.pdf六、YAML 元数据格式与引用管理把论文链接到模型或数据集时README 的 YAML frontmatter 需要规范化。以下是 SKILL.md 给出的两个可直接套用的模板。模型卡片示例--- language: - en license: apache-2.0 tags: - text-generation - transformers - llm library_name: transformers --- # Model Name This model is based on the approach described in [Our Paper](https://arxiv.org/abs/2301.12345). ## Citation bibtex article{doe2023paper, title{Your Paper Title}, author{Doe, Jane and Smith, John}, journal{arXiv preprint arXiv:2301.12345}, year{2023} }**数据集卡片示例** yaml --- language: - en license: cc-by-4.0 task_categories: - text-generation - question-answering size_categories: - 10Kn100K --- # Dataset Name Dataset introduced in [Our Paper](https://arxiv.org/abs/2301.12345). For more details, see the [paper page](https://huggingface.co/papers/2301.12345).Hub 会自动从这些链接中提取 arXiv ID 并创建arxiv:2301.12345标签。引用生成命令generate_citation会先调 arXiv API 拉取真实标题与作者再组装 BibTeX年份从 ID 前缀推断如2301→2023源码见 L382-L427# 生成 BibTeX 引用 uv run scripts/paper_manager.py citation \ --arxiv-id 2301.12345 \ --format bibtex输出示例article{arxiv2301_12345, title{Efficient Fine-Tuning of Large Language Models}, author{Doe, Jane and Smith, John}, journal{arXiv preprint arXiv:2301.12345}, year{2023} }七、端到端集成示例三种典型工作流工作流 1发布全新研究# 1. 创建科研文章 uv run scripts/paper_manager.py create \ --template modern \ --title Novel Fine-Tuning Approach \ --output paper.md # 2. 编辑 paper.md 补充内容 # 3. 提交到 arXiv外部流程拿到 arXiv ID # 4. 在 Hugging Face 索引 uv run scripts/paper_manager.py index --arxiv-id 2301.12345 # 5. 链接到你的模型 uv run scripts/paper_manager.py link \ --repo-id your-username/your-model \ --repo-type model \ --arxiv-id 2301.12345 # 6. 声明作者身份 uv run scripts/paper_manager.py claim \ --arxiv-id 2301.12345 \ --email your.emailedu工作流 2链接已有论文# 1. 检查论文是否存在 uv run scripts/paper_manager.py check --arxiv-id 2301.12345 # 2. 不存在则索引 uv run scripts/paper_manager.py index --arxiv-id 2301.12345 # 3. 链接到多个仓库模型、数据集、Space uv run scripts/paper_manager.py link \ --repo-id username/model-v1 \ --repo-type model \ --arxiv-id 2301.12345 uv run scripts/paper_manager.py link \ --repo-id username/training-data \ --repo-type dataset \ --arxiv-id 2301.12345 uv run scripts/paper_manager.py link \ --repo-id username/demo-space \ --repo-type space \ --arxiv-id 2301.12345工作流 3为模型更新论文引用# 1. 下载当前 README hf download username/model-name README.md # 2. 添加论文链接脚本会自动完成其余工作 uv run scripts/paper_manager.py link \ --repo-id username/model-name \ --repo-type model \ --arxiv-id 2301.12345 \ --citation Full citation for the paper # 脚本会 # - 缺失时补全 YAML 元数据 # - 在 README 中插入 arXiv 链接 # - 添加格式化引用 # - 保留已有内容常见组合模式# 模式 1新论文发布写 → 发 → 索引 → 链接 uv run scripts/paper_manager.py create --template modern --output paper.md # (提交到 arXiv) uv run scripts/paper_manager.py index --arxiv-id 2301.12345 uv run scripts/paper_manager.py link --repo-id user/model --arxiv-id 2301.12345 # 模式 2已有论文发现搜索 → 检查 → 链接 uv run scripts/paper_manager.py search --query transformers uv run scripts/paper_manager.py check --arxiv-id 2301.12345 uv run scripts/paper_manager.py link --repo-id user/model --arxiv-id 2301.12345 # 模式 3作者作品集管理认领 → 验证 → 组织 uv run scripts/paper_manager.py claim --arxiv-id 2301.12345 uv run scripts/paper_manager.py list-my-papers uv run scripts/paper_manager.py toggle-visibility --arxiv-id 2301.12345 --show true八、高级用法批量链接多篇论文for arxiv_id in 2301.12345 2302.67890 2303.11111; do uv run scripts/paper_manager.py link \ --repo-id username/model-name \ --repo-type model \ --arxiv-id $arxiv_id done提取论文信息get_arxiv_info通过 arXiv export API 拉取元数据并对标题、作者、摘要统一做_sanitize_text净化源码见 L338-L380uv run scripts/paper_manager.py info \ --arxiv-id 2301.12345 \ --format json # 或 --format text生成引用uv run scripts/paper_manager.py citation \ --arxiv-id 2301.12345 \ --format bibtex # 支持 bibtex/apa/mla后两者当前返回未实现提示校验链接SKILL.md 描述的规划能力检查仓库中全部论文链接uv run scripts/paper_manager.py validate \ --repo-id username/model-name \ --repo-type model九、Python API 集成PaperManager类可直接作为 Python 库使用适合嵌入训练脚本或流水线from scripts.paper_manager import PaperManager pm PaperManager(hf_tokenyour_token) # 索引论文 pm.index_paper(2301.12345) # 链接到模型 pm.link_paper( repo_idusername/model, repo_typemodel, arxiv_id2301.12345, citationFull citation text ) # 检查状态 status pm.check_paper(2301.12345) print(status)注意源码中link_paper_to_repo是实际实现的方法名L119SKILL.md 的 API 示例写作link_paper属于文档层面的命名规划以当前仓库源码为准时应调用link_paper_to_repo。其余公开方法index_paper、check_paper、create_research_article、get_arxiv_info、generate_citation均与示例一一对应。十、错误处理与故障排查常见错误类型错误含义Paper Not FoundarXiv ID 不存在或尚未被索引Permission DeniedHF_TOKEN对目标仓库缺少写权限Invalid YAMLREADME frontmatter 元数据格式错误Authorship Failed邮箱与论文作者记录不匹配Already Claimed作者身份已被其他用户认领Rate Limiting短时间内 API 请求过多故障排查对照表问题解决方案Paper not found on Hugging Face访问hf.co/papers/{arxiv-id}触发索引Authorship claim not verified等待管理员审核或携带证明材料联系 HF 支持arXiv tag not appearing确认 README 中使用了正确的 arXiv URL 格式Cannot link to repository验证HF_TOKEN是否具备写权限Template rendering errors检查 Markdown 语法与 YAML frontmatter 格式arXiv API 报错稍等重试——arXiv 有速率限制防御式写法的脚本级保障在脚本调用层面推荐先 check 后 link的防御模式示例见 examples/example_usage.md 的 Error Handling 一节if uv run scripts/paper_manager.py check --arxiv-id 2301.12345 | grep -q exists: true; then echo Paper exists, proceeding with link... uv run scripts/paper_manager.py link --repo-id username/model --arxiv-id 2301.12345 else echo Paper doesnt exist, indexing first... uv run scripts/paper_manager.py index --arxiv-id 2301.12345 uv run scripts/paper_manager.py link --repo-id username/model --arxiv-id 2301.12345 fi十一、最佳实践论文索引arXiv 论文一经发表立即索引在模型/数据集卡片中附完整引用信息跨相关仓库使用一致的论文引用。元数据管理为所有模型/数据集卡片补充 YAML frontmatter包含正确的许可信息打上相关任务类别与领域标签。作者身份只认领你确实位列作者名单的论文使用机构邮箱便于验证及时更新论文可见性设置。仓库链接把论文链接到所有相关的模型、数据集与 Space在 README 描述中包含论文上下文添加 BibTeX 引用方便他人引用。科研文章项目内保持模板一致在论文中附代码与数据链接生成网页友好版 HTML 便于分享。十二、CI/CD 与自动化由于脚本是无状态的 CLI天然适合接入 CI/CD 流水线。examples/example_usage.md给出了 GitHub Actions 的参考配置骨架核心步骤astral-sh/setup-uv安装 uv →actions/setup-python配 3.10 → 以secrets.HF_TOKEN注入 token 后执行link。同样的模式也适用于本地定时任务或预提交钩子把模型发布时同步论文引用固化为自动步骤。十三、与 tfrere Research Template 的配合本 Skill 与 tfrere 的科研文章模板Hugging Face Space互补tfrere 模板负责写——在网页端产出美观的 Markdown 论文本 Skill 负责发——论文拿到 arXiv ID 后自动完成 Hub 索引、仓库链接、元数据管理与引用生成。典型衔接流程在 tfrere Space 中完成写作与导出 → 提交 arXiv → 用本 Skill 的indexlink建立 Hub 侧的可发现性。十四、结语与扩展方向huggingface-paper-publisher用一组简洁命令打通了论文在 Hugging Face 生态中的索引 — 关联 — 认领 — 展示 — 引用全链路配合_sanitize_text/_escape_yaml_value/_clean_arxiv_id等输入防御设计可以安全地嵌入个人工作流与自动化流水线。SKILL.md 还预告了未来版本的方向非 arXiv 论文会议/期刊支持、DOI 自动引用格式化、论文对比与版本管理、协作写作、LaTeX 工作流集成、图表自动抽取以及论文指标追踪——这些能力会随 Skill 迭代逐步落地到PaperManager类的新方法中。进一步阅读SKILL.md完整操作文档、references/quick_reference.md命令速查、examples/example_usage.md12 个实战示例与 CI/CD 配置、templates/四套论文模板、scripts/paper_manager.py全部实现源码。【免费下载链接】skillsGive your agents the power of the Hugging Face ecosystem项目地址: https://gitcode.com/GitHub_Trending/skills7/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考