文件保存钩子

基于文件的输出处理与归档

FileSaveHook 将工具输出保存到临时文件中，并返回文件信息，而非原始输出内容。此方法非常适合处理大容量输出或需要将输出作为文件进行处理的场景。

概述

功能说明： - 将工具输出保存到临时文件 - 自动分析数据格式和结构 - 返回文件元数据（路径、大小、格式、结构） - 支持自动清理旧文件

使用场景： - 输出数据量非常大，超出内存限制时 - 将输出作为文件供外部工具处理时 - 归档工具输出以便后续分析时 - 在长时间运行的进程中减少内存使用时

快速入门

简单使用方法

from tooluniverse import ToolUniverse

# Enable FileSaveHook
tu = ToolUniverse(hooks_enabled=True, hook_type='FileSaveHook')
tu.load_tools(['uniprot'])

result = tu.run({
    "name": "UniProt_get_entry_by_accession",
    "arguments": {"accession": "P05067"}
})

# Result contains file information
print(f"File path: {result['file_path']}")
print(f"Data format: {result['data_format']}")
print(f"File size: {result['file_size']} bytes")

高级配置

hook_config = {
    "hooks": [{
        "name": "file_save_hook",
        "type": "FileSaveHook",
        "enabled": True,
        "conditions": {
            "output_length": {
                "operator": ">",
                "threshold": 1000
            }
        },
        "hook_config": {
            "temp_dir": "/tmp/my_outputs",
            "file_prefix": "my_tool_output",
            "include_metadata": True,
            "auto_cleanup": True,
            "cleanup_age_hours": 12
        }
    }]
}

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

配置选项

临时目录 - 文件保存的目录 - 默认：系统临时目录 - 自定义位置请使用绝对路径

文件前缀 - 生成文件名的前缀 - 默认值：”tool_output” - 有助于按用途组织文件

包含元数据 - 是否在响应中包含文件元数据 - 默认值：True - 提供文件信息和上下文

自动清理 - 自动删除旧文件 - 默认值：False - 有助于管理磁盘空间

清理时长（小时） - 自动清理的时间阈值 - 默认值：24 小时 - 超过该时长的文件将被删除

数据格式检测

该钩子能够自动检测并处理不同的数据类型：

JSON 数据 - 字典、列表、JSON 字符串 - 以 .json 文件保存 - 结构：“包含 X 个键的字典”、“包含 X 个元素的列表”

文本数据 - 纯文本，字符串 - 以 .txt 文件保存 - 结构：“text”，“string”

二进制数据 - 非文本数据 - 以 .bin 文件保存 - 结构：“binary”，“data”

其他格式 - 自定义数据类型 - 以相应扩展名保存 - 结构：”custom”、”unknown”

示例

大规模数据集处理

# Process large protein database entries
tu = ToolUniverse(hooks_enabled=True, hook_type='FileSaveHook')
tu.load_tools(['uniprot'])

result = tu.run({
    "name": "UniProt_get_entry_by_accession",
    "arguments": {"accession": "P05067"}
})

# File information for external processing
print(f"Dataset saved to: {result['file_path']}")
print(f"Format: {result['data_format']}")
print(f"Size: {result['file_size']} bytes")

# Process with external tools
import subprocess
external_result = subprocess.run([
    'external_analysis_tool', '--input', result['file_path']
], capture_output=True, text=True)

自定义目录与清理

# Configure custom directory with auto-cleanup
hook_config = {
    "hooks": [{
        "name": "file_save_hook",
        "type": "FileSaveHook",
        "enabled": True,
        "hook_config": {
            "temp_dir": "/tmp/research_outputs",
            "file_prefix": "research_data",
            "auto_cleanup": True,
            "cleanup_age_hours": 6
        }
    }]
}

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

# Files will be saved to /tmp/research_outputs/
# and automatically cleaned up after 6 hours

外部工具集成

# Save output and process with external tool
tu = ToolUniverse(hooks_enabled=True, hook_type='FileSaveHook')
tu.load_tools(['europepmc'])

result = tu.run({
    "name": "EuropePMC_search_publications",
    "arguments": {"query": "machine learning drug discovery"}
})

# Process with external analysis tool
import subprocess
external_output = subprocess.run([
    'your_external_tool', '--input', result['file_path']
], capture_output=True, text=True)

故障排除

文件权限错误 - 确保目录存在且可写 - 检查文件权限和所有权 - 对临时目录使用绝对路径

内存问题 - 对于大输出使用 FileSaveHook - 启用临时文件自动清理 - 监控磁盘空间使用情况

钩子未触发 - 检查触发条件和阈值 - 验证钩子配置及启用状态 - 审核钩子优先级设置

性能问题 - 使用特定工具的钩子，避免使用全局钩子 - 设置适当的阈值以避免不必要的处理 - 监控钩子执行时间

调试

启用钩子操作的详细日志记录：

import logging
logging.basicConfig(level=logging.DEBUG)

# Hook operations will be logged in detail
tu = ToolUniverse(hooks_enabled=True, hook_config=config)

验证

验证钩子配置：

# 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')}")

下一步

参见