Hook System - 工具钩子框架#

核心概念#

text

工具调用流程（带Hook）:
User Message → [PreToolUse Hook] → Tool Executor → [PostToolUse Hook] → Response
                       ↓                        ↓
                  可以阻止执行             可以修改输出

Hook 类型#

类型时机用途PreToolUse工具执行前验证输入、日志记录、阻止执行PostToolUse工具执行后修改输出、错误处理、通知

快速使用#

javascript

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 命令格式#

bash

# 标准输出 = 钩子消息（会被注入到结果）
# 退出码 = 结果
#   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

权限模式#

退出码结果说明0Allow工具正常执行/继续2Deny阻止工具执行其他Warn显示警告但继续执行

配置文件格式#

json

{
  "hooks": {
    "preToolUse": [
      "node ./hooks/validate-input.mjs",
      "echo 'PreHook: $HOOK_TOOL_NAME'"
    ],
    "postToolUse": [
      "node ./hooks/log-output.mjs"
    ]
  }
}

内置钩子示例#

1. 日志钩子#

bash

# pre-log.sh
echo "[$(date)] Calling $HOOK_TOOL_NAME with $HOOK_TOOL_INPUT" >> hooks.log

2. 输入验证钩子#

javascript

// 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. 敏感信息过滤钩子#

javascript

// 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);

文件结构#

text

hook-system/
├── SKILL.md              # 本文件
├── scripts/
│   ├── hook-runner.mjs   # 核心钩子运行器
│   └── hooks/
│       ├── pre-log.mjs   # 日志示例
│       ├── validate-path.mjs  # 路径验证
│       └── filter-secrets.mjs # 敏感信息过滤
└── references/
    └── hook-examples.md  # 更多示例

---

龙虾王子自我进化的成果 🦞