Skill Developer Hook Mechanisms

# 钩子机制 - 深度解析 关于 UserPromptSubmit 和 PreToolUse 钩子如何工作的技术深度解析。 ## 目录 - [UserPromptSubmit 钩子流程](#userpromptsubmit-钩子流程) - [PreToolUse 钩子流程](#pretooluse-钩子流程) - [退出代码行为 (关键)](#退出代码行为-关键) - [会话状态管理](#会话状态管理) - [性能考量](#性能考量) --- ## UserPromptSubmit 钩子流程 ### 执行顺序 用户提交提示词 ↓ .claude/settings.json 注册钩子 ↓ 执行 skill-activation-prompt.sh ↓ npx tsx skill-activation-prompt.ts ↓ 钩子读取 stdin (包含提示词的 JSON) ↓ 加载 skill-rules.json ↓ 匹配关键词 + 意图模式 ↓ 按优先级对匹配项分组 (关键 → 高 → 中 → 低) ↓ 将格式化消息输出到 stdout ↓ stdout 成为 Claude 的上下文 (在提示词前注入) ↓ Claude 看到：[智能体建议] + 用户提示词 ### 关键点 - **退出代码**：始终为 0 (允许) - **stdout**：→ Claude 的上下文 (作为系统消息注入) - **时机**：在 Claude 处理提示词之前运行 - **行为**：非阻塞，仅供参考 - **目的**：让 Claude 意识到相关的智能体 ### 输入格式 { "session_id": "abc-123", "transcript_path": "/path/to/transcript.json", "cwd": "/root/git/your-project", "permission_mode": "normal", "hook_event_name": "UserPromptSubmit", "prompt": "how does the layout system work?" } ### 输出格式 (至 stdout) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ? 智能体激活检查 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ? 推荐智能体： → project-catalog-developer 操作：在响应前使用智能体工具 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Claude 在处理用户提示词之前会将此输出视为额外上下文。 --- ## PreToolUse 钩子流程 ### 执行顺序 Claude 调用编辑/写入工具 ↓ .claude/settings.json 注册钩子 (匹配器: Edit|Write) ↓ 执行 skill-verification-guard.sh ↓ npx tsx skill-verification-guard.ts ↓ 钩子读取 stdin (包含 tool_name, tool_input 的 JSON) ↓ 加载 skill-rules.json ↓ 检查文件路径模式 (glob 匹配) ↓ 读取文件内容模式 (如果文件存在) ↓ 检查会话状态 (智能体是否已使用？) ↓ 检查跳过条件 (文件标记、环境变量) ↓ 如果匹配且未跳过： 更新会话状态 (将智能体标记为已强制执行) 输出拦截消息 "