Skip to content

hooks_configuration.md

Latest commit

 

History

History
180 lines (143 loc) · 4.82 KB

hooks_configuration.md

File metadata and controls

180 lines (143 loc) · 4.82 KB

TaskSentinel Claude Code Hooks 最佳实践配置

中文 | English

这个配置文件为TaskSentinel项目提供了完整的Claude Code hooks配置，结合了实时通知功能和代码质量保证。

配置概览

核心通知钩子

  • Notification: 当Claude Code发送通知时触发TaskSentinel
  • Stop: 主任务完成时发送通知
  • SubagentStop: 子任务完成时发送通知

代码质量钩子

  • PostToolUse: 文件修改后的质量检查和格式化
  • PreToolUse: 文件修改前的保护和命令验证
  • UserPromptSubmit: 用户输入的安全检查和上下文增强

详细说明

1. 通知钩子 (TaskSentinel核心功能)

"Notification": [
  {
    "hooks": [
      {
        "type": "command",
        "command": "$CLAUDE_PROJECT_DIR/scripts/claude-hook-adapter.sh",
        "timeout": 30
      }
    ]
  }
]

用途: 实现项目的核心功能 - 实时通知，支持显示完整的Claude Code钩子信息 触发时机: 当Claude Code需要用户确认或等待输入时 超时设置: 30秒，确保通知发送不会阻塞主进程 特色功能:

  • 自动识别Claude Code钩子类型（PreToolUse、PostToolUse、Notification等）
  • 显示处理后的友好消息（如：⚙️ Claude Code准备执行命令）
  • 完整展示原始钩子JSON数据，包含session_id、tool_name、tool_input等所有字段
  • 智能消息处理，根据不同工具类型优化显示内容

2. 文件保护钩子

"PreToolUse": [
  {
    "matcher": "Write|Edit|MultiEdit",
    "hooks": [
      {
        "type": "command",
        "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/file-protection.sh",
        "timeout": 15
      }
    ]
  }
]

保护的文件类型:

  • 环境配置文件 (.env, .env.*)
  • 依赖锁定文件 (package-lock.json, yarn.lock)
  • Git仓库文件 (.git/)
  • 密钥文件 (*.key, *.pem, id_rsa等)
  • 生产配置文件

3. 代码质量检查钩子

"PostToolUse": [
  {
    "matcher": "Edit|MultiEdit|Write",
    "hooks": [
      {
        "type": "command",
        "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/code-quality.sh",
        "timeout": 60
      }
    ]
  }
]

功能:

  • Shell脚本: 运行shellcheck检查
  • JSON文件: 验证格式并自动格式化
  • Markdown文件: 记录更新日志

4. Bash命令验证钩子

验证规则:

  • 推荐使用 rg 代替 grep
  • 推荐使用 rg --files 代替 find -name
  • 避免 cat | grep 模式
  • 避免 ls | grep 模式

5. 安全检查钩子

UserPromptSubmit钩子检查用户输入中的敏感信息:

  • password, secret, key, token等关键词
  • 阻止包含敏感信息的提示处理
  • 添加项目相关的上下文信息

文件结构

.claude/
├── settings.json              # 主配置文件
└── hooks/
    ├── bash-validation.sh     # Bash命令验证
    ├── file-protection.sh     # 文件保护
    ├── code-quality.sh        # 代码质量检查
    ├── command-log.sh         # 命令日志记录
    ├── context-enhancer.sh    # 上下文增强
    ├── commands.log           # 命令执行日志
    └── quality.log            # 质量检查日志

使用方法

配置 Claude Code Hooks

  1. 将示例配置复制到 Claude Code 配置目录：

    cp config/claude-settings.example.json .claude/settings.json

  2. 确保适配器脚本具有执行权限：

    chmod +x scripts/claude-hook-adapter.sh

  3. 配置 TaskSentinel 通知设置（参考主 README）

手动测试

您可以手动测试适配器脚本：

# 模拟 Claude Code Notification hook
echo '{"event": "notification", "message": "测试消息"}' | ./scripts/claude-hook-adapter.sh

# 模拟 Claude Code Stop hook  
echo '{"event": "stop", "message": "任务完成"}' | ./scripts/claude-hook-adapter.sh

自定义建议

为特定文件类型添加检查

可以在 code-quality.sh 中添加更多文件类型的处理：

case "$file_path" in
    *.py)
        # Python文件检查
        python -m py_compile "$file_path"
        ;;
    *.js|*.ts)
        # JavaScript/TypeScript检查
        npx eslint "$file_path"
        ;;
esac

调整保护文件列表

在 file-protection.sh 中修改 PROTECTED_PATTERNS 数组。

修改通知超时

根据网络环境调整通知钩子的timeout值。

最佳实践

  1. 渐进启用: 先启用核心通知功能，再逐步添加其他钩子
  2. 日志监控: 定期检查 .claude/hooks/ 下的日志文件
  3. 性能考虑: 钩子脚本都设计为异步执行，不会阻塞主进程
  4. 安全优先: 文件保护和安全检查钩子优先级最高

这个配置确保了TaskSentinel项目既能实现核心的通知功能，又能维护高质量的代码标准和安全性。