Tools 实现模式

参数验证与错误处理

工具调用的第一步是验证参数。

验证原则：

1. 类型检查：确保参数类型正确
2. 范围检查：确保参数值在有效范围内
3. 依赖检查：确保前置条件满足
4. 友好错误：返回清晰的错误信息

验证示例：

场景：文件读取工具

输入：
{
  "path": "/Users/用户名/Documents/report.pdf",
  "offset": 0,
  "limit": 1000
}

验证步骤：
  1. path 是否存在？ ✓
  2. path 是否在允许的根目录内？ ✓
  3. offset 是否为非负整数？ ✓
  4. limit 是否在 1-10000 范围内？ ✓

验证通过 → 执行读取操作

错误处理模式：

// 统一错误格式
{
  "error": {
    "code": "INVALID_PATH",
    "message": "路径不在允许的根目录内",
    "details": {
      "provided": "/etc/passwd",
      "allowed": ["/home/user/Documents", "/home/user/Projects"]
    }
  }
}

常见错误码：

异步操作与超时控制

工具可能需要执行长时间运行的操作，如何处理？

方案 1：同步返回，等待完成

优点：实现简单
缺点：长时间操作会阻塞

适用场景：操作时间 < 5 秒

方案 2：异步返回 Task ID

优点：不阻塞，支持进度查询
缺点：需要额外实现 Tasks

适用场景：操作时间 > 5 秒

超时控制模式：

async function callToolWithTimeout(tool, args, timeout = 30000) {
  const controller = new AbortController();
  const timeoutId = setTimeout(() => controller.abort(), timeout);

  try {
    const result = await tool(args, { signal: controller.signal });
    clearTimeout(timeoutId);
    return result;
  } catch (error) {
    if (error.name === 'AbortError') {
      throw new Error(`Tool execution timed out after ${timeout}ms`);
    }
    throw error;
  }
}

工具组合与链式调用

工具可以调用其他工具，形成组合能力。

组合模式 1：并行调用

场景：同时获取多个文件信息

工具：get_file_info(paths)

实现：
  1. 并行调用 get_file_info(path) 对每个路径
  2. 等待所有调用完成
  3. 返回合并结果

优点：充分利用并发