用途:marimo 是响应式 Python 笔记本,单元格组成 DAG,依赖变化时自动执行,笔记本以纯 .py 文件保存,便于版本控制。本技能在编辑任何含 @app.cell 或 marimo.App 的 .py 文件前加载,规范编辑与验证流程。
主要能力与规则:只允许修改 @app.cell 函数体内的代码,不得改动单元格装饰器、函数签名与返回结构;单值返回需保留尾随逗号(return var,)。每个变量只能在一个单元格中定义,所有使用的变量须在函数参数中,所有创建的变量须在返回语句中。Markdown 单元格中 $ 需用反引号包裹,数字与量词(all、every、none 等)应基于数据用 f-string 生成。import marimo 须位于文件前约 400 字节内,否则笔记本仍可运行但不会出现在工作区列表中。
使用方式:常用命令包括 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(运行并捕获输出)、marimo export html notebook.py -o marimo/notebook.html(默认运行)。HTML 导出默认执行笔记本,ipynb 导出默认不执行,需加 --include-outputs。验证流程为:编辑、marimo check、带 --include-outputs 导出、检查输出、确认无误后再声称可用。
适用场景与限制:适合交互式开发、可执行应用、Jupyter 转换与导出。marimo check 只校验语法结构、不执行单元格;响应式传播可能影响下游单元格,仅验证被编辑单元格会遗漏问题。数据文件重新生成不会改变变量,运行时不会自动重跑,需手动重跑所有单元格。会话运行期间不要直接写 .py 文件,应通过 marimo-pair 修改。远程主机默认绑定 127.0.0.1,可绑定 Tailscale 地址;使用 --no-token 时绑定地址即访问控制,不应使用 0.0.0.0。导出会重写源 .py 的修改时间。