AI 插件开发工具插件系统【免费下载链接】claude-plugins-officialOfficial, Anthropic-managed directory of high quality Claude Code Plugins.项目地址https://gitcode.com/GitHub_Trending/cl/claude-plugins-official点击查看免费下载导读本文聚焦 Claude Code 插件 Hookify 中的一条实战规则示例——require-tests-stop.local.md查看原示例文件。该规则利用 Hookify 的Stop 事件钩子在 Agent 准备结束会话时检查整个会话记录transcript若其中没有出现npm test、pytest或cargo test等测试命令就以block动作阻止会话结束从而形成一道测试门禁。读完本文你将掌握Stop 事件规则的完整 frontmatter 字段含义、transcript字段与not_contains运算符的底层求值逻辑、decision: block的响应协议以及如何在自己项目中启用、测试与调试这条规则。一、规则文件全貌逐字段拆解require-tests-stop.local.md采用 Hookify 的标准Markdown YAML frontmatter格式规则声明与提示消息分离。完整内容如下--- name: require-tests-run enabled: false event: stop action: block conditions: - field: transcript operator: not_contains pattern: npm test|pytest|cargo test --- **Tests not detected in transcript!** Before stopping, please run tests to verify your changes work correctly. Look for test commands like: - npm test - pytest - cargo test **Note:** This rule blocks stopping if no test commands appear in the transcript. Enable this rule only when you want strict test enforcement.1.name规则名称require-tests-run。该名称会出现在 Hookify 的规则列表/hookify:list与触发时的提示前缀中如**[require-tests-run]**建议使用 kebab-case 且以动作动词开头require / block / warn便于语义化管理。2.enabled: false默认关闭这是一个默认关闭disabled的示例规则因为它属于严格模式——一旦开启Agent 在没跑过测试的情况下将无法正常结束会话。启用方式有两种手动编辑该文件将enabled: false改为enabled: true运行/hookify:configure交互式切换。3.event: stop绑定 Stop 事件stop是 Hookify 支持的五个事件类型之一bash、file、stop、prompt、all含义是当 Claude 准备停止结束本轮任务时触发常用于完成度检查、交付前校验等场景。4.action: block阻止会话结束在 Stop 事件中block表示拒绝 Agent 停止并要求它先完成条件本例即先运行测试。这与 PreToolUse 事件中的block拒绝工具执行含义一致都是拦截只是拦截对象不同。若只想提示而不强制可改为warn这也是默认值。5.conditionstranscriptnot_contains核心判定逻辑field: transcript匹配目标不是某个工具参数而是本次会话的完整记录文本operator: not_contains要求 transcript不包含pattern 所指定的子串Python 的pattern in field_value取反见 rule_engine.pypattern: npm test|pytest|cargo test这是字面子串匹配非正则|只是普通字符的一部分用于覆盖三类主流测试命令。注意conditions 列表内所有条件必须全部命中AND 关系规则才会触发。本例只有一条条件即transcript 中没有任何一条测试命令字样时触发。6. 消息体提示给 Agent 看的内容frontmatter 之后的内容会被解析为规则消息message字段。当规则触发时RuleEngine 会以**[require-tests-run]**\n{message}的形式注入 systemMessage明确告知 Agent会话记录中未检测到测试命令结束前请先运行测试检查npm test/pytest/cargo test。二、源码级原理从 Stop 事件到 transcript 读取的完整调用链要真正理解这条规则需要沿着 Hookify 的钩子执行链路走一遍对应文件hooks.json、stop.py、rule_engine.py、config_loader.py。第 1 步注册 Stop 钩子在 hooks.json 中Stop事件被注册为Stop: [ { hooks: [ { type: command, command: python3 \${CLAUDE_PLUGIN_ROOT}/hooks/stop.py\, timeout: 10 } ] } ]即每次 Agent 准备停止时Claude Code 都会以 JSONstdin方式调用stop.py。第 2 步stop.py 加载规则并评估stop.py 的核心流程是input_data json.load(sys.stdin) rules load_rules(eventstop) engine RuleEngine() result engine.evaluate_rules(rules, input_data) print(json.dumps(result), filesys.stdout)load_rules(eventstop)只加载event为stop或all且enabled: true的规则见 config_loader.py。这解释了为什么enabled: false的示例规则默认不生效——加载阶段就直接被过滤掉了无论结果如何脚本finally中始终sys.exit(0)即 Hookify 自身出错不会导致流程被意外卡死属于故障时放行的安全设计。第 3 步RuleEngine 对 Stop 事件的求值rule_engine.py 的evaluate_rules中blocking 规则命中的响应格式与事件类型强相关。对于 Stop 事件if hook_event Stop: return { decision: block, reason: combined_message, systemMessage: combined_message }也就是说action: block Stop 事件命中时Claude Code 会收到decision: block从而不允许 Agent 结束会话并把reason/systemMessage中的请先运行测试提示交给 Agent 继续执行。这正是测试门禁的落地机制。第 4 步transcript 字段的取值逻辑field: transcript并不存在于工具参数中它由_extract_field特殊处理见 rule_engine.pyelif field transcript: transcript_path input_data.get(transcript_path) if transcript_path: with open(transcript_path, r) as f: return f.read()即Stop 事件的 hook 输入中带有transcript_pathHookify 会读取该文件全文作为匹配文本再交给not_contains判断。若文件读取失败不存在、无权限、编码问题等会返回空字符串并打印 warning——此时not_contains对空串必然为真规则将触发。这一点在调试为什么一直拦截我停止时需要特别留意。第 5 步not_contains 的运算符语义条件求值在 rule_engine.py 中完成not_contains即pattern not in field_value——是大小写敏感的子串判断并非正则匹配。因此若 Agent 实际执行了NPM TEST大写或pytest --cov仍可能被判定为未检测到测试命令。需要更宽松或更精确的匹配时可改用regex_match运算符配合忽略大小写的正则Hookify 编译正则时使用re.IGNORECASE见 rule_engine.py。三、实战启用、验证与调试测试门禁1. 启用规则将规则文件放入项目根目录的.claude/目录注意不是插件自身目录命名遵循hookify.*.local.md例如复制为.claude/hookify.require-tests.local.md然后把 frontmatter 改为enabled: true。规则即刻生效无需重启——下一次 Stop 事件触发时stop.py会自动加载它。2. 验证触发在一个尚未运行过任何测试的会话中让 Claude 完成任务并尝试停止。预期行为Hookify 返回decision: blockAgent 收到类似Tests not detected in transcript!的 systemMessageAgent 会被引导先去执行npm test/pytest/cargo test之后再次请求停止此时 transcript 中已包含测试命令规则不再命中会话正常结束。3. 调试技巧确认规则被加载运行/hookify:list检查规则是否出现且enabled状态正确单独验证 pattern 语义not_contains是子串匹配可用python3 -c print(npm test in your transcript text)之类的方式先行验证你的判断逻辑规则频繁误拦优先检查是否因 transcript 文件读取失败权限、路径导致匹配文本为空觉得太严格把action: block改为action: warn此时命中后只注入 systemMessage 提示不阻止停止对应evaluate_rules中仅返回 systemMessage 的分支。4. 多语言 / 多场景变体示例 patternnpm test|pytest|cargo test覆盖了 Node、Python、Rust 三种生态。你可以按项目需要扩展例如加入go test、mvn test、./gradlew test如果希望精确匹配而不误伤其他文本可将运算符改为regex_match并写成\b(npm test|pytest|cargo test)\b配合\s转义处理命令中的多空格。四、与其他示例规则的对比定位Hookify 在 examples/ 目录下还提供了另外三条典型规则可与本规则对照理解 Stop 事件的特殊性规则文件eventaction判定目标触发结果dangerous-rm.local.mdbashblockBash 命令rm\s-rf拒绝工具执行console-log-warning.local.mdfilewarn写入内容console\.log\(提示但放行sensitive-files-warning.local.mdfilewarnfile_path new_text 多条件提示但放行require-tests-stop.local.mdstopblock会话 transcript拒绝结束会话可以看出本规则是四者中唯一的会话级完成度校验它不拦截任何单个工具调用而是在任务的出口把关。这类规则特别适合用于CI 前置的质量保障、交付物完整性校验或对 Agent 纪律性有硬性要求的自动化流程。五、使用前提与注意事项严格模式谨慎开启原文档特别注明Enable this rule only when you want strict test enforcement。一旦开启Agent 未运行测试将无法停止若项目没有测试脚本可能导致会话无法正常收尾规则文件位置必须位于项目根目录.claude/Hookify 通过glob.glob(.claude/hookify.*.local.md)扫描见 config_loader.py删除某条规则只需删除对应的.local.md文件匹配是子串级、大小写敏感not_contains不做正则与大小写归一编写 pattern 时需覆盖实际命令形态无需重启所有规则的增删改都在下一次事件触发时生效环境要求Hookify 依赖 Python 3.7且仅使用标准库无第三方依赖见 README。结语require-tests-stop.local.md是 Hookify 插件中极具代表性的一条 Stop 事件规则它用不足 20 行的 frontmatter 实现了测试通过才能结束会话的工程化约束。配合 stop.py、rule_engine.py、config_loader.py 的源码阅读你不仅能直接复制这条规则投入使用更能举一反三将transcriptnot_containsaction: block的组合推广到提交前必须格式化发布前必须更新文档等任何基于会话历史的完成度门禁场景。更多规则书写语法多条件、运算符与字段参考、pattern 技巧可进一步阅读 writing-rules 技能 与 Hookify README。赞分享AI 插件开发工具插件系统【免费下载链接】claude-plugins-officialOfficial, Anthropic-managed directory of high quality Claude Code Plugins.项目地址https://gitcode.com/GitHub_Trending/cl/claude-plugins-official点击查看免费下载相关推荐ECC Hookify 实战指南从会话分析到自动生成 Claude Code 防呆钩子规则ECC Hookify 实战指南从会话分析到自动生成 Claude Code 防呆钩子规则 在 ECCEverything Claude CodeAgen人工智能AI 技能AI 插件AI 评测Agent 评测MCP Clients开发工具ECC Hookify 规则系统实战:用 /hookify 将 Claude Code 的不良行为固化为可管理的钩子规则ECC Hookify 规则系统实战:用 /hookify 将 Claude Code 的不良行为固化为可管理的钩子规则 ECC Everything Clau人工智能AI 技能AI 插件AI 评测Agent 评测MCP Clients开发工具Hookify 插件实战指南用 Markdown 规则文件为 Claude Code 自定义 HookHookify 插件实战指南用 Markdown 规则文件为 Claude Code 自定义 Hook 本指南完整讲解 Claude Code 官方插件目录中AI 插件开发工具插件系统上一篇SteamAutoCrack离线破解教程4步摘掉SteamStub枷锁断网也能畅玩已购游戏下一篇mpv_PlayKit 快速上手指南300 余款着色器与全中文配置Windows 播放器一次调到位创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
