marimo AI Tools 完全指南：让 AI 助手读写 Notebook 的工具集与实现原理-编程实验室

marimo AI Tools 完全指南：让 AI 助手读写 Notebook 的工具集与实现原理

【免费下载链接】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 Notebook 框架，其编辑器内置了一套AI Tools（AI 工具），用于让 AI 助手读取 notebook 内容、检查单元格运行时数据、访问内存变量、定位错误甚至直接修改 notebook。本指南以官方文档 docs/guides/editor_features/tools.md 为骨架，结合仓库中 marimo/_ai/_tools 与 marimo/_server/ai 的源码实现，系统讲解每个工具的参数、输出结构、底层调用链与适用场景，帮助你理解并善用 marimo 的 AI 协作能力。

实验性功能警告：Tools 目前处于实验阶段并在积极开发中，工具定义与可用性可能发生变化，请以当前安装版本为准。

工具可用性与聊天面板模式

AI 工具的可用范围取决于你使用的聊天面板模式（Chat Panel Mode）。marimo 编辑器左侧边栏的聊天面板支持四种模式，详见 ai_completion.md：

模式	Marimo Notebook 工具
Manual（手动）	无工具访问，AI 仅基于对话与手动注入的上下文回答
Ask（询问）	只读的检查、数据、调试与参考工具
Agent（代理）	Ask 模式的全部工具，外加编辑工具
Code mode（代码模式）	代码执行工具与按需参考指南（见下文）

此外，外部 AI 应用也可以通过marimo MCP 服务器访问Ask与Agent模式的 Notebook 工具，详见 mcp.md。

从源码看，模式与工具的绑定由 marimo/_server/ai/tools/tool_manager.py 中的ToolManager.get_tools_for_mode(mode)实现：后端工具在注册时声明mode=["ask", "agent"]（见 tool_manager.py#L54-L65），MCP 客户端工具同样默认在 ask/agent 模式下开放；查询时按mode in tool.mode过滤。所有 10 个后端工具统一登记在 marimo/_ai/_tools/tools_registry.py 的SUPPORTED_BACKEND_AND_MCP_TOOLS列表中，实现"一套定义、双端注册"（后端编辑器 + MCP 服务器）。

工具基础设施：ToolBase 基类

在逐个介绍工具之前，有必要先理解它们的共同基类 marimo/_ai/_tools/base.py 中的ToolBase：

每个工具都是一个ToolBase[ArgsModel, OutputModel]子类，通过泛型参数声明输入（Args）与输出（Output）数据类，基类的__init_subclass__会自动提取这两个类型；
工具名默认由类名转 snake_case（如GetActiveNotebooks→get_active_notebooks），描述默认取类 docstring，并可通过ToolGuidelines追加"When to use / Avoid if / Prerequisites / Side effects / Additional info"结构化指引（见 base.py#L433-L459）；
as_backend_tool(mode)将工具转换为后端使用的ToolDefinition+ 参数校验函数，输入 Schema 通过PythonTypeToOpenAPI从 Args 数据类自动推导；
as_mcp_tool_fn()返回可直接注册到 MCP 的带类型标注的异步函数，输出为 dataclass 时自动转 dict，保证 JSON 可序列化；
统一的__call__会先做参数强制转换与校验，再把意外异常包装成标准化的ToolExecutionError（含code、is_retryable、suggested_fix、meta字段），便于 AI 助手理解并重试。

ToolContext提供了会话级访问能力：get_session(session_id)按会话 ID 取会话（找不到时报SESSION_NOT_FOUND，并建议先用get_active_notebooks获取合法 ID）、get_notebook_errors按 notebook 顺序聚合各单元格错误、get_cell_console_outputs从单元格通知中分离 stdout/stderr（见 base.py#L56-L260）。

检查类工具（Inspection）

检查类工具是 AI 助手"认识" notebook 的入口，全部只读，Ask 与 Agent 模式均可使用。

get_active_notebooks

列出当前所有活动的 marimo notebook，返回汇总统计与 notebook 详情（名称、路径、会话 ID）。这是所有工具调用的起点——先发现有哪些 notebook 可用，再拿到session_id去操作具体会话。

实现位于 marimo/_ai/_tools/tools/notebooks.py：

无参数（EmptyArgs）；
输出GetActiveNotebooksOutput，含data.summary（total_notebooks总 notebook 数、active_connections活跃连接数）与data.notebooks列表（name、path、session_id）；
内部通过ToolContext.get_active_sessions_internal()遍历 session manager，只统计连接状态为OPEN或ORPHANED的会话，未保存的 notebook 路径会显示为(unsaved notebook - save to disk to get file path)，结果按最近使用倒序返回（见 base.py#L104-L134）；
使用指引建议：在开始任何 notebook 交互前调用以获取 session ID；收到会话相关错误时也应先调用此工具。其返回的next_steps会引导下一步使用get_lightweight_cell_map获取 notebook 内容、或get_notebook_errors调试错误。

get_lightweight_cell_map

获取 notebook 结构概览，展示每个单元格的预览文本，用于初始导航。参数：session_id，可选preview_lines（每单元格展示行数，默认 3，源码中限制在 1–50 之间，见 cells.py#L171-L172）。

返回GetLightweightCellMapOutput，其中cells列表的每个LightweightCellInfo包含：

cell_id：单元格 ID（供后续工具引用）；
preview：前preview_lines行代码预览；
line_count：单元格总行数；
cell_type：code/markdown/sql（从编译后单元格的语言与mo.md(前缀综合判断，见 cells.py#L236-L259）；
runtime_state：运行时状态，取值为idle（已执行且静止，含出错单元格）、running（正在执行）、queued（等待运行中的依赖）、disabled-transitively（因父单元格被禁用而禁用），未执行过的单元格为null；
has_output/has_console_output/has_errors：是否含可视化输出、控制台输出、错误。

返回结果的message字段会提醒 AI：与用户交流时应按序数格式@[cell:1]引用单元格，不要使用 cell_id。

get_cell_runtime_data

获取一个或多个单元格的详细运行时信息。参数：session_id、cell_ids（列表；传空列表表示返回全部单元格，见 cells.py#L307-L311）。

每个单元格的GetCellRuntimeDataData包含：

code：完整单元格代码；
errors：错误详情列表（类型、消息、traceback）；
metadata：runtime_state与execution_time（最近一次执行耗时，单位毫秒；仅当runtime_state == "idle"时填充，因为运行期间存储的是启动时间戳，直接返回会造成误解，见 cells.py#L357-L379）；
variables：该单元格定义的变量及其当前值（源码通过单元格的defs与 session view 的variable_values交叉过滤得到，见 cells.py#L381-L402）。

使用时机：检查某个单元格的代码、错误或变量；从 cell map 定位感兴趣单元格之后。若cell_id不存在，会抛出CELL_NOT_FOUND错误并建议先用get_lightweight_cell_map找合法 ID。

get_cell_outputs

获取一个或多个单元格的执行输出。参数：session_id、cell_ids（空列表 = 全部单元格）。

每个单元格的CellOutputData包含：

visual_output：可视化输出内容（HTML、图表、表格等）与visual_mimetype（MIME 类型）；错误输出会被转换为结构化 JSON（application/json），见 cells.py#L475-L513；
console_outputs：stdout与stderr消息列表，从单元格通知中按输出通道分离并清洗（见 base.py#L230-L260）。

使用时机：需要查看单元格展示了什么、打印了什么，或回顾图表、可视化、Markdown、HTML 与控制台输出。

get_cell_dependency_graph

获取单元格依赖图，展示变量归属与单元格之间的关系。参数：session_id，可选cell_id（以某单元格为中心）与depth（从中心向外遍历的跳数，1 = 直接父/子，2 = 两跳，以此类推；不传则返回完整传递闭包；depth必须配合cell_id使用且非负，否则报BAD_ARGUMENTS，见 dependency_graph.py#L121-L136）。

返回GetCellDependencyGraphOutput：

cells：单元格依赖信息——defs（定义的变量，含 kind 与运行时类型 datatype）、refs（引用的变量）、parent_cell_ids/child_cell_ids（父/子单元格）；
variable_owners：变量归属映射（变量名 → 定义它的单元格列表）；
multiply_defined：被多个单元格重复定义的变量列表（对应 lint 规则 MB002）；
cycles：依赖环信息（cell_ids与edges边列表）。

实现上直接复用 marimo 运行时内核的DirectedGraph（来自 marimo/_runtime/dataflow/graph.py）。值得注意的细节：app.graph在遇到环或重复定义时会抛异常，而该工具恰恰以"报告这些问题"为使命，因此实现中会捕获CycleError/MultipleDefinitionError后继续使用图数据（见 dependency_graph.py#L104-L119）。若 notebook 存在语法错误（UnparsableError），则直接报UNPARSABLE_NOTEBOOK，要求先修复语法。

使用时机：在编辑引用共享变量的单元格之前、诊断 MB002 错误时、理解数据流结构与执行顺序时、需要知道某个变量属于哪个单元格时。

数据类工具（Data）

get_tables_and_variables

获取会话中的变量与数据表信息。参数：session_id、variable_names（列表，空列表返回全部）。

返回TablesAndVariablesOutput：

tables：表名 →DataTableMetadata，包含source（数据来源/方言）、num_rows、num_columns、columns（列信息）、primary_keys（主键）、indexes（索引）、engine（引擎或连接处理器）；
variables：变量名 →VariableValue（值 + 数据类型 datatype）。

实现直接从 session view 的datasets.tables与variable_values中过滤（见 tables_and_variables.py#L79-L122）。使用时机：检查内存中的 DataFrame 或 Python 变量、在建议数据操作前了解可用数据。注意其avoid_if指引：若用户询问的是数据库表/数据源，应改用get_database_tables。

get_database_tables

获取数据库 Schema 信息，支持可选的正则查询过滤。参数：session_id，可选query（支持正则，对数据库、Schema、表名做模糊匹配；不传则返回所有表）。

返回GetDatabaseTablesOutput.tables，每个TableDetails含connection（连接名）、database、schema、table（DataTable 详情）以及sample_query（自动生成的示例 SQL）。示例查询会根据是否为默认数据库/默认 Schema 逐级缩短限定名，并为非内置 DuckDB 引擎自动包装成df = mo.sql(f"""...""", engine=...)形式（见 datasource.py#L156-L178）。

实现遍历 session view 的data_connectors，若没有任何数据库连接则报NO_DATABASES_FOUND，提示先创建连接（见 datasource.py#L83-L88）。官方指引建议：为了不遗漏表，最好不传 query；若传则使用宽松的正则（兼容大小写与单复数形式）。使用时机：探索外部连接的数据库表、在编写 SQL 前理解 Schema。

调试类工具（Debugging）

get_notebook_errors

获取 notebook 中所有错误，按单元格组织。参数：session_id。

返回GetNotebookErrorsOutput：has_errors、total_errors（错误总数）、total_cells_with_errors（出错单元格数）、cells（每个MarimoCellErrors含cell_id、errors（类型、消息、traceback）、stderr）。

实现基于 session view 的cell_notifications，只收集输出通道为MARIMO_ERROR的通知，并按 notebook 实际顺序（通过cell_manager.cell_data()）重排（见 errors.py 与 base.py#L136-L228）。使用时机：用户报告 notebook 出错、或调试/修复损坏单元格之前。若存在错误，其next_steps会引导用get_cell_runtime_data深入检查受影响单元格。

lint_notebook

获取 notebook 中所有 marimo lint 诊断。参数：session_id。

返回LintNotebookOutput：summary（按严重级别统计）与diagnostics（完整诊断列表）。严重级别分三类（见 marimo/_lint/diagnostic.py 的Severity）：

Breaking（阻断性）：阻止 notebook 正常运行的问题；
Runtime（运行时）：可能导致意外行为的问题；
Formatting（格式）：代码风格与格式问题。

实现调用 marimo 内置的 lint 引擎RuleEngine.create_default().check_notebook(notebook_ir)，对 notebook 的 IR 做纯静态分析、不执行代码（见 lint.py#L71-L88）。所有 lint 规则的完整说明见 docs/guides/lint_rules/index.md。

使用指引特别强调：在 AI 对 notebook 做任何编辑、增删单元格或改动之后，必须 ALWAYS 调用此工具验证是否引入了新问题；同时要求 AI 使用 marimo 自己的 lint 工具而非默认的 lint 工具。

参考类工具（Reference）

get_marimo_rules

获取面向 AI 助手的官方 marimo 指南与最佳实践。无参数。

返回GetMarimoRulesOutput：rules_content（规则文件内容）与source_url。实现优先读取随包分发的规则文件marimo/_static/CLAUDE.md（见 rules.py#L14-L17），读取失败时回退到在线 URL 拉取，两者都失败则返回status="error"与排查建议（见 rules.py#L42-L93）。

使用指引：在调用其他 marimo 工具、读取或写入 notebook 之前，ALWAYS 先调用此工具以理解 marimo 的工作方式；若最近已获取过（规则很少变动）则可跳过。

编辑类工具（Editing，仅 Agent 模式）

以下工具仅在聊天面板的 Agent 模式下可用，不会通过 MCP 服务器暴露。这保证了外部 MCP 客户端只能进行只读操作。

工具	说明
edit_notebook	添加、删除或更新 notebook 中的单元格。接收单元格操作与修改参数，允许 AI 生成 diff 来修改 notebook 结构与内容
run_stale_cells	运行已过时（因上游变更而失效）的单元格，触发受影响单元格的执行以更新 notebook 状态

从源码层面看，"运行过时单元格"的能力对应内核的run_stale_cells（见 marimo/_runtime/runtime.py#L1880-L1881），该能力也被模块热重载（module autoreloading）复用（见 marimo/_runtime/reload/manager.py）。结合 marimo/_server/ai/prompts.py 的 Agent 模式提示词可知，Agent 被要求"编辑 notebook 后执行一组动作"来保持 notebook 一致，这正是run_stale_cells的用武之地。

Web 搜索与网页抓取（Web search and fetch）

在任意聊天面板模式（Manual、Ask、Agent、Code mode）下，marimo 都可以赋予助手 Web 搜索与 URL 抓取能力。这些是 Pydantic AI 的提供商自适应能力（provider-adaptive capabilities）：marimo 会根据你安装的包和你使用的模型，自动启用最合适的实现。

能力启用方式

marimo 为每项能力选择最佳可用选项：

能力	本地回退（安装在你的环境中）	原生（模型提供商支持时）
Web 搜索	安装`ddgs`时使用 DuckDuckGo 搜索	提供商原生 Web 搜索（如 Anthropic、OpenAI Responses）
Web 抓取	安装`markdownify`时使用 URL 抓取	提供商原生 Web 抓取
X 搜索	—	支持原生 X 搜索的 xAI 模型

本地回退在其对应包已安装时优先；否则，当所配置模型支持时使用提供商的原生工具。

安装本地 Web 搜索与抓取

要让任何模型（包括 Ollama 托管的本地模型）都能使用 Web 搜索与抓取，安装 Pydantic AI 的可选扩展即可：

pip install "pydantic-ai-slim[duckduckgo,web-fetch]"

使用提供商原生工具

当本地包未安装时，只有模型支持才会启用原生工具。例如：

Anthropic与OpenAI Responses模型可使用原生 Web 搜索与 Web 抓取；
xAI模型（如xai/grok-2-latest）可使用原生 Web 搜索与 X 搜索。

xAI 提供商可在marimo.toml或 notebook 设置中配置，详见 llm_providers.md#xai（该指南的 OpenAI-compatible 自定义提供商章节也适用于接入 xAI 这类 OpenAI 兼容接口）。

Code mode：直接访问内核的代码执行工具

!!! warning "实验性" Code mode 让助手直接访问 notebook 的内核，可对 notebook 做出破坏性更改，请谨慎使用。

Code mode 可通过聊天面板的模式选择器启用。与上面"检查 + 编辑"的工具集不同，Code mode 下的助手使用另一套围绕"在活动内核中运行 Python"的工具：

工具 / 能力	说明
execute_code	在 notebook 内核的 scratchpad 中运行 Python。助手用它完成所有 notebook 变更——添加单元格、更新代码、检查变量、运行逻辑
gotchas	按需参考：名称重定义、缓存模块代理（cached module proxies）及其他 notebook 陷阱
notebook-improvements	按需参考：改进、优化或清理现有 notebook
rich-representations	按需参考：自定义组件、视觉编码与交互式输出

实现上，execute_code由 marimo/_server/ai/tools/code_mode.py 的build_execute_code_toolset构建：它绑定到调用者的会话与请求（模型不感知 session id），内部通过run_scratchpad_code将代码送入内核 scratchpad 执行，执行结果（success、output、stdout、stderr、errors）以 CodeExecutionResult 结构返回。三个"按需参考"能力通过references_capability()以Capability形式按需加载（defer_loading=True），指令内容由 marimo/_server/ai/skills/utils.py 的load_reference读取。