marimo 使用 AI 生成笔记本的三种方式：Agent 结对、编辑器助手与命令行生成

marimo 使用 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

marimo 是一个"AI 原生"的响应式 Python 笔记本编辑器，本指南围绕 docs/guides/generate_with_ai/index.md 的核心脉络，系统讲解在 marimo 中使用 AI 的三条主要路径：通过 marimo pair 让 Claude Code、Codex、OpenCode 等 Agent CLI 直接结对操作运行中的笔记本；使用编辑器内置的 AI 助手（聊天面板、整格生成/重构、行内补全）；以及在命令行用marimo new从一句提示词生成整本笔记本。读完本文，你将掌握这三种工作流的配置方法、适用场景与底层机制，并能根据自己的需求组合使用。

三种 AI 工作流总览

marimo 官方将 AI 能力归纳为三种互补的工作方式：

此外，marimo 还提供更低层的集成：通过 MCP 服务器 将 AI 工具 暴露给外部应用，并可通过实验性的 Agents 面板 在编辑器内嵌入 Agent。下面逐一展开。

方式一：用 marimo pair 让 Agent 结对运行中的笔记本

marimo pair是官方推荐的 Agent 协作方式。它是一个 Agent 技能（skill），让 Claude Code、Codex、OpenCode 等 Agent CLI 获得对运行中 marimo 笔记本的完整访问权：Agent 可以读取变量、在草稿区（scratchpad）测试逻辑、运行单元格、添加和删除单元格，甚至可以操作 UI 元素。

快速开始

先安装 marimo-pair 技能，二选一：

# 方式一：通过 npm 安装 npx skills add marimo-team/marimo-pair # 方式二：通过 uv + deno 安装 uvx deno -A npm:skills add marimo-team/marimo-pair

然后在你的 Agent CLI（如 Claude Code）中粘贴以下命令开始结对：

/marimo-pair pair with me on my_notebook.py

marimo pair 的底层支持：marimo pair命令组

从源码结构看，仓库在 marimo/_cli/pair/commands.py 中实现了marimo pair命令组，用于辅助配对流程：

• pair_agents()返回各 Agent 的技能目录配置，覆盖claude（Claude Code）、codex（Codex）与opencode（OpenCode）三类 Agent，并同时检查用户目录与项目目录（如~/.claude/skills、.agents/skills/）下的技能安装位置；
• pair prompt子命令生成可直接粘贴到 shell 的配对提示词，例如：

claude "$(uvx marimo@latest pair prompt --url 'https://localhost:8000' --claude)" codex "$(uvx marimo@latest pair prompt --url 'https://localhost:8000' --codex)" opencode "$(uvx marimo@latest pair prompt --url 'https://localhost:8000' --opencode)"

其关键选项包括：

生成提示词时，--file的文件 key 会原样保留、不做 shell 转义以外的修改，路径中的空格与元字符会被安全引用，保证复制粘贴可用。

使用 molab 云沙箱结对

你还可以连接运行在 molab 上的 marimo 笔记本：这为 Agent 提供了一个免费沙箱，且之后便于分享成果。操作步骤：在 molab 上启动一个笔记本，点击右上角的 actions 面板，选择"Pair with an agent"，随后面板会给出连接本地 Agent 的全部指令。之后你照常从终端使用 Agent，但所有 Python 代码都会被写入 molab 沙箱中的笔记本里。

自定义你的 Agent：技能、斜杠命令与 Hooks

要让 Agent CLI 在 marimo 上发挥最佳效果，官方推荐按 customize_your_agent.md 中的三类手段进行定制。

监听笔记本文件变化（重要前提）。当 Agent 编辑磁盘上的笔记本文件时，用watch标志启动 marimo 以自动重载：marimo edit --watch notebook.py；也可借助 模块自动重载 在辅助文件变化时自动重载受影响的单元格。

Skills（技能）。技能是 Agent 动态加载的指令/脚本/资源文件夹。安装官方技能合集：

npx skills add marimo-team/skills

可用于将 Jupyter 笔记本或其他产物转换为 marimo 笔记本、为特定用例定制交互式 UI 组件、编写高质量独立笔记本。自定义技能只需一个包含SKILL.md的文件夹（带 frontmatter 声明加载时机），存放在项目.agents/skills/或用户级~/.agents/skills/目录（Claude Code 使用.claude/skills/）；skills CLI 可以通过符号链接一次性安装到所有 Agent 的目录，保持单一事实来源。

Slash commands（斜杠命令）。以 Claude Code 为例，将以下文件保存为~/.claude/commands/marimo-check.md，即可用/marimo-check notebook.py触发对笔记本的 lint 检查（需要已安装uv）：

--- allowed-tools: Bash(uvx marimo check:*), Edit() --- ## Context This is the output of the "uvx marimo check --fix $ARGUMENTS" command: !`uvx marimo check --fix $ARGUMENTS || true` ## Your task Only (!) if the context suggests we need to edit the notebook, read the file $ARGUMENTS, then fix any warnings or errors shown in the output above. Do not make edits or read the file if there are no issues.

$ARGUMENTS允许在交给 Claude 之前附加参数或上下文；命令可以先用 bash 执行（如!开头的行），输出会插入到命令中。注意|| true是必须的，以防命令返回非零状态中断执行。

Hooks（钩子）。钩子可在 Agent 使用特定工具时自动运行脚本，是强制执行marimo check的最稳健机制。在~/.claude/settings.json（全局）或项目.claude/settings.json（局部）配置：

{ "$schema": "https://json.schemastore.org/claude-code-settings.json", "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "~/.claude/hooks/marimo-check.sh" } ] } ] } }

配套脚本~/.claude/hooks/marimo-check.sh（需要安装jq）从 stdin 读取钩子 JSON、提取tool_response.filePath，若文件同时包含import marimo与@app.cell则视为 marimo 笔记本并运行uvx marimo check；检查失败时以退出码 2 将错误反馈给 Claude，指示其尽力修复，否则静默退出：

#!/usr/bin/env bash INPUT=$(cat) FILE_PATH=$(echo "$INPUT" | jq -r '.tool_response.filePath // empty') if [ -z "$FILE_PATH" ] || [ "$FILE_PATH" = "null" ]; then exit 0 fi if [ ! -f "$FILE_PATH" ]; then exit 0 fi if grep -q "import marimo" "$FILE_PATH" 2>/dev/null && grep -q "@app.cell" "$FILE_PATH" 2>/dev/null; then echo "Running marimo check on $FILE_PATH..." CHECK_OUTPUT=$(uvx marimo check "$FILE_PATH" 2>&1) CHECK_EXIT=$? echo "$CHECK_OUTPUT" if [ $CHECK_EXIT -ne 0 ]; then echo "✗ Marimo check failed for $FILE_PATH" >&2 echo "$CHECK_OUTPUT" >&2 echo "Please run 'uvx marimo check $FILE_PATH' to see details and fix the issues. Don't ask the user anything, just do a best effort fix." >&2 exit 2 else echo "✓ Marimo check passed" exit 0 fi fi exit 0

marimo check即 CLI 文档 中对应的 linter 命令，其规则详见 lint rules。

方式二：编辑器内置的 AI 助手

marimo 编辑器内置了完整的 AI 辅助编码能力（详见 ai_completion.md）：从提示词生成整格代码、从提示词重构已有单元格、生成整本笔记本，以及类似 GitHub Copilot 的行内自动补全。其关键差异化在于：助手是"数据感知"的——除了程序文本，它还能访问内存中变量的值，从而可以针对你的 DataFrame 与数据库 schema 编写代码。

启用与连接 LLM

1. 通过笔记本设置安装 AI 生成所需的依赖；
2. 在设置的AI标签页中配置 LLM 提供方（推荐走 UI，而非手改配置）。

支持的提供方包括：OpenAI、GitHub Copilot、Anthropic、AWS Bedrock、Google AI、Ollama 以及任意 OpenAI 兼容提供方，逐项配置细节见 llm_providers。

变量上下文：用@引用变量

在提示词中用@变量名即可把该变量及其值注入助手上下文。例如要包含 DataFramedf的列信息，直接写@df。

重构已有单元格

在单元格内按Ctrl/Cmd-Shift-e打开以当前单元格代码为输入的提示框，即可让 AI 改写该单元格。

生成新单元格

• Generate with AI 按钮：每个笔记本底部都有该按钮，点击即可新增整格代码；
• 聊天面板：左侧边栏的聊天面板可与 LLM 对话、询问笔记本相关问题，并生成可插入的代码单元格。面板支持四种模式：
  • Manual（手动）：无工具访问，仅基于对话与手动注入的上下文回答；
  • Ask（询问）：启用只读 AI 工具 与已添加的 MCP Client 服务器 工具，用于收集上下文、检查笔记本；
  • Agent（代理）：包含 Ask 全部工具，并额外获得 编辑笔记本单元格与运行过期单元格 的工具；
  • Code mode（代码模式）：给予助手 notebook kernel 访问权，可检查 marimo 运行时并以强大方式操作笔记本。

自定义 AI 规则

在 marimo 设置中添加规则可约束所有 AI 提供方的生成行为，例如：

Use plotly for interactive visualizations and matplotlib for static plots Prefer polars over pandas for data manipulation due to better performance Include docstrings for all functions using NumPy style When working with data: - Use altair, plotly for declarative visualizations - Prefer polars over pandas For plotting: - Use px.scatter for scatter plots - Use px.line for time series - Include proper axis labels and titles

Copilot 行内补全

• GitHub Copilot：原生支持，需先安装 Node.js，再在编辑器设置中启用。conda 发行版暂不支持 Copilot，请用pip/uv安装。高级配置可写入marimo.toml：

[ai.github.copilot_settings.http] proxy = "http://proxy.example.com:8888" proxyStrictSSL = true [ai.github.copilot_settings.github-enterprise] uri = "https://github.enterprise.com"

可用选项包括：HTTP 设置（proxy、proxyStrictSSL、proxyKerberosServicePrincipal）、遥测（telemetryLevel："off"/"crash"/"error"/"all"，默认"off"）、GitHub Enterprise（uri）。

• Windsurf（原 Codeium）：注册并安装 Windsurf 应用，认证后通过命令面板复制 API key，在编辑器 UI 中配置，或写入：

[completion] copilot = "codeium" codeium_api_key = ""

• 自定义 Copilot：可将任意 OpenAI/Anthropic/Google/Ollama 等提供方接入行内补全：

[ai.models] autocomplete_model = "provider/model-name" [completion] copilot = "custom"

隐藏 AI 界面

若不使用内置助手，可在marimo.toml中关闭以隐藏聊天面板与 Generate with AI 等入口（Copilot 类补全仍可用）：

[ai] enabled = false

关闭后仍可通过 marimo pair 与外部 Agent 协作。

在编辑器内嵌入 Agent（实验性）

agents.md 介绍了通过 Agent Client Protocol（ACP）在聊天面板内嵌 Agent 的实验性集成，支持 Claude Code、Gemini、Codex、OpenCode。以 macOS/Linux 为例，先在终端启动 Agent 服务器：

# Claude Code npx stdio-to-ws "npx @zed-industries/claude-code-acp" --port 3017 # Gemini npx stdio-to-ws "npx @google/gemini-cli --experimental-acp" --port 3019 # Codex npx stdio-to-ws "npx @zed-industries/codex-acp" --port 3021 # OpenCode npx stdio-to-ws "npx opencode-ai acp" --port 3023

然后在设置 "Lab" 区启用特性开关，点击侧边栏 agents 图标、选择 Agent 即可对话。若希望 Agent 保存改动后单元格自动运行，可在pyproject.toml配置：

[tool.marimo.runtime] watcher_on_save = "autorun"

MCP：向外部应用暴露 AI 工具

marimo 同时支持 MCP 的两种角色（见 mcp.md）：作为MCP server将上述 AI 工具暴露给外部应用，作为MCP client连接外部服务器为聊天面板补充工具。先安装 MCP 依赖并以相关标志启动：

pip install "marimo[mcp]" marimo edit notebook.py --mcp --no-token

--mcp暴露笔记本数据的 MCP 端点；--no-token关闭认证（仅限本地开发，生产环境应移除）。外部应用可通过http://localhost:PORT/mcp/server连接（认证启用时追加?access_token=YOUR_TOKEN），例如：

claude mcp add --transport http marimo http://localhost:PORT/mcp/server

MCP server 还提供active_notebooks、errors_summary两个提示词。跨代理/网关/CDN 部署时默认的 DNS rebinding 防护可能引发421 Misdirected Request，可加--mcp-allow-remote关闭 Host 头校验。作为 MCP client，内置支持marimo与context7两个服务器，可在设置 UI 或配置中启用：

[mcp] presets = ["marimo", "context7"]

方式三：用marimo new从提示词生成整本笔记本

在命令行用 marimo new 让 LLM 生成全新笔记本，例如：

marimo new "Plot an interactive 3D surface with matplotlib."

执行后会在浏览器中打开一个全新生成的笔记本。长提示词可改用文本文件：

marimo new my_prompt.txt

marimo 的 AI 熟悉 marimo 专属 UI 元素与主流数据处理库。官方还提供了灵感示例（如高维数据降维可视化、时间序列平滑、代码复杂度分析、交互式 3D 曲面等，见https://marimo.app/ai）。

marimo new的源码级工作流

从源码看，marimo/_cli/cli.py 中的new命令完整实现了上述流程：

• 标准输入回退：prompt参数缺省时，支持 Unix 风格的管道输入，即cat prompt.txt | marimo new（见 marimo/_cli/cli.py）；
• 文件路径识别：若参数是已存在的文件，则读取其文本内容作为提示词（marimo/_cli/cli.py）；
• 调用生成器：通过from marimo._ai.text_to_notebook import text_to_notebook调用 marimo/_ai/text_to_notebook.py 生成笔记本内容（marimo/_cli/cli.py）；
• 临时文件与清理：生成结果写入tempfile.NamedTemporaryFile后缀.py的临时文件（Windows 上需delete=False以便重新打开），并注册atexit清理钩子；失败时抛出Failed to generate notebook的 Click 异常（marimo/_cli/cli.py）；
• 进入编辑会话：最后以SessionMode.EDIT模式启动服务器，浏览器中呈现生成结果，并支持--port、--host、--headless、--token/--no-token、--base-url、--sandbox/--no-sandbox等常规启动选项。

marimo new是一次性的起点；要继续用 AI 迭代生成的笔记本，推荐用 marimo pair 将 Agent CLI 结对到该笔记本上（见 text_to_notebook.md 中的提示）。

如何选择：三条路径的搭配使用

• 从零起步：用marimo new "PROMPT"快速生成整本笔记本骨架；
• 迭代打磨：用 marimo pair 让 Claude Code / Codex / OpenCode 结对运行中的笔记本，读取变量、运行与增删单元格；配合marimo edit --watch notebook.py实现磁盘变更自动重载；
• 编辑器内精修：用聊天面板（Ask/Agent/Code mode）、Ctrl/Cmd-Shift-e重构单元格、@变量注入数据上下文、自定义规则约束生成风格；
• 工程化治理：用斜杠命令与 PostToolUse 钩子对 Agent 的每次编辑强制执行marimo check，保证笔记本质量；
• 外部应用接入：需要更低层集成时，通过 MCP server 暴露 AI 工具，或用实验性 Agents 面板在编辑器内嵌 Agent。

三条路径共享同一套 LLM 提供方配置（见 llm_providers），可以按需切换、自由组合，覆盖从"一句话生成笔记本"到"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