Skip to content
Back to search

paper-guide

SkillWorks with Claude CodeGitHub

把一篇论文(PDF 或 arXiv 链接)加上它的 project 主页,做成一份单文件、可离线分享的中文交互式论文导读网页: 公式逐符号可点、关键词带超链接、逐字引用原文并链接到页码、嵌入论文原图(可放大)、点击播放官方演示视频、 重绘的系统流程图与教学交互。用户给出论文和项目主页并要求"导读 / 论文导读 / paper guide / 总结成交互网页 / 像 SimToolReal 导读那样"时使用,或用户运行 /paper-guide 时使用。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nat-j--paper-guide/badge.svg)](/listings/nat-j--paper-guide)

HTML

<a href="/listings/nat-j--paper-guide"><img src="/api/listings/nat-j--paper-guide/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

需要 Claude Code、Python 3.9 及以上、PyMuPDF。

git clone https://github.com/Nat-J/paper-guide.git ~/.claude/skills/paper-guide
pip install pymupdf

装在 `~/.claude/skills/` 下对所有项目生效;只想在某个项目里用,就克隆到该项目的 `.claude/skills/paper-guide`。

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 153 lines
  1. ---
  2. name: paper-guide
  3. description: >
  4. 把一篇论文(PDF 或 arXiv 链接)加上它的 project 主页,做成一份单文件、可离线分享的中文交互式论文导读网页:
  5. 公式逐符号可点、关键词带超链接、逐字引用原文并链接到页码、嵌入论文原图(可放大)、点击播放官方演示视频、
  6. 重绘的系统流程图与教学交互。用户给出论文和项目主页并要求"导读 / 论文导读 / paper guide / 总结成交互网页 /
  7. 像 SimToolReal 导读那样"时使用,或用户运行 /paper-guide 时使用。
  8. ---
  9. # 论文导读(paper-guide)
  10. 输入:一篇论文(本地 PDF,或 arXiv 链接)+ project 主页 URL。
  11. 输出:当前工作目录下的 `<slug>_paper_guide.html`,单文件,图片内嵌,视频按需联网加载。
  12. 设计系统、交互脚本和骨架取自一份 SimToolReal 导读范本(下文的"范本"都指它),已经抽出来放在本目录,不要从零写样式或脚本:
  13. | 文件 | 用途 |
  14. |---|---|
  15. | `assets/template.html` | 草稿骨架,含每种组件的最小写法 |
  16. | `assets/guide.css` `assets/guide.js` | 设计系统与运行时,构建时自动内联,不要改写进草稿 |
  17. | `scripts/extract.py` | 取素材:论文文本、图表裁剪、项目页媒体清单 |
  18. | `scripts/build.py` | 内联资源与图片,并做检查(含"引文是否逐字来自论文") |
  19. | `scripts/serve.py` | 预览用静态服务器 |
  20. | `reference/components.md` | 组件目录与写法规则,含 SVG 画法,写草稿前读 |
  21. ## 流程
  22. 以下 `$S` 指本 skill 目录,`work/` 是系统临时目录下新建的工作目录(不要建在用户项目里)。
  23. 1. **取素材**
  24. ```bash
  25. python3 $S/scripts/extract.py text paper.pdf -o work/
  26. python3 $S/scripts/extract.py figures paper.pdf -o work/figs --jpg
  27. python3 $S/scripts/extract.py site https://project.page/
  28. ```
  29. - 只有 arXiv 链接时先下载 PDF。记下 arXiv 编号与**版本号**,全文引用都用 `https://arxiv.org/pdf/<id>v<N>#page=<页码>`;不在 arXiv 的论文用它的公开 PDF 地址加 `#page=`。
  30. - 通读 `work/paper.txt` 全文,**包括附录**。范本里最有价值的细节(状态维数、超参数、失败分析)大多在附录。
  31. - `--jpg` 把所有图存成 JPEG(照片类图小很多),表格仍是 PNG。曲线图、柱状图用打印出来的 `rect` 重裁成 `.png`,线条才清晰。
  32. - 自动裁图是猜的:逐张打开检查,裁错的用 `extract.py page` 看整页,再用 `extract.py crop --page --rect` 手工裁。纯文字表格会标 `NO GRAPHICS FOUND`,直接转写成 HTML 表格。
  33. - `site` 只列出媒体地址和它所在的标题。每段视频展示什么,要读项目页上它旁边的正文;由页面脚本拼出来的地址逐个确认能打开。
  34. - 有官方代码仓库就克隆下来,记下当前 commit。引用代码一律用 `https://github.com/<owner>/<repo>/blob/<commit>/<path>#L<行号>`。
  35. 2. **定提纲**(写正文之前先列出来)
  36. - 章节:`00 系统概述` → `01 问题定义(含路线对比)` → 若干方法章(一章一个机制)→ 真实演示 → 实验评估 → 局限 → `方法再思考` → `原文阅读索引`。按论文实际内容增减方法章,不要硬套。
  37. - 路线对比:本文与其他方向最大的差别是哪**一个**维度;列出 2–4 条被比较的路线。
  38. - 方法再思考:读完全文后合上方法部分,只把论文的背景和目标写成两句话,从这两句话出发自己列方案,列完再对照作者的做法。与作者方案只差一个超参数或一个模块的不算替代方案。
  39. - 术语表:全文会出现的每个符号和关键术语,一项一条。
  40. - **图示清单**(和提纲同等重要,先列再写):逐章列出要画的图和要做的交互,写明每一项替代了哪段文字。对照下面"图文比例"的硬指标,不够就继续加图,直到每章都达标再动笔。
  41. - 公式清单、原图放在哪一章、每段视频配哪一章。
  42. 3. **写草稿**:复制 `assets/template.html` 为 `work/guide.src.html`,按 `reference/components.md` 填写。图片写相对路径 `figs/fig2.jpg`。
  43. - 增删章节后,`section-no` 和每个小节标题的"N.M ·"前缀要跟着改,`build.py` 会检查两者是否一致。
  44. - 草稿很长时可以按章分成几个文件再拼接;最终交给 `build.py` 的是一个完整的 `guide.src.html`。
  45. 4. **构建并检查**
  46. ```bash
  47. python3 $S/scripts/build.py work/guide.src.html -o <slug>_paper_guide.html --paper work/paper.txt
  48. ```
  49. `ERROR` 必须清零;`warn` 逐条处理,确实不适用的在交付时说明。构建会打印逐章的"正文字数 / 图示 / 交互"表,比例不达标按上面"图文比例"的办法改。
  50. 想看某份现成导读的比例:`python3 $S/scripts/build.py some.html --measure`。
  51. 5. **在浏览器里实测**:把成品复制到临时预览目录,用 `scripts/serve.py <目录> 8732` 起服务(经 preview 工具启动;预览进程可能读不了 `~/Documents` 这类受系统保护的目录,所以目录要放在临时目录下)。逐项确认:点一个公式符号弹出解释卡、点流程图连线高亮、原图能放大、视频点击后才加载并能播放、目录按钮能展开、夜间配色、手机宽度不横向溢出、控制台无报错。
  52. 6. **交付**:给出文件路径;说明哪些内容没有核实、哪些 `warn` 保留及原因。
  53. ## 内容规则
  54. 这些规则是范本好读的原因,比样式更重要。
  55. **图文比例**(硬指标,`build.py` 检查;数字取自范本的实测值)
  56. 范本读起来轻松,是因为它用图和交互讲,文字只做旁白。范本全文约 9000 字可见正文、18 张重绘图、30 处图示;按这个标准:
  57. | 指标 | 要求 | 范本实测 |
  58. |---|---|---|
  59. | 可见正文字数 ÷(图示 + 交互)| ≤ 380 | 291 |
  60. | 重绘 SVG 图 | ≥ 10 张 | 18 |
  61. | 每章(阅读索引除外)| 至少 1 处图示或交互 | — |
  62. | 连续纯文字 | 不超过约 650 字就要出现图或交互 | — |
  63. | 必备组件 | 可播放流程、概念图解、滑块实验、结构板各至少 1 个 | 都有 |
  64. | 不点开就能看到的图示 | 至少占全部图示的一半;每章至少 1 处 | — |
  65. "可见正文"指不点开就看得到的段落、列表和表格文字。达标的办法是**把文字换成图**,不是删内容:
  66. - **先画后写**。每个小节先问"这段话能不能画出来"。能画的画成图,正文只留两三句旁白和一个数字例子。
  67. - 一段话在描述**过程** → 可播放流程(`flow-player`)或步骤器。
  68. - 在描述**对象、坐标系、数据长什么样** → 概念图解(`concept-gallery`)里的一张 SVG。
  69. - 在描述**模型结构** → 结构板(`arch-board`),写上真实尺寸。
  70. - 在描述**数量关系** → 滑块实验(`goal-lab`),让读者自己拖。
  71. - 在描述**多组数字** → 条形图、散点行(`dot-chart`),原始表格收进 `<details>`。
  72. - 在描述**对比** → 并排的结构示意图(`illus`),不同之处用另一种颜色。
  73. - 在描述**硬件或场景布局** → 一张布局示意(`illus`)。
  74. - 定义性的文字搬进术语卡(`variable-term`),正文里只留那个可点的词。
  75. - 论证细节、超参数、推导、实现依据收进 `<details>`。
  76. - 路线对比、方法再思考这两块最容易写成纯文字:每条对比路线、每个替代方案配一张结构对比图,每个盲点配一张"何时不成立"的示意图。
  77. - 图是用来替代解释的,不是把句子搬进图里:图内只放名称、数值和编号,解释写在图注或旁边。
  78. **读者与写法**
  79. - 读者是懂机器学习、但不熟这个子方向的中文读者。术语首次出现时加粗并当场用一句白话解释。
  80. - 每章固定节奏:导语(一两句,本章回答的一个问题)→ 图或交互 → 公式 → 代入一组具体数字 → `依据` 行。图在前,解释在后。
  81. - 正文段落不超过 3 句。写到第 4 句时,要么它该是一张图,要么它该进 `<details>` 或术语卡。
  82. - 标题用名词短语说清内容("目标序列按到达事件推进"),不用"方法""实验"这种空标题。
  83. - 概述章先讲系统做什么,再出现公式。用 3 个阶段卡和 4 个关键数字让读者 30 秒内知道全貌。
  84. **忠实于原文**
  85. - 数字、结论只能来自论文、项目页或固定版本的代码。导读自己算的汇总要标"本导读据 TABLE N 汇总"。
  86. - 三类依据始终分开标注:论文、代码(固定 commit)、导读补充(推断与类比)。论文没写的不要写成论文说的。
  87. - 每章至少一条 `依据` 行,链接到具体页码。每张表、每个关键数字都能点回原文。
  88. - **引用原文**:全篇至少 3 处 `paper-quote`,英文逐字照抄,下面给中文释义和页码链接。省略用 `…`。`build.py --paper` 会逐条核对,不是逐字的会报错。
  89. - 把容易被误读的主张单独澄清(范本:"零样本"仍需要示范、重建和人工提示)。局限章区分"论文自述"与"实验暴露但论文未强调"。
  90. - 论文标题不翻译成"官方中文名"。文末注明原图与视频版权归原作者,本页非官方翻译。
  91. **路线对比**(讲"为什么是这个方法"时必须有,`#approach-contrast`)
  92. - 先用一句话说出本文与其他方向**最大的一个差别**,只讲一个维度(范本:别的路线模仿人手动作或逐任务训练;本文只跟随工具位姿)。接着说这个选择换来什么、让出什么。
  93. - 每条被比较的路线做成一个可点开的小栏(`details.rival`):代表工作(带链接)、它怎么做、与本文的关键差别、它更合适的情形、依据。
  94. - 对手要写得公平:"它更合适的情形"不能空着,也不能写成稻草人。
  95. - 来源优先用论文的 Related Work 和基线实验。论文没比较、由导读补上的路线,在"依据"里注明"导读补充",并给出那条路线自己的论文链接。
  96. - 各方法章讲到关键设计选择时,用一句话点回这个差别("这里正是与 X 路线分开的地方"),并链接到 `#approach-contrast`。
  97. **方法再思考**(独立一章 `#rethink`,放在局限之后,全部标"导读补充")
  98. - 局限章写的是论文承认或实验暴露的问题;这一章写的是导读自己的判断,两者不要混。
  99. - `#rethink-blindspots` 可能没考虑到的地方,2–4 条。每条指向一个具体设计(哪条公式、哪个输入、哪个评测口径)默认了什么、何时不成立、论文里有什么线索、怎样验证。不写"泛化性有待提高"这类放在任何论文上都成立的话。
  100. - `#rethink-alternatives` 只看背景和目标、不看它的方法,还能怎么做,2–3 个方案。每个写清思路、可能胜出的理由、它自己的风险、最小验证实验(用哪个指标和本文比)。有已发表工作走过类似路线的给出链接;没有把握的写成"值得试",不写成"会更好"。
  101. - `#rethink-transfer` 这个方法能迁移到哪个亟待解决的目的或场景,1–2 个。写清为什么对口、可以原样搬的、必须改的、可能搬不动的。
  102. - 这一章的事实部分(数字、论文原话)照样要有页码链接;推断部分用"可能""值得验证"的口气。
  103. **公式**
  104. - 用 HTML 排版(`<sub>` `<sup>`、`.frac`),不引入 MathJax 等外部库,页面必须离线可读。
  105. - 公式里每个符号都是 `variable-term`,同一变量全文同一颜色。
  106. - `eq-label` 写明来源:"论文式 (2)"或"导读解释式"。编号是导读自己的顺序编号。
  107. - 每条公式下面有一行逐项读法,后面紧跟一个代入数字的例子。
  108. **关键词超链接**(三种,都要有)
  109. - 符号与术语 → `variable-term` 解释卡:定义、来源、下游用途、最易混淆的一点,可带原文链接。
  110. - 章节互引 → 页内链接("见 <a href="#experiments">第 4 章</a>")。
  111. - 外部来源 → 论文页码、代码行(固定 commit)、被引工作的论文或文档。
  112. **图与视频**
  113. - 概述章放一张**重绘的系统流程图**(节点、连线都可点),论文原图收在折叠块里作"对照"。
  114. - 论文原图内嵌、可点击放大。图注三件事:一句话读图结论、该看图里哪一部分、原文页码链接。
  115. - 视频只用项目页的官方地址,点击后才请求,不自动播放。每段配"看点",并说明视频没有验证什么。
  116. - YouTube / Bilibili 用 `iframe data-src`,写法见组件目录。
  117. **交互**
  118. - 全篇至少 8 处交互(切换、滑块、可播放流程、概念图解、视频切换),其中可播放流程演示方法的核心循环。
  119. - 每个交互只回答一个问题(范本:拖动平移和转角,看"中心对齐但转歪了为什么仍算误差")。
  120. - 不是真实数据的图示一律标"教学示意"。
  121. - 细节(超参数表、原始数据、推导)收进 `<details>`,正文保持可扫读。
  122. **不要做**
  123. - 不留占位文字,不编造数字,不写论文没有的结论。
  124. - 不加外部 CDN 依赖,不让图片走外链。
  125. - 不重写 `guide.css` / `guide.js` 里已有的组件;论文专用的图示样式写在草稿里那个单独的 `<style>` 块。
README.md · README · 133 lines
  1. # paper-guide
  2. 一个 [Claude Code](https://claude.com/claude-code) skill:给它一篇论文的 PDF(或 arXiv 链接)和 project 主页,它生成一份**单文件、可离线分享的中文交互式论文导读网页**。
  3. 导读以图和交互为主,文字只做旁白:
  4. - **公式逐符号可点**:每个符号弹出"定义 / 来源 / 下游用途 / 易混淆点",同一变量全文同色,公式后紧跟代入数字的例子。
  5. - **重绘的系统流程图**:节点和连线都可点,点连线高亮起止节点并说明传递的数据。
  6. - **可播放的流程动画**:一步步演示方法的核心循环,可暂停、步进、拖动进度。
  7. - **概念图解、结构板、滑块实验**:把"对象长什么样""模型内部怎么连""一个量怎样随另一个量变"画出来。
  8. - **逐字引用原文**:英文原句加中文释义,链接到论文页码;构建时逐条与论文文本比对,不是逐字的直接报错。
  9. - **论文原图与官方视频**:原图内嵌、可点击放大;视频点击后才加载,不自动播放。
  10. - **路线对比**:本文与其他方向最大的一个差别,每条被比较的路线是一个可点开的小栏。
  11. - **方法再思考**:这条路线可能没考虑到什么、只看背景和目标还能怎么做、能迁移到哪里。全章标明是导读的推断。
  12. - 日间 / 夜间配色、可拖动的悬浮目录、阅读进度、打印为 PDF。
  13. ![可播放的训练回合流程](docs/flow-player.jpg)
  14. ![方法再思考:每个盲点配一张"何时不成立"的示意图](docs/rethink.jpg)
  15. ## 安装
  16. 需要 Claude Code、Python 3.9 及以上、PyMuPDF。
  17. ```bash
  18. git clone https://github.com/Nat-J/paper-guide.git ~/.claude/skills/paper-guide
  19. ```
  20. ```bash
  21. pip install pymupdf
  22. ```
  23. 装在 `~/.claude/skills/` 下对所有项目生效;只想在某个项目里用,就克隆到该项目的 `.claude/skills/paper-guide`。
  24. ## 使用
  25. 在 Claude Code 里给出论文和主页:
  26. ```text
  27. /paper-guide @/path/to/paper.pdf https://project.page/
  28. ```
  29. 或者直接说:
  30. ```text
  31. 用 paper-guide 给这篇论文做导读:@/path/to/paper.pdf,项目主页 https://project.page/
  32. ```
  33. - 只有 arXiv 链接也可以,不必先下载 PDF。
  34. - 有官方代码仓库就一起给,导读引用代码时会固定到当时的 commit。
  35. - 想改默认做法在同一句话里说明,例如"重点讲实验部分"。
  36. 产出是当前目录下的 `<论文短名>_paper_guide.html`。正文、公式、数据、原图和交互都在这一个文件里;官方视频和外部链接需要联网。
  37. ## 它怎样工作
  38. 1. **取素材**:提取论文全文、按图注自动裁出图表、列出项目页的视频和链接。
  39. 2. **定提纲和图示清单**:先列出每章要画的图和要做的交互,再动笔。
  40. 3. **写草稿**:从 `assets/template.html` 出发,按 `reference/components.md` 的组件写。
  41. 4. **构建并检查**:内联样式、脚本和图片成单文件,同时跑下面的检查。
  42. 5. **浏览器实测**:解释卡、流程图、动画、视频、暗色、窄屏逐项确认。
  43. ### 构建时的检查
  44. `scripts/build.py` 把这些当作错误,不清零不算完成:
  45. | 检查 | 要求 |
  46. |---|---|
  47. | 引文 | 每条原文引用逐字出现在论文文本里 |
  48. | 图文比例 | 不点开可见的正文字数 ÷(图示 + 交互)≤ 380 |
  49. | 重绘图 | 至少 10 张 SVG |
  50. | 每章 | 至少一处不点开就能看到的图示或交互(阅读索引除外) |
  51. | 可见性 | 至少一半图示不点开可见 |
  52. | 必备组件 | 可播放流程、概念图解、滑块实验、结构板各至少一个 |
  53. | 路线对比 | 至少 2 条可点开的对比路线 |
  54. | 方法再思考 | 盲点、替代方案、迁移三节齐全 |
  55. | 链接与词条 | 页内链接、标签页、术语词条、流程图连线都能对上 |
  56. | 媒体 | 视频必须按需加载,图片必须有替代文字 |
  57. 比例的阈值来自范本导读的实测值(每处图示约对应 291 字正文)。
  58. ## 目录
  59. | 文件 | 用途 |
  60. |---|---|
  61. | `SKILL.md` | skill 入口:流程与内容规则 |
  62. | `reference/components.md` | 组件目录、SVG 画法 |
  63. | `assets/template.html` | 草稿骨架,含每种组件的最小写法 |
  64. | `assets/guide.css`、`assets/guide.js` | 设计系统与运行时,构建时自动内联 |
  65. | `scripts/extract.py` | 取论文文本、裁图表、列项目页媒体 |
  66. | `scripts/build.py` | 构建单文件并检查 |
  67. | `scripts/serve.py` | 预览用静态服务器 |
  68. ## 脚本也可以单独用
  69. ```bash
  70. python3 scripts/extract.py text paper.pdf -o work/
  71. ```
  72. ```bash
  73. python3 scripts/extract.py figures paper.pdf -o work/figs --jpg
  74. ```
  75. ```bash
  76. python3 scripts/extract.py site https://project.page/
  77. ```
  78. ```bash
  79. python3 scripts/build.py work/guide.src.html -o paper_guide.html --paper work/paper.txt
  80. ```
  81. 查看任意一份已生成导读的图文比例:
  82. ```bash
  83. python3 scripts/build.py paper_guide.html --measure
  84. ```
  85. ## 已知限制
  86. - 只在一篇论文(SimToolReal,arXiv 2602.16863)上完整跑过。
  87. - 生成一份导读耗时较长,那次用了一小时以上。
  88. - 自动裁图按图注位置猜测,需要逐张检查;纯文字表格要手工转写。
  89. - 导读默认是中文,面向懂机器学习但不熟该子方向的读者。
  90. - 手机宽度下部分图内标注偏小。
  91. - "方法再思考"一章是模型的推断,没有实验支撑,读的时候请当作讨论提纲。
  92. ## 许可证
  93. [MIT](LICENSE)。许可证只覆盖本仓库的代码和文档;用它生成的导读里嵌入的论文原图与视频不在其内。
  94. ## 来源
  95. 页面样式和一部分交互脚本提取自一份 SimToolReal 论文导读网页,并在此基础上扩展。导读中嵌入的论文原图与视频版权归各论文作者所有。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.