Community研究与数据分析github.com

论文转笔记本

将一篇研究论文(以 PDF、HTML 或纯文本源(如 LaTeX、Markdown)形式提供)转化为一个可运行的、引导式的 marimo 学习笔记本。当用户要求制作论文讲解笔记本、交互式教授论文、或构建出版物 walkthrough 时使用。

论文转笔记本 是什么?

该技能旨在将单篇研究论文转化为一个交互式的 marimo 笔记本,引导读者理解论文核心内容。它不只是生成摘要,而是通过分步引导、交互式控件和解释“阶梯”(为不同背景读者提供从儿童到专家的5级解释)来教授。技能支持 PDF、HTML 及 LaTeX/Markdown 等文本源作为输入。它自动提取论文结构、关键概念、公式和图形,规划学习路径,并生成带有依赖声明的自包含 marimo 笔记本。笔记本包含非正式理解检查、最终五题测验,并遵循严格的编写规范,避免生成泛泛的AI内容。该技能特别强调为不同成熟度的研究领域定制词汇入门模块,以及通过验证确保笔记可运行,最终输出一个可直接通过 `uvx marimo edit --sandbox` 运行的 `*.py` 文件。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ericmjl/paper-to-notebook-skill/tree/main

Installed? Explore more 研究与数据分析 skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

论文转笔记本 是做什么的?

引导智能体从一篇论文生成一个可运行的 marimo 笔记本,帮助读者理解该论文。该笔记本是一堂课,而非摘要页:包含通俗易懂的解释、在合适的地方提供交互式控件,并在过程中穿插非正式的检查。行文必须清晰易懂并忠实反映论文内容,而非泛泛的AI套话。

此文件为骨架。大量细节将在后续填充。标记为 TODO 的项目尚未决定或仅做了简要描述。

契约

输入论文,格式为 PDF、HTML 或纯文本源(LaTeX、Markdown 等)。可以是路径、URL 或标识符,只要能获取全文即可。
输出一个可运行的 marimo 笔记本(*.py),读者可用 uvx marimo edit --sandbox … 打开。

如果以下内容缺失,可以请求用户提供(如果用户仅提供了论文,不要阻止流程):

  • 起始读者群体,或“让我边走边适应。”默认工作假设:本科生到研究生,外加刚接触这篇论文或该领域、具备一定通用科学知识的在职专业人士。TODO: 收紧默认设定。
  • 额外上下文:用户希望作为基础(而不仅仅是通用知识)的支持性信息、被引论文或其他来源。
  • 深度:完整 walkthrough vs. 仅方法、结果或一个图表。
  • 输出路径和运行时约束。

不要将此技能视为审查大量文献的工具。那是另一项工作。

工作流

1. 摄取论文(PDF / HTML / 纯文本源)
2. 提取结构、术语、公式、图表和空白点
3. 规划学习路径
4. 生成 marimo 笔记本
5. 使用 `uv run` 验证其运行,然后交付

1. 摄取论文

获取全文,而不仅仅是摘要。根据输入类型分支;将格式特定的说明放在 resources/ 目录下,任何辅助脚本放在 scripts/ 目录下(始终使用 uv run,不要使用全局 pip install)。

  • PDF: TODO: 如何获取和解析(文本、数学公式、图表、阅读顺序)。应标记失败而非猜测。
  • HTML: TODO: 如何获取和解析(主体内容 vs. 导航/装饰元素,MathJax/MathML,图表)。
  • 纯文本源(LaTeX、Markdown 等): TODO: 如何跟踪包含、参考文献和图表文件;如何保持公式和图表标签。

记录论文的标题、作者、年份,并在可用时记录稳定链接或标识符。

2. 提取结构、公式和图表

在编写任何笔记本之前构建论文的中间表示。TODO: 确定此步骤的数据结构(参见“良好的中间结构可以使其余工作更轻松”的想法)。

至少提取:

  • 问题和贡献,用你自己的话表述。
  • 先决条件分布:每个级别的读者知道什么、不知道什么以及必须教授什么(参见多级解释)。
  • 关键概念和论文使用但未定义的术语(核心元数据或领域术语)。设计讨论中提出的示例:一篇关于心脏病发作但从未解释“心肌梗死”的论文。
  • 关键公式,按照论文中的编号,附有变量。
  • 关键图表:每个图表编码了什么、如何标记的,以及底层数据是否似乎可用。
  • 生成的风险点:大量 LaTeX 或数学公式、希腊字母图表标签、其他非 ASCII 文本。
  • 方法或报告中的明显空白。不要编造缺失的实验结果。

使用 resources/field-maturity.md 中的准则和轻量级文献样本,对领域成熟度进行分类(成熟、新兴、跨学科或混合)。记录类别、证据以及需要哪些词汇入门笔记本组件(词汇表、消歧、术语变化)。

TODO: 是否将论文归类为算法类(编码练习、逆向工程方法)与概念类(智能体编写的解释器控件)。讨论中使用的化学示例:质量平衡、反应动力学、新动力学模型。

3. 规划学习路径

设计一个人可以在一次阅读中遵循的路径。TODO: 目标时长。

不要将整个笔记本锁定在单一阅读水平。规划自适应解释:读者应该能够获得困难段落的更简单或更高级的解释。TODO: 默认方向——从简单开始并增加复杂度,或者从高处开始并在读者困惑时降级。两者都曾被提出,但均未被选中。核心概念获得完整的阶梯(参见多级解释)。

建议主线结构(根据论文调整):

  1. 这篇论文为什么重要。
  2. 在引入大量符号之前的直觉或玩具示例。
  3. 准备:符号、假设、术语和领域词汇入门(词汇表;在需要时进行消歧或术语变化处理——参见 resources/field-maturity.md)。
  4. 核心思想,与公式或图表相关联。
  5. 与论文对齐的逐步讲解。
  6. 在段落之后进行非正式检查,与解释水平相匹配:解释、预测、应用或批判(非正式评估——正式评估不在范围内)。
  7. 对于研究生及以上读者,批判环节:实验设计是否解决了所述问题;统计框架是否合适;缺少什么;读者在做什么假设。
  8. 总结:局限性、下一步阅读、引用。
  9. 最终测验:关于论文的五个多选题,始终是最后一部分(参见最终测验)。

TODO: 在第一个版本中,批判、结果部分分析和图表解读提示走多远,与简单引导式 walkthrough 相对。

如果用户提供了额外来源,规划在笔记本中何处引用这些来源,以及如何将基于来源的证据与通用知识区分开来。TODO: 区分机制,以及之后是否需要一个小型概念图或“知识维基”。

4. 生成 marimo 笔记本

从 assets/ 中的模板开始(如果存在)(TODO: 添加 assets/notebook_template.py)。编写一个可以用 uvx marimo edit --sandbox 打开的 marimo 笔记本。

遵循安装在 .agents/skills/ 中的 marimo 技能(一个 import marimo as mo 单元格;唯一的顶级名称;驱动探索而非装饰的控件):

  • marimo-notebook-patterns:在编写或编辑任何笔记本单元格之前阅读(导入和单元格参数规则、唯一变量、控件 API 签名、常见错误)。
  • marimo:更广泛的创作参考,包括实时配对和在 Web 上嵌入笔记本。
  • awesome-marimo-notebook:如何使论文或数据集解释器更具吸引力和精致性。

在文件顶部声明 PEP 723 内联脚本元数据块中的依赖项(# /// script … # ///),列出 marimo 和笔记本导入的每个包,每个都带有一个下限版本(例如 numpy>=2.0)。这允许 uv run 和 marimo edit --sandbox 安装它们。

以最终测验中描述的五题测验结束笔记本。

行文的硬性要求:

  • 清晰易懂,并忠实反映论文的核心思想。
  • 不要是泛泛的“AI 垃圾”。如果一句话可以用于任何论文,请重写。
  • 在符号和领域术语首次出现时进行定义,或指向词汇表/工具提示/高亮解释辅助工具。根据 resources/field-maturity.md 为不同成熟度提供特定的入门章节。TODO: 首先提供哪些读者辅助工具。讨论中提到“Marimo Lens”可能适合实现高亮解释;请确认实际的功能名称和主机支持。

其他生成规则:

  • 公式:在 mo.md 中使用 LaTeX;在参数上使用控件以帮助建立直觉。
  • 图表:在数据允许时复现或简化;链接回论文中的图表编号。如果数据不可用,请说明——不要编造图表。TODO: v1 中基于视觉估计或读者编写的图表解释可以走多远。
  • 图表讲解:当一个关键图表需要引导式、逐步的导览时,请阅读 resources/dynamic_figure_annotation.md(FigureAnnotatorWidget 加上 scripts/ 中的坐标审计辅助工具)。
  • 核心概念(每个笔记本 1-3 个)获得一个解释阶梯(多级解释)。
  • 非正式检查:简答题,非评分评估。使用 resources/explanation-levels.md §9 中的 show_check 模式(单选、带容差的数值答案、或带模版答案的开放式答案)。
  • 来自步骤 2 的领域模式:对于算法类论文,进行编码练习和方法重构;对于概念类论文,进行智能体编写的可视化/控件解释器(例如,单元格中的机制)。
  • 标记任何超出论文范围的内容(“我们的演示”、“简化假设”)。
  • 包含论文元数据和引用。

5. 验证和交付

最低要求(v1 骨架):笔记本必须能够运行。

uv run scripts/validate_notebook.py path/to/notebook.py --run

它将检查 Python 语法,运行 marimo check --strict,并使用 --run 从头到尾执行笔记本。在交付前修复每个报告的问题。

告知用户:

  • 笔记本的路径和打开命令(uvx marimo edit --sandbox …)。
  • 假定的读者群体和简化内容。
  • TODO 和已知空白(包括缺失数据或未定义的术语)。
  • 论文参考(标题、作者、年份、链接)。

计划中的“非仅运行”验证(首版草图不要求全部完成):

  • 行文清晰易懂并忠实反映论文,不是垃圾。
  • 核心概念和元数据术语确实得到解释。
  • 没有编造的数字或声明。
  • 笔记本以五题测验结束,且问题关乎论文的主张、发现和局限性,而非其实现细节。
  • 每个阶梯在每一级别解释相同的机制主线;每个层级的简化在后面的层级得到纠正;类比的范围得到说明。
  • 词汇入门: 针对成熟、新兴和跨学科案例研究,验证词汇表覆盖范围,并在需要时验证消歧或术语变化部分(根据 resources/field-maturity.md §8)。
  • TODO: 断言或金问题评估;多模型运行(提供了中文开放权重和 Claude 模型);仅当 LLM 作为评判者作为第一道过滤器时,其在识别“坏”内容上比识别“好”内容更可信;由人类在陌生论文上进行试用;在自己的领域进行烟雾测试后由领域专家进行审查。
  • TODO: 一个共享的测试论文集,涵盖成熟、新兴和跨学科工作,以及子领域,而非仅单一领域。一篇 2016 年的流感论文被提议作为一个可能的案例;列表尚未选定。

多级解释

核心思想获得一个解释阶梯:一个机制在五个级别上解释,每个级别针对具有特定先决条件的读者编写。其模型源于 WIRED 的 5 Levels 系列。级别名称是简写。定义级别的因素是读者带来的学科知识和数学水平,以及该级别增加的精度。

级别(简写)假设的学科知识假设的数学水平为机制增加的内容
1 · 儿童日常经验计数和比较因果关系,用日常用语表述
2 · 青少年通用科学素养算术、百分比、简单图表使用真实小数值的玩具示例
3 · 本科生该领域的一门入门课程该领域的入门工具精确的公式或算法,每个符号都定义
4 · 研究生相邻领域的标准方法跟随论文的推导假设、何时成立、什么会失效,以及如何与标准方法比较
5 · 专家本子领域的文献完整的形式化体系新内容、权衡、局限性和开放问题

规则:

  1. 按论文概况先决条件(阶段 1):对于每个级别,读者知道什么、不知道什么、以及笔记本必须教授什么。将用户声明的背景(来自契约中的可选输入)映射到一个级别。

  2. 每个级别一个机制。 首先编写一句话的机制主线;每个级别为其增加精度。没有任何级别可以用更模糊或不同的机制来替代。

  3. 每个级别都准确。 通过省略某些内容来简化,永远不要说假话。在账本中记录每个简化,并在后面的级别中予以纠正。

  4. 映射类比并说明其局限性。 将一个锚点带到级别 3,将其部分映射到方法的部分,并在级别 3 中指出其失效之处。

  5. 与级别相匹配的检查:

    • 儿童:解释。
    • 青少年:预测。
    • 本科生:应用。
    • 研究生:应用和批判假设。
    • 专家:批判。

    每个检查都应有预期答案、推理过程和论文中的位置。

  6. 阶梯用于核心内容: 每个笔记本 1-3 个概念。

  7. 基于文本: 引用你阅读的文本中的位置,切勿猜测。在草稿阶段标记空白处 [cite: …],并在交付前解决。

  8. 数字附带其条件: 表格、队列、特征集或范围应放在同一句子中。在真实论文测试中,阶梯引起的两个误解均源自一个被剥离了条件的数字。

在笔记本中: 在顶部附近添加一个级别选择器。每个阶梯得到一个 mo.ui.tabs,在读者的级别上打开,并在其下方显示该级别的检查。

在编写前阅读: resources/explanation-levels.md 包含分布和账本模板、一个工作示例、经过测试的 marimo 单元格以及常见陷阱。resources/examples/ 中有两个更完整的阶梯示例,……

……[为翻译截断]

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相关技能