论文转笔记本 是做什么的?
引导智能体从一篇论文生成一个可运行的 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: 默认方向——从简单开始并增加复杂度,或者从高处开始并在读者困惑时降级。两者都曾被提出,但均未被选中。核心概念获得完整的阶梯(参见多级解释)。
建议主线结构(根据论文调整):
- 这篇论文为什么重要。
- 在引入大量符号之前的直觉或玩具示例。
- 准备:符号、假设、术语和领域词汇入门(词汇表;在需要时进行消歧或术语变化处理——参见
resources/field-maturity.md)。 - 核心思想,与公式或图表相关联。
- 与论文对齐的逐步讲解。
- 在段落之后进行非正式检查,与解释水平相匹配:解释、预测、应用或批判(非正式评估——正式评估不在范围内)。
- 对于研究生及以上读者,批判环节:实验设计是否解决了所述问题;统计框架是否合适;缺少什么;读者在做什么假设。
- 总结:局限性、下一步阅读、引用。
- 最终测验:关于论文的五个多选题,始终是最后一部分(参见最终测验)。
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):对于每个级别,读者知道什么、不知道什么、以及笔记本必须教授什么。将用户声明的背景(来自契约中的可选输入)映射到一个级别。
-
每个级别一个机制。 首先编写一句话的机制主线;每个级别为其增加精度。没有任何级别可以用更模糊或不同的机制来替代。
-
每个级别都准确。 通过省略某些内容来简化,永远不要说假话。在账本中记录每个简化,并在后面的级别中予以纠正。
-
映射类比并说明其局限性。 将一个锚点带到级别 3,将其部分映射到方法的部分,并在级别 3 中指出其失效之处。
-
与级别相匹配的检查:
- 儿童:解释。
- 青少年:预测。
- 本科生:应用。
- 研究生:应用和批判假设。
- 专家:批判。
每个检查都应有预期答案、推理过程和论文中的位置。
-
阶梯用于核心内容: 每个笔记本 1-3 个概念。
-
基于文本: 引用你阅读的文本中的位置,切勿猜测。在草稿阶段标记空白处
[cite: …],并在交付前解决。 -
数字附带其条件: 表格、队列、特征集或范围应放在同一句子中。在真实论文测试中,阶梯引起的两个误解均源自一个被剥离了条件的数字。
在笔记本中: 在顶部附近添加一个级别选择器。每个阶梯得到一个 mo.ui.tabs,在读者的级别上打开,并在其下方显示该级别的检查。
在编写前阅读: resources/explanation-levels.md 包含分布和账本模板、一个工作示例、经过测试的 marimo 单元格以及常见陷阱。resources/examples/ 中有两个更完整的阶梯示例,……
……[为翻译截断]