跳到主要内容

🪝 Hooks 钩子

Hooks（钩子） 是在特定事件发生时自动执行的操作，让重复性任务自动化、可观测化。ECC v2.0.0 引入了统一调度器架构（consolidated dispatcher），所有 hook 通过 hooks/hooks.json 注册，由 pre-bash-dispatcher.js 和 post-bash-dispatcher.js 统一调度。

什么是钩子？​

钩子就像 智能管家：

  • 📁 保存文件时 → 自动格式化
  • 🔨 编辑 TypeScript 时 → 自动类型检查
  • 🚫 检测到 console.log → 自动警告
  • 🛡️ 危险命令 → 自动拦截（GateGuard）
  • 📊 会话开始 → 加载上下文、检测项目状态

7 类事件​

事件触发时机用途
SessionStart会话开始加载上下文、检测项目状态、注入历史
PreToolUse工具调用前拦截危险操作、提醒检查、注入观察信号
PostToolUse工具调用后格式化、类型检查、记录结果
PostToolUseFailure工具调用失败记录失败、分析静默失败
PreCompact上下文压缩前持久化会话状态
Stop每次响应结束格式检查、覆盖率检查、console.log 审计
SessionEnd会话结束归档、清理、释放资源

47 个钩子脚本​

🛡️ Pre-tool 拦截类​

脚本 ID触发条件用途
pre:bash:dispatcherBash统一调度：质量、tmux、push、GateGuard
pre:write:doc-file-warningWrite警告非标准文档文件
pre:edit-write:suggest-compactEdit/Write提示手动压缩上下文
pre:observe:continuous-learning任意捕获工具调用用于持续学习
pre-bash-dev-server-blockBash阻止后台 dev 服务器
pre-bash-tmux-reminderBash提醒使用 tmux
pre-bash-git-push-reminderBashpush 之前提醒
pre-bash-commit-qualityBashcommit 前质量检查
pre-write-doc-warnWrite文档写入警告
block-no-verifyBash拦截 --no-verify
config-protectionEdit/Write阻止修改 hooks.json
gateguard-fact-forceBashGateGuard 强制检查
quality-gateBash质量门检查

🔧 Post-tool 处理类​

脚本 ID触发条件用途
post:bash:dispatcherBash统一调度：构建完成、PR 创建、命令日志
post:edit:formatEditPrettier 自动格式化
post:edit:typecheckEditTypeScript 类型检查
post:edit:console-warnEdit检测 console.log
post:edit:accumulatorEdit编辑累积器
post-bash-build-completeBash构建完成通知
post-bash-pr-createdBashPR 创建后处理
post-bash-command-logBash命令日志
check-console-logStop审计 console.log
stop-format-typecheckStop格式与类型检查
evaluate-sessionStop会话评估

📊 会话生命周期​

脚本 ID触发条件用途
session:startSessionStart加载上下文
session-start-bootstrapSessionStart项目状态检测
session-startSessionStart会话启动
session-activity-tracker周期活动追踪
session-end-markerSessionEnd结束标记
session-endSessionEnd会话结束处理
pre:compactPreCompact压缩前持久化

📈 可观测与监控​

脚本 ID用途
observe-runner连续学习观察器（pre + post 两个 hook ID）
ecc-context-monitor上下文窗口监控
ecc-metrics-bridge指标桥接
ecc-statusline状态栏
desktop-notify桌面通知
cost-tracker成本追踪
governance-capture治理捕获
mcp-health-checkMCP 健康检查

🔒 安全与合规​

脚本 ID用途
insaits-security-monitor.py实时安全监控
insaits-security-wrapper.js安全包装器
cursor-session-envCursor 会话环境隔离

🎨 设计与质量​

脚本 ID用途
design-quality-check设计质量检查
auto-tmux-dev.js自动 tmux dev 环境

Hook 配置：hooks/hooks.json​

所有 hook 在 hooks/hooks.json 中注册：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "...", "id": "pre:bash:dispatcher" }
        ]
      },
      {
        "matcher": "Write",
        "hooks": [
          { "type": "command", "command": "...", "id": "pre:write:doc-file-warning" }
        ]
      }
    ],
    "PostToolUse": [...],
    "SessionStart": [...],
    "PreCompact": [...],
    "Stop": [...],
    "SessionEnd": [...]
  }
}

调度器架构（v2.0.0 新增）​

ECC v2.0.0 引入统一调度器（consolidated dispatcher）模式：

  • pre-bash-dispatcher.js 是所有 Bash 调用的入口
  • 根据命令类型分发到对应的专项 hook（quality / tmux / push / GateGuard）
  • 减少 hook 数量但保持功能完整性
  • 显著降低延迟（从 7-8 个 hook 串行执行 → 1 个调度器分发）

旧版的多个独立 hook（如 pre-bash-quality.js + pre-bash-tmux.js + pre-bash-push.js）已合并到调度器内。

干跑模式（dry-run，v2.0.0）​

任何 hook 都可通过 --dry-run 标志预览其行为而不真正执行：

# 查看 hook 决策但不应用
git commit --dry-run
node scripts/hooks/pre-bash-dispatcher.js --dry-run

干跑模式输出 hook 将要执行的命令、拦截原因和建议动作。

钩子执行流程​

自定义 Hook​

在 ~/.claude/settings.json 中添加：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_TOOL_FILE_PATH"
          }
        ]
      }
    ]
  }
}

可用的占位符：

  • $CLAUDE_TOOL_FILE_PATH — 被修改的文件路径
  • $CLAUDE_TOOL_INPUT — 工具输入
  • $CLAUDE_PROJECT_DIR — 项目根目录

最佳实践​

  1. 保持钩子轻量 - 避免耗时操作阻塞工具调用
  2. 明确触发条件 - 用 matcher 限定精确范围
  3. 友好错误信息 - 拦截时说明原因和建议
  4. 可配置开关 - 允许临时禁用（用 /hookify 命令）
  5. 使用调度器模式 - 不要为每个场景写独立 hook

调试与排查​

# 列出所有已注册 hook
/hookify-list

# 查看 hook 帮助
/hookify-help

# 临时禁用某个 hook
/hookify-configure disable pre:bash:dispatcher

# 启用干跑模式查看决策
git commit --dry-run

💡 提示：钩子是提升开发效率的利器，但过多的钩子可能拖慢工作流。ECC 用调度器架构解决了这个权衡 — 7 类事件，47 个脚本，单入口调度。