Available tools【免费下载链接】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[Appropriate Category]ToolDescriptionyour_tool_nameBrief description of what the tool does. Takesparam1andparam2parameters. Returns description of output.选择合适分类 - **Inspection检查**用于探索笔记本结构与运行时状态的工具 - **Data数据**用于访问变量与数据库信息的工具 - **Debugging调试**用于发现和修复问题的工具 - **Reference参考**用于访问 marimo 文档的工具。 仓库中 [tools.md](https://link.gitcode.com/i/1f3709b3fc01e04fabec6e588cdcd263) 目前按此四类组织了 10 个内置工具的描述另有 Agent 模式专属的编辑类工具与 Code mode 工具集。注意该页面顶部标注了Experimental警告——工具定义与可用性仍处于活跃开发中。 ## 十三、最佳实践 ### 类型安全 - 所有输入/输出类型**使用 dataclass** - 所有方法与属性**添加类型注解** - 仅类型检查需要的导入放在 if TYPE_CHECKING: 块内如 Session 仅作类型提示 - 从 marimo 类型系统导入SessionId、CellId_t 等 - 类型定义**保留在工具文件中**除非被多个工具共享——只有被大量文件复用时才考虑放入 [types.py](https://link.gitcode.com/i/ea8e3168904cdd1cb7427fb6b0ed500b)。 ### 文档 - 遵循模板编写清晰的 docstring它会被用作 AI 助手看到的工具描述 - 在类 docstring 中记录**所有 Args** - 在类 docstring 中描述 **Returns** - 提供 **ToolGuidelines** 帮助 AI 助手 - 需要时在 docstring 中包含示例。 ### 输出设计 python return YourToolOutput( dataresult, # Provide actionable next steps next_steps[ Use get_cell_runtime_data to inspect cells, Check errors with get_notebook_errors, ], # Optional user-facing message messageFound 5 items matching your query, # Optional metadata meta{query_time: 0.5}, )Helper 方法私有方法用_前缀handle()保持聚焦于编排复杂逻辑抽取为 helper 方法复用 ToolContext 方法而非重复实现逻辑。十四、常见陷阱Common Pitfalls❌ 不要重复实现 ToolContext 逻辑# Bad: Reimplementing context logic def handle(self, args: Args) - Output: session self.context.get_session(args.session_id) cell_notifications session.session_view.cell_notifications errors [] for cell_id, op in cell_notifications.items(): if op.output and op.output.channel CellChannel.MARIMO_ERROR: errors.append(...) # Duplicating error extraction✅ 应该使用 ToolContext 方法# Good: Using context methods def handle(self, args: Args) - Output: errors self.context.get_notebook_errors( args.session_id, include_stderrTrue )❌ 不要抛出通用异常# Bad: Using generic exceptions if not found: raise ValueError(Not found)✅ 应该抛出 ToolExecutionError# Good: Structured error with metadata if not found: raise ToolExecutionError( Cell not found in session, codeCELL_NOT_FOUND, is_retryableFalse, suggested_fixUse get_lightweight_cell_map to find valid cell IDs, )❌ 不要返回非结构化数据# Bad: Returning raw data def handle(self, args: Args) - Output: return {data: [...], count: 5} # type: ignore✅ 应该使用类型化 dataclass 输出# Good: Structured output with SuccessResult def handle(self, args: Args) - Output: return YourToolOutput( data[...], count5, next_steps[Review the results], )❌ 不要使用 TypedDict 或其他类型注解# Bad: Using TypedDict for tool input/output from typing import TypedDict class YourToolArgs(TypedDict): session_id: str count: int✅ 应该使用 dataclass# Good: Using dataclasses as required from dataclasses import dataclass dataclass class YourToolArgs: session_id: SessionId count: int 0为什么工具系统要求 dataclass 以保证正确的序列化、验证以及与后端和 MCP 两个上下文的兼容性。参数转换parse_raw、OpenAPI schema 生成PythonTypeToOpenAPI与 MCP 的 pydantic 互操作都依赖这一约定。十五、进阶主题异步工具对于需要 async/await 的操作class AsyncTool(ToolBase[Args, Output]): Tool with async operations. async def handle(self, args: Args) - Output: # type: ignore[override] Note: Add type: ignore[override] for async handle. session self.context.get_session(args.session_id) result await self._async_work(session) return Output(resultresult)异步handle之所以能透明工作是因为统一入口__call__会通过inspect.isawaitable(result)检测并await协程返回值base.py。此外后端 tool_manager.py 的_call_handler也会用inspect.iscoroutinefunction区分同步与异步处理器。带副作用的工具通常应尽量避免在工具中产生副作用。若无法避免务必在 guidelines 中记录guidelines ToolGuidelines( side_effects[ Modifies notebook cells, Triggers cell re-execution, ], )注意仓库内置的 10 个双通道工具目前都是只读检查类工具真正带副作用的编辑工具edit_notebook、run_stale_cells仅在后端 Agent 模式可用不通过 MCP 服务器暴露见 tools.md。复杂返回类型使用嵌套 dataclass 组织复杂输出dataclass class CellInfo: cell_id: str code: str dataclass class ComplexOutput(SuccessResult): cells: list[CellInfo] field(default_factorylist) summary: dict[str, Any] field(default_factorydict)【免费下载链接】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），仅供参考
