钩子配置

钩子的高级配置与自定义

配置方法

简单配置（推荐）

使用 hook_type 以便轻松选择：

from tooluniverse import ToolUniverse

# Enable default SummarizationHook
tu = ToolUniverse(hooks_enabled=True)

# Choose specific hook type
tu = ToolUniverse(hooks_enabled=True, hook_type='FileSaveHook')

# Use multiple hooks
tu = ToolUniverse(hooks_enabled=True, hook_type=['SummarizationHook', 'FileSaveHook'])

高级配置

使用 hook_config 进行详细控制：

hook_config = {
    "hooks": [{
        "name": "my_hook",
        "type": "SummarizationHook",
        "enabled": True,
        "conditions": {"output_length": {"operator": ">", "threshold": 5000}},
        "hook_config": {
            "chunk_size": 30000,
            "focus_areas": "key_findings_and_results"
        }
    }]
}

tu = ToolUniverse(hooks_enabled=True, hook_config=hook_config)

配置优先级

当同时提供 hook_type 和 hook_config 时，以 hook_config 为准。

Excluding Tools from Hook Processing

exclude_tools Configuration

Use exclude_tools to prevent specific tools from being processed by hooks. This is useful for excluding tool discovery tools (like Tool_RAG) and other special tools that shouldn’t be summarized.

Default Excluded Tools

The default configuration excludes these tools:

  • Tool_RAG - Embedding-based tool finder

  • ToolFinderEmbedding - Tool discovery tool

  • ToolFinderLLM - LLM-based tool finder

  • ToolOutputSummarizer - Hook tool (always excluded)

  • OutputSummarizationComposer - Hook tool (always excluded)

Custom Exclude Tools

{
  "exclude_tools": [
    "Tool_RAG",
    "ToolFinderEmbedding",
    "MyCustomTool",
    "SpecialTool_*"
  ],
  "hooks": [...]
}

Wildcard Patterns

You can use wildcard patterns to exclude multiple tools:

{
  "exclude_tools": [
    "Tool_*",      # Excludes all tools starting with "Tool_"
    "Finder*",     # Excludes all tools starting with "Finder"
    "CustomTool_*" # Excludes all tools starting with "CustomTool_"
  ]
}

Python Configuration

hook_config = {
    "exclude_tools": [
        "Tool_RAG",
        "ToolFinderEmbedding",
        "CustomTool_*"  # Wildcard pattern
    ],
    "hooks": [{
        "name": "summarization_hook",
        "type": "SummarizationHook",
        "enabled": True
    }]
}

tu = ToolUniverse(hooks_enabled=True, hook_config=hook_config)

Why Exclude Tools?

  • Prevent Recursive Processing: Hook tools themselves are excluded to avoid infinite loops

  • Performance: Skip unnecessary processing for tool discovery tools

  • Correctness: Some tools produce outputs that shouldn’t be summarized (e.g., tool lists)

配置结构

全局设置

{
  "global_settings": {
    "default_timeout": 30,
    "max_hook_depth": 3,
    "enable_hook_caching": true,
    "hook_execution_order": "priority_desc"
  },
  "exclude_tools": [
    "Tool_RAG",
    "ToolFinderEmbedding",
    "ToolFinderLLM"
  ]
}

钩子类型默认值

{
  "hook_type_defaults": {
    "SummarizationHook": {
      "default_output_length_threshold": 5000,
      "default_chunk_size": 30000,
      "default_focus_areas": "key_findings_and_results",
      "default_max_summary_length": 3000
    },
    "FileSaveHook": {
      "default_temp_dir": null,
      "default_file_prefix": "tool_output",
      "default_include_metadata": true,
      "default_auto_cleanup": false,
      "default_cleanup_age_hours": 24
    }
  }
}

单独钩子配置

{
  "hooks": [
    {
      "name": "summarization_hook",
      "type": "SummarizationHook",
      "enabled": true,
      "priority": 1,
      "conditions": {
        "output_length": {
          "operator": ">",
          "threshold": 5000
        }
      },
      "hook_config": {
        "chunk_size": 32000,
        "focus_areas": "key_findings_and_results",
        "max_summary_length": 3000
      }
    }
  ]
}

配置级别

全局钩子

适用于所有工具：

{
  "hooks": [
    {
      "name": "global_summarization",
      "type": "SummarizationHook",
      "enabled": true,
      "conditions": {
        "output_length": {"operator": ">", "threshold": 10000}
      }
    }
  ]
}

工具特定钩子

适用于特定工具：

{
  "tool_specific_hooks": {
    "UniProt_get_entry_by_accession": {
      "enabled": true,
      "hooks": [
        {
          "name": "protein_summarization",
          "type": "SummarizationHook",
          "enabled": true,
          "conditions": {
            "output_length": {"operator": ">", "threshold": 8000}
          },
          "hook_config": {
            "focus_areas": "protein_function_and_structure",
            "max_summary_length": 3500
          }
        }
      ]
    }
  }
}

类别特定钩子

适用于工具类别：

{
  "category_hooks": {
    "uniprot": {
      "enabled": true,
      "hooks": [
        {
          "name": "protein_file_save",
          "type": "FileSaveHook",
          "enabled": true,
          "conditions": {
            "output_length": {"operator": ">", "threshold": 5000}
          },
          "hook_config": {
            "file_prefix": "protein_data",
            "auto_cleanup": true
          }
        }
      ]
    }
  }
}

条件类型

输出长度条件

{
  "conditions": {
    "output_length": {
      "operator": ">",
      "threshold": 5000
    }
  }
}

可用运算符： - >：大于 - >=：大于或等于 - <：小于 - <=：小于或等于 - ==：等于 - !=：不等于

工具名称条件

{
  "conditions": {
    "tool_name": {
      "operator": "==",
      "value": "UniProt_get_entry_by_accession"
    }
  }
}

多个条件

{
  "conditions": {
    "output_length": {
      "operator": ">",
      "threshold": 5000
    },
    "tool_name": {
      "operator": "!=",
      "value": "ToolOutputSummarizer"
    }
  }
}

性能优化

工具特定配置

使用特定工具的钩子以提升性能：

{
  "tool_specific_hooks": {
    "UniProt_get_entry_by_accession": {
      "enabled": true,
      "hooks": [
        {
          "name": "protein_hook",
          "type": "SummarizationHook",
          "enabled": true,
          "conditions": {
            "output_length": {"operator": ">", "threshold": 8000}
          }
        }
      ]
    }
  }
}

适当的阈值

设置阈值以避免不必要的处理：

{
  "conditions": {
    "output_length": {
      "operator": ">",
      "threshold": 10000
    }
  }
}

缓存配置

启用缓存以提升性能：

{
  "global_settings": {
    "enable_hook_caching": true
  }
}

Excluding Tools

Exclude tool discovery and special tools:

{
  "exclude_tools": [
    "Tool_RAG",
    "ToolFinderEmbedding",
    "ToolFinderLLM"
  ]
}

This prevents unnecessary processing and avoids recursive hook calls.

自动清理

启用基于文件的钩子自动清理功能：

{
  "hook_config": {
    "auto_cleanup": true,
    "cleanup_age_hours": 12
  }
}

最佳实践

配置管理

  1. 从简单开始：使用 hook_type 满足基本需求

  2. 逐步复杂化：添加 hook_config 以满足特定需求

  3. 逐步测试：测试每项配置更改

  4. 文档设置：记录自定义配置

性能优化提示

  1. 使用特定工具的挂钩：比全局挂钩更高效

  2. 设置适当的阈值：避免不必要的处理

  3. 启用缓存：减少冗余操作

  4. 监控资源使用情况：跟踪内存和磁盘使用情况

  5. Exclude Unnecessary Tools: Use exclude_tools to skip tool discovery tools

错误处理

  1. 验证配置：检查 JSON 语法和结构

  2. 处理缺失工具：确保所需工具可用

  3. 优雅降级：提供后备选项

  4. 日志记录：启用详细日志以便调试

安全注意事项

  1. 文件权限：确保适当的文件访问控制

  2. 临时文件：使用安全的临时目录

  3. 数据隐私：考虑敏感数据的处理

  4. 清理：定期清理临时文件

故障排除

配置验证

# Validate hook configuration
import json

try:
    with open('hook_config.json', 'r') as f:
        config = json.load(f)
    print("Configuration is valid JSON")
except (FileNotFoundError, json.JSONDecodeError) as e:
    print(f"Error: {e}")

调试配置

# Check hook configuration
hook_manager = tu.hook_manager
for hook in hook_manager.hooks:
    print(f"Hook: {hook.name}")
    print(f"Enabled: {hook.enabled}")
    print(f"Type: {hook.config.get('type')}")
    print(f"Conditions: {hook.config.get('conditions')}")

常见问题

Hook Not Triggering - Check threshold settings - Verify hook is enabled - Confirm tool name matching - Review condition parameters - Check if tool is in exclude_tools list (excluded tools won’t trigger hooks)

性能问题 - 使用特定工具的钩子 - 设置适当的阈值 - 启用缓存 - 监控资源使用情况

文件权限错误 - 检查目录权限 - 使用绝对路径 - 验证文件访问权限

下一步

参见