SuperAPI AI 工具集

writing-hookify-rules

编程与开发

查看项目

更新于 11-10 16:24

技能介绍

Writing Hookify Rules 介绍

用途

Writing Hookify Rules 是一项技能指导,用于帮助用户创建、编写和配置 Hookify 规则。当用户提出“创建 hookify 规则”“编写 hook 规则”“配置 hookify”“添加 hookify 规则”等需求时使用。

Hookify 规则是带有 YAML frontmatter 的 Markdown 文件,用于定义需要监控的模式,以及模式匹配时要显示的消息。规则存储在 .claude/hookify.{rule-name}.local.md 文件中。

规则文件格式

基本结构包含 YAML frontmatter 和正文消息:

---
name: rule-identifier
enabled: true
event: bash|file|stop|prompt|all
pattern: regex-pattern-here
---

frontmatter 之后的 Markdown 内容会在规则触发时展示给 Antigravity,可包含 Markdown 格式、警告、建议等。

字段说明

  • name(必填):规则唯一标识,建议使用 kebab-case,以动词开头(warn、prevent、block、require、check)。
  • enabled(必填):布尔值,控制规则启用或禁用,可切换而无需删除规则。
  • event(必填):触发规则的事件类型:
    • bash:run_command 工具命令
    • file:replace_file_content、write_to_file、MultiEdit 工具
    • stop:智能体准备停止时
    • prompt:用户提交提示词时
    • all:所有事件
  • action(可选):规则匹配后的动作,warn 显示消息但允许操作(默认),block 阻止操作(PreToolUse)或终止会话(Stop 事件)。
  • pattern:用于简单单条件规则的正则模式,匹配 bash 命令或 file 的 new_text,使用 Python 正则语法。

高级格式(多条件)

复杂规则可使用 conditions 列表,每个条件包含 field、operator、pattern,所有条件都匹配时规则才触发。

条件字段:bash 事件为 command;file 事件为 file_path、new_text、old_text、content;prompt 事件为 user_prompt。

操作符:regex_match(正则匹配)、contains(包含子串)、equals(精确匹配)、not_contains(不得包含)、starts_with(前缀)、ends_with(后缀)。

消息正文

frontmatter 之后的 Markdown 内容会展示给 Antigravity。好的消息应说明检测到了什么、为什么有问题、建议替代方案或最佳实践,并可使用加粗、列表等格式增强可读性。

事件类型指南

  • bash:匹配 run_command 命令模式,常见如危险命令(rm -rf、dd if=、mkfs)、权限提升(sudo、su)、权限问题(chmod 777、chown root)。
  • file:匹配文件编辑操作,可针对不同字段匹配,如限定 .tsx 文件中的 console.log。常见模式包括调试代码、安全风险(eval、innerHTML、dangerouslySetInnerHTML)、敏感文件(.env、credentials、.pem)、生成文件(node_modules、dist、build)。
  • stop:智能体准备停止时触发,用于完成检查清单、步骤提醒、流程强制。
  • prompt:匹配用户提示内容,例如检测“deploy to production”以显示生产部署检查清单。

正则表达式技巧

普通字符直接匹配;特殊字符需要转义(. 写作 \.,括号写作 \( \))。常用元字符:\s 空白、\d 数字、\w 单词字符、. 任意字符、+ 一个或多个、* 零个或多个、? 零个或一个、| 或。

可使用 Python 测试正则:python3 -c "import re; print(re.search(r'your_pattern', 'test text'))",或使用在线正则测试工具(Python 风格)。

常见陷阱:模式过宽(如 log 会匹配 login、dialog、catalog)、模式过窄(如 rm -rf /tmp 只匹配精确路径)、转义问题(YAML 引号字符串需双反斜杠,建议使用不带引号的模式)。

文件组织

所有规则放在 .claude/ 目录,命名为 .claude/hookify.{descriptive-name}.local.md,并将 .claude/*.local.md 加入 .gitignore。应使用描述性的名称,如 hookify.dangerous-rm.local.md、hookify.console-log.local.md。

工作流程

创建规则:识别不期望的行为 → 确定涉及的工具 → 选择事件类型 → 编写正则模式 → 在项目根目录创建 .claude/hookify.{name}.local.md 文件 → 立即测试(规则在下一次工具使用时动态读取)。

调整规则:编辑 .local.md 文件调整模式或消息,更改在下一次工具使用时生效。

禁用规则:临时禁用可在 frontmatter 中设置 enabled: false;永久禁用可删除 .local.md 文件。

示例

插件示例目录(${ANTIGRAVITY_PLUGIN_ROOT}/examples/)包含完整示例:dangerous-rm.local.md(阻止危险的 rm 命令)、console-log-warning.local.md(警告 console.log)、sensitive-files-warning.local.md(警告编辑 .env 文件)。

适用场景与限制

适用于需要为 Antigravity 智能体添加行为约束、安全提示、完成检查与流程强制的开发场景。规则以文件形式定义并在工具调用时动态加载,修改后需在下一次工具使用时生效。规则依赖 Python 正则语法,需注意转义与模式范围。关于收费、平台支持范围等更多信息暂未提供。