hooks-eval

不适用场景

• 编写新钩子（使用 abstract:hook-authoring）
• 评估技能（使用 abstract:skills-eval）
• 评估 .claude/rules/ 中的规则（使用 abstract:rules-eval）

钩子评估框架

概述

此技能提供一套详细框架，用于评估、审计和实现适用于所有作用域（插件、项目、全局）以及基于 JSON 和程序化（Python SDK）钩子的 Claude Code 钩子。

核心功能

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

核心组件

组件	用途
钩子类型参考	完整的 SDK 钩子事件类型和签名
评估标准	评分系统和质量门槛
安全模式	常见漏洞和缓解措施
性能基准	阈值和优化指南

快速参考

钩子事件类型

HookEvent = Literal[
    "PreToolUse",  # Before tool execution
    "PostToolUse",  # After tool execution
    "UserPromptSubmit",  # When user submits prompt
    "Stop",  # When stopping execution
    "SubagentStop",  # When a subagent stops
    "TeammateIdle",  # When teammate agent becomes idle (2.1.33+)
    "TaskCompleted",  # When a task finishes execution (2.1.33+)
    "PreCompact",  # Before message compaction
]

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

插件级 hooks.json

插件可以在 plugin.json 中通过 "hooks": "./hooks/hooks.json" 声明钩子。评估器会验证：

• 引用的 hooks.json 是否存在且为有效 JSON
• 钩子引用的 shell 命令是否存在且可执行
• 钩子匹配器是否使用有效的事件类型

钩子回调签名

async def my_hook(
    input_data: dict[str, Any],  # Hook-specific input
    tool_use_id: str | None,  # Tool ID (for tool hooks)
    context: HookContext,  # Additional context
) -> dict[str, Any]:  # Return decision/messages
    ...

返回值

return {
    "hookSpecificOutput": {
        "hookEventName": "PreToolUse",  # Match hook type
        "permissionDecision": "deny",  # Optional: block action
        "permissionDecisionReason": "...",  # Reason for denial
        "additionalContext": "...",  # Optional: context added
    }
}

质量评分（100 分）

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

详细资源

• SDK 钩子类型：参见 modules/sdk-hook-types.md，了解完整的 Python SDK 类型定义、模式和示例
• 评估标准：参见 modules/evaluation-criteria.md，了解详细的评分标准和质量门槛
• 安全模式：参见 modules/sdk-hook-types.md，了解漏洞检测和缓解措施
• 性能指南：参见 modules/evaluation-criteria.md，了解基准测试和优化

基本评估工作流

# 1. Run detailed evaluation
/hooks-eval --detailed

# 2. Focus on security issues
/hooks-eval --security-only --format sarif

# 3. Benchmark performance
/hooks-eval --performance-baseline

# 4. Check compliance
/hooks-eval --compliance-report

与其他工具集成

# Complete plugin evaluation pipeline
/hooks-eval --detailed          # Evaluate all hooks
/analyze-hook hooks/specific.py      # Deep-dive on one hook
/validate-plugin .                   # Validate overall structure

相关技能

• abstract:hook-scope-guide - 决定钩子的放置位置（插件/项目/全局）
• abstract:hook-authoring - 编写钩子规则和模式
• abstract:validate-plugin - 验证完整的插件结构

故障排除

常见问题

钩子未触发 验证钩子模式是否与事件匹配。检查钩子日志中是否有错误

语法错误 部署前运行 python3 plugins/abstract/scripts/hook_validator.py hooks/hooks.json （或 Python 钩子文件）。它会解析文件并报告 结构和 SDK 签名问题。

权限被拒绝 检查钩子文件的权限和所有权

退出标准

• 作用域内的每个钩子都获得一个综合质量评分（0-100），评分覆盖以下五个加权 类别：安全性（30）、性能（25）、合规性（20）、可靠性（15）、 可维护性（10）。
• 安全性类别评分低于 60 的任何钩子都会被标记为阻断问题，然后才会返回 评估报告。
• 验证 hooks.json 中引用的 shell 命令确实存在且可执行；缺失的 脚本会列为 FAIL 结果。
• 评估报告会区分 JSON 钩子（Claude Code）和 Python SDK 钩子， 并对每种类型应用正确的签名要求。