marimo 笔记本优化指南从 notebook-improvements 技能看单元格重构、setup 设计与持久化缓存【免费下载链接】marimoA reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.项目地址: https://gitcode.com/GitHub_Trending/ma/marimo本文以 marimo 仓库中 AI Agent 技能marimo-pair的按需参考文档 notebook-improvements 为主线系统讲解如何在用户的实时 notebook 会话中执行改进、优化、清理工作包括单元格命名策略、setup 单元格的创建与约束、将通用函数提升为独立可复用单元格以及用mo.persistent_cache消除重复计算。读完本文你将掌握一套基于 marimo 数据流DAG模型的 notebook 重构方法论以及支撑这些规则的源码级原理。一、能力从何而来notebook-improvements 的加载机制notebook-improvements并不是一个常驻的系统模块而是marimo-pair技能下的一个按需加载defer_loading的参考能力capability。在 code_mode.py 中可以看到它的注册方式notebook_improvements_capability: Capability Capability( idnotebook-improvements, descriptionImproving, optimizing, or cleaning up an existing notebook., instructionsload_reference(notebook-improvements), defer_loadingTrue, )defer_loadingTrue意味着该能力只在模型判定用户要求改进、优化或清理 notebook时才被load_capability工具按需注入上下文避免在每次对话中都占用 token。这与 SKILL.md 中on-demand references的设计一致——gotchas、rich-representations、notebook-improvements三个参考文档都遵循这一模式且明确要求不要直接从磁盘读取参考文件而是通过load_capability加载。使用前提本文所有重构操作都运行在marimo._code_modecm提供的代码模式上下文code-mode context中通过execute_code工具在用户的实时内核 scratchpad 中执行。cm是私有且不稳定的 Agent API只能出现在 scratchpad 中禁止在 notebook 单元格、库代码或任何用户代码中导入。二、Cell names命名优先级与 UI 成本单元格命名在重构中属于低优先级事项除非用户明确要求否则不应过度应用。marimo 对两类单元格会自动命名无需手工干预名为setup的单元格定义函数或类的单元格会被自动赋予名称。命名 markdown 单元格会带来 UI 成本正常情况下 markdown 单元格不显示单元格头部一旦命名头部就会常驻显示造成界面杂乱。因此需要与用户沟通时只对有意义的单元格命名不确定某个命名是否值得宁可询问用户也不要自作主张。命名在代码模式中通过name参数完成见下文 setup 示例单元格既可以通过字符串 ID 引用也可以通过名称引用例如ctx.cells[setup]、ctx.cells[0]以及list(ctx.cells.keys())获取按 notebook 顺序排列的全部 ID见 SKILL.md。三、Setup cell导入汇聚的规范位置3.1 什么是 setup 单元格setup 单元格是名为setup的特殊单元格保证在其他所有单元格之前运行是模块导入的规范位置。把散落在各单元格的import汇聚到这里可以让 notebook 更干净并确保每个单元格都能依赖这些已加载的模块。在代码模式中创建 setup 单元格非常简单namesetup会自动把单元格定位到首位无需额外指定before/aftercid ctx.create_cell(import polars as pl import marimo as mo import anywidget import traitlets, namesetup) ctx.run_cell(cid)3.2 关键约束setup 不能引用其他单元格的变量setup 单元格不能引用其他单元格的变量。因为它最先运行必须完全自包含只包含导入、常量以及彼此依赖的定义。如果引用了其他单元格定义的名字例如df或某个 UI 元素会触发运行时错误The setup cell cannot have references。这条错误信息并非前端文案而是后端运行时错误结构的describe()输出。在 errors.py 中可以找到其定义class SetupRootError(msgspec.Struct, tagsetup-refs): edges_with_vars: tuple[EdgeWithVar, ...] def describe(self) - str: return The setup cell cannot have referencesedges_with_vars携带了具体涉及哪些变量边的信息说明该错误由数据流图分析产生——一旦 setup 单元格与其他单元格之间出现入边便视为违反根节点约束。3.3 尽量保持 import-only减少全量重跑如果可能让 setup 单元格只包含导入语句。marimo 在被编辑的单元格只含 import 语句时会跳过对后代单元格的重跑因为 import 的解析独立于 notebook 的响应式数据流。这一优化对所有 import-only 单元格都生效而不仅仅针对setup。它对setup的影响最大因为其他所有单元格都依赖 setup如果 setup 里还定义了常量或其他值编辑 setup 会导致整个 notebook 重跑。因此模块导入 → 留在 setup常量、派生值等定义 → 放进 setup下游的独立单元格。例如# setup只含导入 import polars as pl import marimo as mo # 下游单元格定义常量 DATA_URL https://example.com/objects.csv这样编辑DATA_URL时只会触发下游依赖重跑而不会连累全 notebook。3.4 已存在 setup 时的更新方式如果 notebook 中已有 setup 单元格再次调用create_cell(namesetup)会抛出ValueError。在 _context.py 的源码注释与实现中可以确认# The setup name is special-cased to use the well-known setup # cell ID. Raises ValueError if a setup cell already exists. # Check if a setup cell already exists (by name or by ID). # A setup cell already exists. Use # ctx.edit_cell(setup, code...) to modify it.此时应改用ctx.edit_cell(setup, code...) # 更新 setup 内容仅结构性变更 ctx.run_cell(setup) # 显式排队执行注意edit_cell与create_cell一样只改变 notebook 结构不会自动执行必须通过run_cell显式排队运行见 SKILL.md。另外create_cell默认hide_codeTrue会折叠代码编辑器若用户希望新建单元格默认展开需传hide_codeFalse。四、把可复用函数提升为独立单元格4.1 判定标准是否值得被 import当一个单元格包含单个函数或类且不引用其他单元格的变量时marimo 会把它特殊对待——它可以被写成独立定义并在 notebook 之外复用这类函数可以使用 setup 单元格中的模块。寻找的候选对象是**本可以放进库的函数**数据加载、数据变换、解析器、领域逻辑、自定义组件等。判断方法很朴素如果其他人有理由从另一个模块import它它就值得被提升到独立单元格。反之不要盲目提升所有内容notebook 特有的接线代码——UI 布局、展示逻辑、单元格级编排——应留在原位仅供单元格内部使用的辅助函数用_前缀私有名标记私有名不会进入 notebook 级数据流图详见 SKILL.md 中关于 public/private 定义的规则。4.2 重构前后对比重构前通用逻辑埋在大型单元格里难以复用、难以测试。# before: useful logic buried in a larger cell objects pl.read_csv(https://example.com/objects.csv) artists pl.read_csv(https://example.com/artists.csv) def top_counts(df, col, n5): return df.group_by(col).len().sort(len, descendingTrue).head(n) result top_counts(objects.join(artists, onid), category)重构后top_counts是通用函数拥有自己的单元格。# cell 1 —— 通用函数独立成格 def top_counts(df, col, n5): return df.group_by(col).len().sort(len, descendingTrue).head(n)# cell 2 —— 数据加载与调用留在数据流中 result top_counts(df, category)注意重构后第二个单元格中的df应来自 notebook 中已有的数据单元格如 setup 或数据加载单元格示例仅为展示调用形态。提升后函数的变更只重跑其下游数据加载逻辑的变更也不再牵连函数定义数据流图的依赖粒度因此更精细。4.3 与 marimo 图契约的配合create_cell/edit_cell提交单元格时marimo 会解析顶层定义与引用。公共名无_前缀会进入数据流图且每个公共名只能有一个属主单元格重复定义会报Multiply-defined names对应 errors.py 中的MultipleDefinitionError。因此在提升函数时要注意新单元格的函数名不得与 notebook 中其他公共名冲突函数体内部的中间变量应使用私有名或函数局部变量避免污染全局数据流若被提升的函数依赖 notebook 中已存在的导入优先复用 setup 中的模块而不是新增import numpy as _np之类的旁路导入。五、mo.persistent_cache跨内核重启的磁盘缓存5.1 基本用法mo.persistent_cache把函数的计算结果缓存到磁盘后续运行不再重复计算且缓存跨内核重启持久存在mo.persistent_cache def load_data(): objects pl.read_csv(https://example.com/objects.csv) artists pl.read_csv(https://example.com/artists.csv) return objects.join(artists, onid, howleft) df load_data()5.2 适用场景与克制原则好的候选数据加载、ETL、很少变化的昂贵计算。不要过度优化如果拿不准某个函数是否值得缓存把它作为建议提给用户而不是擅自套用。文档原文明确要求use your judgment — dont over-apply, and if youre unsure whether a change is worthwhile, ask the user——这与整个 notebook-improvements 技能的基调一致以用户意图为中心宁可询问也不过度改动。5.3 源码层的双重形态从 save.py 的 docstring 可以看到persistent_cache实际上支持两种形态上下文管理器with mo.persistent_cache(namemy_cache): variable expensive_function() # 首次计算后缓存到磁盘 print(hello, cache) # 命中缓存时整块跳过print 不会执行函数装饰器即本文示例用法作为mo.cache/mo.lru_cache的磁盘版记忆化比mo.cache慢但能跨内核重启保存函数返回值。缓存失效由源码哈希驱动mo.persistent_cache会基于单元格代码与其祖先单元格的内容生成哈希见 hash.py只有当代码块或祖先未变化时才从磁盘恢复变量、跳过整块执行。这意味着缓存命中时with块内的副作用stdout/stderr 输出也会被跳过mo.state和UIElement的变更会触发缓存失效并同步更新该机制基于sys.settrace帧追踪实现可能与同样使用sys.settrace的调试工具/库冲突docstring 中的明确警告。六、实践检查清单将以上规则整合为一次 notebook 改进会话的执行清单先探测再动手通过cm.get_context()读取ctx.cells与ctx.graph确认是否已有setup单元格、各公共名的属主与依赖关系删除单元格前先用ctx.graph.descendants(cid)评估影响面marimo 的删除是破坏性的。汇聚导入无 setup 则创建 import-only 的 setup已有则edit_cell(setup, code...)后run_cell(setup)常量与派生值移入 setup 下游单元格。命名克制只对用户要求或有明确语义的单元格命名不命名 markdown 单元格。提升通用函数对值得被 import的纯函数/类提升为独立单元格并保持私有名用于内部中间量UI 编排类代码留在原位。按需缓存对数据加载、ETL 等昂贵且少变的计算应用mo.persistent_cache不确定时向用户提出建议。通过 cm 持久化所有结构变更一律走ctx.create_cell/ctx.edit_cell/ctx.run_cell绝不直接改写磁盘上的.py文件——活动内核才是事实来源source of truth直接改文件既到不了实时会话还可能被内核在保存时覆盖。七、总结notebook-improvements 技能文档浓缩了 marimo notebook 工程的四条核心经验命名要克制、导入要汇聚、函数要提炼、计算要缓存。它们的共同底层逻辑是 marimo 的响应式 DAG让每个单元格的依赖边界最小、最清晰就能获得最小的重跑范围、最快的启动速度和最易复用的代码结构。结合 code_mode.py、_context.py、errors.py 与 save.py 等源码可以确认这些规则并非约定俗成而是由运行时数据流分析、setup 根节点校验、import-only 重跑优化与哈希驱动的磁盘缓存共同支撑的实现事实。无论是人类开发者手动重构还是 AI Agent 在代码模式下自动改进这套方法论都同样适用。【免费下载链接】marimoA reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.项目地址: https://gitcode.com/GitHub_Trending/ma/marimo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考