工具调用测试

TODO: 截图 — 工具主界面，展示四个标签页

概述

工具调用测试（Tool Calling Tester）是一个内部工具调用系统的调试与验证矩阵。它让你能够直观地查看系统中所有已注册的工具和方法，在安全的沙盒环境中执行测试调用，验证 LLM 生成的 VCP 格式请求是否能正确解析，并监控异步任务的执行状态。

简单来说，它是整个 AIO Hub "工具调用生态"的控制台——无论你是想了解某个工具提供了什么能力，还是想调试智能体调用工具时出了什么问题，这里都能帮你搞定。

核心功能

• 工具库浏览：查看系统中所有已注册工具及其可调用的方法、参数列表，支持搜索、筛选和排序
• 执行沙盒：在隔离环境中选择一个工具方法，填写参数（支持表单模式和 JSON 模式），执行并查看完整结果
• 解析器验证：输入包含 VCP 格式请求块的混合文本，一键解析并验证 LLM 生成的工具请求是否正确
• 异步任务监控：实时跟踪所有异步任务的执行状态（排队中、执行中、完成、失败），支持取消、重试和清理
• VCP 指令生成：从当前选择的工具方法一键生成 VCP 格式的调用指令，方便复制到其他场景测试

---

快速上手

场景一：浏览可用工具（2 分钟）

打开工具后，默认进入 工具库浏览 标签页。这里以卡片网格的形式展示系统内所有已注册的工具。

TODO: 截图 — 工具库浏览页面，展示工具卡片网格

1. 查看工具详情：点击任意工具卡片，右侧展开详情的侧边栏，显示该工具下所有可调用的方法。
2. 搜索工具：在顶部搜索框输入工具名称或方法名称，实时过滤。
3. 切换排序：点击「名称 / 数量」按钮，在按名称排序和按方法数量排序之间切换。
4. 筛选：点击「筛选」按钮展开筛选面板，可以按执行模式（同步/异步）、工厂类等方式过滤。

TODO: 截图 — 展开筛选面板，展示执行模式、工厂类筛选

场景二：执行一次工具调用（5 分钟）

假设你想测试系统的目录树生成功能：

1. 切换到 执行沙盒 标签页。
2. 在顶部下拉框中搜索或选择目标方法，例如 directory-tree 组的 generateTree。
3. 选择方法后，下方会自动加载参数配置区域。默认使用表单模式，每个参数都有对应的输入控件：
   • path：输入一个目录路径，如 E:\rc20\allinweb\all-in-one-tools\src
   • maxDepth：设置为 3
   • showFiles：切换开关为 true
   • showHidden：切换开关为 false

TODO: 截图 — 执行沙盒页面，展示已选方法、参数表单

4. 点击 触发调用 按钮，右侧面板会显示执行结果（包括状态、耗时、返回数据）。

TODO: 截图 — 执行结果面板，展示成功/失败的反馈

5. 你也可以切换到 JSON 模式 直接编辑参数 JSON，适合需要精确控制参数值的场景。

场景三：验证 LLM 解析结果（3 分钟）

当你好奇智能体生成的工具调用指令是否正确时，可以使用解析器验证功能：

1. 切换到 解析器验证 标签页。
2. 左侧编辑器中有一段预填充的示例文本，包含一个 VCP 格式的 [TOOL_REQUEST] 块。
3. 点击 运行解析引擎，右侧会展示解析出的工具请求列表。

TODO: 截图 — 解析器验证页面，左侧输入/右侧结果

每个解析结果卡片都会显示：

• 工具名称：解析出的目标工具
• 状态标签：已就绪（工具存在且方法可调用）、格式错误（VCP 语法出错）、工具不存在（未注册的工具）
• 提取参数：解析出的参数键值对

---

功能详解

① 工具库浏览（Discovery）

这是工具调用系统的"体检中心"，让你一目了然地看到所有工具提供了哪些能力。

工具卡片网格

每个工具以卡片形式展示：

• 图标：工具注册时的图标
• 名称：工具显示名称
• ID：工具内部标识符（如 directory-tree、smart-ocr）
• 方法数：该工具下可被智能体调用的方法数量
• 工厂标签：如果工具属于某个工厂类，会显示工厂标签

详情侧边栏

点击任意卡片，右侧会滑出详情面板，展示该工具下所有方法的详细信息：

• 方法名称：显示名称和标识符
• 执行模式：⚡同步方法（即时返回结果）或 ⏳异步方法（返回任务 ID，需后续查询）
• 方法描述：说明方法的用途
• 参数列表：列出所有参数名和类型
• 加载至执行沙盒：点击后自动跳转到执行沙盒页并预填好该方法的参数

搜索与筛选

功能	说明
搜索框	按工具名称、ID 或方法名称搜索，实时过滤
排除词	输入关键词后，匹配的工具和方法会被排除
排序	按名称排序 / 按方法数量排序
执行模式筛选	全部 / 仅同步方法 / 仅异步方法
工厂类筛选	按工厂类分组查看
刷新库	手动刷新工具列表（订阅了注册表变更，通常会自动更新）

② 执行沙盒（Executor）

执行沙盒提供了一个安全的测试环境，让你可以在不经过智能体审批流程的情况下，直接调用任何已注册工具的任意方法。

方法选择器

顶部下拉选择器分为两组：

• 组标签：工具名称（如 directory-tree、tool-calling）
• 选项：该工具下的方法，显示名称 + 方法标识符（次级文字）

选择方法后，系统会自动加载该方法的参数定义，并初始化默认值。

TODO: 截图 — 方法选择器下拉菜单

参数配置

表单模式（默认）：每个参数都有对应的输入控件：

• string 类型 → 文本输入框
• number 类型 → 数字输入框
• boolean 类型 → 开关/勾选框
• array / object 类型 → 代码编辑器输入

JSON 模式：直接编辑 JSON 格式的参数，适合高级用户或需要传递复杂结构的场景。

两种模式是双向同步的——在表单中修改会自动更新 JSON，在 JSON 中修改也会同步回表单。

TODO: 截图 — 表单模式 vs JSON 模式切换

执行与结果

• 触发调用：执行当前配置的工具调用
• 生成 VCP：将当前方法调用生成为 VCP 格式指令并复制到剪贴板
• 结果面板：右侧展示最近 10 条执行记录，每条包含状态标记（成功/失败/被拒绝）、执行耗时和返回数据

TODO: 截图 — 执行结果卡片，展示成功/失败的视觉差异

参数类型自适应

系统会自动根据参数元数据的类型做适配（类型强转），确保字符串形式的 "true" 被转为布尔值 true，数字字符串 "42" 被转为数字 42。这意味着无论是智能体生成的参数还是手动输入，都会被正确处理。

③ 解析器验证（Parser）

这个模块专门用于验证 LLM 回复中的工具调用请求能否被正确解析。

VCP 协议格式

工具调用采用 VCP（Verbal Command Protocol）协议格式，在 LLM 的回复文本中用特殊标记包裹：

<<<[TOOL_REQUEST]>>>
tool_name:「始」directory-tree「末」,
command:「始」generateTree「末」,
path:「始」E:\path「末」,
maxDepth:「始」5「末」
<<<[END_TOOL_REQUEST]>>>

解析器可以从混合文本中提取出这些标记块，解析出工具名称、方法名和参数。

解析结果验证

解析后，每个请求会进行三级验证：

1. 格式验证：VCP 语法是否正确（标记完整性、字段格式）
2. 工具验证：目标工具是否已在系统中注册
3. 方法验证：目标方法是否存在于该工具中且标记为可调用

验证结果以标签形式展示：

• 🟢 已就绪：工具和方法都存在，可以正常执行
• 🔴 格式错误：VCP 语法有问题，点击标签查看详情
• 🔴 工具不存在：系统中未注册该工具

典型场景

当你发现智能体没有正确执行工具调用时，可以把 LLM 的完整回复文本粘贴到解析器验证中，检查：

• VCP 格式是否正确（字段名是否匹配）
• 工具名称是否拼写正确
• 参数名是否与定义的参数列表一致

④ 异步任务监控（AsyncTask）

异步任务监控是一个完整的任务队列管理面板，让你可以实时跟踪所有通过工具调用系统提交的长时间任务。

TODO: 截图 — 异步任务监控完整界面

统计概览

页面顶部的统计栏展示当前任务队列概况：

• 总任务：所有提交过的任务总数
• 运行中：当前正在执行的任务
• 已完成：成功完成的任务
• 失败：执行失败的任务

任务表格

任务列表以表格形式展示，支持：

• 状态筛选：全部 / 排队中 / 运行中 / 已完成 / 失败
• 关键词搜索：按任务 ID 或工具名称搜索
• 自动刷新：订阅了任务状态变更，实时更新

任务操作：

状态	可用操作
运行中	取消任务
已完成	查看详情
失败	查看详情 / 重试任务
已取消	重试任务

TODO: 截图 — 任务详情弹窗

批量清理

• 清理已完成：一键删除所有已完成的任务
• 清理失败：一键删除所有失败的任务
• 清理全部：清空整个任务队列

---

高级用法

跨工具链路测试

你可以使用工具库浏览功能了解多个工具的能力，然后在执行沙盒中逐个测试它们的方法，验证参数传递和数据返回是否符合预期。这对于调试复杂的多工具协作场景非常有用。

解析器边界测试

解析器验证支持任意文本输入，你可以在左侧编辑器中构造各种边界情况的 VCP 请求：

✅ 正常请求：标准格式，所有字段完整
⚠️ 缺少字段：不带 tool_name 的请求块
❌ 格式错误：标记不完整或字段值格式错误

这样可以提前发现解析器的处理边界，确保智能体在极端情况下也能稳定工作。

异步任务压力测试

通过注册表中的 testAsyncTask 方法，你可以提交多个模拟的异步任务（可以控制持续时间和是否失败），然后在异步任务监控中观察它们的执行状态变化、取消操作和重试行为。

TODO: 截图 — 异步任务监控页面的统计卡片和任务列表

---

常见问题

Q：执行沙盒中的调用会经过审批流程吗？

A：不会。执行沙盒直接通过系统内部的 execute 服务调用工具方法，跳过了 LLM 智能体的审批流程。这意味着所有在沙盒中执行的调用都是立即执行且无需审批的。这适合开发调试场景，但在生产环境中需要注意操作风险。

Q：解析器验证的结果和实际 LLM 解析有什么不同？

A：解析器验证使用的是和 LLM 智能体完全相同的解析引擎（core/parser.ts），所以结果是一致的。你看到的每一个解析结果，都反映了实际智能体在调用工具时的解析效果。区别在于解析器验证没有后续的执行和审批流程。

Q：异步任务的状态是实时更新的吗？

A：是的。异步任务监控通过 Pinia Store 订阅了任务管理器的状态变更事件，当任何任务的状态发生变化时（排队 → 执行中 → 完成/失败），监控面板会实时更新。你不需要手动刷新页面。

Q：为什么点击"加载至执行沙盒"后，参数显示为空？

A：可能是该方法的参数定义中没有设置默认值。你可以切换到 JSON 模式，手动填入参数 JSON，或先在 表单模式 中逐个填写参数值。参数配置支持表单/JSON 双向同步，填写任意一侧都会同步到另一侧。

Q：执行结果提示"方法不存在"或"工具不存在"？

A：这可能是因为目标工具虽然在工具库中可见，但其注册的 Registry 实例可能由于某种原因未能正确初始化。请尝试：

1. 点击 刷新库 按钮，确认工具列表已更新
2. 检查目标工具是否已正确初始化（在工具库浏览中查看工具卡片是否正常显示方法列表）
3. 如果问题持续，可能是工具注册的 agentCallable 标记未正确设置，请联系开发者