本文提供详细的工具注册决策指南。

决策树

                     开始：我需要开发一个新工具
                                  │
                                  ▼
               ┌─────────────────────────────────────┐
               │ 问题1: 需要维护长连接或持久状态吗？      │
               │                                     │
               │ - TCP/WebSocket 长连接              │
               │ - 进程句柄                          │
               │ - VM/容器实例                       │
               │ - 数据库连接池                      │
               │ - 浏览器 Session                   │
               └─────────────────────────────────────┘
                         │              │
                        是              否
                         │              │
                         ▼              ▼
              ┌──────────────┐  ┌─────────────────────────┐
              │  Backend 类   │  │ 问题2: 需要预加载资源吗？ │
              │              │  │                         │
              │ 继续下一步... │  │ - ML 模型               │
              └──────────────┘  │ - 向量索引               │
                         │      │ - 大型配置文件           │
                         │      └─────────────────────────┘
                         │               │           │
                         │              是           否
                         │               │           │
                         │               ▼           ▼
                         │    ┌──────────────┐  ┌──────────────────┐
                         │    │  Backend 类   │  │ @register_api_tool │
                         │    │ (共享资源型)  │  │   (轻量级工具)      │
                         │    └──────────────┘  └──────────────────┘
                         │
                         ▼
              ┌───────────────────────────────────┐
              │ 问题3: 资源是全局共享还是用户独立？   │
              └───────────────────────────────────┘
                         │              │
                     全局共享        用户独立
                         │              │
                         ▼              ▼
              ┌─────────────────┐  ┌─────────────────┐
              │ 实现 warmup()   │  │ 实现 initialize()│
              │     shutdown()  │  │     cleanup()   │
              │                 │  │                 │
              │ 例: RAG、模型    │  │ 例: VM、Bash    │
              └─────────────────┘  └─────────────────┘
                         │              │
                         └──────┬───────┘
                                ▼
               ┌─────────────────────────────────────┐
               │ 问题4: 是否同时需要两种资源？          │
               │                                     │
               │ 例: 浏览器（共享进程 + 独立页面）      │
               └─────────────────────────────────────┘
                         │              │
                        是              否
                         │              │
                         ▼              ▼
              ┌─────────────────┐  ┌─────────────────┐
              │ 混合后端        │  │ 完成！          │
              │ 实现全部四个方法 │  │                 │
              └─────────────────┘  └─────────────────┘

边界情况指南

场景	推荐选择	原因
需要鉴权的复杂 API Client	APITool	鉴权是无状态的
带连接池的 API Client	Backend (warmup)	连接池需要生命周期管理
需要 Session Cookie 的 API	Backend (initialize)	Session 状态跨请求维护
简单的 HTTP API 调用	APITool	请求-响应模式
需要重试逻辑的 API	APITool	重试是无状态操作
需要限流/熔断的 API	Backend (warmup)	限流器需要全局状态

实现方式对照表

类型	基类	Session	生命周期方法	工具命名	示例
轻量级 API 工具	无	❌	无	action	WebSearch
共享资源后端	Backend	❌	warmup(), shutdown()	resource:action	RAG
Session 资源后端	Backend	✅	initialize(), cleanup()	resource:action	VM
混合后端	Backend	✅	全部四个	resource:action	Browser

常见问题

Q: 什么时候用 APITool？

当你的工具：

• 调用外部 HTTP API
• 不需要保持状态
• 不需要预加载资源
• 每次调用相互独立

Q: 什么时候用 Backend？

当你的工具：

• 需要预加载模型或资源
• 需要维护长连接
• 需要为每个用户分配独立资源
• 需要管理资源生命周期

Q: 什么时候实现 warmup()？

当你需要：

• 加载 ML 模型
• 建立连接池
• 初始化全局缓存
• 启动后台进程

Q: 什么时候实现 initialize()？

当你需要：

• 为每个用户分配独立资源
• 维护用户级别的状态
• 隔离用户之间的操作

CI/CD 验证

建议在 CI/CD 中验证配置：

python -m sandbox validate --config configs/profiles/production.json --strict

验证内容：

检查项	说明
backend_class 路径	验证类路径可导入
@tool 装饰器	验证工具方法存在
API 工具注册	验证 config_key 匹配
配置完整性	验证必需配置项