⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

kelip-paper-reading

skjack@skjack⭐ 355 stars· last commit 1mo ago· 0 open issues

带着用户精读一篇论文(尤其是机器人 / VLA / 世界模型 / 深度学习方向):先把 PDF、LaTeX 源码、每张图裁好的 PNG、官方代码拉到本地,再一站一站讲——① 动机 → ② 架构 → ③ 训练和损失函数 → ④ 数据(一条样本到底长什么样)→ ⑤ 输入输出信息流 → ⑥ 拿一个具体例子把信息流走一遍(对照代码),讲到哪张图就把那张图发给用户,每站讲完主动问要不要进下一站。任何「读 / 精读 / 讲讲 / 解读 / 拆解 / 带我读这篇论文」「这篇 paper 在干嘛」「帮我看看 arxiv.org/abs/…」的请求都用它——包括只丢一个 arXiv 链接或 PDF、只说「讲讲 π0」「这篇的架构 / 损失函数 / 数据是什么」「对着代码讲讲这篇」「举个例子走一遍」的时候。不用于:批量检索调研、只要一句话总结、写论文或审稿。

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐ 355 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

kelip-paper-reading

简体中文 | English

让 AI Agent 带你精读一篇论文。它不给你一段摘要了事,而是像一个已经读懂这篇的人,一站一站带你看。

丢给它一个 arXiv 链接,它先把 PDF、LaTeX 源码、每张图(自动裁好的 PNG)、官方代码 拉到本地, 然后按六站讲,讲到哪张图就把那张图发给你,每站讲完问你要不要往下走:

① 动机 → ② 架构 → ③ 训练(损失函数)→ ④ 数据(一条样本长什么样)→ ⑤ 输入输出信息流 → ⑥ 拿一个例子把信息流走一遍(对照代码)
                                                                                (可选 ⑦ 实验和这篇现在的地位)

边讲边把每一站和你问过的问题记进论文目录里的 精读笔记.md。

六站,每站讲完你能说出什么

站讲完你能说出
① 动机要解决什么问题、以前的做法卡在哪、作者押注的关键想法
② 架构总览图上每个框是什么、数据从哪进从哪出;模型一次看几帧、输出几步
③ 训练损失函数在逼模型学什么、分几个阶段、每阶段动了哪些参数
④ 数据一条训练样本长什么样:字段、形状、单位、一行真实数值,而不只是数据集名字
⑤ 信息流从输入一路跟到输出,每一步张量多大,哪些只算一次、哪些要循环
⑥ 例子用一个具体任务,对着代码把整条链按时间顺序走一遍

几条规矩(都来自真实读论文时的反馈)

  • 图要发出来。 只说「见图 3」,你是看不到的。讲之前它会先自己看一遍图,再告诉你「这张图是什么、怎么读」。
  • 公式写成不用渲染也能读的样子。 Unicode 公式 + 符号表 + 代一组小数字算一遍。
  • 没听懂就换讲法,而不是把原话说得更长:真实数字 → 缩到玩具尺寸一步步走 → 先讲「最朴素的做法为什么不行」→ 日常比喻 + 一张对照表。
  • 先基本情况,再设计细节。 谁做的、输入什么输出什么、开源没有;去掉论文的推销腔。
  • 区分来源。 论文写的、代码里看到的、它自己推测的,分开标;代码和论文对不上的地方会指出来。
  • 代码只读不跑。 克隆官方仓库是为了对照,不替你装依赖、不跑脚本。

安装

Claude Code(装成 skill,说「读一下这篇论文」就会自动用上):

git clone https://github.com/skJack/kelip-paper-reading.git ~/.claude/skills/kelip-paper-reading
pip install pymupdf

其他 AI Agent(Cursor / Codex / Copilot / 自己写的 agent):clone 到项目里,让 agent 读 SKILL.md 照着做。 仓库根目录有一份 AGENTS.md,会自动读它的 agent 不用额外配置。

依赖只有 Python 3 和 PyMuPDF。要能访问 arxiv.org 和 github.com;Hugging Face 连不上不影响。

用法

读一下这篇 https://arxiv.org/abs/2410.24164
带我精读 π0,放到 ~/papers 下面
直接讲数据:一条训练样本到底长什么样?
拿一个具体例子,对着代码把推理走一遍

第一条回复是「基本情况 + 第 ① 站」,之后每站结尾它会问要不要继续。随时可以打断提问、跳站、 让它「翻译一下引言」(原文和译文对照),或者「整理成文档」(精读笔记已经在了)。

每篇论文会得到一个这样的目录

papers/pi0-vision-language-action/
├── paper.pdf         原文
├── source/           arXiv 的 LaTeX 源码
├── paper.tex         源码拍平成一个文件(\input 展开、去注释和参考文献),公式和表格以它为准
├── paper.txt         PDF 逐页文本
├── outline.md        章节、公式在 paper.tex 里的行号,按需跳读
├── meta.json         标题、作者、日期、摘要、代码和项目页链接
├── figures/          每张图和表一个 PNG,index.md 写 caption 和正文在哪引用,_contact.png 一眼看完全部
├── code/             官方代码(浅克隆)
└── 精读笔记.md        每一站的要点、用到的图、你问过的问题

在 research-workflow 结构的项目里(当前目录有 related_work/), 论文自动放进 related_work/<slug>/,代码放进 复现/<repo>/code。论文目录里本来就有你自己整理的 figures/ 时, 自动裁的图放到 figures-auto/,不碰原来的。

让它更懂你:profile.md

cp profile.example.md profile.md

写上你的方向、已经熟的东西(讲到时一句带过)、不熟需要铺垫的、喜欢拿什么场景举例。 不写也能用:第一次走到第 ⑥ 站时它会问你想用什么场景举例,并替你记下来。profile.md 已经在 .gitignore 里,不会被提交。

只用脚本

python3 scripts/fetch_paper.py 2410.24164 --dest ~/papers/pi0             # 拉全部材料
python3 scripts/fetch_paper.py ~/papers/pi0 --code https://github.com/Physical-Intelligence/openpi   # 论文里没写代码地址时手动补
python3 scripts/extract_figures.py ~/papers/pi0                              # 重新裁所有图表
python3 scripts/crop.py ~/papers/pi0/figures/fig-03.png --grid               # 带刻度看图,找要放大的那块
python3 scripts/crop.py ~/papers/pi0/paper.pdf --page 4 0.08 0.06 0.92 0.3 -o eq.png   # 从 PDF 页面裁一块(公式、表)

输入可以是 arXiv ID / 链接(abs、pdf、alphaxiv、Hugging Face Papers 都行)、PDF 直链、本地 PDF(改过名的 arXiv PDF 能从第一页水印认出 ID,照样拉源码),或者已经下好的论文目录(只补缺的)。

已知限制

  • 裁图靠 caption 定位加版式规则:单栏、双栏、IEEE、NeurIPS / ICLR、期刊等常见模板都测过,图基本都能裁对; 表格比图差一些。裁坏的在 _contact.png 里一眼能看出来,用 crop.py 重裁就行,agent 也会在讲到之前先检查。
  • LaTeX 源码只有 arXiv 有;其他来源的 PDF 只能读抽出来的文本,公式和表格会粗糙一些。
  • 找代码看的是摘要、arXiv 备注、PDF 首页链接、Hugging Face Papers 和项目页;论文里压根没写的 (比如 π0 → openpi),要 agent 去搜,再用 --code 补上。

文件

路径是什么
SKILL.md给 agent 的带读流程:六站各讲什么、图和公式怎么处理、没听懂时怎么换讲法
AGENTS.md一页指路,给会自动读它的 agent
references/examples.md每一站讲成什么样的样例
references/notes-template.md精读笔记模板
profile.example.md用户画像模板(复制成 profile.md)
scripts/fetch_paper.py下载 PDF / LaTeX / 元数据,拍平源码,生成大纲,找官方代码并浅克隆,调用裁图
scripts/extract_figures.py按 caption 从 PDF 裁出每张图和表,写 index.md 和总览拼图
scripts/crop.py放大图的局部、从 PDF 页面裁公式或重裁坏图

相关

  • kelip-slide:把读懂的论文做成讲解用的 HTML 幻灯片
  • research-workflow:用 Agent 协作做科研的项目结构(文献、复现、实验)

License

MIT

// HOW IT'S BUILT

// FILES

13 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • SKILL.md21 KBa1ad7c81fb41upstream ↗
    ---
    name: kelip-paper-reading
    description: 带着用户精读一篇论文(尤其是机器人 / VLA / 世界模型 / 深度学习方向):先把 PDF、LaTeX 源码、每张图裁好的 PNG、官方代码拉到本地,再一站一站讲——① 动机 → ② 架构 → ③ 训练和损失函数 → ④ 数据(一条样本到底长什么样)→ ⑤ 输入输出信息流 → ⑥ 拿一个具体例子把信息流走一遍(对照代码),讲到哪张图就把那张图发给用户,每站讲完主动问要不要进下一站。任何「读 / 精读 / 讲讲 / 解读 / 拆解 / 带我读这篇论文」「这篇 paper 在干嘛」「帮我看看 arxiv.org/abs/…」的请求都用它——包括只丢一个 arXiv 链接或 PDF、只说「讲讲 π0」「这篇的架构 / 损失函数 / 数据是什么」「对着代码讲讲这篇」「举个例子走一遍」的时候。不用于:批量检索调研、只要一句话总结、写论文或审稿。
    ---
    
    # 带读论文
    
    一篇论文拆成六站,一次只讲一站,讲完问要不要往下走:
    
    ```
    ① 动机 → ② 架构 → ③ 训练 → ④ 数据 → ⑤ 输入输出信息流 → ⑥ 拿一个例子把信息流走一遍(对照代码)
                                                                       (可选 ⑦ 实验和这篇现在的地位)
    ```
    
    两条规矩贯穿全程,后面每一节都是在展开它们:
    
    - **图要发出来。** 讲到哪张图就把那张 PNG 发给用户,再对着图讲。只写「见图 3」,用户是看不到的——
      实测:讲了四张架构图,用户回过来一句「你介绍的图我都看不到啊」。
    - **用人话,配例子。** 先说它干什么、吃什么吐什么,再说细节;每个抽象的东西都配一个带具体数字的例子。
      读论文时最常听到的三句话是「没看懂」「太抽象了」「能不能举个例子走一遍」。
    
    下文 `<skill>` 指这个 SKILL.md 所在的目录。
    
    ---
    
    ## 第 0 步:拉材料(每篇一次)
    
    ```bash
    python3 <skill>/scripts/fetch_paper.py <arXiv 链接 / ID / PDF 链接 / 本地 PDF / 已有论文目录> [--dest 目录]
    ```
    
    放哪:用户说了位置就用 `--dest`;当前目录有 `related_work/`([research-workflow](https://github.com/skJack/research-workflow) 的项目结构)会自动放进去,
    代码进 `复现/<repo>/code`;都没有就放 `./papers/<slug>/`。项目自己的 AGENTS.md / CLAUDE.md 规定了位置的,照它的。
    依赖只有 Python 3 和 PyMuPDF(缺了就 `pip install pymupdf`)。重复跑是安全的,只补缺的。
    
    脚本做完的事(5–30 秒):PDF、LaTeX 源码、拍平的 `paper.tex`、逐页 `paper.txt`、`outline.md`(章节和公式的行号)、
    `meta.json`(作者 / 日期 / 摘要 / 代码和项目页链接)、`figures/`(每张图和表一个 PNG + `index.md` + 拼图 `_contact.png`)、
    官方代码浅克隆。论文目录里原本就有用户自己整理的 `figures/` 时,自动裁的图放进 `figures-auto/`、不碰原来的——
    下文写 `figures/` 的地方都按脚本输出里的实际目录来。
    
    跑完马上做两件事:
    
    1. **看 `figures/_contact.png`**(所有裁剪拼在一张图里)。标了「整页」或者裁坏的(混进正文、缺一半),在讲到它之前用 `crop.py` 修好。
    2. **没找到代码**:搜一下「<方法名> github」「<方法名> official code」(π0 的论文里就没有代码链接,代码是后来的 openpi);
       找到了就重跑一次 `fetch_paper.py <论文目录> --code <仓库地址>`,它会克隆并记进 meta.json。还是没有就照常讲,第 ⑥ 站不对照代码。
    
    代码只用来读:不跑仓库里的脚本、不装依赖,除非用户要求。为了讲清楚,自己写几行 numpy 复算一个变换、
    读仓库公开的统计量文件(如 norm_stats.json)、从 Hugging Face 上读几行公开数据集的样本,都可以。
    
    ## 第 1 步:先自己读懂,再开口
    
    用户要的是一个**已经读懂了**的人带着读,不是边翻边念。开讲前:
    
    1. 读 `meta.json`、`outline.md`、`figures/index.md`。
    2. 读正文:有 `paper.tex` 就读它(公式、表格是准的),否则读 `paper.txt`。摘要、引言、方法整节读完;
       实验和附录按 outline 挑「implementation / training details / hyperparameters / dataset」那几节。超过 40 页的长文先读到方法结束,其余到用的那一站再读。
    3. **亲眼看关键的图**:teaser、方法总览图、数据图,Read 那个 PNG。caption 只说图想表达什么,不说哪个框在左边、箭头往哪走。
    4. 有代码就扫一遍结构:README、模型 forward、loss、dataset / transform、推理入口各在哪个文件哪个函数。细读留到 ③⑤⑥。
    5. 读 `<skill>/profile.md`(用户背景、熟什么不熟什么、喜欢什么例子),没有就跳过。
       profile 里写着用户读过这篇时,基本情况后面加一句「这篇你读过,按顺序来,还是直接跳到某一站?」——重读的人多半只想看其中几站。
    6. 在论文目录里建 `精读笔记.md`(模板 `references/notes-template.md`),写好「基本情况」和「导读地图」:
       每站讲什么、用哪张图、在 paper.tex 哪几行、对应代码哪个文件。地图是给你自己用的路线,不整张贴给用户。
    
    ## 第 2 步:开场——基本情况,然后直接进第 ① 站
    
    第一条回复先给坐标,再讲内容(实测反馈:「首先介绍一下它的机构……先介绍基本情况,然后再说它的设计细节」):
    
    **基本情况**(不超过 6 行)
    - 谁做的(机构从 PDF 第一页读;有的期刊模板不印,就去 paper.tex 的 `\author` / `\affiliation` 找)、什么时候、发在哪
    - 一句话:它让模型能做什么——**输入什么 → 输出什么**
    - 开源情况:代码 / 权重 / 数据,各开没开
    - 材料放在哪(一行路径)
    - 路线一行:`① 动机(图 1)→ ② 架构(图 3)→ ③ 训练(式 1)→ ④ 数据(图 4)→ ⑤ 信息流 → ⑥ 例子走一遍(openpi 代码)`
    
    然后直接讲第 ① 站,讲完按「每一站怎么收尾」结束。
    
    ---
    
    ## 六站各讲什么
    
    开讲前把 `references/examples.md` 读一遍(一次就够,不用每站重读):里面是每站讲成什么样的样例,大多来自真实读论文时被回了一句「这下懂了」的回答,对齐的是深度和形状。
    
    ### ① 动机
    
    讲完用户能一句话说出:**要解决什么问题、以前的做法卡在哪、作者押注的关键想法**。
    
    1. 任务是什么——用具体场景说(「让机械臂从烘干机里把衣服掏出来叠好」),不要只说 generalist robot policy。
    2. 以前怎么做、卡在哪——具体到一个失败的样子(「换一台机器人就得从头采数据」)。
    3. 作者的关键想法,一句话,说成一个押注:「作者赌的是:VLM 从网上学到的常识能直接搬到动作上」。
    4. 举一个例子把问题讲实。
    5. 发 teaser 图(通常是图 1),先说这张图是什么、每块在讲什么。
    
    去掉论文的故事性和推销腔("holds tremendous promise"),直接说它干了什么——实测反馈:「有点太绕了,能不能先去除他的故事性,直接先告诉我他是咋办的」。
    
    ### ② 架构
    
    讲完用户能对着总览图指出:**每个框是什么、数据从哪进、从哪出**。
    
    1. 先发总览图,第一段只讲「这张图是什么」:分几块、怎么读(从左到右?虚线、颜色代表什么?)、哪几个框其实是同一个网络。
    2. **先交代模型的接口**,给真实数值:一次看几帧、输出几步动作、执行几步就重新算、多少 Hz。这些数在总览图上往往就画着,
       留到 ⑤ 再讲的话,用户在这一站就会卡住。
    3. 按数据流动的顺序逐个模块讲:它是什么(从哪个预训练模型来、多大、训不训)、吃什么吐什么(形状说个大概)、
       **为什么要有它**——最朴素的做法是什么,为什么不行,所以才这么设计。用户卡住的点永远是「为什么不能更简单」。
    4. 收尾一张模块表:模块 | 来源 / 初始化 | 参数量 | 训练时更新吗 | 作用。
    5. 图太密就把正在讲的那一块裁出来单独发(见「图」一节)。
    6. 用户读过的相近模型(profile.md 或同目录下其他论文的笔记里有)对比一句。
    
    这一站只讲结构。损失函数和训练流程留给 ③,信息流的细节留给 ⑤。
    
    ### ③ 训练
    
    讲完用户知道:**损失函数在逼模型学什么、分几个阶段、每阶段用什么数据、动了哪些参数**。
    
    1. 先一句人话说训练目标(「给一段加了噪声的动作,让模型预测往干净动作走的方向」)。
    2. 再给公式(写法见「公式」一节),逐个符号解释,然后代一组小数字算一遍。
    3. 为什么是这个损失、而不是更简单的那个(例:为什么不直接回归动作——同一个场景有好几种对的做法,回归会把它们平均成一个错的)。
    4. 训练流程:阶段一 → 阶段二 → …,每阶段写清数据、冻结 / 更新哪些部分、步数 / batch / 算力、关键 trick。
    5. 训练和推理不一样的地方点一句(推理要去噪 10 步、要 KV cache……),细节留给 ⑤。
    6. 有代码就给 loss 的位置(`文件:行`)和那几行,逐行说;**代码和论文对不上的地方要指出来**(时间约定反过来、多了一项正则)。
    
    ### ④ 数据
    
    讲完用户脑子里有**一条训练样本长什么样**的画面——数据集名字只是开头。
    
    1. 先讲一个时刻的样本,用一张表:字段 | 形状 | 单位 / 取值 | 一个真实的例子值。动作、本体状态、图像、指令都要有。
       动作要讲到「每一维是什么」:`[Δx, Δy, Δz, Δroll, Δpitch, Δyaw, gripper]`,再给一行真实数值。
    2. 再讲它怎么变成模型输入:归一化、tokenize、动作块怎么切(多少步、多少 Hz、几秒)、多帧怎么取、不同机器人维度不一样怎么对齐。
    3. 最后讲规模和来源:多少小时 / 条、几种机器人、几个任务、怎么采(遥操作 / 仿真 / 网络视频)、配比、有没有人工标注(标什么、谁标、怎么标)。
    4. 发数据相关的图(样例、配比饼图),说开源没有。
    
    字段和形状优先从代码的 dataset / transform / config 里读——论文常常写不全。例子值能用真的就用真的:
    数据没公开时,仓库常带公开的示例数据集和归一化统计量,读一帧出来,把每一步变换用真实数值算一遍——
    「动作其实是相对当前状态的增量」这种论文没写的事,就是这样看出来的。用了编的示意数要标「示意」。
    论文和代码都没有的,就说「没写」,不要编。
    
    ### ⑤ 输入输出信息流
    
    讲完用户能**从输入一路跟到输出,每一步知道张量长什么样**。
    
    1. 画一张文字流程图(代码块),箭头上标形状和次数:
    
       ```
       3 张图 224×224×3 ──SigLIP──▶ 3×256 个 token
       指令 "fold the shirt" ──tokenizer──▶ ~20 个 token
               └──────────▶ Gemma(前缀,只算一次,存 KV cache)──┐
       状态 q_t(14) + 带噪动作 A^τ(50×14) + τ ──▶ action expert ◀──┘ ──▶ 速度 v(50×14)
               ↑________________ A^τ ← A^τ + 0.1·v,循环 10 次 ________________│
       ```
    
    2. 分清哪些只算一次、哪些要循环、哪些结果被丢掉。
    3. 训练时和推理时的流不一样,就分两张画。
    4. 机器人 / 在线系统补上时间:控制频率、一个动作块多长、一次推理多久、执行几步再推一次。
    
    ### ⑥ 拿一个例子把信息流走一遍
    
    最重要的一站:前面每站都「懂了」,走一遍才是真的看见它怎么跑。实测里最常见的请求就是:「举一个例子,信息流走一走,配合代码」。
    
    1. **选场景**:profile.md「喜欢的场景」里有就用它。是空的,就在正式进 ⑥ 时先问一句,给两三个具体选项让用户挑:
       论文公开数据里的一条真实样本(有公开数据时首选,数字全是真的)、论文自己的 demo 任务、用户自己的研究设置
       (profile 背景里的机器人、仿真环境)、一个日常场景;答完写进 profile.md,以后不再问。
       用户在别的站插话要「举个例子」时不要反问,直接用论文自己的任务。场景要具体到一句指令:「把桌上的马克笔放进杯子里」。
    2. **缩到玩具尺寸**,让每个下标都写得出来:4 帧、32 个 token、动作 3 步 × 2 维……走完再说真实尺寸是多少(结构不变,只是数字变大)。
    3. **按时间顺序走**,每一步:现在手里有什么(具体数值 / 形状)→ 做了什么 → 变成什么。有代码就标 `文件:行` + 3–10 行关键代码,逐行说它在干嘛。
    4. 关键的那一步单独用「这一刻发生了什么,用大白话说」再讲一遍。
    5. 多轮的系统(机器人、自回归)至少走两轮:t=0 第一次调用 → t=1(状态变了、缓存里多了什么、什么被丢掉)→ 之后的稳态循环。
    6. 最后一行把整条链串起来:`采样 → 编码 → … → 动作 → 执行 → 下一轮`。
    7. 配一张简图会清楚很多:一条时间轴 + 一次调用内部的方块图,标上真实数值。代码块里的文字图就够;能出图的环境也可以画成图发出来。
    
    一次回复放不下(超过三屏)就拆开:这一轮走完 t=0,结尾问「要不要接着看第二轮和之后的循环?」。
    
    用户说「不用给我讲代码」时:照样读代码,用它保证例子是准的(token 怎么排、形状多大、哪一步丢弃),只是不贴代码——
    实测反馈:「对着代码,你不用给我讲具体代码怎么做的,但是你要看到代码之后,确切的给我举一个例子」。
    
    ### ⑦(可选)实验和地位
    
    六站讲完后提一句。用户几乎每篇都会问:效果到什么程度、跟谁比、仿真还是真机、开源没、训练和推理要多少卡、现在还有人用吗、后来谁超过了它。
    讲最关键的 2–3 个结果(数字 + 对比对象 + 一句话意义)、局限(作者承认的 + 你看出来的)、资源需求。
    「现在」的情况(后续工作、是否被超越)要去搜,并写明是哪天查的。
    
    ---
    
    ## 每一站怎么收尾
    
    最后三行左右,固定这个形状:
    
    ```
    一句话回顾:<用户能拿去复述的那句>
    下一站:② 架构——对着图 3 讲 VLM 和 action expert 怎么接在一起。继续吗?
    (或者先岔开:flow matching 想先补一下吗?)
    ```
    
    岔路最多两个,跟刚讲的内容有关。一次只讲一站;用户说「继续」「好」「下一个」就进下一站。
    
    **跳站**(「直接讲数据」):直接跳。当前这一站要用到被跳过那站的东西时,开头用两三行补上最小的必要背景
    (讲数据要先知道动作块是 50×14,就先说这一句);⑥ 可以顺路把 ⑤ 走掉。跳过之后,「下一站」推荐还没讲的站里编号最小的,
    被跳过的放进岔路,用户随时能回去。
    
    篇幅:①–⑤ 每站一屏到一屏半(800–1500 字 + 一两张图 + 一张小表),④ 内容多可以再长一点;⑥ 两三屏。宁可多一轮,也不要一次塞满。
    
    ## 用户插话的时候
    
    - **随时会被打断问问题**:先回答,不要强行拉回路线;答完最后一行提醒位置:「我们还在 ② 讲完的位置,下一站 ③ 训练,继续吗?」
    - **用户复述自己的理解**(「所以是不是……对吧」):第一句先判对错——「对」/「基本对,差在 X」/「不对」——再补那一点。
    - **「没懂」「太抽象」「太乱了」**:别把同样的话说得更长,换一种讲法,按这个顺序试:
      ① 具体例子 + 真实数字 → ② 缩到玩具尺寸一步步走 → ③ 先摆出「最朴素的做法」和它为什么不行,再说作者的设计 → ④ 日常比喻 + 一张「比喻 ↔ 论文」对照表。
      换完还不懂,请用户指出卡在哪一句,只解释那一句。
    - **卡在前置知识**(「我是强化学习小白」):停下来用三五段讲清这个概念(是什么、一个例子、在这篇里扮演什么角色),再回到原来的位置。
    - **要翻译**(「翻译一下引言」):逐段翻,原文和译文对照着放,公式照「公式」一节的写法,不加自己的解读——要翻译的人通常想先自己理解,再来问。
    - **问「这个和 X 有什么区别」**:先一句话说本质区别,再一张对照表(输入 / 输出 / 训练目标 / 数据 / 推理方式)。
    - **要「整理成文档」**:精读笔记已经在了,补齐用户问过的问题,给绝对路径。
    
    ## 图:发出来,先说是什么,再对着讲
    
    - **讲到哪张图就发哪张。** 用当前环境里能把文件直接显示给用户的工具(Claude 桌面端是 `SendUserFile`,`display: render`);
      没有这种工具就给图片的绝对路径(macOS 上用户可以 `open` 它)。
    - **讲之前自己先 Read 这张图。** 要说「左边蓝色那块」,就得真的看过。
    - **发图后的第一段讲「这张图是什么」**:几块、怎么读、颜色和虚线的意思。然后才讲机制。
    - **用位置指代**:「左边三个 ViT」「右上角的 a_t … a_{t+H}」,让用户的视线跟得上。
    - **图太密就放大**:先 `crop.py figures/fig-03.png --grid` 看刻度(小元素加 `--step 0.05`),再 `crop.py figures/fig-03.png x0 y0 x1 y1 -o figures/fig-03-右.png` 把正在讲的那块裁出来发。
      要放大的块很小时,从 `paper.pdf` 那一页裁(`--page P`)比从 PNG 裁清楚。带刻度的图只给自己定坐标用,不发给用户。
    - **一站两三张图就够**。表格也可以发图,但表里的数字从 `paper.tex` 读(PDF 抽出来的表常常错位)。
    - **图裁坏了先修再发**:`crop.py paper.pdf --page P --grid` → `crop.py paper.pdf --page P x0 y0 x1 y1 -o figures/fig-NN.png`。
    
    ## 公式:写成不用渲染也能读的样子
    
    对话界面里 LaTeX 常常渲染不出来——实测反馈:「你的公式都没渲染出来,我没法阅读」。所以:
    
    - 公式放进代码块,用 Unicode 写:`L(θ) = E ‖ v_θ(A^τ, o) − (ε − A) ‖²`。不要写 `\mathbb{E}_{p(A_t|o_t)}`。
    - 紧跟一张符号表:符号 | 是什么 | 形状 / 取值。
    - 再代一组小数字算一遍。只有符号没有数字,用户就会说「公式太多啦,又看不懂了」。
    - 原式太复杂、必须看原样时,从 PDF 上裁下来发:outline.md 找到公式所在小节 → paper.txt 里找页码 → `crop.py paper.pdf --page P ...`。
    
    ## 说话方式
    
    - 跟用户用同一种语言讲;中文讲时术语保留英文(flow matching、action chunk、KV cache),第一次出现时跟一句人话解释。不自造术语。
    - 先结论后细节,先「是什么」后「为什么」。
    - 区分三种来源并标出来:论文写的 / 代码里看到的 / 我推测的。论文没写的不要编;代码和论文不一致时两边都说。
    - 数字带出处(「图 4」「表 2」「附录 B」「`configs/pi0.py:120`」)。
    - 比喻只用日常物理场景(下棋、开车、考试抄答案),不用拟人小故事(「模型就像一个厨师……」),用完给对照表落回论文。
    
    ## 精读笔记:边讲边记
    
    论文目录里的 `精读笔记.md`(模板 `references/notes-template.md`)。目录里已有的其他笔记(比如 research-workflow 生成的 `调研笔记.md`)是另一份,不要动它。
    
    - 开讲前写好「基本情况」和「导读地图」。
    - 每讲完一站,把这一站整理进去:要点、图(相对路径 `![](figures/fig-03.png)`)、公式、例子。整理过的,不是原样粘贴回复。
    - 用户问过的问题和最后的答案记进「问答」:问过的问题本身就是最好的复习提纲,也是以后讲给别人听的骨架。
    - 每站结束时一次性追加,别为了记笔记拖慢回复。
    
    ## 用户画像
    
    `<skill>/profile.md` 记着用户的背景、熟什么不熟什么、喜欢什么样的例子(格式见 `profile.example.md`)。
    熟的东西一句带过,不熟的主动铺垫;第 ⑥ 站的场景从这里挑。用户在对话里透露了新的偏好(「别用比喻」「我不懂强化学习」),顺手更新它。
    
    ## 脚本速查
    
    脚本都在 `<skill>/scripts/`;下表的相对路径(`figures/…`、`paper.pdf`)指论文目录,在论文目录里跑或者写绝对路径。
    
    | 命令 | 干什么 |
    |---|---|
    | `fetch_paper.py <链接/ID/PDF/目录> [--dest D \| --root R] [--code URL] [--code-dir D] [--no-clone]` | 拉全部材料;重复跑只补缺的。`--root` 放到 R/<slug>/,`--code` 手动指定官方仓库 |
    | `extract_figures.py <论文目录> [--dpi 250]` | 重新裁所有图表 |
    | `crop.py <图或 paper.pdf> [--page N] [--grid [--step 0.05]] [x0 y0 x1 y1] -o 输出.png` | 放大局部 / 裁公式 / 重裁坏图(坐标是 0–1 的比例) |
    
    论文目录:`paper.pdf` · `source/` · `paper.tex` · `paper.txt` · `outline.md` · `meta.json` ·
    `figures/`(`fig-NN.png` `tab-NN.png` `index.md` `_contact.png`)· `code/`(或 `复现/<repo>/code`)· `精读笔记.md`
    
  • README.md7.4 KB5dabcb0cc6f6upstream ↗
    # kelip-paper-reading
    
    **简体中文** | [English](README.en.md)
    
    让 AI Agent 带你精读一篇论文。它不给你一段摘要了事,而是像一个已经读懂这篇的人,一站一站带你看。
    
    丢给它一个 arXiv 链接,它先把 **PDF、LaTeX 源码、每张图(自动裁好的 PNG)、官方代码** 拉到本地,
    然后按六站讲,讲到哪张图就把那张图发给你,每站讲完问你要不要往下走:
    
    ```
    ① 动机 → ② 架构 → ③ 训练(损失函数)→ ④ 数据(一条样本长什么样)→ ⑤ 输入输出信息流 → ⑥ 拿一个例子把信息流走一遍(对照代码)
                                                                                    (可选 ⑦ 实验和这篇现在的地位)
    ```
    
    边讲边把每一站和你问过的问题记进论文目录里的 `精读笔记.md`。
    
    ## 六站,每站讲完你能说出什么
    
    | 站 | 讲完你能说出 |
    |---|---|
    | ① 动机 | 要解决什么问题、以前的做法卡在哪、作者押注的关键想法 |
    | ② 架构 | 总览图上每个框是什么、数据从哪进从哪出;模型一次看几帧、输出几步 |
    | ③ 训练 | 损失函数在逼模型学什么、分几个阶段、每阶段动了哪些参数 |
    | ④ 数据 | 一条训练样本长什么样:字段、形状、单位、一行真实数值,而不只是数据集名字 |
    | ⑤ 信息流 | 从输入一路跟到输出,每一步张量多大,哪些只算一次、哪些要循环 |
    | ⑥ 例子 | 用一个具体任务,对着代码把整条链按时间顺序走一遍 |
    
    ## 几条规矩(都来自真实读论文时的反馈)
    
    - **图要发出来。** 只说「见图 3」,你是看不到的。讲之前它会先自己看一遍图,再告诉你「这张图是什么、怎么读」。
    - **公式写成不用渲染也能读的样子。** Unicode 公式 + 符号表 + 代一组小数字算一遍。
    - **没听懂就换讲法,而不是把原话说得更长**:真实数字 → 缩到玩具尺寸一步步走 → 先讲「最朴素的做法为什么不行」→ 日常比喻 + 一张对照表。
    - **先基本情况,再设计细节。** 谁做的、输入什么输出什么、开源没有;去掉论文的推销腔。
    - **区分来源。** 论文写的、代码里看到的、它自己推测的,分开标;代码和论文对不上的地方会指出来。
    - **代码只读不跑。** 克隆官方仓库是为了对照,不替你装依赖、不跑脚本。
    
    ## 安装
    
    **Claude Code**(装成 skill,说「读一下这篇论文」就会自动用上):
    
    ```bash
    git clone https://github.com/skJack/kelip-paper-reading.git ~/.claude/skills/kelip-paper-reading
    pip install pymupdf
    ```
    
    **其他 AI Agent**(Cursor / Codex / Copilot / 自己写的 agent):clone 到项目里,让 agent 读 `SKILL.md` 照着做。
    仓库根目录有一份 `AGENTS.md`,会自动读它的 agent 不用额外配置。
    
    依赖只有 Python 3 和 [PyMuPDF](https://pymupdf.readthedocs.io/)。要能访问 arxiv.org 和 github.com;Hugging Face 连不上不影响。
    
    ## 用法
    
    ```
    读一下这篇 https://arxiv.org/abs/2410.24164
    带我精读 π0,放到 ~/papers 下面
    直接讲数据:一条训练样本到底长什么样?
    拿一个具体例子,对着代码把推理走一遍
    ```
    
    第一条回复是「基本情况 + 第 ① 站」,之后每站结尾它会问要不要继续。随时可以打断提问、跳站、
    让它「翻译一下引言」(原文和译文对照),或者「整理成文档」(精读笔记已经在了)。
    
    ## 每篇论文会得到一个这样的目录
    
    ```
    papers/pi0-vision-language-action/
    ├── paper.pdf         原文
    ├── source/           arXiv 的 LaTeX 源码
    ├── paper.tex         源码拍平成一个文件(\input 展开、去注释和参考文献),公式和表格以它为准
    ├── paper.txt         PDF 逐页文本
    ├── outline.md        章节、公式在 paper.tex 里的行号,按需跳读
    ├── meta.json         标题、作者、日期、摘要、代码和项目页链接
    ├── figures/          每张图和表一个 PNG,index.md 写 caption 和正文在哪引用,_contact.png 一眼看完全部
    ├── code/             官方代码(浅克隆)
    └── 精读笔记.md        每一站的要点、用到的图、你问过的问题
    ```
    
    在 [research-workflow](https://github.com/skJack/research-workflow) 结构的项目里(当前目录有 `related_work/`),
    论文自动放进 `related_work/<slug>/`,代码放进 `复现/<repo>/code`。论文目录里本来就有你自己整理的 `figures/` 时,
    自动裁的图放到 `figures-auto/`,不碰原来的。
    
    ## 让它更懂你:profile.md
    
    ```bash
    cp profile.example.md profile.md
    ```
    
    写上你的方向、已经熟的东西(讲到时一句带过)、不熟需要铺垫的、喜欢拿什么场景举例。
    不写也能用:第一次走到第 ⑥ 站时它会问你想用什么场景举例,并替你记下来。`profile.md` 已经在 `.gitignore` 里,不会被提交。
    
    ## 只用脚本
    
    ```bash
    python3 scripts/fetch_paper.py 2410.24164 --dest ~/papers/pi0             # 拉全部材料
    python3 scripts/fetch_paper.py ~/papers/pi0 --code https://github.com/Physical-Intelligence/openpi   # 论文里没写代码地址时手动补
    python3 scripts/extract_figures.py ~/papers/pi0                              # 重新裁所有图表
    python3 scripts/crop.py ~/papers/pi0/figures/fig-03.png --grid               # 带刻度看图,找要放大的那块
    python3 scripts/crop.py ~/papers/pi0/paper.pdf --page 4 0.08 0.06 0.92 0.3 -o eq.png   # 从 PDF 页面裁一块(公式、表)
    ```
    
    输入可以是 arXiv ID / 链接(abs、pdf、alphaxiv、Hugging Face Papers 都行)、PDF 直链、本地 PDF(改过名的 arXiv PDF
    能从第一页水印认出 ID,照样拉源码),或者已经下好的论文目录(只补缺的)。
    
    ## 已知限制
    
    - **裁图**靠 caption 定位加版式规则:单栏、双栏、IEEE、NeurIPS / ICLR、期刊等常见模板都测过,图基本都能裁对;
      表格比图差一些。裁坏的在 `_contact.png` 里一眼能看出来,用 `crop.py` 重裁就行,agent 也会在讲到之前先检查。
    - **LaTeX 源码**只有 arXiv 有;其他来源的 PDF 只能读抽出来的文本,公式和表格会粗糙一些。
    - **找代码**看的是摘要、arXiv 备注、PDF 首页链接、Hugging Face Papers 和项目页;论文里压根没写的
      (比如 π0 → openpi),要 agent 去搜,再用 `--code` 补上。
    
    ## 文件
    
    | 路径 | 是什么 |
    |---|---|
    | `SKILL.md` | 给 agent 的带读流程:六站各讲什么、图和公式怎么处理、没听懂时怎么换讲法 |
    | `AGENTS.md` | 一页指路,给会自动读它的 agent |
    | `references/examples.md` | 每一站讲成什么样的样例 |
    | `references/notes-template.md` | 精读笔记模板 |
    | `profile.example.md` | 用户画像模板(复制成 `profile.md`) |
    | `scripts/fetch_paper.py` | 下载 PDF / LaTeX / 元数据,拍平源码,生成大纲,找官方代码并浅克隆,调用裁图 |
    | `scripts/extract_figures.py` | 按 caption 从 PDF 裁出每张图和表,写 `index.md` 和总览拼图 |
    | `scripts/crop.py` | 放大图的局部、从 PDF 页面裁公式或重裁坏图 |
    
    ## 相关
    
    - [kelip-slide](https://github.com/skJack/kelip-slide):把读懂的论文做成讲解用的 HTML 幻灯片
    - [research-workflow](https://github.com/skJack/research-workflow):用 Agent 协作做科研的项目结构(文献、复现、实验)
    
    ## License
    
    MIT
    
  • scripts/crop.py4.5 KB48ade234ed0cupstream ↗
    #!/usr/bin/env python3
    # -*- coding: utf-8 -*-
    """
    放大图里的一块,或者从 PDF 页面上裁一块(公式、表、自动裁坏了的图)。坐标一律是比例 0–1,左上角是 (0, 0)。
    
      python3 crop.py figures/fig-03.png --grid                          # 先看带刻度的图,找要放大的那块在哪
      python3 crop.py figures/fig-03.png 0 0 0.45 1 -o figures/fig-03-左半.png   # 讲到左边那个模块时只发这一块
      python3 crop.py paper.pdf --page 5 --grid                          # 带刻度的整页
      python3 crop.py paper.pdf --page 5 0.08 0.12 0.92 0.31 -o figures/eq-loss.png   # 页面上的公式 / 表 / 重裁的图
    
    --grid 每 0.1 画一条线并标数字(--step 0.05 更细),出来的图只用来定坐标,不要发给用户。
    要放大的是图里很小的一块时,从 paper.pdf 那一页裁比从 figures/ 里的 PNG 裁更清楚。
    """
    import argparse
    import sys
    from pathlib import Path
    
    sys.dont_write_bytecode = True  # 别在 skill 目录里留 __pycache__
    
    try:
        import fitz  # PyMuPDF
    except ImportError:
        sys.exit("需要 PyMuPDF:pip install pymupdf")
    
    
    def draw_grid_on_page(page, step=0.1):
        W, H = page.rect.width, page.rect.height
        n = round(1 / step)
        for k in range(1, n):
            f = k * step
            x, y = W * f, H * f
            major = abs(f * 10 - round(f * 10)) < 1e-6
            width, alpha = (0.5, 0.6) if major else (0.3, 0.35)
            page.draw_line((x, 0), (x, H), color=(1, 0, 0), width=width, stroke_opacity=alpha)
            page.draw_line((0, y), (W, y), color=(1, 0, 0), width=width, stroke_opacity=alpha)
            page.insert_text((x + 2, 9), f"{f:.2f}".rstrip("0").rstrip("."), fontsize=6 if not major else 7, color=(1, 0, 0))
            page.insert_text((2, y - 2), f"{f:.2f}".rstrip("0").rstrip("."), fontsize=6 if not major else 7, color=(1, 0, 0))
    
    
    def main():
        ap = argparse.ArgumentParser(description="按比例坐标裁图 / 裁 PDF 页面")
        ap.add_argument("src", help="PNG/JPG 图,或 paper.pdf")
        ap.add_argument("box", nargs="*", type=float, help="x0 y0 x1 y1(0–1);不给就是整张")
        ap.add_argument("--page", type=int, help="PDF 页码(从 1 开始)")
        ap.add_argument("--grid", action="store_true", help="叠加刻度,用来定坐标")
        ap.add_argument("--step", type=float, default=0.1, help="刻度间隔,小元素用 0.05")
        ap.add_argument("--dpi", type=int, help="PDF 渲染分辨率,默认 220(--grid 时 110)")
        ap.add_argument("-o", "--out", help="输出文件")
        a = ap.parse_intermixed_args()  # 坐标写在 --page 前后都行
    
        src = Path(a.src)
        if a.box and len(a.box) != 4:
            sys.exit("坐标要四个数:x0 y0 x1 y1")
        x0, y0, x1, y1 = a.box if a.box else (0, 0, 1, 1)
        if not (0 <= x0 < x1 <= 1 and 0 <= y0 < y1 <= 1):
            sys.exit("坐标要满足 0 ≤ x0 < x1 ≤ 1、0 ≤ y0 < y1 ≤ 1")
    
        if src.suffix.lower() == ".pdf":
            if not a.page:
                sys.exit("PDF 要给 --page")
            doc = fitz.open(str(src))
            page = doc[a.page - 1]
            if a.grid:
                draw_grid_on_page(page, a.step)
            W, H = page.rect.width, page.rect.height
            clip = fitz.Rect(x0 * W, y0 * H, x1 * W, y1 * H)
            dpi = a.dpi or (110 if a.grid else 220)
            sys.path.insert(0, str(Path(__file__).resolve().parent))
            from extract_figures import figures_dir
            fd = figures_dir(src.parent)
            default = (fd if fd.is_dir() else src.parent) / f"page-{a.page:02d}{'-grid' if a.grid else ''}.png"
            out = Path(a.out) if a.out else default
            page.get_pixmap(matrix=fitz.Matrix(dpi / 72, dpi / 72), clip=clip, alpha=False).save(str(out))
        else:
            doc = fitz.open(str(src))  # PyMuPDF 能把图片当成单页文档打开
            page = doc[0]
            W, H = page.rect.width, page.rect.height
            if a.grid:
                pdf = fitz.open()
                p2 = pdf.new_page(width=W, height=H)
                p2.insert_image(p2.rect, filename=str(src))
                draw_grid_on_page(p2, a.step)
                page = p2
            clip = fitz.Rect(x0 * W, y0 * H, x1 * W, y1 * H)
            tag = "-grid" if a.grid else "-crop"
            out = Path(a.out) if a.out else src.with_name(src.stem + tag + ".png")
            # 图片文档的页面尺寸就是像素数,按 1:1 渲染不损失清晰度;太小的块放大一点
            zoom = max(1.0, min(3.0, 900 / max(clip.width, 1)))
            page.get_pixmap(matrix=fitz.Matrix(zoom, zoom), clip=clip, alpha=False).save(str(out))
        print(out)
    
    
    if __name__ == "__main__":
        main()
    
  • scripts/extract_figures.py34 KBaccf842b3ca3upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • scripts/fetch_paper.py34 KB2ff4715fb518upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • references/examples.md18 KBfb8ec6466306upstream ↗
    # 样例:每一站讲成什么样
    
    第 1 节是照着 π0 原文写的示范,1b 节来自一次试跑,其余都节选自真实读论文时、被回了「明白了」「这下懂了」的回答。
    抄的是**形状和深度**,不是内容。每节后面写了它为什么管用。
    
    目录
    1. 开场:基本情况 + ① 动机(π0)
    1b. ② 架构:先读图、先给接口参数,再按数据流逐个模块(Diffusion Policy)
    2. ④ 数据:一条样本从小到大讲(Cosmos Policy)
    3. ⑥ 玩具尺寸 + 对着代码一步步走(V-JEPA 2)
    4. ⑥ 真实场景走多轮(DreamZero 推理)
    5. 「没看懂」之后换讲法:比喻 + 对照表(Dreamer 的两个公式)
    6. 用户复述理解时怎么回
    
    ---
    
    ## 1. 开场:基本情况 + ① 动机(π0)
    
    > **基本情况**
    > - Physical Intelligence,2024-10 挂 arXiv,RSS 2025。
    > - 一句话:给机器人看几路相机画面 + 一句指令("fold the shirt"),它直接输出接下来 50 步的连续动作,最高 50 Hz。
    > - 开源:代码和权重在 openpi(2025-02);它自己采的约 1 万小时数据没开源,混进去的 OXE 是公开的。
    > - 材料:`~/papers/pi0-vision-language-action/`(PDF、源码、14 张图、openpi 代码)
    > - 路线:① 动机(图 1)→ ② 架构(图 3)→ ③ 训练(式 1、2)→ ④ 数据(图 4)→ ⑤ 信息流 → ⑥ 叠衣服走一遍(openpi 代码)
    >
    > **① 动机**
    >
    > 〔发 figures/fig-01.png〕
    >
    > 先说这张图:最左边一列是 π 自己采的跨机器人数据(7 种机器人 + 各种任务的缩略图),顶上两个小图标是另外两路数据——
    > VLM 自带的互联网预训练、公开的 Open X-Embodiment。中间蓝框是模型本体:一根白色长条是预训练好的 VLM,
    > 右端接着一小块绿色的 action expert,三张相机画面经过 ViT 从下面进去,"fold shirt" 这句指令也从下面进。
    > 蓝框下面是后训练用的高质量数据;最右边三栏是三种用法:直接上手(zero-shot)、拿少量高质量数据专门微调去做难任务、微调学没见过的新任务。
    >
    > **要解决什么**:一个「通用」的机器人策略——同一个模型换机器人、换任务都能用,而且能干叠衣服这种又长又精细的活。
    >
    > **以前卡在哪**
    > 1. 数据:每个实验室只有自己那台机器人的几百条演示,换一台就得从头采。
    > 2. 常识:只见过机器人数据的模型不知道 shirt 是什么、杯子该从哪儿拿。
    > 3. 灵巧:之前拿 VLM 做机器人的(RT-2、OpenVLA)把动作切成离散 token 一个个往外蹦,叠衣服这种要 50 Hz 连续微调的动作跟不上。
    >
    > **作者押注的想法**:拿一个已经从网上学到常识的 VLM 当大脑,后面接一个专门出连续动作的小网络,用 flow matching 一次生成一整段 50 步的动作;
    > 再拿 7 种机器人、68 个任务、1 万小时的数据一起训。
    >
    > **举个例子**:让机器人从烘干机里掏衣服再叠好。RT-2 那种做法,每一步都要先「说出」下一个关节角的编号,说完一个才能说下一个;
    > π0 是一次「画」出接下来一秒钟整条手的轨迹,边执行边画下一段。
    >
    > 一句话回顾:π0 = 有常识的 VLM 大脑 + 一个一次画出整段连续动作的小网络,用多种机器人的大量数据一起训。
    > 下一站:② 架构——对着图 3 讲 VLM 和 action expert 怎么接在一起、各吃什么。继续吗?
    > (或者先岔开:flow matching 想先补一下吗?)
    
    为什么管用:基本情况先给坐标(谁、输入输出、开没开源);图先说「是什么」再讲;三个卡点各有一个具体的样子;
    押注一句话说得出来;收尾三行固定,用户知道下一步是什么。
    
    ---
    
    ## 1b. ② 架构:先读图、先给接口参数,再按数据流逐个模块(Diffusion Policy)
    
    试跑时写的(节选;数字出自论文表 5、表 7 和官方 Push-T 配置):
    
    > 〔发 figures/fig-02.png〕
    >
    > 先说这张图怎么读,分三块:
    > - **最左一列**:上面是输入 O_t——真机 Push-T 的两路相机画面加一叠蓝卡片(机器人位姿);下面是输出,从左到右是去噪过程:
    >   A_t^K 是撒满一片的纯噪声,蓝框里的 A_t^0 是最后那条干净轨迹。
    > - **中间 a)**:时间轴——只看最近几帧,一次预测一长段,只执行前面几步。
    > - **右边大框**:去噪网络 ε_θ 的两种实现,b) CNN、c) Transformer,二选一;「×K」是说这个网络要反复调 K 次。
    >
    > **接口先说清**(Push-T 官方配置,10 Hz):每次看最近 **2 帧**,一次预测 **16 步**动作,只执行前 **8 步**(0.8 秒)就重新看、重新算。
    >
    > **1. 观测编码器:图 → 向量,每次推理只算一次**
    > - 每个相机一个 ResNet-18,从头训,和后面一起端到端训。改了两处:全局平均池化换成 spatial softmax(平均池化会把「T 块在画面哪儿」丢掉);
    >   BatchNorm 换成 GroupNorm(和扩散训练用的 EMA 放一起不稳)。
    > - 形状:每帧 96×96 → 64 维,加推杆位置 2 维 = 66 维;看 2 帧 → O_t = 132 维。
    > - **为什么不拿预训练模型冻住直接用?** 试过,更差:Square 任务上冻住的 ImageNet ResNet-18 是 0.58,从头训是 0.94(表 5)。
    > - **为什么观测只当条件、不跟动作一起去噪?** 一起去噪就得把未来的画面也生成出来;只生成动作,ResNet 跑一次,后面 K 轮都复用同一个 O_t——这是能实时控制的前提。
    >
    > **2. 去噪网络 ε_θ**(吃「带噪动作 16×2 + O_t + 第几轮 k」,吐同样形状的噪声)…… **3. ×K 循环**(没有参数)……
    >
    > | 模块 | 来源 / 初始化 | 参数量 | 训练时更新吗 | 作用 |
    > |---|---|---|---|---|
    > | ResNet-18(每个相机一个) | 从头训;BN → GN;池化换 spatial softmax | 约 11M / 个 | 是 | 每帧图 → 64 维 |
    > | ε_θ:1D U-Net + FiLM | 从头训 | 仿真 256M / 真机 67M(表 7) | 是 | 带噪动作 → 噪声 |
    > | 去噪循环 | DDPM 100 轮 / DDIM 十几轮 | 0 | — | 噪声 → 动作序列 |
    >
    > 和 π0 比:骨架一样——观测编码一次,动作块反复去噪;π0 把 ResNet-18 换成 3B 的 VLM,去噪网络换成 300M 的 action expert,DDPM 换成 flow matching,16 步换成 50 步。
    
    为什么管用:图拆成三块先讲怎么读;接口参数在这一站就给了真实数值;模块按数据流的顺序讲,每个都回答「最朴素的办法为什么不行」,
    而且拿论文的表当证据;最后一句挂到用户已经熟的模型上。
    
    ---
    
    ## 2. ④ 数据:一条样本从小到大讲(Cosmos Policy,LIBERO)
    
    用户问:「动作块和本体状态原始是什么样的?怎么变成 16×7、112 个数的?」回答分四层:
    
    > **一个时刻的动作 a_t:7 个数。** LIBERO 用末端增量控制,20 Hz,一条指令 7 个数:
    >
    > ```
    > [ Δx, Δy, Δz,  Δroll, Δpitch, Δyaw,  gripper ]
    >    末端往哪挪(米)   末端往哪转(弧度)    −1 开 / +1 合
    > ```
    >
    > 比如 `[0.012, −0.004, 0.000, 0.00, 0.01, 0.00, −1]`:这 50 毫秒里末端沿 x 前进 1.2 厘米、沿 y 退 0.4 厘米、俯仰转 0.01 弧度,夹爪张开。
    > 控制器拿到这 7 个数,用逆运动学算出各关节怎么转——这一步不是模型的事。7 也不是固定的:ALOHA 双臂是 14 个关节角。
    >
    > **动作块 a_{t:t+K}:K 行 7 列。** LIBERO 里 K = 16,一张 16 × 7 的表:
    >
    > ```
    >           Δx      Δy      Δz     Δroll  Δpitch  Δyaw   gripper
    > 第 1 步   0.012  −0.004   0.000   0.00   0.01    0.00    −1
    > 第 2 步   0.011  −0.004   0.001   0.00   0.01    0.00    −1
    >   …
    > 第 13 步  0.000   0.000  −0.002   0.00   0.00    0.00    +1   ← 这一步开始合夹爪
    >   …
    > ```
    >
    > 读法:前几步往苹果上方挪,然后往下压,第 13 步合爪,最后提起来。16 步在 20 Hz 下是 0.8 秒。按行拉平就是 112 个数。
    >
    > **本体状态 s_t:机器人自己量到的。** 末端位置 3 个 + 姿态四元数 4 个 + 两根手指开度 2 个……
    >
    > | | 动作 | 本体状态 |
    > |---|---|---|
    > | 是什么 | 发出去的指令 | 读回来的测量 |
    > | 绝对还是相对 | LIBERO 里是增量 | 绝对量 |
    >
    > **怎么变成一个 latent 帧**:① 每维归一化到 −1~1 ② 复制填满一帧 32×32×16 个格子 ③ 覆盖掉占位帧。读回来反着做。
    
    为什么管用:从「一个时刻的一个数是什么意思」一路讲到「进模型的样子」;每层都有真实数值和单位;
    用一张对比表把最容易混的两个东西(动作 vs 状态)分开;论文没写的(尾巴怎么处理)直接说没写。
    
    另一种拿到真实数值的办法(π0 试跑时用的):自采数据没公开,就读 openpi 公开的示例数据集里一帧
    (`aloha_pen_uncap_diverse` 第 4.00 秒)和 π0 base 的归一化统计量,把「换约定 → 关节变增量 → z-score → 补到 32 维」每一步用这帧的真值算一遍。
    「动作是相对当前状态的增量」论文没写,是从统计量的均值只有 0.00–0.02 看出来的。
    
    ---
    
    ## 3. ⑥ 玩具尺寸 + 对着代码一步步走(V-JEPA 2 预训练)
    
    用户说「你讲的太乱了,能不能举一个例子,信息流走一走,配合代码」之后的回答(节选):
    
    > 只走**一个样本、一套 mask**,把尺寸缩小到能把下标全写出来。真实模型是 16 帧、2048 个 token、1408 维;例子里用 4 帧、32 个 token。
    > 代码行号都是官方仓库 facebookresearch/vjepa2 里的。
    >
    > **玩具设定**:视频 4 帧 64×64,tubelet 2×16×16 → 时间上 2 片,空间上 4×4 = 16 格,共 32 个 token,编号 `t×16 + h×4 + w`:
    >
    > ```
    > 第 0 片(t=0)           第 1 片(t=1)
    >  0  1  2  3             16 17 18 19
    >  4  5  6  7             20 21 22 23
    >  8  9 10 11             24 25 26 27
    > 12 13 14 15             28 29 30 31
    > ```
    >
    > 内容:一只猫的头在往右挪,耳朵在第 1–2 行、第 1–2 列那块。
    >
    > **第 1 步:先把 mask 采好**(`src/masks/multiseq_multiblock3d.py`)
    >
    > ```python
    > mask = torch.ones((2, 4, 4))
    > mask[0:2, 1:3, 1:3] = 0        # 被遮的置 0
    > ```
    >
    > 展平后是两个**下标列表**:`masks_pred = [5, 6, 9, 10, 21, 22, 25, 26]`(要预测的 8 个),`masks_enc` 是剩下 24 个。
    > 猫耳朵那块在两个时刻都看不见——这就是 "tube"。
    >
    > **第 2 步:老师看整段,算出标准答案**(`app/vjepa/train.py` L429–433)……输出 `[1, 32, D]`,抠出 8 个 → 目标 `[1, 8, D]`。
    >
    > **第 3 步:学生只看 24 个**……`apply_masks` 就是 `torch.gather`:**把 8 个被遮的 token 从序列里删掉**,长度 32 → 24,不是填零。
    >
    > **第 4 步:预测器——z 登场**(`src/models/predictor.py` L186–226)
    >
    > ```python
    > pred_tokens = self.mask_tokens[mask_index]                 # 一个 [1, 1, 384] 的可学习向量 ← 图上的 z
    > pred_tokens = pred_tokens.repeat(B, self.num_patches, 1)   # 复制 32 份
    > pred_tokens = apply_masks(pred_tokens, masks_y)            # 只留 8 个 → [1, 8, 384]
    > ```
    >
    > 注意:**这 8 个向量完全一样**。它们不知道自己是 5 号还是 26 号,也不知道猫耳朵长什么样——只是 8 张「请在此处作答」的空白答题卡。
    > ……(第 5–7 步:L1 损失、梯度只回学生、老师做 EMA)
    >
    > **串成一句话**
    >
    > ```
    > 采下标 → 老师看全部 32 个算出 8 个答案(无梯度)
    >        → 学生只看 24 个 → 预测器拿 24 个表征 + 8 张空白答题卡,排回原位,双向注意力填答案
    >        → 8 个预测 vs 8 个答案 做 L1 → 梯度只更新学生和预测器 → 老师慢慢跟上
    > ```
    >
    > 真实规模只是把数字换掉:32 → 2048 个 token,结构一模一样。
    
    为什么管用:尺寸小到每个下标都写得出来;每一步都有「代码位置 + 几行代码 + 形状变化」;
    关键的那个反直觉点(8 个向量完全一样)单独点破;最后一句话串起来,再说明真实规模只是换数字。
    
    ---
    
    ## 4. ⑥ 真实场景走多轮(DreamZero 推理)
    
    用户问:「可以用一个真实的例子讲一下它 inference 一遍都怎么做的吗?用一个流程化的真实的例子,直观的说一下。」(节选)
    
    > 用开源仓库实际能跑的 setup:DROID 平台,一台 Franka + 夹爪,三个相机。**场景**:桌上有一支马克笔和一个杯子,指令 `"put the marker in the cup"`。
    >
    > **先建立一个直觉:硬件和模型是解耦的。**
    >
    > ```
    > 机器人控制器:  15 Hz 连续执行动作 ─────────────────────────────▶ 时间
    > 模型:          每 1.6 秒醒来一次,花 ~0.6 s 算出下一段 1.6 秒的动作
    > ```
    >
    > **t = 0:第一次调用**
    > ① 服务端收到什么:
    >
    > ```python
    > obs = {
    >     "observation/exterior_image_0_left": ndarray(H, W, 3),   # 第三人称相机 1
    >     "observation/wrist_image_left":      ndarray(H, W, 3),   # 腕部相机
    >     "observation/joint_position":        ndarray(7,),        # 七个关节角
    >     "observation/gripper_position":      ndarray(1,),
    >     "prompt": "put the marker in the cup",
    > }
    > ```
    >
    > ② 编码 → ③ prefill(只写缓存,不预测)→ ④ 从两团纯噪声联合去噪 16 步 → ⑤ 输出 `(24, 8)` 的动作发回机器人。
    >
    > **t = 1:1.6 秒后。** 相机拍到:手臂到了马克笔附近,但**偏右了 2 厘米**(模型想象的是精准对准)。
    >
    > ```python
    > if self.current_start_frame != 1:
    >     current_ref_latents = image[:, -K:]      # 取最新的真实帧
    >     self._run_diffusion_steps(noisy_input=current_ref_latents, timestep=timestep * 0,
    >                               action=None, state=None, update_kv_cache=True)
    > ```
    >
    > **这一刻发生了什么,用大白话说:** 模型上一轮想象的是「手精准对准马克笔」,现实是「手偏右 2 厘米」。
    > 这一步把**现实**写进了记忆,想象的那几帧**从来没进过记忆**。所以下一轮它基于「偏右 2 厘米」这个事实规划修正动作。
    >
    > | 轮次 | KV cache 里有什么 | 想象的帧去哪了 |
    > |---|---|---|
    > | t=0 | 首帧(真) | 丢 |
    > | t=1 | 首帧 + 真实帧 1 | 丢 |
    > | … | **永远只有真实画面** | **永远丢** |
    
    为什么管用:一句具体指令当场景;先给时间轴直觉;每一轮写清「收到什么 → 做了什么 → 输出什么」;
    关键分叉处贴那几行代码再用大白话重说;一张表把「缓存里有什么」随时间的变化摆出来。
    
    ---
    
    ## 5. 「没看懂」之后换讲法:比喻 + 对照表(Dreamer 的公式 3、4)
    
    用户说「太抽象了,看不懂,能不能简单地解释一下」之后(节选):
    
    > 不是你的问题,是这两个公式把两个很日常的想法包在符号里了。忘掉符号,用下棋来说。
    >
    > 你在下棋,脑子只够往后算 3 步。**公式 (3) 说的是:算不到底的时候,一条路线怎么估分。**
    > 第 1 步吃兵(+2),第 2 步吃马(+3),第 3 步吃兵(+1),之后算不动了,凭直觉说「这局面以后大概还能赢 10 分」。
    > 这条路线值 2 + 3 + 1 + 10 = 16。**算得到的部分老老实实加,算不到的尾巴用直觉估。**
    >
    > **公式 (4) 说的是:算完之后棋风怎么改。** 算之前直觉估 12,算出来 16,比预想好 4 分 → 下次更倾向走这步。
    >
    > | 下棋 | 论文 |
    > |---|---|
    > | 往后算 3 步 | 在世界模型里做 15 步的梦 |
    > | 每步吃子得的分 | reward 头预测的每步分 |
    > | 对一个局面「以后还能赢多少」的直觉 | critic v(s) |
    > | 路线总分 − 事前直觉 = 意外 | 优势 V^λ − v |
    > | 比预想好就多走、差就少走 | 公式 (4) |
    >
    > 一句话各一个:(3) 路线的分 = 算得到的每步分 + 直觉补的尾巴;(4) 比直觉预想的好,就多走这步。
    > 如果这个版本能看懂,你已经懂了 actor-critic,剩下的全是记号。哪一句还别扭告诉我,我只解释那一句。
    
    为什么管用:换了讲法而不是加长;比喻是日常的、带数字的;最后一张对照表把每个比喻落回论文的符号;
    结尾请对方指出具体哪一句卡住。
    
    ---
    
    ## 6. 用户复述理解时怎么回
    
    > 用户:那我理解成 UniPi 还是学的视频,只是把视频帧的首帧作为条件输入给 Diffusion 了,帮助生成;可能因为机械结构整体变化不大,只是想学到运动?
    >
    > **对了一大半,改两个地方。**
    >
    > **对的部分。** UniPi 学的就是视频生成模型,输出是视频。首帧是条件输入,和文本一起喂给扩散模型。
    >
    > **要改的地方一:给首帧不是因为「结构变化不大」,是因为计划必须从眼前这个状态开始。** 没有首帧,模型生成的是「某个场景里执行这条指令的视频」,
    > 桌子、积木位置都是它编的,IDM 翻译出来的动作也对应编出来的场景。首帧把视频钉在真实的当前状态上。
    >
    > **要改的地方二:「只想学运动」要说精确一点。** 不变的部分(桌子、背景、机械臂外观)直接从参考帧抄——平铺就是为了每一帧都能抄;
    > 变的部分(机械臂位姿、积木位置)才是模型要想象的。它没有任何显式的运动表示,运动只隐含在相邻帧的差别里,真正把运动读出来的是后面的 IDM。
    
    判对错放在第一句(「对」/「对了一大半,改两个地方」/「不对」),先承认对的部分,再只改差的那几点、每点给理由。
    不要先夸,也不要把整个机制从头再讲一遍。
    
  • references/notes-template.md2.1 KBfef84c5481aeupstream ↗
    # 精读笔记 · {{标题}}
    
    > {{arXiv ID / 会议}} · {{机构}} · {{日期}} · 代码:{{链接,或"无"}} · 材料都在本目录(paper.pdf / paper.tex / figures/)
    
    ## 基本情况
    
    - 一句话:输入 {{…}} → 输出 {{…}}
    - 开源:代码 {{…}} / 权重 {{…}} / 数据 {{…}}
    - 和读过的哪篇最像、差在哪:{{…}}
    
    ## 导读地图
    
    开讲前填好;讲的时候照着走。行号指 paper.tex(没有源码就写页码)。
    
    | 站 | 这一站讲清楚什么(一句话) | 图 | 原文位置 | 代码 |
    |---|---|---|---|---|
    | ① 动机 | {{要解决什么、以前卡在哪、押注什么}} | 图 {{N}} | §1 L{{…}} | — |
    | ② 架构 | {{有哪几块、怎么接}} | 图 {{N}} | §{{…}} L{{…}} | `{{文件}}` |
    | ③ 训练 | {{损失在逼它学什么、几个阶段}} | 式 {{N}} | §{{…}} / 附录 {{…}} | `{{loss 所在文件:行}}` |
    | ④ 数据 | {{一条样本有哪些字段、多少数据}} | 图 {{N}} / 表 {{N}} | §{{…}} | `{{dataset / transform}}` |
    | ⑤ 信息流 | {{输入 → … → 输出,训练和推理差在哪}} | 图 {{N}} | §{{…}} | `{{推理入口}}` |
    | ⑥ 例子 | 场景:{{一句具体指令}} | — | — | `{{要逐行看的函数}}` |
    | ⑦ 实验 | {{最关键的 2–3 个结果}} | 图 / 表 {{N}} | §{{…}} | — |
    
    ## ① 动机
    
    ## ② 架构
    
    ![](figures/fig-{{NN}}.png)
    
    | 模块 | 来源 / 初始化 | 参数量 | 训练时更新吗 | 作用 |
    |---|---|---|---|---|
    
    ## ③ 训练
    
    ```
    {{公式,Unicode 写法}}
    ```
    
    | 符号 | 是什么 | 形状 / 取值 |
    |---|---|---|
    
    ## ④ 数据
    
    | 字段 | 形状 | 单位 / 取值 | 例子 |
    |---|---|---|---|
    
    ## ⑤ 输入输出信息流
    
    ```
    {{文字流程图,箭头上标形状}}
    ```
    
    ## ⑥ 例子走一遍
    
    ## ⑦ 实验与地位
    
    ## 问答
    
    按时间顺序记用户问过的问题和最后讲通的答案(讲通之前绕的弯不用记)。
    
    - **Q(第 {{N}} 站)**:{{用户原话}}
      **A**:{{最后讲通的那个版本,几句话}}
    
    ## 代码 ↔ 论文
    
    | 论文里 | 代码位置 | 备注(对不上的地方写这里) |
    |---|---|---|
    
  • .gitignore199 Bdee45f226f82upstream ↗
    # 个人画像:每个人自己写,不进仓库(模板见 profile.example.md)
    profile.md
    
    __pycache__/
    *.pyc
    .DS_Store
    
    # 在仓库目录里试跑 fetch_paper.py 时默认下到这里
    papers/
    
  • AGENTS.md1.1 KB07aa7dc591b8upstream ↗
    # 给 AI Agent 的说明
    
    这个目录是一套**带人精读论文**的流程和脚本:先把论文材料拉到本地(PDF、LaTeX 源码、裁好的图、官方代码),
    再按六站一站一站讲——动机 → 架构 → 训练 → 数据 → 输入输出信息流 → 拿一个例子对着代码走一遍。
    
    有人让你读 / 精读 / 讲解 / 拆解一篇论文时:
    
    1. **先读 `SKILL.md`**,按它的流程来,不要直接给一段摘要。
    2. 第 0 步用 `scripts/fetch_paper.py <arXiv 链接 / PDF / 目录>` 拉材料,看一眼 `figures/_contact.png` 检查裁图。
    3. 开讲前自己先读懂:读 `outline.md`、`paper.tex`,亲眼看关键的图;第一次讲之前读一遍 `references/examples.md`。
    4. **讲到哪张图就把那张图显示给用户**,先说「这张图是什么」再讲;一次只讲一站,讲完问要不要继续。
    5. 公式写成 Unicode + 符号表 + 一组代入的数字,不要写裸 LaTeX。
    6. 有 `profile.md` 就按它调整讲法(熟的一句带过、不熟的先铺垫)。
    
    依赖:Python 3 + PyMuPDF(`pip install pymupdf`)。代码只读,不替用户跑仓库脚本或装依赖。
    
  • LICENSE1.0 KB5f9ab30f6b29upstream ↗
    MIT License
    
    Copyright (c) 2026 skJack
    
    Permission is hereby granted, free of charge, to any person obtaining a copy
    of this software and associated documentation files (the "Software"), to deal
    in the Software without restriction, including without limitation the rights
    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
    copies of the Software, and to permit persons to whom the Software is
    furnished to do so, subject to the following conditions:
    
    The above copyright notice and this permission notice shall be included in all
    copies or substantial portions of the Software.
    
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
    SOFTWARE.
    
  • profile.example.md850 B60db6caa06beupstream ↗
    # 用户画像
    
    kelip-paper-reading 开讲前读这个文件来调整讲法。复制成同目录下的 `profile.md` 再改;
    不写也能用,第一次走到第 ⑥ 站时它会问你想用什么场景举例,并替你记下来。
    
    ## 背景
    - 方向:{{例:具身智能,VLA / 世界模型}}
    - 身份:{{例:研一,刚从 CV 转过来}}
    
    ## 已经熟的(讲到时一句带过)
    - {{例:Transformer、扩散模型的基本思路}}
    - 读过的论文:{{例:π0、OpenVLA}}
    
    ## 不熟、需要先铺垫的
    - {{例:强化学习,value / advantage 要从头讲}}
    
    ## 举例子
    - 喜欢的场景:{{例:做饭、篮球、让机械臂收拾桌子}}
    - 讲法偏好:{{例:玩具尺寸 + 真实数字;比喻只用日常物理场景,不要拟人故事}}
    
    ## 其他偏好
    - {{例:先结论后细节;公式要能直接读}}
    
  • README.en.md8.7 KBa3bc5f831c23upstream ↗
    # kelip-paper-reading
    
    [简体中文](README.md) | **English**
    
    Let an AI agent walk you through a paper. It won't stop at a summary. It reads the paper first, the way
    someone who already understands it would, and then takes you through it one stop at a time.
    
    Give it an arXiv link. It pulls the **PDF, the LaTeX source, every figure (auto-cropped to PNG), and the official code**
    to your machine, then explains the paper in six stops. Whenever it talks about a figure, it shows you that figure.
    After each stop it asks whether you want to move on:
    
    ```
    ① Motivation → ② Architecture → ③ Training (loss) → ④ Data (what one sample looks like) → ⑤ Input/output flow → ⑥ Walk one example through (against the code)
                                                                                              (optional ⑦ Results, and where the paper stands today)
    ```
    
    As it goes, it writes each stop and every question you asked into a notes file in the paper folder (`精读笔记.md`, "reading notes").
    
    ## Six stops: what you can say after each one
    
    | Stop | After this stop you can tell someone |
    |---|---|
    | ① Motivation | What problem it solves, where earlier approaches got stuck, and the key bet the authors made |
    | ② Architecture | What every box in the overview figure is, where data goes in and comes out; how many frames the model sees and how many steps it outputs |
    | ③ Training | What the loss pushes the model to learn, how many stages there are, and which parameters each stage updates |
    | ④ Data | What one training sample actually looks like: fields, shapes, units, one row of real values. More than the dataset's name |
    | ⑤ Information flow | How to follow an input all the way to the output, tensor shape at every step, what runs once and what loops |
    | ⑥ Example | One concrete task, walked through in time order against the code |
    
    ## House rules (each one came from feedback while reading real papers)
    
    - **Show the figure.** Saying "see Figure 3" doesn't help: you can't see it. The agent looks at the figure itself first,
      then tells you what the figure is and how to read it.
    - **Write formulas so they read without a renderer.** Unicode formula + a symbol table + one set of small numbers plugged in.
    - **If you didn't get it, explain it differently instead of saying the same thing longer**: real numbers → shrink to toy size
      and step through → first show why the naive approach fails → an everyday analogy plus a mapping table back to the paper.
    - **Basics first, design details second.** Who made it, what goes in and what comes out, what's open-sourced. Skip the paper's sales pitch.
    - **Keep sources apart.** What the paper says, what the code shows, and what the agent is guessing are labelled separately;
      places where the code disagrees with the paper get pointed out.
    - **Code is read-only.** The official repo is cloned to compare against, not to install or run.
    
    ## Install
    
    **Claude Code** (installed as a skill, it kicks in when you say "read this paper with me"):
    
    ```bash
    git clone https://github.com/skJack/kelip-paper-reading.git ~/.claude/skills/kelip-paper-reading
    pip install pymupdf
    ```
    
    **Other AI agents** (Cursor / Codex / Copilot / your own agent): clone it into your project and have the agent read `SKILL.md`.
    There's an `AGENTS.md` at the repo root, so agents that pick that file up automatically need no extra setup.
    
    The only dependencies are Python 3 and [PyMuPDF](https://pymupdf.readthedocs.io/). You need access to arxiv.org and github.com;
    Hugging Face being unreachable is fine.
    
    `SKILL.md` is written in Chinese. Any modern LLM agent reads it fine and will still talk to you in your own language.
    
    ## Usage
    
    ```
    Read this paper with me: https://arxiv.org/abs/2410.24164
    Walk me through π0 and put it under ~/papers
    Skip to the data: what does one training sample actually look like?
    Take one concrete example and walk the inference through the code
    ```
    
    The first reply is "basics + stop ①". Every stop ends by asking whether to continue. You can interrupt with questions any time,
    jump to another stop, ask it to "translate the introduction" (original and translation side by side), or ask it to
    "turn this into a document" (the reading notes are already there).
    
    ## What you get for each paper
    
    ```
    papers/pi0-vision-language-action/
    ├── paper.pdf         the paper
    ├── source/           LaTeX source from arXiv
    ├── paper.tex         the source flattened into one file (\input expanded, comments and references removed); trusted for formulas and tables
    ├── paper.txt         PDF text, page by page
    ├── outline.md        line numbers of every section and equation in paper.tex, so the agent can jump around
    ├── meta.json         title, authors, dates, abstract, code and project-page links
    ├── figures/          one PNG per figure and table; index.md has captions and where each is cited; _contact.png shows them all at once
    ├── code/             the official code (shallow clone)
    └── 精读笔记.md        reading notes: the gist of each stop, the figures used, the questions you asked
    ```
    
    In a project laid out like [research-workflow](https://github.com/skJack/research-workflow) (the current directory has `related_work/`),
    papers go to `related_work/<slug>/` and code goes to `复现/<repo>/code`. If the paper folder already has a `figures/`
    you curated yourself, the auto-cropped figures go to `figures-auto/` and yours are left alone.
    
    ## Make it fit you: profile.md
    
    ```bash
    cp profile.example.md profile.md
    ```
    
    Write down your field, what you already know (it'll mention those in one line), what needs groundwork first, and what kind of
    scenarios you like for examples. It works without one too: the first time it reaches stop ⑥ it asks what scenario to use and
    writes the answer down for you. `profile.md` is in `.gitignore`, so it never gets committed.
    
    ## Use the scripts on their own
    
    ```bash
    python3 scripts/fetch_paper.py 2410.24164 --dest ~/papers/pi0             # pull everything
    python3 scripts/fetch_paper.py ~/papers/pi0 --code https://github.com/Physical-Intelligence/openpi   # add the code repo when the paper doesn't link it
    python3 scripts/extract_figures.py ~/papers/pi0                              # re-crop all figures and tables
    python3 scripts/crop.py ~/papers/pi0/figures/fig-03.png --grid               # overlay a grid to locate the part you want to zoom into
    python3 scripts/crop.py ~/papers/pi0/paper.pdf --page 4 0.08 0.06 0.92 0.3 -o eq.png   # crop a region of a PDF page (equation, table)
    ```
    
    Input can be an arXiv ID or link (abs, pdf, alphaxiv and Hugging Face Papers links all work), a direct PDF link, a local PDF
    (a renamed arXiv PDF is recognised by the arXiv stamp on its first page, so the source still gets pulled), or a paper folder
    you already have (only what's missing gets filled in). The scripts print their progress in Chinese.
    
    ## Known limitations
    
    - **Figure cropping** locates captions and applies layout rules. It's been tested on common templates (single column,
      two column, IEEE, NeurIPS / ICLR, journals) and gets figures right nearly all the time; tables are less reliable.
      A bad crop is obvious in `_contact.png`; re-crop it with `crop.py`. The agent also checks before it uses a figure.
    - **LaTeX source** only exists for arXiv papers. For PDFs from elsewhere only the extracted text is available, so formulas and tables are rougher.
    - **Finding the code** checks the abstract, the arXiv comment, links on the PDF's first page, Hugging Face Papers and the project page.
      When the paper never mentions its code (e.g. π0 → openpi), the agent has to search and add it with `--code`.
    
    ## Files
    
    | Path | What it is |
    |---|---|
    | `SKILL.md` | The reading protocol for the agent: what each stop covers, how to handle figures and formulas, how to re-explain when something didn't land |
    | `AGENTS.md` | One-page pointer for agents that read it automatically |
    | `references/examples.md` | Examples of what each stop looks like when it's done well |
    | `references/notes-template.md` | Template for the reading notes |
    | `profile.example.md` | Template for your profile (copy to `profile.md`) |
    | `scripts/fetch_paper.py` | Downloads PDF / LaTeX / metadata, flattens the source, builds the outline, finds and shallow-clones the official code, runs figure extraction |
    | `scripts/extract_figures.py` | Crops every figure and table out of the PDF by caption, writes `index.md` and a contact sheet |
    | `scripts/crop.py` | Zooms into part of a figure, crops equations from a PDF page, or re-crops a bad figure |
    
    ## Related
    
    - [kelip-slide](https://github.com/skJack/kelip-slide): turn a paper you understand into an HTML slide deck for explaining it
    - [research-workflow](https://github.com/skJack/research-workflow): a project layout for doing research with agents (literature, reproduction, experiments)
    
    ## License
    
    MIT
    
  • requirements.txt14 Bf80d1e8aedc6upstream ↗
    pymupdf>=1.22
    

Plain-text copy, no login: /skill-bundles/skjack-kelip-paper-reading.md

// REPO STATS

355 stars
0 open issues
Last commit: 1mo ago