服务器与标准输入输出钩子集成¶
使用 hooks 连接 ToolUniverse 服务器和 stdio 接口的完整教程
概述¶
ToolUniverse 提供智能输出处理钩子，能够自动处理大型工具输出，具体包括：
SummarizationHook：基于人工智能的长文本输出摘要功能
FileSaveHook：基于文件的归档及元数据管理
自定义 Hook：用户定义的处理逻辑
这些钩子可在 server 模式和 stdio 模式下使用，且默认行为各不相同。
服务器模式（HTTP/SSE）¶
服务器模式提供支持可配置钩子的 HTTP 和 SSE 传输。
基本用法¶
启动启用钩子的服务器：
# Enable hooks with default SummarizationHook
tooluniverse-smcp-server --hooks-enabled --port 8000
# Use specific hook type
tooluniverse-smcp-server --hook-type SummarizationHook --port 8000
tooluniverse-smcp-server --hook-type FileSaveHook --port 8000
# Use custom hook configuration
tooluniverse-smcp-server --hook-config-file hook_config.json --port 8000
可用参数¶
--hooks-enabled：启用输出处理钩子（默认值：False）--hook-type：选择钩子类型（SummarizationHook，FileSaveHook）--hook-config-file：自定义钩子配置 JSON 文件的路径
示例配置¶
SummarizationHook 配置：
{
"hooks": [
{
"name": "summarization_hook",
"type": "SummarizationHook",
"enabled": true,
"conditions": {
"output_length": {
"operator": ">",
"threshold": 5000
}
},
"hook_config": {
"chunk_size": 30000,
"focus_areas": "key_findings_and_results",
"max_summary_length": 3000
}
}
]
}
FileSaveHook 配置：
{
"hooks": [
{
"name": "file_save_hook",
"type": "FileSaveHook",
"enabled": true,
"conditions": {
"output_length": {
"operator": ">",
"threshold": 1000
}
},
"hook_config": {
"temp_dir": "/tmp/tooluniverse_outputs",
"file_prefix": "tool_output",
"include_metadata": true,
"auto_cleanup": true,
"cleanup_age_hours": 24
}
}
]
}
标准输入输出模式（桌面人工智能）¶
stdio 模式专为桌面 AI 应用程序（如 Claude Desktop）设计，默认启用钩子功能。
默认行为¶
Stdio 模式默认启用 SummarizationHook：
# Default: hooks enabled with SummarizationHook
tooluniverse-smcp-stdio
# Equivalent to:
tooluniverse-smcp-stdio --hook-type SummarizationHook
挂钩控制¶
禁用或修改钩子行为：
# Disable hooks completely
tooluniverse-smcp-stdio --no-hooks
# Use FileSaveHook instead
tooluniverse-smcp-stdio --hook-type FileSaveHook
# Use custom configuration
tooluniverse-smcp-stdio --hook-config-file hook_config.json
可用参数¶
--no-hooks：禁用输出处理钩子（默认：启用）--hook-type：选择钩子类型（SummarizationHook，FileSaveHook）--hook-config-file：自定义钩子配置 JSON 文件的路径
Python API 集成¶
使用 SMCP 类以编程方式使用钩子：
基本用法¶
from tooluniverse import SMCP
# Enable hooks with default SummarizationHook
server = SMCP(
name="My Server",
hooks_enabled=True
)
# Use specific hook type
server = SMCP(
name="My Server",
hooks_enabled=True,
hook_type="SummarizationHook"
)
# Use FileSaveHook
server = SMCP(
name="My Server",
hooks_enabled=True,
hook_type="FileSaveHook"
)
高级配置¶
使用自定义钩子配置：
import json
# Load custom configuration
with open('hook_config.json', 'r') as f:
hook_config = json.load(f)
server = SMCP(
name="My Server",
hooks_enabled=True,
hook_config=hook_config
)
# Or define inline
hook_config = {
"hooks": [
{
"name": "custom_hook",
"type": "SummarizationHook",
"enabled": True,
"conditions": {
"output_length": {
"operator": ">",
"threshold": 3000
}
},
"hook_config": {
"chunk_size": 2000,
"focus_areas": "key_findings_and_results",
"max_summary_length": 2000
}
}
]
}
server = SMCP(
name="My Server",
hooks_enabled=True,
hook_config=hook_config
)
配置优先级¶
当使用多种配置方法时，将遵循以下优先级：
请提供需要翻译的具体英文文本，我将为您提供准确、流畅的中文翻译。
# hook_config takes precedence over hook_type
server = SMCP(
name="My Server",
hooks_enabled=True,
hook_type="SummarizationHook", # Ignored
hook_config=custom_config # Used
)
最佳实践¶
服务器模式¶
在生产服务器上使用
--hooks-enabled根据使用场景选择适当的钩子类型
针对复杂需求使用自定义配置
监控钩子性能并调整阈值
标准输入输出模式¶
利用默认钩子行为优化桌面端人工智能
仅在钩子引发问题时使用
--no-hooks请考虑使用 FileSaveHook 满足数据归档需求
在部署之前测试挂钩配置
性能注意事项¶
SummarizationHook：增加处理时间，但减小输出大小
FileSaveHook：处理开销极小，适合归档使用
阈值：设置适当的输出长度阈值
块大小：平衡处理效率与上下文保留
故障排除¶
常见问题¶
钩子未触发：
检查输出长度阈值
验证钩子配置语法
确保已启用钩子
性能问题：
调整块大小
提高阈值
使用特定工具的配置
配置错误：
验证 JSON 语法
检查参数名称
验证钩子类型
调试模式¶
启用详细日志记录以进行故障排除：
# Server mode
tooluniverse-smcp-server --hooks-enabled --verbose --port 8000
# Stdio mode
tooluniverse-smcp-stdio --hook-type SummarizationHook --verbose