#Tool 管理

过滤和组织 Agent 工具能力，针对特定任务和性能进行优化。

#概述

Tarko 包含 32 个内置工具，分为 4 个类别：general (1)、browser (18)、filesystem (11) 和 commands (2)。Tool 管理允许你精确控制哪些工具可用，以优化性能和聚焦能力。

#快速开始

# 仅包含浏览器工具（18 个工具）
tarko --tool.include browser

# 包含文件系统但排除文件编辑
tarko --tool.include filesystem --tool.exclude edit_file

# 多个类别并排除特定工具
tarko --tool.include "browser,filesystem" --tool.exclude "run_command,run_script"

#CLI Tool 过滤

#可用选项

#模式匹配规则

• 子字符串匹配：使用 string.includes() 实现高性能
• 大小写敏感：模式必须匹配确切的大小写（browser 而不是 Browser）
• 执行顺序：先应用包含过滤器，然后应用排除过滤器
• 分类名称：使用分类名称进行批量操作

#常见用例

#仅 Web 自动化

# 浏览器工具 + 网络搜索（19 个工具）
tarko --tool.include "browser,web_search"

#安全文件操作

# 文件系统但不执行命令（11 个工具）
tarko --tool.include filesystem --tool.exclude "run_command,run_script"

#只读 Agent

# 不允许文件写入或命令执行
tarko --tool.exclude "write_file,edit_file,create_directory,move_file,run_command,run_script"

#最小化 Agent

# 仅基本只读工具
tarko --tool.include "read_file,read_multiple_files,list_directory,browser_screenshot,web_search"

#编程式 Tool 管理

#Agent 配置

import { Agent } from '@tarko/agent';

const agent = new Agent({
  tool: {
    include: ['browser', 'filesystem'],
    exclude: ['browser_get_markdown', 'run_command']
  }
});

#配置文件

{
  "tool": {
    "include": ["browser", "filesystem"],
    "exclude": ["delete", "remove"]
  }
}

#Tool 注册

import { Agent, Tool } from '@tarko/agent';

const agent = new Agent();

// 注册自定义工具
const customTool = new Tool({
  id: 'custom_tool',
  description: '我的自定义工具',
  parameters: {
    type: 'object',
    properties: {
      input: { type: 'string', description: '输入参数' }
    }
  },
  function: async (params) => {
    return `处理结果: ${params.input}`;
  }
});

agent.registerTool(customTool);

// 获取所有可用工具
const tools = agent.getTools();
console.log(`可用工具: ${tools.length}`);

#Tool 分类

#内置分类

#📦 general (1 个工具)

• web_search - 搜索网络信息

#📦 browser (18 个工具)

• browser_click - 点击页面元素
• browser_close_tab - 关闭浏览器标签页
• browser_evaluate - 执行 JavaScript 代码
• browser_form_input_fill - 填写表单输入
• browser_get_clickable_elements - 获取可点击元素
• browser_get_markdown - 提取页面内容为 markdown
• browser_go_back - 在历史记录中后退
• browser_go_forward - 在历史记录中前进
• browser_hover - 悬停在元素上
• browser_navigate - 导航到 URL
• browser_new_tab - 打开新浏览器标签页
• browser_press_key - 按下键盘按键
• browser_read_links - 提取所有页面链接
• browser_screenshot - 截取页面截图
• browser_scroll - 滚动页面内容
• browser_select - 选择下拉选项
• browser_switch_tab - 在标签页间切换
• browser_tab_list - 列出所有打开的标签页

#📦 filesystem (11 个工具)

• create_directory - 创建新目录
• directory_tree - 获取目录结构
• edit_file - 编辑现有文件
• get_file_info - 获取文件元数据
• list_allowed_directories - 列出可访问目录
• list_directory - 列出目录内容
• move_file - 移动或重命名文件
• read_file - 读取文件内容
• read_multiple_files - 一次读取多个文件
• search_files - 按模式搜索文件
• write_file - 写入内容到文件

#📦 commands (2 个工具)

• run_command - 执行 shell 命令
• run_script - 运行脚本和解释器

#故障排除

#调试 Tool 过滤

# 查看哪些工具被过滤
tarko --debug --tool.include browser
# 输出: "应用包含过滤器，模式 [browser]，32/32 工具中匹配了 18 个"

#常见问题

#没有可用工具

# 使用更宽泛的模式
tarko --tool.exclude "run_command" # 排除特定工具而不是严格包含

#模式不工作

• 验证大小写敏感性（browser 而不是 Browser）
• 使用确切的工具名称（browser_click 而不是 click）
• 检查分类名称：browser、filesystem、commands、general

#Tool 加载错误

try {
  const agent = new Agent({
    tool: { include: ['invalid_tool'] }
  });
} catch (error) {
  console.error('工具加载失败:', error.message);
  // 回退到默认工具
}

#性能考虑

#过滤器实现

• 复杂度：O(n×m) 其中 n=工具数，m=模式数
• 匹配：简单的 string.includes() 实现最佳速度
• 日志：详细的过滤操作日志用于调试
• 兼容性：完全向后兼容

#示例

#仅浏览器 Agent

tarko --tool.include browser
# 结果：18 个浏览器工具（browser_click、browser_navigate 等）

#文件操作但不编辑

tarko --tool.include filesystem --tool.exclude edit_file
# 结果：10 个文件系统工具（read_file、write_file、list_directory 等）

#特定工具排除

tarko --tool.include "browser,filesystem" --tool.exclude "browser_get_markdown,run_command"
# 结果：28 个工具（17 个浏览器 + 11 个文件系统，排除 markdown 和命令）

#下一步

• 了解 Tool 开发 来创建自定义工具
• 探索 Tool Call Engine 的执行优化