用途:marimo 是响应式 Python 笔记本,单元(cell)构成有向无环图(DAG),依赖变化时自动执行,笔记本以纯 .py 文件存储,便于版本控制。该技能用于创建、检查、调试 marimo 笔记本并理解其响应式机制。
主要能力:响应式执行,单元随依赖自动更新;无隐藏状态,每个变量只在一个单元中定义;单元采用 @app.cell 装饰器结构;支持 mo.ui 交互组件、mo.sql 执行 SQL、mo.md 显示 Markdown,数据与可视化建议优先使用 polars。
必要用法:只编辑 @app.cell 函数体内部代码,不得修改单元装饰器或函数签名;所有使用变量须列在函数参数中,所有创建变量须出现在 return 语句,单一返回须带尾逗号 return var,;同一变量不可跨单元重定义。常用命令:marimo edit notebook.py 浏览编辑,marimo run notebook.py 作为应用运行,marimo check notebook.py 校验结构与语法,marimo convert notebook.ipynb 转换格式。导出:marimo export ipynb notebook.py -o marimo/notebook.ipynb --include-outputs(ipynb 默认不执行,需加 --include-outputs);marimo export html notebook.py -o marimo/notebook.html(HTML 默认执行);--watch 可自动刷新。
验证流程:先编辑,再 marimo check notebook.py,然后执行导出并检查输出,确认无 traceback、所有单元均执行、输出符合预期后才可声称可用。
适用场景:数据加载、过滤与可视化,交互式 UI,SQL 单元格,以及需要响应式依赖追踪与版本控制友好的 Python 笔记本。
限制:在 Markdown 单元中须将 $ 用反引号包裹,如 mo.md("Cost: $50");常见问题包括变量重定义、循环依赖、缺少 return、导入单元未返回模块。参考资料见 references/ 下的 reactivity.md、debugging.md、widgets.md、sql.md,示例见 examples/,校验脚本为 scripts/check_notebook.sh,相关技能为 notebook-debug。