SuperAPI AI 工具集

Hook Development

编程与开发

查看项目

更新于 10-16 13:15

技能介绍

Hook Development 是一套面向 Claude Code 插件的技能文档,讲解如何创建和使用 hooks(事件驱动的自动化脚本)。Hooks 在 Claude Code 事件发生时自动执行,可用于校验操作、执行策略、添加上下文,以及把外部工具集成到工作流中。

一、主要能力 根据文档,hooks 可用于:在工具执行前校验工具调用(PreToolUse);对工具结果作出反应(PostToolUse);强制执行完成标准(Stop、SubagentStop);加载项目上下文(SessionStart);在开发生命周期中自动化工作流。

二、Hook 类型

  1. 基于提示的 hooks(文档标注为推荐):使用 LLM 驱动的决策进行上下文感知校验。示例配置包含 type: prompt、prompt 字段(可用 $TOOL_INPUT 等变量)与 timeout。文档称其支持的事件为 Stop、SubagentStop、UserPromptSubmit、PreToolUse。文档列出的优点包括:基于自然语言推理的上下文感知决策、无需 bash 脚本的灵活评估逻辑、更好的边界情况处理、更易维护与扩展。
  2. 命令 hooks:执行 bash 命令做确定性检查。示例使用 type: command、command(如 bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh)与 timeout。文档给出的适用场景包括快速确定性校验、文件系统操作、外部工具集成、性能关键检查。

三、Hook 配置格式 插件 hooks.json 格式:位于 hooks/hooks.json,使用包装格式,description 字段可选,hooks 字段为必需包装,内含实际 hook 事件。 设置格式(直接格式):用于 .claude/settings.json 中的用户设置,事件直接位于顶层,无包装、无 description 字段。

四、Hook 事件 PreToolUse:在任何工具运行前执行,用于批准、拒绝或修改工具调用;输出支持 hookSpecificOutput.permissionDecision(allow|deny|ask)与 updatedInput,以及 systemMessage。 PostToolUse:工具完成后执行,用于对结果作出反应、提供反馈或记录;退出码 0 时 stdout 显示在 transcript,退出码 2 时 stderr 反馈给 Claude。 Stop:主代理考虑停止时执行,用于校验完整性;决策输出为 decision(approve|block)、reason、systemMessage。 SubagentStop:子代理考虑停止时执行,类似 Stop,用于确保子代理完成任务。 UserPromptSubmit:用户提交提示时执行,用于添加上下文、校验或阻止提示。 SessionStart:会话开始时执行,用于加载上下文和设置环境;文档提到可通过 $CLAUDE_ENV_FILE 持久化环境变量。 SessionEnd:会话结束时执行,用于清理、记录和状态保存。 PreCompact:上下文压缩前执行,用于添加需要保留的关键信息。 Notification:Claude 发送通知时执行,用于对用户通知作出反应。

五、输出与输入格式 所有 hooks 的标准输出支持 continue(false 时停止处理,默认 true)、suppressOutput(默认 false)、systemMessage。退出码:0 成功(stdout 显示在 transcript),2 阻塞性错误(stderr 反馈给 Claude),其他为非阻塞性错误。 所有 hooks 通过 stdin 接收 JSON 输入,公共字段包括 session_id、transcript_path、cwd、permission_mode、hook_event_name;事件特定字段包括 PreToolUse/PostToolUse 的 tool_name、tool_input、tool_result;UserPromptSubmit 的 user_prompt;Stop/SubagentStop 的 reason。提示中可用 $TOOL_INPUT、$TOOL_RESULT、$USER_PROMPT 等访问字段。

六、环境变量(命令 hooks 中可用) $CLAUDE_PROJECT_DIR(项目根路径)、$CLAUDE_PLUGIN_ROOT(插件目录,用于可移植路径)、$CLAUDE_ENV_FILE(仅 SessionStart,用于持久化环境变量)、$CLAUDE_CODE_REMOTE(远程上下文时设置)。文档建议始终使用 ${CLAUDE_PLUGIN_ROOT} 以保证可移植性。

七、匹配器(Matchers) 支持精确匹配(Write)、多工具(Read|Write|Edit)、通配符()、正则(如 mcp__.__delete.*)。文档指出匹配区分大小写,并列出常见模式,如所有 MCP 工具、特定插件的 MCP 工具、所有文件操作、仅 Bash 命令。

八、安全最佳实践 文档建议:在命令 hooks 中始终校验输入(示例用 jq 解析 tool_name 并校验格式);检查路径穿越与敏感文件(示例拒绝包含 .. 的路径与 .env 文件);为所有变量加引号(echo "$file_path" 与未加引号的对比);设置合适超时(命令 hooks 默认 60s,提示 hooks 默认 30s)。参考文件包括 examples/validate-write.sh 与 examples/validate-bash.sh。

九、性能考量 所有匹配的 hooks 并行运行,因此互不可见输出、顺序不确定,应以独立性为设计目标。优化建议包括:用命令 hooks 做快速确定性检查、用提示 hooks 做复杂推理、在临时文件中缓存校验结果、减少热路径 I/O。

十、临时激活 hooks 文档给出两种模式:标志文件激活(检查 $CLAUDE_PROJECT_DIR 下的标志文件,不存在则 exit 0 跳过)与配置激活(读取 .claude/plugin-config.json 中的 strictMode 等开关)。适用场景:仅在需要时启用严格校验、临时调试钩子、项目特定行为、hook 的功能开关。文档建议在插件 README 中记录激活机制,便于用户启用/禁用。

十一、生命周期与限制 Hooks 在 Claude Code 会话启动时加载,修改 hook 配置需要重启 Claude Code 才能生效;不能热替换 hooks:编辑 hooks/hooks.json 不影响当前会话,新增脚本不被识别,修改命令/提示不会更新。测试流程为:编辑配置或脚本,退出会话,重启(claude 或 cc),新配置加载,再用 claude --debug 测试。启动时会校验 hooks:hooks.json 的无效 JSON 会导致加载失败,缺失脚本会产生警告,语法错误在调试模式中报告。可用 /hooks 命令查看当前会话已加载的 hooks。

十二、调试 启用调试模式:claude --debug,查看 hook 注册、执行日志、输入/输出 JSON 与耗时信息。可直接测试命令 hooks(用 echo 管道传入 JSON 后检查退出码),并用 jq 校验 hook 的 JSON 输出。

十三、最佳实践摘要 文档建议:复杂逻辑用提示型 hooks;用 ${CLAUDE_PLUGIN_ROOT} 保证可移植;命令 hooks 中校验所有输入;为所有 bash 变量加引号;设置合适超时;返回结构化 JSON 输出;充分测试。不建议:硬编码路径;不校验就信任用户输入;创建长时间运行的 hooks;依赖 hook 执行顺序;不可预测地修改全局状态;记录敏感信息。

十四、附加资源与实现流程 参考文件包括 references/patterns.md(常见模式)、references/migration.md(迁移指南)、references/advanced.md(高级用例);示例脚本包括 validate-write.sh、validate-bash.sh、load-context.sh;工具脚本包括 validate-hook-schema.sh、test-hook.sh、hook-linter.sh。文档还给出官方文档链接 https://docs.claude.com/en/docs/claude-code/hooks,以及测试(claude --debug)与校验(jq)方式。实现流程为:确定要挂钩的事件、选择提示型或命令型、编写 hooks/hooks.json 配置、为命令 hooks 创建脚本、使用 ${CLAUDE_PLUGIN_ROOT} 引用文件、用 validate-hook-schema.sh 校验配置、用 test-hook.sh 测试、在 Claude Code 中以 claude --debug 测试、在插件 README 中记录 hooks。文档建议大多数用例优先使用提示型 hooks,命令型 hooks 留给性能关键或确定性检查。

关于收费、价格、可用平台与效果等信息,暂未提供。