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/marimomarimo 是一套面向数据与 AI 原生的响应式 Python Notebook 框架其编辑器内置了一套AI ToolsAI 工具用于让 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-L65MCP 客户端工具同样默认在 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-L459as_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.summarytotal_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_typecode/markdown/sql从编译后单元格的语言与mo.md(前缀综合判断见 cells.py#L236-L259runtime_state运行时状态取值为idle已执行且静止含出错单元格、running正在执行、queued等待运行中的依赖、disabled-transitively因父单元格被禁用而禁用未执行过的单元格为nullhas_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错误详情列表类型、消息、tracebackmetadataruntime_state与execution_time最近一次执行耗时单位毫秒仅当runtime_state idle时填充因为运行期间存储的是启动时间戳直接返回会造成误解见 cells.py#L357-L379variables该单元格定义的变量及其当前值源码通过单元格的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_mimetypeMIME 类型错误输出会被转换为结构化 JSONapplication/json见 cells.py#L475-L513console_outputsstdout与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。返回GetCellDependencyGraphOutputcells单元格依赖信息——defs定义的变量含 kind 与运行时类型 datatype、refs引用的变量、parent_cell_ids/child_cell_ids父/子单元格variable_owners变量归属映射变量名 → 定义它的单元格列表multiply_defined被多个单元格重复定义的变量列表对应 lint 规则 MB002cycles依赖环信息cell_ids与edges边列表。实现上直接复用 marimo 运行时内核的DirectedGraph来自 marimo/_runtime/dataflow/graph.py。值得注意的细节app.graph在遇到环或重复定义时会抛异常而该工具恰恰以报告这些问题为使命因此实现中会捕获CycleError/MultipleDefinitionError后继续使用图数据见 dependency_graph.py#L104-L119。若 notebook 存在语法错误UnparsableError则直接报UNPARSABLE_NOTEBOOK要求先修复语法。使用时机在编辑引用共享变量的单元格之前、诊断 MB002 错误时、理解数据流结构与执行顺序时、需要知道某个变量属于哪个单元格时。数据类工具Dataget_tables_and_variables获取会话中的变量与数据表信息。参数session_id、variable_names列表空列表返回全部。返回TablesAndVariablesOutputtables表名 →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、tableDataTable 详情以及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。调试类工具Debuggingget_notebook_errors获取 notebook 中所有错误按单元格组织。参数session_id。返回GetNotebookErrorsOutputhas_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。返回LintNotebookOutputsummary按严重级别统计与diagnostics完整诊断列表。严重级别分三类见 marimo/_lint/diagnostic.py 的SeverityBreaking阻断性阻止 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 工具。参考类工具Referenceget_marimo_rules获取面向 AI 助手的官方 marimo 指南与最佳实践。无参数。返回GetMarimoRulesOutputrules_content规则文件内容与source_url。实现优先读取随包分发的规则文件marimo/_static/CLAUDE.md见 rules.py#L14-L17读取失败时回退到在线 URL 拉取两者都失败则返回statuserror与排查建议见 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 capabilitiesmarimo 会根据你安装的包和你使用的模型自动启用最合适的实现。能力启用方式marimo 为每项能力选择最佳可用选项能力本地回退安装在你的环境中原生模型提供商支持时Web 搜索安装ddgs时使用 DuckDuckGo 搜索提供商原生 Web 搜索如 Anthropic、OpenAI ResponsesWeb 抓取安装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按需参考改进、优化或清理现有 notebookrich-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_loadingTrue指令内容由 marimo/_server/ai/skills/utils.py 的load_reference读取。Code mode 会以marimo pair技能作为系统提示词加载详见 marimo_pair.md因此助手遵循与外部 Agent CLI 配对到你的 notebook 时相同的约定。相关文档Model Context ProtocolMCP了解如何通过 marimo MCP 服务器向外部应用暴露工具Ask/Agent 只读工具以及如何为聊天面板配置 MCP 客户端AI 辅助编码了解更多 AI 编码功能包括聊天面板各模式、变量上下文、marimo new PROMPT生成整本 notebook 等LLM 提供商配置配置 OpenAI、Anthropic、Ollama、xAI 等提供商是启用聊天面板与 AI 工具的前提【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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/marimomarimo 是一套面向数据与 AI 原生的响应式 Python Notebook 框架其编辑器内置了一套AI ToolsAI 工具用于让 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-L65MCP 客户端工具同样默认在 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-L459as_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.summarytotal_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_typecode/markdown/sql从编译后单元格的语言与mo.md(前缀综合判断见 cells.py#L236-L259runtime_state运行时状态取值为idle已执行且静止含出错单元格、running正在执行、queued等待运行中的依赖、disabled-transitively因父单元格被禁用而禁用未执行过的单元格为nullhas_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错误详情列表类型、消息、tracebackmetadataruntime_state与execution_time最近一次执行耗时单位毫秒仅当runtime_state idle时填充因为运行期间存储的是启动时间戳直接返回会造成误解见 cells.py#L357-L379variables该单元格定义的变量及其当前值源码通过单元格的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_mimetypeMIME 类型错误输出会被转换为结构化 JSONapplication/json见 cells.py#L475-L513console_outputsstdout与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。返回GetCellDependencyGraphOutputcells单元格依赖信息——defs定义的变量含 kind 与运行时类型 datatype、refs引用的变量、parent_cell_ids/child_cell_ids父/子单元格variable_owners变量归属映射变量名 → 定义它的单元格列表multiply_defined被多个单元格重复定义的变量列表对应 lint 规则 MB002cycles依赖环信息cell_ids与edges边列表。实现上直接复用 marimo 运行时内核的DirectedGraph来自 marimo/_runtime/dataflow/graph.py。值得注意的细节app.graph在遇到环或重复定义时会抛异常而该工具恰恰以报告这些问题为使命因此实现中会捕获CycleError/MultipleDefinitionError后继续使用图数据见 dependency_graph.py#L104-L119。若 notebook 存在语法错误UnparsableError则直接报UNPARSABLE_NOTEBOOK要求先修复语法。使用时机在编辑引用共享变量的单元格之前、诊断 MB002 错误时、理解数据流结构与执行顺序时、需要知道某个变量属于哪个单元格时。数据类工具Dataget_tables_and_variables获取会话中的变量与数据表信息。参数session_id、variable_names列表空列表返回全部。返回TablesAndVariablesOutputtables表名 →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、tableDataTable 详情以及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。调试类工具Debuggingget_notebook_errors获取 notebook 中所有错误按单元格组织。参数session_id。返回GetNotebookErrorsOutputhas_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。返回LintNotebookOutputsummary按严重级别统计与diagnostics完整诊断列表。严重级别分三类见 marimo/_lint/diagnostic.py 的SeverityBreaking阻断性阻止 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 工具。参考类工具Referenceget_marimo_rules获取面向 AI 助手的官方 marimo 指南与最佳实践。无参数。返回GetMarimoRulesOutputrules_content规则文件内容与source_url。实现优先读取随包分发的规则文件marimo/_static/CLAUDE.md见 rules.py#L14-L17读取失败时回退到在线 URL 拉取两者都失败则返回statuserror与排查建议见 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 capabilitiesmarimo 会根据你安装的包和你使用的模型自动启用最合适的实现。能力启用方式marimo 为每项能力选择最佳可用选项能力本地回退安装在你的环境中原生模型提供商支持时Web 搜索安装ddgs时使用 DuckDuckGo 搜索提供商原生 Web 搜索如 Anthropic、OpenAI ResponsesWeb 抓取安装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按需参考改进、优化或清理现有 notebookrich-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_loadingTrue指令内容由 marimo/_server/ai/skills/utils.py 的load_reference读取。Code mode 会以marimo pair技能作为系统提示词加载详见 marimo_pair.md因此助手遵循与外部 Agent CLI 配对到你的 notebook 时相同的约定。相关文档Model Context ProtocolMCP了解如何通过 marimo MCP 服务器向外部应用暴露工具Ask/Agent 只读工具以及如何为聊天面板配置 MCP 客户端AI 辅助编码了解更多 AI 编码功能包括聊天面板各模式、变量上下文、marimo new PROMPT生成整本 notebook 等LLM 提供商配置配置 OpenAI、Anthropic、Ollama、xAI 等提供商是启用聊天面板与 AI 工具的前提【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考