ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

Claude Code Hook 反馈处理完全指南:将 Hook 视为用户反馈并正确处理阻塞

Claude Code Hook 反馈处理完全指南:将 Hook 视为用户反馈并正确处理阻塞 文档提示工程人工智能【免费下载链接】claude-code-system-promptsAll parts of Claude Codes system prompt, 27 builtin tool descriptions, sub agent prompts (Plan/Explore/Task), utility prompts (CLAUDE.md, compact, statusline, magic docs, WebFetch, Bash cmd, security review, agent creation). Updated for each Claude Code version.项目地址https://gitcode.com/gh_mirrors/cl/claude-code-system-prompts点击查看免费下载Hook钩子是 Claude Code 中在工具调用等事件发生时自动执行的 shell 命令也是 Claude Code 系统提示体系里一条重要的反馈通道。本文以system-prompts/system-prompt-hook-feedback-handling.md为核心结合仓库中完整的 Hooks 配置规范、Hook 阻塞/成功/停止等系统提醒文件讲解 Hook 的配置结构、反馈语义Hook 反馈应被视为来自用户的反馈以及被 Hook 阻塞时正确的应对流程帮助你理解并驾驭 Claude Code 的 Hook 机制。一、核心语义Hook 反馈等于用户反馈system-prompts/system-prompt-hook-feedback-handling.md确立了一条贯穿整个 Hook 体系的基本原则Users may configure hooks, shell commands that execute in response to events like tool calls, in settings. Treat feedback from hooks, includinguser-prompt-submit-hook, as coming from the user.翻译过来就是三层含义Hook 由用户配置用户在设置settings中定义 Hook——它们本质上是响应工具调用等生命周期事件而执行的 shell 命令反馈等同用户无论 Hook 是成功输出、附加上下文还是发出警告其反馈都应被模型当作来自用户本人的反馈对待而不是当作无关的外部噪声user-prompt-submit-hook同样适用用户在提交提示词时触发的 HookUserPromptSubmit 事件所产生的反馈也具有同等的用户反馈地位。这一语义决定了模型在处理 Hook 输出时的姿态Hook 的systemMessage、additionalContext、stopReason等字段本质上都是用户在自动化链路上预设的指令模型应当像对待用户消息一样认真处理而不是忽略或轻视。二、Hook 的配置结构与事件体系要理解反馈从何而来先要理解 Hook 长什么样。system-prompts/system-prompt-hooks-configuration.md给出了完整的 Hook 结构与事件清单。2.1 Hook 结构Hook 配置使用嵌套的 JSON 结构按事件名分组每个事件可挂多个 matcher每个 matcher 下可挂多个 Hook{ hooks: { EVENT_NAME: [ { matcher: ToolName|OtherTool, hooks: [ { type: command, command: your-command-here, timeout: 60, statusMessage: Running... } ] } ] } }字段含义字段说明EVENT_NAME生命周期事件名见下表matcher事件匹配器如工具名支持\|分隔多个匹配项typeHook 类型command/prompt/agentcommand要执行的 shell 命令timeout超时时间秒超时后 Hook 视为失败statusMessage运行时在界面展示的状态消息2.2 Hook 事件一览事件Matcher用途PermissionRequest工具名在权限确认弹窗之前运行PreToolUse工具名工具执行前运行可以阻塞PostToolUse工具名工具成功执行后运行PostToolUseFailure工具名工具执行失败后运行Notification通知类型收到通知时运行Stop-Claude 停止时运行含 clear、resume、compactPreCompactmanual/auto压缩上下文之前PostCompactmanual/auto压缩上下文之后会收到摘要UserPromptSubmit-用户提交提示词时SessionStart-会话启动时常用工具 matcher 包括Bash、Write、Edit、Read、Glob、Grep。其中UserPromptSubmit正是本文核心文档特别点名的user-prompt-submit-hook它发生在用户提交提示词的瞬间其反馈同样被视为用户反馈。2.3 Hook 的三种类型Command Hook命令型运行 shell 命令如{ type: command, command: prettier --write $FILE, timeout: 30 }Prompt Hook提示型让 LLM 评估条件如{ type: prompt, prompt: Is this safe? $ARGUMENTS }仅可用于 PreToolUse、PostToolUse、PermissionRequest 等工具事件Agent Hook代理型运行带工具的代理如{ type: agent, prompt: Verify tests pass: $ARGUMENTS }同样仅可用于工具事件。2.4 Hook 的输入stdin JSONHook 通过 stdin 接收 JSON内容包含{ session_id: abc123, tool_name: Write, tool_input: { file_path: /path/to/file.txt, content: ... }, tool_response: { success: true } // PostToolUse 才有 }这意味着 Hook 可以读取当前会话 ID、正在调用的工具及其参数甚至是工具的执行结果——正是这些信息让 Hook 有能力产生有内容的反馈。三、Hook 反馈的输出通道JSON 输出字段Hook 可以向模型和用户回传反馈通过 stdout 输出 JSON 控制行为{ systemMessage: Warning shown to user in UI, continue: false, stopReason: Message shown when blocking, suppressOutput: false, decision: block, reason: Explanation for decision, hookSpecificOutput: { hookEventName: PostToolUse, additionalContext: Context injected back to model } }各字段的作用详见system-prompts/system-prompt-hooks-configuration.mdsystemMessage向用户展示一条消息所有 Hook 可用continue设为false即阻塞/停止默认truestopReason当continue为false时展示的说明消息suppressOutput隐藏 stdout不写入转录默认falsedecisionblock用于 PostToolUse / Stop / UserPromptSubmit 事件PreToolUse 已废弃改用hookSpecificOutput.permissionDecisionreason对该决策的解释hookSpecificOutput事件专属输出必须包含hookEventName其中additionalContext注入回模型上下文的文本permissionDecisionallow、deny或ask仅 PreToolUsepermissionDecisionReason权限决策的理由仅 PreToolUseupdatedInput修改后的工具输入仅 PreToolUse。可以看出Hook 的反馈既能上达用户systemMessage也能直达模型additionalContext还能截停流程continue: false/decision: block。这正是本文核心文档要求把 Hook 反馈当作用户反馈的技术基础——additionalContext会直接注入模型上下文其效力与用户消息相当。四、被 Hook 阻塞时的正确应对流程这是system-prompt-hook-feedback-handling.md给出的第二项核心指令If you get blocked by a hook, determine if you can adjust your actions in response to the blocked message. If not, ask the user to check their hooks configuration.即当被 Hook 阻塞时先判断能否根据阻塞消息调整自己的行动如果无法调整就请用户检查其 Hook 配置。一个可落地的应对流程如下接收阻塞反馈Hook 通过stopReason/systemMessage/ 阻塞错误消息给出原因。仓库中对应的阻塞提醒模板见system-prompts/system-reminder-hook-blocking-error.md${ATTACHMENT_OBJECT.hookName} hook blocking error from command: ...与system-prompts/system-reminder-stop-hook-blocking-error.mdStop hook blocking error from command ${HOOK_NAME}:解读阻塞意图判断阻塞是可修复的执行条件还是硬性安全/策略边界。例如 PreToolUse 的permissionDecision: deny属于策略拒绝而updatedInput则提示模型可以按修改后的输入继续尝试调整行动如果阻塞消息指明了可调整的空间比如禁止写入某个路径、要求先跑测试、要求使用格式化后的代码就修改自己的计划与工具调用后重试无法调整则求助用户如果阻塞与模型可控范围无关例如 Hook 命令本身报错、配置指向了不存在的脚本、deny属于用户明确的策略边界则应明确告知用户无法继续并请其检查 Hook 配置路径、命令、matcher、事件绑定等而不是反复强行触发同一阻塞。从源码结构看这一流程还受到system-prompts/system-prompt-harness-instructions.md中关于执行动作需谨慎的约束支撑模型不应无视 Hook 的阻塞反复重试而应把阻塞当作真实反馈来响应。五、与 Hook 反馈相关的系统提醒与子代理仓库中还配套了若干与 Hook 反馈直接相关的系统提醒与子代理提示共同构成完整的反馈回路system-prompts/system-reminder-hook-success.mdHook 成功时通知模型${ATTACHMENT_OBJECT.hookName} hook success: ...system-prompts/system-reminder-hook-additional-context.mdHook 附加上下文注入${ATTACHMENT_OBJECT.hookName} hook additional context: ...多行内容以换行拼接system-prompts/system-reminder-hook-stopped-continuation.md与system-prompts/system-reminder-hook-stopped-continuation-prefix.mdHook 停止继续时的通知与前缀system-prompts/system-reminder-session-stop-hook-active.md会话停止 Hook 激活时的提醒agent-prompt-hook-condition-evaluator.md条件评估子代理判断用户提供的 Hook 条件是否满足并以{ok: true/false, reason: ...}的 JSON 返回agent-prompt-hook-condition-evaluator-stop.mdStop 条件评估子代理需精读转录后判断停止条件是否达成支持{ok: false, impossible: true}表达本会话内永不可能满足system-prompt-hook-evaluator-truncated-transcript-note.md当转录被截断时对 Hook 评估的注意提示。这些提醒文件表明Hook 反馈不仅出现在工具调用链路PreToolUse/PostToolUse也贯穿 Stop、UserPromptSubmit 等事件模型在每个环节都应保持把 Hook 当用户的处理姿态。六、Hook 实战示例从反馈到自动化的常见模式结合system-prompts/system-prompt-hooks-configuration.md中的常见模式可以更直观地理解Hook 反馈在真实工作流中的形态。1. 写入后自动格式化PostToolUse Write|Edit{ hooks: { PostToolUse: [{ matcher: Write|Edit, hooks: [{ type: command, command: jq -r .tool_response.filePath // .tool_input.file_path | { read -r f; prettier --write \$f\; } 2/dev/null || true }] }] } }2. 记录所有 Bash 命令日志PreToolUse Bash{ hooks: { PreToolUse: [{ matcher: Bash, hooks: [{ type: command, command: jq -r .tool_input.command ~/.claude/bash-log.txt }] }] } }3. Stop Hook 向用户展示消息——命令必须输出含systemMessage字段的 JSONecho {systemMessage: Session complete!}4. 代码变更后自动跑测试PostToolUse Write|Edit{ hooks: { PostToolUse: [{ matcher: Write|Edit, hooks: [{ type: command, command: jq -r .tool_input.file_path // .tool_response.filePath | grep -E \\.(ts|js)$ npm test || true }] }] } }这些模式展示了 Hook 反馈的两种典型形态静默的工程自动化格式化、测试、日志通常不打扰模型与显式的流程控制systemMessage、continue: false、阻塞错误。前者提供事实性上下文后者则需要模型按照本文第四节的流程处理。七、总结Claude Code 的 Hook 机制本质上是一条用户预编程的反馈通道用户通过设置中的 JSON 配置把何时触发、如何反馈、是否阻塞的规则写进工具调用、提示词提交与会话停止等生命周期事件中。system-prompt-hook-feedback-handling.md给出的两条行为准则——把 Hook 反馈当作用户反馈、被阻塞时先调整行动、调整不了则请用户检查配置——是模型与这条通道正确协作的关键。在撰写或审查自己的 Hook 配置时可以对照system-prompts/system-prompt-hooks-configuration.md的事件表与输出字段并留意system-reminder-hook-blocking-error.md、system-reminder-stop-hook-blocking-error.md等提醒模板所呈现的阻塞反馈形态从而让 Hook 成为安全、可预期、可诊断的自动化护栏而不是打断协作的黑盒报错。赞分享文档提示工程人工智能【免费下载链接】claude-code-system-promptsAll parts of Claude Codes system prompt, 27 builtin tool descriptions, sub agent prompts (Plan/Explore/Task), utility prompts (CLAUDE.md, compact, statusline, magic docs, WebFetch, Bash cmd, security review, agent creation). Updated for each Claude Code version.项目地址https://gitcode.com/gh_mirrors/cl/claude-code-system-prompts点击查看免费下载相关推荐nowinandroid用户反馈用户反馈收集与处理机制nowinandroid用户反馈用户反馈收集与处理机制 痛点用户声音难以有效触达开发团队 在移动应用开发过程中用户反馈是产品迭代和优化的重要依据。然而许移动开发Open MCT用户反馈系统集成与反馈处理流程Open MCT用户反馈系统集成与反馈处理流程 引言解决航天任务中的用户反馈痛点 在航天任务控制场景中操作员与任务工程师需要快速上报界面异常、数据异常或功数据可视化前端Docker部署Claude应用快速实操指南四条命令一次搞定完整容器化部署Docker部署Claude应用快速实操指南四条命令一次搞定完整容器化部署 想在客户现场演示一个 Claude 客服机器人却被本地环境配置卡住办法很简单示例工程创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表