- name
- hook-system
- description
- >
Hook System - 工具钩子框架
核心概念
工具调用流程（带Hook）:
User Message → [PreToolUse Hook] → Tool Executor → [PostToolUse Hook] → Response
↓ ↓
可以阻止执行 可以修改输出
Hook 类型
| 类型 | 时机 | 用途 |
|---|
| PreToolUse | 工具执行前 | 验证输入、日志记录、阻止执行 |
| PostToolUse | 工具执行后 | 修改输出、错误处理、通知 |
快速使用
const { HookRunner } = require('./scripts/hook-runner.mjs');
const runner = new HookRunner({
preToolUse: ['echo "Calling $HOOK_TOOL_NAME"'],
postToolUse: ['echo "Done: $HOOK_TOOL_NAME"']
});
// 执行前钩子
const preResult = runner.runPreToolUse('read_file', '{"path":"README.md"}');
console.log(preResult.allow); // true/false
console.log(preResult.messages); // 钩子输出
// 执行后钩子
const postResult = runner.runPostToolUse('read_file', '{"path":"README.md"}', 'file content...', false);
Hook 命令格式
# 标准输出 = 钩子消息（会被注入到结果）
# 退出码 = 结果
# 0 = 允许/成功
# 2 = 拒绝（仅PreToolUse）
# 其他 = 警告（不阻止执行）
环境变量
钩子运行时自动注入：
| 变量 | 说明 |
|---|
HOOK_EVENT | 事件类型：PreToolUse 或 PostToolUse |
HOOK_TOOL_NAME | 工具名称 |
HOOK_TOOL_INPUT | 工具输入（原始JSON字符串） |
HOOK_TOOL_INPUT_PARSED | 解析后的JSON（美化格式） |
HOOK_TOOL_OUTPUT | 工具输出（PostToolUse才有） |
HOOK_TOOL_IS_ERROR | 是否错误：0 或 1 |
权限模式
| 退出码 | 结果 | 说明 |
|---|
| 0 | Allow | 工具正常执行/继续 |
| 2 | Deny | 阻止工具执行 |
| 其他 | Warn | 显示警告但继续执行 |
配置文件格式
{
"hooks": {
"preToolUse": [
"node ./hooks/validate-input.mjs",
"echo 'PreHook: $HOOK_TOOL_NAME'"
],
"postToolUse": [
"node ./hooks/log-output.mjs"
]
}
}
内置钩子示例
1. 日志钩子
# pre-log.sh
echo "[$(date)] Calling $HOOK_TOOL_NAME with $HOOK_TOOL_INPUT" >> hooks.log
2. 输入验证钩子
// validate-input.mjs
const input = JSON.parse(process.env.HOOK_TOOL_INPUT || '{}');
if (input.path?.includes('..')) {
console.error('Path traversal detected');
process.exit(2); // Deny
}
console.log('Input valid');
process.exit(0);
3. 敏感信息过滤钩子
// filter-secrets.mjs
const output = process.env.HOOK_TOOL_OUTPUT || '';
const filtered = output.replace(/sk-\w{32,}/g, '[REDACTED_API_KEY]');
console.log(filtered);
process.exit(0);
文件结构
hook-system/
├── SKILL.md # 本文件
├── scripts/
│ ├── hook-runner.mjs # 核心钩子运行器
│ └── hooks/
│ ├── pre-log.mjs # 日志示例
│ ├── validate-path.mjs # 路径验证
│ └── filter-secrets.mjs # 敏感信息过滤
└── references/
└── hook-examples.md # 更多示例
_龙虾王子自我进化的成果 🦞_
