智能体钩子开发

# Claude Code 插件钩子开发 ## 概述 钩子（Hooks）是事件驱动的自动化脚本，用于响应 Claude Code 事件。使用钩子可以验证操作、执行策略、添加上下文并将外部工具集成到工作流中。 **核心能力：** - 在执行前验证工具调用 (PreToolUse) - 对工具结果做出反应 (PostToolUse) - 强制执行完成标准 (Stop, SubagentStop) - 加载项目上下文 (SessionStart) - 在整个开发生命周期中自动化工作流 ## 钩子类型 ### 基于提示词的钩子（推荐） 使用大模型驱动的决策进行上下文感知的验证： { "type": "prompt", "prompt": "Evaluate if this tool use is appropriate: $TOOL_INPUT", "timeout": 30 } **支持的事件：** Stop, SubagentStop, UserPromptSubmit, PreToolUse **优势：** - 基于自然语言推理的上下文感知决策 - 无需 Bash 脚本即可实现灵活的评估逻辑 - 更好的边缘情况处理 - 更易于维护和扩展 ### 命令钩子 执行 Bash 命令进行确定性检查： { "type": "command", "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh", "timeout": 60 } **适用场景：** - 快速确定性验证 - 文件系统操作 - 外部工具集成 - 性能关键型检查 ## 钩子配置格式 ### 插件 hooks.json 格式 **对于 `hooks/hooks.json` 中的插件钩子**，请使用包装格式： { "description": "Brief explanation of hooks (optional)", "hooks": { "PreToolUse": [...], "Stop": [...], "SessionStart": [...] } } **要点：** - `description` 字段可选 - `hooks` 字段是必需的包装器，包含实际的钩子事件 - 这是**插件特定格式** **示例：** { "description": "Validation hooks for code quality", "hooks": { "PreToolUse": [ { "matcher": "Write", "hooks": [ { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/validate.sh" } ] } ] } } ### 设置格式（直接） **对于 `.claude/settings.json` 中的用户设置**，请使用直接格式： { "PreToolUse": [...], "Stop": [...], "SessionStart": [...] } **要点：** - 无包装器 - 事件直接位于顶层 - 无描述字段 - 这是**设置格式** **重要：** 下面的示例展示了两种格式中通用的钩子事件结构。