概述
ECC 通过内置的 Node 运行时评估项目本地的 Hookify 规则。启用 ECC hooks 时，无需单独的 Hookify 插件或 Python 安装。
Hookify 规则是带 YAML frontmatter 的 Markdown 文件，用于定义要监视的模式以及模式匹配时要显示的消息。规则存储在 .claude/hookify.{rule-name}.local.md 文件中。
规则文件格式
基本结构
---
name: rule-identifier
enabled: true
event: bash|file|stop|prompt|all
pattern: regex-pattern-here
---
Message to show Claude when this rule triggers.
Can include markdown formatting, warnings, suggestions, etc.
Frontmatter 字段
| 字段 | 必填 | 取值 | 说明 |
|---|---|---|---|
| name | 是 | kebab-case 字符串 | 唯一标识符（动词优先：warn-、block-、require-*） |
| enabled | 是 | true/false | 无需删除即可开关 |
| event | 是 | bash/file/stop/prompt/all | 触发此规则的 hook 事件 |
| action | 否 | warn/block | warn（默认）显示消息；block 阻止操作 |
| pattern | 是* | 正则字符串 | 要匹配的模式（*或使用 conditions 编写复杂规则） |
高级格式（多条件）
---
name: warn-env-api-keys
enabled: true
event: file
conditions:
- field: file_path
operator: regex_match
pattern: \.env$
- field: new_text
operator: contains
pattern: API_KEY
---
You're adding an API key to a .env file. Ensure this file is in .gitignore!
各事件可用的条件字段：
- bash：command
- file：file_path、new_text、old_text、content
- prompt：user_prompt
运算符：regex_match、contains、equals、not_contains、starts_with、ends_with。所有条件必须同时匹配，规则才会触发。
事件类型指南
bash 事件
匹配 Bash 命令模式：
- 危险命令：
rm\s+-rf、dd\s+if=、mkfs - 权限提升：
sudo\s+、su\s+ - 权限问题：
chmod\s+777
file 事件
匹配 Edit/Write/MultiEdit 操作：
- 调试代码：
console\.log\(、debugger - 安全风险：
eval\(、innerHTML\s*= - 敏感文件：
\.env$、credentials、\.pem$
stop 事件
完成检查与提醒。模式 .* 始终匹配。
prompt 事件
匹配用户提示内容以强制执行工作流。
模式编写技巧
正则基础
- 转义特殊字符：
.写作\.，(写作\( \s空白，\d数字，\w单词字符+一个或多个，*零个或多个，?可选|或运算符
常见陷阱
- 过宽：
log会匹配 "login"、"dialog"——应使用console\.log\( - 过窄：
rm -rf /tmp——应使用rm\s+-rf - YAML 转义：使用不带引号的模式；带引号字符串需要
\\s
测试
python3 -c "import re; print(re.search(r'your_pattern', 'test text'))"
避免嵌套量词，如 (a+)+。运行时拒绝具有常见灾难性回溯形态的模式，因为规则在 hook 路径中同步运行，且每次正则求值都有 25 ms 硬超时。无效、符号链接或过大的本地规则会 fail open，并输出诊断信息，而不会禁用其他 Hookify 规则。
受 Git 跟踪的本地规则默认禁用。仅在审阅这些文件后设置 ECC_HOOKIFY_ALLOW_TRACKED=1；本地创建的普通被 gitignore 的规则无需该覆盖即可保持活跃。
运行时行为
- warn 将消息作为事件特定的额外上下文注入，不会阻止。
- block 在匹配的 Bash、PowerShell、Write、Edit 或 MultiEdit 调用执行前予以拒绝。
- 在 prompt、post-tool 和 stop 事件上，block 使用 Claude Code 的结构化阻止决定。
- Stop 规则跳过递归的 stop_hook_active 事件，以防止无限续接循环。
文件组织
- 位置：项目根目录的
.claude/目录 - 命名：
.claude/hookify.{descriptive-name}.local.md - Gitignore：将
.claude/*.local.md加入.gitignore
命令
/hookify [description]— 创建新规则（无参数时自动分析对话）/hookify-list— 以表格形式查看所有规则/hookify-configure— 交互式开关规则/hookify-help— 完整文档
快速参考
最小可用规则：
---
name: my-rule
enabled: true
event: bash
pattern: dangerous_command
---
Warning message here