marimo

目录

• 编辑与验证强制要求
• 关键概念
• 单元格结构
• 编辑规则
• 核心 CLI 命令
• 导出命令
• 数据与可视化
• 调试工作流
• 常见问题
• 其他资源

Marimo 响应式笔记本

Marimo 是一种响应式 Python 笔记本，单元格构成一个 DAG，并会在依赖项发生变化时自动执行。笔记本以纯 .py 文件的形式存储。

编辑与验证强制要求

铁律 #1：绝不修改单元格装饰器或签名

只能编辑 @app.cell 函数体内的代码。这一点不容妥协。

绝不修改：

• 单元格装饰器（@app.cell）
• 函数签名（def _(deps):）
• 返回语句的结构（必须保留尾随逗号）

务必验证：

• 所有使用的变量都在函数参数中
• 所有创建的变量都在返回语句中
• 单个返回值要加尾随逗号：return var,

铁律 #2：未经输出验证，不得声称已执行

在声称任何 marimo 笔记本可用之前：

1. 验证语法和结构：marimo check notebook.py
2. 执行并生成输出：marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs
3. 核验 notebook-debug 技能的核验清单
4. 仅在核验通过后才声称成功

这不容妥协。未执行并检查输出就声称“笔记本可用”，是在对用户撒谎。

自我辩解对照表——想到以下说法时请停下：

借口	事实	应采取的做法
“marimo check 通过了，所以能用”	语法检查 ≠ 运行时正确性	使用 --include-outputs 执行并检查
“只是一个小改动，不可能出问题”	响应式特性意味着小改动也会影响各处	通过完整执行进行核验
“让 marimo 处理依赖追踪就行”	仍然必须验证行为是否正确	检查输出是否符合预期
“函数签名看起来没问题”	依赖项或返回值错误会悄无声息地破坏响应式行为	验证所有变量都在参数中且也在返回值中
“我可以修改函数签名”	这会破坏 marimo 的依赖检测	只能编辑函数体内的代码
“变量不返回也能使用”	依赖该变量的单元格会因此出现 NameError	返回所有创建的变量
“单个返回值可以不加尾随逗号”	Python 会将 return var 视为返回该值，导致解包失败	单个返回值使用 return var,

危险信号——想到以下说法时请立即停下：

• “我把这个变量加到函数签名里吧” → 不行。签名由 marimo 管理。
• “我运行 marimo check 就算完成了” → 不行。必须执行并生成输出。
• “代码看起来没问题” → 不行。必须在运行时验证 marimo 的响应式行为。
• “我可以在另一个单元格中重新定义这个变量” → 不行。一个变量只能属于一个单元格。

编辑检查清单

每次编辑 marimo 之前：

结构验证：

• 只编辑 @app.cell 函数体内的代码
• 不要修改装饰器或签名
• 验证所有使用的变量都在函数参数中
• 验证所有创建的变量都在 return 语句中
• 单个返回值要确保使用尾随逗号
• 确保不同单元格之间没有变量重定义

语法验证：

• 执行 marimo check notebook.py
• 验证没有报告语法错误
• 验证没有未定义变量警告
• 验证没有重定义警告

运行时验证：

• 执行 marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs
• 验证导出成功（退出代码为 0）
• 验证输出的 ipynb 文件存在且非空
• 按照 notebook-debug 验证清单进行检查
• 验证任何单元格中都没有回溯信息
• 验证所有单元格均已执行（execution_count 不为 null）
• 验证输出符合预期

只有在所有检查都通过后：

• 声称“notebook 可以正常运行”

门控函数：Marimo 验证

每次处理 marimo 任务时，都要遵循以下顺序：

1. EDIT     → Modify code inside @app.cell function bodies only
2. CHECK    → marimo check notebook.py
3. EXECUTE  → marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs
4. INSPECT  → Use notebook-debug verification
5. VERIFY   → Outputs match expectations
6. CLAIM    → "Notebook works" only after all gates passed

绝不要跳过验证门控。 Marimo 的响应式特性意味着更改会以不可预测的方式传播。

诚实声明

未使用 --include-outputs 执行并检查结果，就声称 marimo notebook 可以正常运行，这是在撒谎。

语法检查和代码检查无法证明响应式执行正确性。用户期待的是一个可以正常运行的 notebook，其中所有单元格都能正确执行，并具备正确的依赖跟踪。

核心概念

• 响应式执行：依赖项发生变化时，单元格会自动更新
• 无隐藏状态：每个变量只在一个单元格中定义
• 纯 Python：.py 文件，便于版本控制
• 单元格结构：@app.cell 装饰器模式

单元格结构

import marimo

app = marimo.App()

@app.cell
def _(pl):  # Dependencies as parameters
    df = pl.read_csv("data.csv")
    return df,  # Trailing comma required for single return

@app.cell
def _(df, pl):
    summary = df.describe()
    filtered = df.filter(pl.col("value") > 0)
    return summary, filtered  # Multiple returns

编辑规则

• 只编辑 @app.cell 函数内的代码
• 绝不要修改单元格装饰器或函数签名
• 不同单元格之间不能重定义变量
• 所有使用的变量都必须由定义它的单元格返回
• Markdown 单元格：始终用反引号包住 $——使用 mo.md("Cost: $50")，而不是 mo.md("Cost: $50")

核心 CLI 命令

命令	用途
marimo edit notebook.py	marimo：在浏览器编辑器中打开 notebook，以便进行交互式开发
marimo run notebook.py	marimo：将 notebook 作为可执行应用运行
marimo check notebook.py	marimo：验证 notebook 的结构和语法，不执行 notebook
marimo convert notebook.ipynb	marimo：将 Jupyter notebook 转换为 marimo 格式

导出命令

# marimo: Export to ipynb with code only
marimo export ipynb notebook.py -o __marimo__/notebook.ipynb

# marimo: Export to ipynb with outputs (runs notebook first)
marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs

# marimo: Export to HTML (runs notebook by default)
marimo export html notebook.py -o __marimo__/notebook.html

# marimo: Export to HTML with auto-refresh on changes (live preview)
marimo export html notebook.py -o __marimo__/notebook.html --watch

**主要区别：**HTML 导出默认会运行 notebook。ipynb 导出不会运行——使用 --include-outputs 来运行并捕获输出。

**提示：**将所有导出文件（ipynb、html）放在 __marimo__/ 文件夹中。编辑器可以自动保存到该文件夹。

数据和可视化

• 出于性能考虑，优先使用 polars 而非 pandas
• 使用 mo.ui 创建交互式小组件
• SQL 单元格：mo.sql(df, "SELECT * FROM df")
• 显示 Markdown：mo.md("# Heading")

调试工作流

1. 执行前验证：

# scripts: Validate notebook syntax and cell structure
scripts/check_notebook.sh notebook.py

使用一条命令运行语法检查、marimo 验证和单元格结构概览。

**2. 运行时错误：**导出并包含输出，然后使用 notebook-debug 技能：

# marimo: Export to ipynb with outputs for inspection
marimo export ipynb notebook.py -o __marimo__/notebook.ipynb --include-outputs

常见问题

问题	修复方法
变量重定义	重命名一个变量或合并单元格
循环依赖	合并单元格或调整结构以打破循环
缺少返回值	添加 return var,，并在末尾加逗号
导入不可用	确保导入单元格返回该模块

更多资源

参考文件

如需了解详细模式和高级技巧，请参阅：

• references/reactivity.md - DAG 执行、变量规则、依赖检测模式
• references/debugging.md - 错误模式、运行时调试、特定环境问题
• references/widgets.md - 交互式 UI 组件和 mo.ui 模式
• references/sql.md - SQL 单元格和数据库集成技巧

示例

examples/ 中提供了可运行的示例：

• examples/basic_notebook.py - 最简 marimo 笔记本结构
• examples/data_analysis.py - 数据加载、筛选和可视化模式
• examples/interactive_widgets.py - 交互式 UI 组件用法

脚本

/scripts/ 中提供了验证工具：

• scripts/check_notebook.sh - 主要验证工具：语法检查、marimo 验证、单元格结构概览
• scripts/get_cell_map.py - 提取单元格元数据（由 check_notebook.sh 调用）

相关技能

• notebook-debug - 使用回溯信息和输出检查，调试已执行的 ipynb 文件