--- name: kelip-paper-reading description: 带着用户精读一篇论文(尤其是机器人 / VLA / 世界模型 / 深度学习方向):先把 PDF、LaTeX 源码、每张图裁好的 PNG、官方代码拉到本地,再一站一站讲——① 动机 → ② 架构 → ③ 训练和损失函数 → ④ 数据(一条样本到底长什么样)→ ⑤ 输入输出信息流 → ⑥ 拿一个具体例子把信息流走一遍(对照代码),讲到哪张图就把那张图发给用户,每站讲完主动问要不要进下一站。任何「读 / 精读 / 讲讲 / 解读 / 拆解 / 带我读这篇论文」「这篇 paper 在干嘛」「帮我看看 arxiv.org/abs/…」的请求都用它——包括只丢一个 arXiv 链接或 PDF、只说「讲讲 π0」「这篇的架构 / 损失函数 / 数据是什么」「对着代码讲讲这篇」「举个例子走一遍」的时候。不用于:批量检索调研、只要一句话总结、写论文或审稿。 --- # 带读论文 一篇论文拆成六站,一次只讲一站,讲完问要不要往下走: ``` ① 动机 → ② 架构 → ③ 训练 → ④ 数据 → ⑤ 输入输出信息流 → ⑥ 拿一个例子把信息流走一遍(对照代码) (可选 ⑦ 实验和这篇现在的地位) ``` 两条规矩贯穿全程,后面每一节都是在展开它们: - **图要发出来。** 讲到哪张图就把那张 PNG 发给用户,再对着图讲。只写「见图 3」,用户是看不到的—— 实测:讲了四张架构图,用户回过来一句「你介绍的图我都看不到啊」。 - **用人话,配例子。** 先说它干什么、吃什么吐什么,再说细节;每个抽象的东西都配一个带具体数字的例子。 读论文时最常听到的三句话是「没看懂」「太抽象了」「能不能举个例子走一遍」。 下文 `` 指这个 SKILL.md 所在的目录。 --- ## 第 0 步:拉材料(每篇一次) ```bash python3 /scripts/fetch_paper.py [--dest 目录] ``` 放哪:用户说了位置就用 `--dest`;当前目录有 `related_work/`([research-workflow](https://github.com/skJack/research-workflow) 的项目结构)会自动放进去, 代码进 `复现//code`;都没有就放 `./papers//`。项目自己的 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. 读 `/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)`)、公式、例子。整理过的,不是原样粘贴回复。 - 用户问过的问题和最后的答案记进「问答」:问过的问题本身就是最好的复习提纲,也是以后讲给别人听的骨架。 - 每站结束时一次性追加,别为了记笔记拖慢回复。 ## 用户画像 `/profile.md` 记着用户的背景、熟什么不熟什么、喜欢什么样的例子(格式见 `profile.example.md`)。 熟的东西一句带过,不熟的主动铺垫;第 ⑥ 站的场景从这里挑。用户在对话里透露了新的偏好(「别用比喻」「我不懂强化学习」),顺手更新它。 ## 脚本速查 脚本都在 `/scripts/`;下表的相对路径(`figures/…`、`paper.pdf`)指论文目录,在论文目录里跑或者写绝对路径。 | 命令 | 干什么 | |---|---| | `fetch_paper.py <链接/ID/PDF/目录> [--dest D \| --root R] [--code URL] [--code-dir D] [--no-clone]` | 拉全部材料;重复跑只补缺的。`--root` 放到 R//,`--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/`(或 `复现//code`)· `精读笔记.md`