mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-12 02:37:45 +08:00
391 lines
7.1 KiB
Markdown
391 lines
7.1 KiB
Markdown
# Claude Code Hooks - 快速参考
|
||
|
||
## 12 个官方钩子事件
|
||
|
||
| # | 事件名称 | 触发时机 | 可阻止 | 匹配器 |
|
||
|---|---------|---------|--------|--------|
|
||
| 1 | `SessionStart` | 会话开始/恢复 | ❌ | startup, resume, clear, compact |
|
||
| 2 | `UserPromptSubmit` | 用户提交提示词前 | ✅ | ❌ 不支持 |
|
||
| 3 | `PreToolUse` | 工具调用前 | ✅ | 工具名称 |
|
||
| 4 | `PermissionRequest` | 权限对话时 | ✅ | 工具名称 |
|
||
| 5 | `PostToolUse` | 工具成功后 | ❌ | 工具名称 |
|
||
| 6 | `PostToolUseFailure` | 工具失败后 | ❌ | 工具名称 |
|
||
| 7 | `Notification` | 发送通知时 | ❌ | 通知类型 |
|
||
| 8 | `SubagentStart` | 子代理开始 | ❌ | 代理类型 |
|
||
| 9 | `SubagentStop` | 子代理完成 | ✅ | 代理类型 |
|
||
| 10 | `Stop` | Claude完成响应 | ✅ | ❌ 不支持 |
|
||
| 11 | `PreCompact` | 上下文压缩前 | ❌ | manual, auto |
|
||
| 12 | `SessionEnd` | 会话终止 | ❌ | 终止原因 |
|
||
|
||
---
|
||
|
||
## 配置模板
|
||
|
||
### 基础结构
|
||
|
||
```json
|
||
{
|
||
"hooks": {
|
||
"EventName": [
|
||
{
|
||
"matcher": "pattern",
|
||
"hooks": [
|
||
{
|
||
"type": "command|prompt|agent",
|
||
"command": "...",
|
||
"timeout": 600,
|
||
"async": false
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 工具名称（用于匹配器）
|
||
|
||
### 内置工具
|
||
```
|
||
Bash, Edit, Write, Read, Glob, Grep, Task, WebFetch, WebSearch
|
||
```
|
||
|
||
### MCP 工具
|
||
```
|
||
mcp__<server>__<tool>
|
||
mcp__memory__.*
|
||
mcp__.*__write.*
|
||
```
|
||
|
||
---
|
||
|
||
## Exit Codes
|
||
|
||
| Code | 含义 | Claude反馈 |
|
||
|------|------|-----------|
|
||
| 0 | 成功 | 解析 stdout JSON，允许操作 |
|
||
| 2 | 阻止 | stderr 发送给 Claude，阻止操作 |
|
||
| 其他 | 错误 | stderr 仅在详细模式显示 |
|
||
|
||
---
|
||
|
||
## 标准 JSON 输入（stdin）
|
||
|
||
```json
|
||
{
|
||
"session_id": "abc123",
|
||
"transcript_path": "/path/to/transcript.jsonl",
|
||
"cwd": "/current/dir",
|
||
"permission_mode": "default",
|
||
"hook_event_name": "PreToolUse",
|
||
"tool_name": "Bash",
|
||
"tool_input": {
|
||
"command": "npm test"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 标准 JSON 输出（stdout, exit 0）
|
||
|
||
### PreToolUse
|
||
```json
|
||
{
|
||
"hookSpecificOutput": {
|
||
"hookEventName": "PreToolUse",
|
||
"permissionDecision": "allow|deny|ask",
|
||
"permissionDecisionReason": "explanation"
|
||
}
|
||
}
|
||
```
|
||
|
||
### UserPromptSubmit
|
||
```json
|
||
{
|
||
"decision": "block",
|
||
"reason": "explanation",
|
||
"hookSpecificOutput": {
|
||
"hookEventName": "UserPromptSubmit",
|
||
"additionalContext": "context string"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Stop
|
||
```json
|
||
{
|
||
"decision": "block",
|
||
"reason": "Must complete tasks X, Y, Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 处理器类型
|
||
|
||
### 1. Command Hook
|
||
```json
|
||
{
|
||
"type": "command",
|
||
"command": "bash /path/to/script.sh",
|
||
"timeout": 600,
|
||
"async": false
|
||
}
|
||
```
|
||
|
||
### 2. Prompt Hook
|
||
```json
|
||
{
|
||
"type": "prompt",
|
||
"prompt": "Evaluate: $ARGUMENTS",
|
||
"model": "haiku",
|
||
"timeout": 30
|
||
}
|
||
```
|
||
|
||
响应格式：
|
||
```json
|
||
{
|
||
"ok": true|false,
|
||
"reason": "explanation if ok is false"
|
||
}
|
||
```
|
||
|
||
### 3. Agent Hook
|
||
```json
|
||
{
|
||
"type": "agent",
|
||
"prompt": "Verify tests pass: $ARGUMENTS",
|
||
"model": "haiku",
|
||
"timeout": 60
|
||
}
|
||
```
|
||
|
||
响应格式：与 Prompt Hook 相同
|
||
|
||
---
|
||
|
||
## 环境变量
|
||
|
||
### 标准变量
|
||
```bash
|
||
$CLAUDE_PROJECT_DIR # 项目根目录
|
||
$CLAUDE_PLUGIN_ROOT # 插件根目录（插件内部使用）
|
||
$CLAUDE_CODE_REMOTE # "true" 在远程环境
|
||
```
|
||
|
||
### SessionStart 特殊变量
|
||
```bash
|
||
$CLAUDE_ENV_FILE # 持久化环境变量的文件路径
|
||
```
|
||
|
||
用法：
|
||
```bash
|
||
#!/bin/bash
|
||
if [ -n "$CLAUDE_ENV_FILE" ]; then
|
||
echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
|
||
fi
|
||
```
|
||
|
||
---
|
||
|
||
## 常见用例
|
||
|
||
### 1. 格式化代码
|
||
```json
|
||
{
|
||
"hooks": {
|
||
"PostToolUse": [
|
||
{
|
||
"matcher": "Edit|Write",
|
||
"hooks": [
|
||
{
|
||
"type": "command",
|
||
"command": "jq -r '.tool_input.file_path' | xargs prettier --write"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 阻止危险命令
|
||
```json
|
||
{
|
||
"hooks": {
|
||
"PreToolUse": [
|
||
{
|
||
"matcher": "Bash",
|
||
"hooks": [
|
||
{
|
||
"type": "command",
|
||
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm.sh"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
脚本 `block-rm.sh`:
|
||
```bash
|
||
#!/bin/bash
|
||
COMMAND=$(jq -r '.tool_input.command')
|
||
if echo "$COMMAND" | grep -q 'rm -rf'; then
|
||
echo "Blocked: rm -rf is not allowed" >&2
|
||
exit 2
|
||
fi
|
||
exit 0
|
||
```
|
||
|
||
### 3. 通知用户
|
||
```json
|
||
{
|
||
"hooks": {
|
||
"Notification": [
|
||
{
|
||
"matcher": "permission_prompt",
|
||
"hooks": [
|
||
{
|
||
"type": "command",
|
||
"command": "osascript -e 'display notification \"Claude needs your attention\"'"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 确认任务完成
|
||
```json
|
||
{
|
||
"hooks": {
|
||
"Stop": [
|
||
{
|
||
"hooks": [
|
||
{
|
||
"type": "prompt",
|
||
"prompt": "Check if all tasks complete: $ARGUMENTS"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5. 异步运行测试
|
||
```json
|
||
{
|
||
"hooks": {
|
||
"PostToolUse": [
|
||
{
|
||
"matcher": "Write",
|
||
"hooks": [
|
||
{
|
||
"type": "command",
|
||
"command": "/path/to/run-tests.sh",
|
||
"async": true,
|
||
"timeout": 120
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6. 会话开始注入上下文
|
||
```json
|
||
{
|
||
"hooks": {
|
||
"SessionStart": [
|
||
{
|
||
"matcher": "compact",
|
||
"hooks": [
|
||
{
|
||
"type": "command",
|
||
"command": "echo 'Reminder: use Bun, not npm'"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 配置位置
|
||
|
||
| 位置 | 作用域 | 可共享 |
|
||
|------|--------|--------|
|
||
| `~/.claude/settings.json` | 全局用户 | ❌ |
|
||
| `.claude/settings.json` | 单个项目 | ✅ |
|
||
| `.claude/settings.local.json` | 单个项目 | ❌ (gitignored) |
|
||
| 插件 `hooks/hooks.json` | 插件启用时 | ✅ |
|
||
| Skill/Agent frontmatter | 组件活动时 | ✅ |
|
||
|
||
---
|
||
|
||
## 调试技巧
|
||
|
||
### 1. 详细模式
|
||
```bash
|
||
claude --debug # 查看完整钩子执行细节
|
||
Ctrl+O # 切换详细模式（实时）
|
||
```
|
||
|
||
### 2. 测试钩子脚本
|
||
```bash
|
||
echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
|
||
echo $? # 检查退出码
|
||
```
|
||
|
||
### 3. 检查钩子配置
|
||
```
|
||
/hooks # 交互式钩子管理器
|
||
```
|
||
|
||
---
|
||
|
||
## 最佳实践
|
||
|
||
✅ **推荐：**
|
||
- 总是引用 shell 变量：`"$VAR"`
|
||
- 使用绝对路径：`"$CLAUDE_PROJECT_DIR"/script.sh`
|
||
- 设置合理的超时时间
|
||
- 验证和清理输入数据
|
||
- 在 Stop 钩子中检查 `stop_hook_active`
|
||
- 使用 async 进行长时间运行的操作
|
||
|
||
❌ **避免：**
|
||
- 直接信任输入数据
|
||
- 使用相对路径
|
||
- 在钩子输出中暴露敏感数据
|
||
- 创建无限循环（尤其在 Stop 钩子）
|
||
- 没有设置超时的阻塞操作
|
||
|
||
---
|
||
|
||
## 官方资源
|
||
|
||
- **指南**: https://code.claude.com/docs/en/hooks-guide
|
||
- **参考**: https://code.claude.com/docs/en/hooks
|
||
- **示例**: https://github.com/anthropics/claude-code/tree/main/examples/hooks
|
||
|
||
---
|
||
|
||
## 本地文档
|
||
|
||
- `HOOKS_OFFICIAL_GUIDE.md` - 官方指南中文版
|
||
- `HOOKS_OFFICIAL_REFERENCE.md` - 官方参考中文版
|
||
- `HOOKS_ANALYSIS_REPORT.md` - 当前实现对比分析
|
||
- `hooks_bash_command_validator.py` - 官方示例脚本
|