企业官网建设流程全解析

• 文档
• 提示工程
• 人工智能

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, including<user-prompt-submit-hook>, as coming from the user.

翻译过来就是三层含义：

1. Hook 由用户配置：用户在设置（settings）中定义 Hook——它们本质上是响应工具调用等生命周期事件而执行的 shell 命令；
2. 反馈等同用户：无论 Hook 是成功输出、附加上下文还是发出警告，其反馈都应被模型当作来自用户本人的反馈对待，而不是当作无关的外部噪声；
3. <user-prompt-submit-hook>同样适用：用户在提交提示词时触发的 Hook（UserPromptSubmit 事件）所产生的反馈，也具有同等的"用户反馈"地位。

这一语义决定了模型在处理 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..." } ] } ] } }

字段含义：

2.2 Hook 事件一览

常用工具 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 JSON）

Hook 通过 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.md）：

• systemMessage：向用户展示一条消息（所有 Hook 可用）；
• continue：设为false即阻塞/停止（默认true）；
• stopReason：当continue为false时展示的说明消息；
• suppressOutput：隐藏 stdout，不写入转录（默认false）；
• decision："block"，用于 PostToolUse / Stop / UserPromptSubmit 事件（PreToolUse 已废弃，改用hookSpecificOutput.permissionDecision）；
• reason：对该决策的解释；
• hookSpecificOutput：事件专属输出（必须包含hookEventName），其中：
  • additionalContext：注入回模型上下文的文本；
  • permissionDecision："allow"、"deny"或"ask"（仅 PreToolUse）；
  • permissionDecisionReason：权限决策的理由（仅 PreToolUse）；
  • updatedInput：修改后的工具输入（仅 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 配置。

一个可落地的应对流程如下：

1. 接收阻塞反馈：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.md（Stop hook blocking error from command "${HOOK_NAME}":）；
2. 解读阻塞意图：判断阻塞是"可修复的执行条件"还是"硬性安全/策略边界"。例如 PreToolUse 的permissionDecision: "deny"属于策略拒绝，而updatedInput则提示模型可以按修改后的输入继续；
3. 尝试调整行动：如果阻塞消息指明了可调整的空间（比如禁止写入某个路径、要求先跑测试、要求使用格式化后的代码），就修改自己的计划与工具调用后重试；
4. 无法调整则求助用户：如果阻塞与模型可控范围无关（例如 Hook 命令本身报错、配置指向了不存在的脚本、deny属于用户明确的策略边界），则应明确告知用户"无法继续"，并请其检查 Hook 配置（路径、命令、matcher、事件绑定等），而不是反复强行触发同一阻塞。

从源码结构看，这一流程还受到system-prompts/system-prompt-harness-instructions.md中关于执行动作需谨慎的约束支撑：模型不应无视 Hook 的阻塞反复重试，而应把阻塞当作真实反馈来响应。

五、与 Hook 反馈相关的系统提醒与子代理

仓库中还配套了若干与 Hook 反馈直接相关的系统提醒与子代理提示，共同构成完整的反馈回路：

• system-prompts/system-reminder-hook-success.md：Hook 成功时通知模型（${ATTACHMENT_OBJECT.hookName} hook success: ...）；
• system-prompts/system-reminder-hook-additional-context.md：Hook 附加上下文注入（${ATTACHMENT_OBJECT.hookName} hook additional context: ...），多行内容以换行拼接；
• system-prompts/system-reminder-hook-stopped-continuation.md与system-prompts/system-reminder-hook-stopped-continuation-prefix.md：Hook 停止继续时的通知与前缀；
• 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.md：Stop 条件评估子代理，需精读转录后判断停止条件是否达成，支持{"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字段的 JSON：

echo '{"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 成为安全、可预期、可诊断的自动化护栏，而不是打断协作的"黑盒报错"。

• 文档
• 提示工程
• 人工智能