hooks-eval

用途

hooks-eval 是一个用于评估、审计和实现 Claude Code hooks 的技能，覆盖所有作用域（插件、项目、全局），并同时支持基于 JSON 的 hooks 和基于 Python SDK 的编程式 hooks。它主要用于对已有 hook 进行安全、性能与 SDK 合规方面的审计。

主要能力

安全分析：漏洞扫描、危险模式检测、注入防护。
性能分析：执行时间基准测试、资源使用情况、优化建议。
合规检查：结构校验、文档要求、最佳实践检查。
SDK 集成：Python SDK 的 hook 类型、回调、匹配器与模式。

核心组件

Hook Types Reference：完整的 SDK hook 事件类型与签名。
Evaluation Criteria：评分系统与质量门禁。
Security Patterns：常见漏洞与缓解措施。
Performance Benchmarks：阈值与优化指导。

Hook 事件类型

HookEvent 包括：PreToolUse（工具执行前）、PostToolUse（工具执行后）、UserPromptSubmit（用户提交提示时）、Stop（停止执行时）、SubagentStop（子代理停止时）、TeammateIdle（队友代理空闲时，2.1.33+）、TaskCompleted（任务完成执行时，2.1.33+）、PreCompact（消息压缩前）。

注意：Python SDK 由于设置限制，不支持 SessionStart、SessionEnd 或 Notification hooks。但插件可以通过 hooks.json 使用 shell 命令定义 SessionStart hooks（例如 leyline 的 detect-git-platform.sh）。

插件级 hooks.json

插件可在 plugin.json 中通过 "hooks": "./hooks/hooks.json" 声明 hooks。评估器会校验：引用的 hooks.json 是否存在且为有效 JSON；hooks 中引用的 shell 命令是否存在且可执行；hook 匹配器是否使用有效的事件类型。

Hook 回调签名

async def my_hook(input_data: dict[str, Any], tool_use_id: str | None, context: HookContext) -> dict[str, Any]。返回值可包含 hookSpecificOutput，其中含 hookEventName、permissionDecision（可选，用于阻止操作）、permissionDecisionReason、additionalContext（可选）。

质量评分（100 分）

安全：30 分，关注漏洞、注入、校验。
性能：25 分，关注执行时间、内存、I/O。
合规：20 分，关注结构、文档、错误处理。
可靠性：15 分，关注超时、幂等性、降级。
可维护性：10 分，关注代码结构、模块化。

使用方式

基本评估工作流：

1. 运行详细评估

/hooks-eval --detailed

2. 聚焦安全问题

/hooks-eval --security-only --format sarif

3. 性能基准测试

/hooks-eval --performance-baseline

4. 检查合规

/hooks-eval --compliance-report

与其他工具集成（完整插件评估流水线）：

/hooks-eval --detailed # 评估所有 hooks /analyze-hook hooks/specific.py # 深入分析单个 hook /validate-plugin . # 校验整体结构

适用场景

对 hook 进行安全审计与漏洞排查。
对 hook 进行性能基准测试与优化。
检查 hook 是否符合 SDK 规范与最佳实践。
校验插件级 hooks.json 的结构与引用完整性。

限制与不适用场景

不适用于编写新 hook（应使用 abstract:hook-authoring）。
不适用于评估 skills（应使用 abstract:skills-eval）。
不适用于评估 .claude/rules/ 中的规则（应使用 abstract:rules-eval）。
Python SDK 不支持 SessionStart、SessionEnd、Notification hooks。

故障排查

Hook 未触发：确认 hook 模式与事件匹配，检查 hook 日志中的错误。
语法错误：部署前校验 JSON/Python 语法。
权限被拒：检查 hook 文件权限与所有权。

退出标准

作用域内每个 hook 都获得跨五个加权类别的综合质量分（0-100）：安全（30）、性能（25）、合规（20）、可靠性（15）、可维护性（10）。
任何在安全类别低于 60 分的 hook 在返回评估报告前被标记为阻塞性问题。
hooks.json 中引用的 shell 命令被验证存在且可执行；缺失脚本列为 FAIL 发现项。
评估报告区分 JSON hooks（Claude Code）与 Python SDK hooks，并对每种类型应用正确的签名预期。

技能介绍

用途