批量工具执行插件 (Batch Tool Executor)

插件简介

批量工具执行插件为 XpertAI 智能体提供 并行批量执行多个工具 的能力。通过 batch 工具，智能体可以在一次调用中同时执行多个独立工具，显著提升 I/O 密集型操作的执行效率。

适用场景

• 并行读取多个文件：同时读取多个配置文件、代码文件等
• 并行搜索：同时执行多个 grep 搜索或文件查找操作
• 并行执行命令：同时运行多个独立的 shell 命令
• 混合工具调用：在一次 batch 中组合不同类型的工具（读取 + 搜索 + 命令）
• 批量数据处理：对多个数据源同时执行查询或转换操作

目录结构

batch-tool-executor/
├── .xpertai-plugin/
│   └── plugin.json              # 插件清单
├── index.js                     # 插件入口（CommonJS）
├── package.json                 # 项目依赖与元信息
├── self-check.js                # 自检脚本
├── README.md                    # 本文件
├── src/
│   ├── batch-tool-executor.module.ts    # NestJS 模块
│   ├── middlewares/
│   │   └── batch-tool-executor.middleware.ts  # 中间件策略实现
│   └── schemas/
│       ├── config.schema.ts     # 插件配置 Schema
│       └── tool.schema.ts       # 工具入参/出参 Schema
└── examples/
    └── request.example.json     # 调用示例

安装与导入

通过 npm 安装到 XpertAI 平台

# 在 XpertAI 平台通过 API 安装
POST /api/plugin
{
  "pluginName": "@timmy_hu/batch-tool-executor",
  "version": "1.0.0",
  "source": "npm"
}

本地开发

cd batch-tool-executor
npm install
npm test  # 运行自检

配置项说明

| 配置项 | 类型 | 默认值 | 必填 | 说明 | |--------|------|--------|------|------| | maxBatchSize | number | 10 | 否 | 单次批量执行的最大工具数量（1-10） | | defaultTimeout | number | 60000 | 否 | 每个工具调用的默认超时时间（毫秒） |

Agent Middleware 工具列表

中间件 Provider

• 名称：BatchToolExecutorMiddleware
• 标签：批量工具执行
• 描述：并行执行多个工具以获得最佳性能。每个工具调用都是独立和隔离的，并各自遵守自己的超时行为。

工具：batch

功能：并行执行多个工具调用

入参：

| 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | tool_calls | array | 是 | 工具调用数组，最多 10 个 | | tool_calls[].tool | string | 是 | 要执行的工具名称 | | tool_calls[].parameters | object | 是 | 工具参数，键值对形式 |

出参：

| 字段 | 类型 | 说明 | |------|------|------| | success | boolean | 是否所有工具都成功 | | totalCalls | number | 总调用数量 | | successCount | number | 成功数量 | | failCount | number | 失败数量 | | totalDuration | number | 总耗时（毫秒） | | results | array | 每个工具调用的详细结果 | | results[].index | number | 调用序号 | | results[].tool | string | 工具名称 | | results[].success | boolean | 是否成功 | | results[].result | string/null | 执行结果 | | results[].error | string/null | 错误信息 | | results[].duration | number | 单个调用耗时（毫秒） |

调用示例

并行读取 3 个文件

{
  "tool_calls": [
    { "tool": "sandbox_read_file", "parameters": { "file_path": "/path/to/file1.ts" } },
    { "tool": "sandbox_read_file", "parameters": { "file_path": "/path/to/file2.ts" } },
    { "tool": "sandbox_read_file", "parameters": { "file_path": "/path/to/file3.ts" } }
  ]
}

混合工具类型

{
  "tool_calls": [
    { "tool": "sandbox_read_file", "parameters": { "file_path": "/path/to/config.json" } },
    { "tool": "sandbox_grep", "parameters": { "pattern": "function", "path": "." } },
    { "tool": "sandbox_shell", "parameters": { "command": "echo hello" } }
  ]
}

常见错误和处理方式

| 错误 | 原因 | 处理方式 | |------|------|----------| | 工具注册表不可用 | 平台未传递 context.tools | 确认平台版本支持工具注册表传递 | | 批量大小超出限制 | tool_calls 数量超过 maxBatchSize | 减少工具调用数量或调大 maxBatchSize | | 工具 "xxx" 不允许在 batch 中调用 | 尝试递归调用 batch 自身 | 不要在 batch 中嵌套 batch | | 工具 "xxx" 未找到 | 工具名称错误或未注册 | 检查工具名称拼写，确认工具已在智能体中注册 |

安全注意事项

• batch 工具本身不执行任何外部请求，仅调用智能体已注册的工具
• 每个工具调用独立隔离，单个失败不影响其他调用
• 不支持递归调用 batch，防止无限嵌套
• 最大批量数限制为 10，防止资源耗尽
• 工具调用结果以字符串形式返回，不会执行任意代码

使用方式

1. 在 XpertAI 平台安装本插件
2. 在智能体编排中，添加中间件 → 选择「批量工具执行」
3. 配置 maxBatchSize 和 defaultTimeout（可选）
4. 智能体即可使用 batch 工具并行执行多个已注册工具

下一步

安装完成后，前往 http://10.191.20.254:3300 平台：

1. 进入「插件管理」确认插件已安装
2. 在智能体编排中添加「批量工具执行」中间件
3. 在对话中测试 batch 工具的并行执行能力