SuperAPI AI 工具集

mastering-hooks

编程与开发

查看项目

更新于 10-16 06:39

技能介绍

用途

RuleZ 是一个高性能的 AI 策略引擎,用于拦截 AI 编程助手事件并执行配置好的动作。它通过基于适配器的事件转换在多个平台上工作。本技能(mastering-hooks)是用于安装、调试和优化 RuleZ 的智能助手。

工作流程示意:

User Prompt --> AI Assistant --> RuleZ Binary --> [Match Rules] --> Execute Actions
                    |                                 |
                    v                                 v
              PreToolUse                       inject/run/block
              PostToolUse                      context/validation
              BeforeAgent
              PermissionRequest

支持的平台:

  • Claude Code(原生)——完整事件支持
  • Gemini CLI——通过适配器,双触发事件
  • GitHub Copilot——通过适配器
  • OpenCode——通过适配器,双触发事件

系统组件:

  • RuleZ Binary(Rust):运行时快速、确定性地执行钩子
  • hooks.yaml:声明式配置,定义规则、匹配器和动作
  • 平台适配器:将平台特定事件转换为统一的 RuleZ 事件类型
  • 本技能:用于安装、调试和优化的智能助手

主要能力

1. 安装与初始化 RuleZ

适用场景:首次在项目中或用户范围内设置 RuleZ。

检查清单:

  • 验证 RuleZ 二进制已安装:rulez --version
  • 初始化配置:rulez init(创建 .claude/hooks.yaml)
  • 注册到 Claude Code:rulez install(项目本地)或 rulez install --global
  • 验证配置:rulez validate
  • 验证安装:检查 .claude/settings.json 中的钩子条目

参考:cli-commands.md

2. 创建钩子规则

适用场景:添加新行为,如上下文注入、命令验证或工作流自动化。

检查清单:

  • 确定事件类型(PreToolUse、PostToolUse、BeforeAgent 等)
  • 定义匹配器(工具、扩展名、目录、模式)
  • 选择动作类型(inject、run、block、require_fields)
  • 在 hooks.yaml 中编写规则
  • 验证:rulez validate
  • 测试:rulez debug <event> --tool <tool_name>

规则结构示例:

rules:
  - name: rule-name           # kebab-case 标识符
    matchers:
      operations: [PreToolUse]  # 何时触发
      tools: [Write, Edit]    # 匹配什么
      extensions: [.py]       # 可选:文件过滤
    actions:
      inject: .claude/context/python-standards.md  # 做什么

参考:hooks-yaml-schema.md | rule-patterns.md

3. 解释配置

适用场景:理解现有钩子的作用、存在原因或它们如何交互。

检查清单:

  • 运行 rulez explain rule <rule-name> 进行特定规则分析
  • 运行 rulez explain rules 获取完整配置概览
  • 检查规则优先级(同一事件内先匹配者胜出)
  • 识别潜在冲突或重叠

rulez explain rule python-standards 的示例输出:

Rule: python-standards
Event: PreToolUse
Triggers when: Write or Edit tool used on .py files
Action: Injects content from .claude/context/python-standards.md

参考:cli-commands.md

4. 排查钩子问题

适用场景:钩子未触发、行为异常或出现错误消息。

诊断检查清单:

  • 验证配置:rulez validate——捕获 YAML/schema 错误
  • 检查注册:cat .claude/settings.json | grep hooks
  • 启用调试日志:rulez debug PreToolUse --tool Write --verbose
  • 检查日志:rulez logs --limit 20
  • 验证文件路径:确保所有 path: 引用存在

常见问题:

症状 可能原因 修复
钩子从不触发 事件/匹配器不匹配 使用 rulez debug 追踪匹配
"file not found" 动作中的路径无效 检查相对于项目根目录的路径
上下文未注入 脚本返回无效 JSON 验证脚本输出格式
Permission denied 脚本不可执行 chmod +x script.sh
Gemini 上事件不触发 事件名称错误 查看 platform-adapters.md 中的映射

参考:troubleshooting-guide.md

5. 优化配置

适用场景:规则过多、执行缓慢或维护复杂。

优化检查清单:

  • 用更宽的匹配器合并重叠规则
  • 使用 enabled_when 实现条件规则,而非重复规则
  • 将共享上下文移至可复用的 markdown 文件
  • 按频率排序规则(最常见的在前)
  • 尽早使用 block 短路不必要的处理

参考:rule-patterns.md

6. 多平台设置

适用场景:配置 RuleZ 以在 Claude Code 之外还支持 Gemini CLI、GitHub Copilot 或 OpenCode。

关键概念:

  • RuleZ 使用平台适配器将各平台的原生事件转换为统一的 RuleZ 事件类型
  • 使用 RuleZ 事件类型(如 PreToolUse)编写规则——适配器自动处理转换
  • 某些平台会触发双事件(例如 Gemini 的 BeforeAgent 会同时触发 BeforeAgent 和 UserPromptSubmit)

检查清单:

  • 安装 RuleZ:rulez install
  • 使用标准 RuleZ 事件类型编写规则
  • 使用 rulez debug <event> 测试以验证匹配
  • 查看 platform-adapters.md 了解平台特定事件映射

参考:platform-adapters.md

使用方式

根据需求选择路径(决策树):

What do you need?
|
+-- New to RuleZ? --> [1. Install & Initialize]
|
+-- Have hooks.yaml but hooks not working? --> [4. Troubleshoot]
|
+-- Need to add new behavior? --> [2. Create Rules]
|
+-- Want to understand existing config? --> [3. Explain Configuration]
|
+-- Performance or complexity issues? --> [5. Optimize]
|
+-- Setting up for Gemini/Copilot/OpenCode? --> [6. Multi-Platform Setup]

适用场景

  • 首次在项目中或用户范围内安装与初始化 RuleZ
  • 添加上下文注入、命令验证或工作流自动化等新行为
  • 理解现有钩子配置的作用与交互
  • 排查钩子未触发、行为异常或错误消息
  • 优化规则数量、执行速度或维护复杂度
  • 为 Gemini CLI、GitHub Copilot 或 OpenCode 进行多平台设置

限制

以下情况不适合使用本技能:

  • 简单的 Claude Code 配置:直接使用 settings.json 进行基本权限设置
  • 一次性上下文注入:直接粘贴到提示词中即可
  • 动态运行时决策:RuleZ 是确定性的;复杂逻辑请使用 MCP 服务器

参考资料

文档 用途
quick-reference.md 事件、匹配器、动作、文件位置
hooks-yaml-schema.md 完整 YAML 配置参考
cli-commands.md 所有 CLI 命令及示例
rule-patterns.md 常见模式与配方
troubleshooting-guide.md 诊断流程
platform-adapters.md 多平台事件映射与双触发

完整 hooks.yaml 示例

# .claude/hooks.yaml
version: "1"

rules:
  # Inject Python standards before writing Python files
  - name: python-standards
    matchers:
      operations: [PreToolUse]
      tools: [Write, Edit]
      extensions: [.py]
    actions:
      inject: .claude/context/python-standards.md

  # Block dangerous git commands
  - name: block-force-push
    priority: 10
    matchers:
      operations: [PreToolUse]
      tools: [Bash]
      command_match: "git push.*--force"
    actions:
      block: true

  # Run security check before committing
  - name: pre-commit-security
    matchers:
      operations: [PreToolUse]
      tools: [Bash]
      command_match: "git commit"
    actions:
      run: .claude/validators/check-secrets.sh

  # Track agent activity (works on Claude Code and Gemini)
  - name: log-agent-start
    description: Ensure agents follow project conventions
    matchers:
      operations: [BeforeAgent]
    actions:
      inject_inline: |
        **Agent Policy**: Follow project conventions in CLAUDE.md.