Read Arxiv Paper

arXiv 论文阅读

触发条件

当用户给出一个 arxiv 论文 URL 并要求阅读、总结、分析时启用本 skill。

• 若用户要求 Markdown 摘要/总结，使用「默认工作流」。
• 若用户要求 中文博客 JSON / 保留图表 / 结构化输出，使用「read-paper 工作流」。

输入 URL 示例

https://arxiv.org/abs/2601.07372

默认工作流：生成 Markdown 摘要

1. 标准化 URL

• 从用户提供的 URL 中提取 arxiv_id。
• 构造 TeX 源码下载地址：

  https://arxiv.org/src/{arxiv_id}
  

• 必须获取 LaTeX 源码（.tar.gz），而不是 PDF。

2. 下载论文源码

• 缓存路径：~/.cache/nanochat/knowledge/{arxiv_id}.tar.gz。
• 如果文件已存在，跳过下载。
• 推荐调用工具脚本：

  python3 skills/read-arxiv-paper/scripts/fetch_arxiv.py {arxiv_id}
  

3. 解包

• 将源码解压到：~/.cache/nanochat/knowledge/{arxiv_id}/。
• 工具脚本会自动完成此步骤。

4. 定位入口文件

• 在解压目录中寻找入口 .tex 文件，通常是 main.tex，也可能是与论文同名的 .tex。
• 选择包含 \documentclass 的文件作为入口。

5. 阅读论文

• 读取入口文件内容。
• 递归解析 \input{...} / \include{...} / \bibliography{...} 等引用，读取相关 .tex、.bib、.sty 文件。
• 跳过二进制资源文件（.png、.jpg、.pdf、.eps 等）。
• 合并得到完整论文文本。

6. 生成总结

• 在当前项目的 ./knowledge/ 目录下创建 summary_{tag}.md。
• tag 命名规则：
  • 根据论文主题生成一个简短、有意义的英文小写标签，例如 conditional_memory、rag_fusion、moe_scaling。
  • 先检查 ./knowledge/summary_{tag}.md 是否已存在；若存在，换一个 tag 或在 tag 后加序号（如 rag_fusion_2），禁止覆盖已有文件。
• 总结内容要求：
  • 用中文撰写。
  • 包含：研究背景、核心方法、主要实验/结果、创新点、局限性。
  • 结合当前项目：如果论文与当前工作项目（例如 nanochat）的技术栈或目标相关，主动阅读项目相关代码，并在总结中明确指出论文对当前项目的启发、可落地的方向或值得尝试的实验。
  • 保留关键公式、方法名称、论文链接。

read-paper：生成中文博客 JSON

触发条件

当用户输入 arxiv URL，并明确或隐含以下任一目标时启用 read-paper 工作流：

• “生成中文博客” / “写成博客” / “转成博客”
• “输出 JSON” / “结构化数据”
• “保留图表” / “图片也要”
• 要求“摘要基础介绍、解决痛点、总结未来展望”作为博客元数据

工作流

1. 标准化 URL 并下载源码

• 从 URL 中提取 arxiv_id。
• 调用脚本下载并解压：

  python3 skills/read-arxiv-paper/scripts/fetch_arxiv.py {arxiv_id}
  

• 缓存位置：~/.cache/nanochat/knowledge/{arxiv_id}/。

2. 定位入口文件与递归阅读

• 找到含 \documentclass 的入口 .tex。
• 递归读取 \input{} / \include{} / \bibliography{}。
• 跳过二进制资源文件，但记录 \includegraphics{...} 引用的图片文件名。

3. 复制图表到测试工作区并统一转 PNG

• 调用：

  python3 skills/read-arxiv-paper/scripts/copy_figures.py {arxiv_id} test-skills/read-paper/output
  

• 支持的原始图片格式：.png、.jpg、.jpeg、.pdf、.eps。
• 脚本会自动将所有非 PNG 文件转换为 PNG，最终 assets/ 目录中只保留 .png 文件。
• 转换成功后删除原始非 PNG 文件；转换失败则记录到 resources.missing_files。
• 复制/转换后生成 test-skills/read-paper/output/figure_manifest.json。

4. 提取表格

• 调用：

  python3 skills/read-arxiv-paper/scripts/extract_tables.py {arxiv_id} test-skills/read-paper/output
  

• 输出 test-skills/read-paper/output/tables.json。

5. 生成中文博客 JSON

• 由大模型阅读完整论文文本，按下方 JSON Schema 生成结构化中文博客。
• 章节要“浓缩、缩短”，但必须保留所有图表引用；每章至少保留原文中的关键方法名、核心公式、实验结论。
• 输出文件：test-skills/read-paper/output/blog_{arxiv_id}.json。

6. 生成预览页面

• 调用：

  python3 skills/read-arxiv-paper/scripts/generate_preview.py test-skills/read-paper/output/blog_{arxiv_id}.json
  

• 输出 test-skills/read-paper/output/preview.html。

7. 报告结果

• 向用户返回 JSON 路径、assets 目录路径、图表复制数量、预览文件路径。

输出路径规范

• 测试工作区根目录：{project_root}/test-skills/read-paper/
• JSON 输出：{project_root}/test-skills/read-paper/output/blog_{arxiv_id}.json
• 图表资源：{project_root}/test-skills/read-paper/output/assets/
• 预览文件：{project_root}/test-skills/read-paper/output/preview.html
• 图表在 JSON 中的引用路径统一使用相对路径：assets/{filename}

图表处理规则

• 复制图片时会自动转换为 PNG 格式，最终 assets/ 目录中只允许存在 .png 文件。
• 输出文件名统一为 {stem}.png；若重名，追加 _1、_2 序号。
• 如果 \includegraphics 引用的文件不存在或转换失败，记录到 JSON 的 resources.missing_files。
• PNG 转换优先使用 macOS 内置 sips，其次尝试 pdftoppm 或 ImageMagick convert；转换工具不可用时需安装。
• 预览页中图片统一使用 <img> 渲染。

JSON Schema

最终输出文件：test-skills/read-paper/output/blog_{arxiv_id}.json

顶层字段

metadata 对象

chapters 数组元素

figures 数组元素

tables 数组元素

resources 对象

read-pub-paper：生成并发布中文博客

触发条件

当用户给出 arxiv URL，并明确要求“发布到网站/博客/上线/publish the blog/发布中文博客”等目标时启用 read-pub-paper 工作流。

该工作流首先完整执行 read-paper 工作流，然后再执行资源上传与远程发布。

前置条件

• read-paper 工作流已执行完毕。
• 存在 test-skills/read-paper/output/blog_{arxiv_id}.json。
• test-skills/read-paper/output/assets/ 目录中只包含 PNG 图片（由 copy_figures.py 自动保证）。

环境变量

所有环境变量仅通过当前 shell 环境读取，不得硬编码到脚本或 JSON 中。

工作流

1. 完整执行 read-paper 工作流，生成 blog_{arxiv_id}.json、PNG 资源 assets/、preview.html。
2. 读取环境变量并校验 READ_PAPER_PUBLISH_URL。
3. 上传 assets/ 下所有 PNG 文件到远程上传接口，记录每个文件的远程 URL。
4. 在 blog_{arxiv_id}.json 中为每个 chapters[].figures[] 新增 remote_url 字段，同时保留 relative_path。
5. 在 JSON 顶层新增 arxiv 对象，包含原论文网页链接与 PDF 链接：

   {
     "abs_url": "https://arxiv.org/abs/{arxiv_id}",
     "pdf_url": "https://arxiv.org/pdf/{arxiv_id}.pdf",
     "html_url": "https://arxiv.org/html/{arxiv_id}",
     "source_url": "https://arxiv.org/e-print/{arxiv_id}"
   }
   

6. 将完整 JSON POST 到 READ_PAPER_PUBLISH_URL。
7. 根据响应向用户报告发布成功或失败；失败时保留本地改写后的 JSON 并提示手动发布。

静态资源上传接口

• URL：READ_PAPER_UPLOAD_URL；未设置时从 READ_PAPER_PUBLISH_URL 派生 /upload。
• 方法：POST
• Content-Type：multipart/form-data
• 表单字段：
  • file：单个 PNG 图片文件（二进制）
  • arxiv_id：论文 ID
  • filename：原始 PNG 文件名
• 成功响应示例：

  {
    "success": true,
    "url": "https://cdn.example.com/papers/2606.32034/assets/fig1.png",
    "path": "papers/2606.32034/assets/fig1.png"
  }
  

• 失败响应示例：

  {
    "success": false,
    "error": "Unsupported file type"
  }
  

最终发布接口

• URL：READ_PAPER_PUBLISH_URL
• 方法：POST
• Content-Type：application/json
• 请求头：若 READ_PAPER_PUBLISH_TOKEN 已设置，添加 Authorization: Bearer {token}
• 请求体：在 read-paper 生成的 blog JSON 基础上，包含 arxiv 对象与每个 figure 的 remote_url。
• 成功响应示例：

  {
    "success": true,
    "publishedUrl": "https://blog.example.com/papers/2606.32034",
    "postId": "abc123"
  }
  

• 失败响应示例：

  {
    "success": false,
    "error": "Duplicate arxiv_id"
  }
  

进度与错误处理

• 单个资源上传失败：指数退避重试 3 次；任一文件最终失败即中止整个 read-pub-paper 流程，避免发布缺图的博客。
• 最终 POST 失败：重试 3 次，保存改写后的 JSON 到 test-skills/read-paper/output/blog_{arxiv_id}_published.json，提示用户手动 POST。
• 脚本执行期间输出机器可读进度：

  upload_progress=1/5 file=assets/fig1.png status=success remote=https://cdn.example.com/.../fig1.png
  ...
  publish_status=success published_url=https://blog.example.com/papers/2606.32034 post_id=abc123
  

工具脚本

• scripts/fetch_arxiv.py：下载并解压指定 arxiv_id 的 LaTeX 源码。
• scripts/copy_figures.py：复制论文图片到测试工作区并统一转换为 PNG。
• scripts/extract_tables.py：提取论文表格。
• scripts/generate_preview.py：从 JSON 生成 HTML 预览页。
• scripts/publish_blog.py：上传 PNG 资源并发布博客 JSON。

  export READ_PAPER_PUBLISH_URL=https://api.example.com/v1/papers/publish
  export READ_PAPER_PUBLISH_TOKEN=your_token
  python3 skills/read-arxiv-paper/scripts/publish_blog.py test-skills/read-paper/output/blog_2606.32034.json
  

注意事项

• 不要下载 PDF 作为阅读来源，LaTeX 源码更利于提取完整文本和公式。
• 递归读取时跳过二进制资源文件。
• 如果 arxiv 没有提供源码或源码不是 LaTeX（如只有 PDF/Word），告知用户无法处理。
• 总结文件放在 ./knowledge/（项目本地），便于用户直接打开和引用；缓存放在 ~/.cache/nanochat/knowledge/。
• read-paper 输出放在 test-skills/read-paper/output/，该目录已被 .gitignore 忽略，不会进入版本控制。
• read-pub-paper 通过环境变量 READ_PAPER_PUBLISH_URL 和可选的 READ_PAPER_UPLOAD_URL、READ_PAPER_PUBLISH_TOKEN 配置远程接口。
• READ_PAPER_PUBLISH_TOKEN 仅用于请求头，禁止写入日志、JSON 或任何可被版本控制的文件。
• 生成 JSON 前检查 blog_{arxiv_id}.json 是否已存在；若存在，先备份为 blog_{arxiv_id}_{timestamp}.json，再写入新文件。