Hook System - 工具钩子框架

核心概念

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

Hook 类型

快速使用

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）
#   其他 = 警告（不阻止执行）

环境变量

钩子运行时自动注入：

权限模式

配置文件格式

{
  "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  # 更多示例

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