oh-my-claudecode 事件驱动 Hook 体系深度解析31 个 Hook 如何撑起执行模式、校验与恢复机制【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode导读oh-my-claudecode 是一套面向 Claude Code 的 Multi-agent 编排方案。在其内部src/hooks/目录下聚集了 31 个事件驱动 Hook它们是整套系统行为模式autopilot、ralph、ultrapilot、swarm、pipeline 等的底层发动机通过拦截 Claude Code 的UserPromptSubmit、Stop、PreToolUse、PostToolUse等生命周期事件实现执行模式切换、输入校验、错误恢复、规则注入与模式检测。本文以 src/hooks/AGENTS.md 为骨架结合 hooks/hooks.json、src/hooks/bridge.ts、src/hooks/index.ts 及 persistent-mode、registry 等核心实现系统拆解这套 Hook 体系的目录组织、事件契约、状态管理、Stop Hook 软强制机制与扩展开发规范。读完本文你将理解 Claude Code Hook 系统的高阶用法并能照规范为该项目新增、测试与维护一个 Hook。Hook 体系的定位与总体架构Claude Code 原生提供了一套基于 Shell 脚本的 Hook 机制在特定生命周期事件发生时Claude Code 执行配置好的命令。oh-my-claudecode 的价值在于把事件拦截提升为行为编排事件发生后Shell 脚本调用 Node.js 桥接层bridge执行复杂 TypeScript 逻辑bridge 将处理结果以 JSON 返回给 Shell再由 Shell 回传给 Claude Code处理逻辑分散在 31 个职责单一的子模块中通过 src/hooks/index.ts 统一导出。正如 src/hooks/index.ts 文件头注释所描述的架构闭环Claude Code 事件 → 执行 Shell 脚本 → 调用 Node.js bridge → 返回 JSON → Shell 回传 Claude Code实际挂载配置在 hooks/hooks.json 中可见一斑该文件为每个事件UserPromptSubmit、SessionStart、PreToolUse、PostToolUse、Stop、SessionEnd等注册了多个带超时控制的命令钩子。例如UserPromptSubmit上挂了keyword-detector.mjs关键词检测与skill-injector.mjs技能注入两个 30 秒超时的命令Stop上依次挂了context-guard-stop.mjs、workflow-drift-guard.mjs、persistent-mode.mjs、code-simplifier.mjs。从整体职责看Hook 体系服务于六类能力能力域覆盖场景执行模式autopilot、ralph、ultrapilot、swarm、pipeline由 mode-registry 统一跟踪校验thinking 块校验、空消息清洗、代码注释检查恢复编辑错误恢复、会话恢复、上下文窗口保护增强规则注入、目录 README 注入、notepad、技能抽取检测关键词、思考模式、斜杠命令、非交互环境协调任务延续、编排器、子代理跟踪、会话收尾目录组织六大类 Hook 的职责地图src/hooks/AGENTS.md 将 Hook 分为六大类。对照 src/hooks 目录的实际结构每一类都有清晰的落点执行模式 HookExecution Mode Hooks目录职责触发词autopilot/全自主执行校验目标、制定计划、管理执行状态、处理取消、强制完成autopilot、build meralph/持久执行直到验证通过经 PRD 跟踪进度、派生子代理architect验证、循环直至验证完成、支持结构化 PRD 格式ralph、dont stopultrapilot/并行 autopilot任务分解为子任务、为 worker 分配文件所有权、协调并行执行、整合结果ultrapilotswarm/多代理协调基于 SQLite 的任务认领、单任务 5 分钟超时、原子认领/释放、干净的完成检测swarm N agentsmode-registry/集中式执行模式状态管理内部触发internalpersistent-mode/跨会话维持模式状态内部触发internal从 src/hooks/index.ts 可以看到mode-registry提供了MODE_CONFIGS、getActiveModes、isModeActive、getActiveExclusiveMode、canStartMode、createModeMarker等集中式状态管理 API——它扮演模式仲裁者角色决定当前会话能否启动某个互斥模式。校验 HookValidation Hooksthinking-block-validator/校验响应中的 thinking 块是否完整。源码导出了validateMessages、prependThinkingBlock、findPreviousThinkingContent等函数并区分CONTENT_PART_TYPES与THINKING_PART_TYPES说明它按 Claude Code 消息 part 类型做细粒度校验。empty-message-sanitizer/清洗空/纯空白消息提供sanitizeMessages、hasTextContent、isToolPart等函数防止空消息破坏对话流。comment-checker/检查代码注释质量内置BDD_KEYWORDS、TYPE_CHECKER_PREFIXES、LINE_COMMENT_PATTERNS等启发式规则。permission-handler/处理权限请求与校验导出processPermissionRequest、isSafeCommand、isActiveModeRunning在 hooks/hooks.json 中挂载于PermissionRequest事件matcher 为Bash。恢复 HookRecovery Hooksrecovery/统一恢复模块涵盖编辑错误恢复detectEditError、handleEditErrorRecovery、会话恢复handleSessionRecovery、上下文窗口受限恢复handleContextWindowRecovery并内置TOKEN_LIMIT_PATTERNS、RETRY_CONFIG、TRUNCATE_CONFIG等重试与截断配置。preemptive-compaction/主动防止上下文溢出通过estimateTokens、analyzeContextUsage估算 token按DEFAULT_THRESHOLD预压缩阈值与CRITICAL_THRESHOLD临界阈值分级告警并带COMPACTION_COOLDOWN_MS冷却与MAX_WARNINGS上限避免频繁打扰。pre-compact/压缩前处理createCompactCheckpoint创建检查点、exportWisdomToNotepad将智慧沉淀到 notepad配合 src/hooks/pre-compact/restore.js 提供检查点恢复能力对应 issue #3730。增强 HookEnhancement Hooksrules-injector/按路径匹配注入规则文件。源码支持PROJECT_MARKERS、PROJECT_RULE_SUBDIRS、RULE_EXTENSIONS等项目规则发现配置并通过createContentHash、isDuplicateByRealPath、isDuplicateByContentHash做去重避免同一规则重复注入。directory-readme-injector/注入目录 README/AGENTS.mdREADME_FILENAME、AGENTS_FILENAME、CONTEXT_FILENAMES本文所在的src/hooks/AGENTS.md正是这类被注入的上下文文件。notepad/为压缩韧性提供持久化笔记导出initNotepad、getPriorityContext、getWorkingMemory、pruneOldEntries、formatNotepadContext等 API是跨压缩会话保存关键信息的手段。learner/从对话中抽取技能。包含完整的技能生命周期detectExtractableMoment检测可抽取时机→generateExtractionPrompt生成抽取提示→validateSkillMetadata校验元数据→writeSkill写入本地技能文件→findMatchingSkills后续自动匹配调用还支持promoteLearning将学习记录升级为正式技能。agent-usage-reminder/提醒用户进行代理委派跟踪TARGET_TOOLS与AGENT_TOOLS的使用情况。检测 HookDetection Hookskeyword-detector/魔法关键词检测autopilot、ralph 等导出detectKeywordsWithType、extractPromptText、removeCodeBlocks是执行模式触发的第一道闸门。think-mode/扩展思考模式检测支持detectThinkKeyword、detectUltrathinkKeyword并通过THINKING_CONFIGS、getClaudeThinkingConfig将思考强度映射到 Claude 的 thinking 配置。auto-slash-command/斜杠命令展开discoverAllCommands、executeSlashCommand实现/命令的解析与执行带EXCLUDED_COMMANDS黑名单。non-interactive-env/非交互环境检测CI 等isNonInteractive结合SHELL_COMMAND_PATTERNS判断。plugin-patterns/社区常见插件模式检测如代码格式化formatFile、lintlintFile、提交信息校验validateCommitMessage、pre-commit 检查runPreCommitChecks。协调 HookCoordination Hookstodo-continuation/强制任务完成checkIncompleteTodos检查未完成 TODO是 persistent-mode 的重要输入源。omc-orchestrator/编排器行为processOrchestratorPreTool/processOrchestratorPostTool在工具调用前后执行路径白名单ALLOWED_PATH_PREFIX、委派强制ORCHESTRATOR_DELEGATION_REQUIRED等策略。subagent-tracker/跟踪派生的子代理提供getActiveAgentCount、getStaleAgents、cleanupStaleAgents及flow-tracer的recordHookFire、recordModeChange等流程轨迹记录。session-end/会话终止处理recordSessionMetrics记录指标、cleanupTransientState清理瞬态状态、exportSessionSummary导出会话摘要。background-notification/后台任务通知processBackgroundNotification与 HUD 后台任务模块联动。基础设施与其他registry/声明式 Hook 注册表 调度器影子模式对应 issue #3707设计文档见 docs/design/ISSUE-3707-HOOK-REGISTRY-SHADOW.md。setup/初始安装与配置目录结构创建、配置文件校验、环境变量设置、孤儿状态清理。bridge.tsShell 入口processHook()按事件路由到各 handler。核心入口bridge 与统一导出bridge.tsShell 与 TypeScript 之间的网关src/hooks/bridge.ts 是 Shell 脚本调用 TypeScript 逻辑的统一入口。其头部注释给出了标准 Shell 调用范式#!/bin/bash INPUT$(cat) echo $INPUT | node ~/.claude/omc/hook-bridge.mjs --hookkeyword-detectorbridge 内部做了大量热路径优化keyword-detector、pre/post-tool-use相关模块被标记为Hot-path imports每次 Hook 调用几乎都会用到而其他模块采用懒加载Type-only imports for lazy-loaded modules (zero runtime cost)以此控制每次事件触发时的开销。bridge 还内置了安全措施——用wrapUntrustedFileContent包裹不可信文件内容以防止提示注入prompt injection。从 hooks/hooks.json 可以看到几乎所有命令钩子都通过scripts/run.cjs加超时参数运行例如PostToolUse事件同时触发post-tool-verifier.mjs、project-memory-posttool.mjs、post-tool-rules-injector.mjs三个脚本各 3 秒超时体现一个事件、多关注点的分层设计。index.tsHook 的统一门面src/hooks/index.ts 按模块分区重导出全部 Hook 的 API 与类型。它不仅是代码组织手段也是文档性质的目录读一遍导出清单即可了解系统全部能力。值得注意的细节Ralph 是最大的聚合模块导出包含 loopcreateRalphLoopHook、incrementRalphIteration、PRD 集成readPrd、getPrdCompletionStatus、amendCriterion、supersedeCriterion、进度记忆readProgress、appendProgress、addPattern、VerifierstartVerification、recordArchitectFeedback、detectArchitectApproval四组功能印证了文档中ralph 持久执行 PRD 跟踪 architect 验证的描述。autopilot 是状态机transitionPhase、transitionRalphToUltraQA、transitionUltraQAToValidation、transitionToComplete、transitionToFailed等函数揭示了其内部相位流转expansion → planning → execution → QA → validation并支持canResumeAutopilot/resumeAutopilot的断点续跑。时间线之外的模块agents-overlay.ts、codebase-map.ts、project-memory/、beads-context/、skill-state/等也在 index 中导出说明实际 Hook 数量多于 AGENTS.md 表格列举的经典 31 个——文档表格是核心主干目录是完整全集。Hook 事件契约与生命周期Claude Code 的 Hook 事件模型在 src/hooks/AGENTS.md 中有权威总结hooks/hooks.json 则给出了本项目实际使用的扩展事件集事件触发时机常见用途hooks.json 中的实际挂载UserPromptSubmit提示词处理前关键词检测、模式激活、技能注入keyword-detector、skill-injectorSessionStart会话启动环境初始化、项目记忆、wiki 加载session-start、project-memory-session、wiki-session-start含 init/maintenance 两个 matcherPreToolUse工具执行前权限校验、路径守卫pre-tool-enforcerPermissionRequest权限请求Bash 命令安全评估permission-handlerPostToolUse工具执行后错误恢复、规则注入、结果校验post-tool-verifier、project-memory-posttool、post-tool-rules-injectorPostToolUseFailure工具执行失败失败诊断与恢复post-tool-use-failureStop会话结束前延续强制、持久模式检查context-guard-stop、workflow-drift-guard、persistent-mode、code-simplifierPreCompact上下文压缩前检查点、智慧导出pre-compact、project-memory-precompact、wiki-pre-compactSubagentStart/SubagentStop子代理启停子代理跟踪、交付物验证subagent-tracker、verify-deliverablesSessionEnd会话终止指标记录、摘要导出session-end、wiki-session-end均 async 异步执行扩展事件是理解本项目的关键SessionStart的matcher: init与maintenance分别绑定setup-init.mjs30s 超时与setup-maintenance.mjs60s 超时实现安装时初始化、日常维护的分流SessionEnd钩子均标记async: true让耗时收尾不阻塞会话关闭。深度原理一Stop Hook 的软强制输出契约文档中最具实战价值的部分是 persistent-mode 的Stop Hook 软强制soft enforcement契约src/hooks/AGENTS.md 明确规定 Stop 钩子永远返回continue: true强制手段是消息注入而非事件阻塞// Stop hook ALWAYS returns continue: true // Enforcement is via message injection, not blocking return { continue: true, message: result.message || undefined // Injected into context };这一设计在 src/hooks/persistent-mode/index.ts 中得到印证。文件头注释明确指出其职责This hook intercepts Stop events and enforces work continuation based on: 1. Active ralph loop (until cancelled via /oh-my-claudecode:cancel) 2. Any pending todos优先级为Ralph Todo Continuation。为什么必须软强制文档给出的理由是硬阻塞continue: false会阻止上下文压缩context compaction甚至可能导致 Claude Code 死锁。硬阻塞是闸门而消息注入是路标——它把续作指令写进上下文让模型自行决定继续执行既达到目的又不破坏 Claude Code 自身的生命周期。先检查的放行条件bypass conditionscontext-limit上下文窗口已耗尽必须放行以允许压缩。源码中 src/hooks/persistent-mode/index.ts 有明确注释CRITICAL: Never block context-limit/critical-context stops并用isContextLimitStop(stopContext)判定。user-abort用户显式请求停止由isUserAbort(stopContext)识别src/hooks/persistent-mode/index.ts。放行后再按模式优先级注入延续消息Ralph显式持久循环Autopilot完整编排Ultrapilot并行 workerSwarm协调代理Pipeline顺序阶段Ultrawork并行执行会话隔离与陈旧状态Hook 只对匹配的session_id生效超过 2 小时的陈旧状态被忽略源码中STALE_STATE_THRESHOLD_MS 2 * 60 * 60 * 1000。完成判据是state.active true state.session_id currentSession !isStaleState()运行/cancel会设置active: false并删除状态文件CANCEL_SIGNAL_TTL_MS 30_000的取消信号 TTL 防止误判。此外src/hooks/persistent-mode/index.ts 定义MAX_TODO_CONTINUATION_ATTEMPTS 5作为 todo 延续的最大尝试次数上限防止无限循环——这是软强制之外的又一道安全网。对应的测试覆盖见 src/hooks/persistent-mode/tests含stop-hook-blocking.test.ts、session-isolation.test.ts、idle-cooldown.test.ts可直接定位验证。深度原理二状态文件与跨会话持久化执行模式依赖落盘状态实现跨提示词、跨会话的持续性。文档给出的状态文件清单与源码实现一一对应Hook状态文件autopilot.omc/state/autopilot-state.jsonultrapilot.omc/state/ultrapilot-state.jsonralph.omc/state/ralph-state.jsonswarm.omc/state/swarm-tasks.dbSQLitelearner~/.claude/local-skills/这些状态文件由features/state-manager统一读写见 src/hooks/AGENTS.md 的 State Management 模式实际实现中更演进为mode-state-ioreadModeState/writeModeState/writeStateFileLockedIf加文件锁withStateFileMutationLock与原子写atomicWriteJsonSync的组合配合resolveSessionStatePath实现按会话隔离的状态文件布局。swarm 使用 SQLite依赖better-sqlite3支撑任务认领的原子性而 learner 将抽取的技能持久化到用户级local-skills目录实现跨项目的技能复用。注册表与影子模式Hook 体系的自我演进src/hooks/AGENTS.md 特别提到registry/目录承载声明式 Hook 注册表 调度器影子模式#3707。从 src/hooks/registry/index.ts 可以看到这套机制的核心 APIisHookShadowEnabled/runShadowObservation判断影子模式是否开启、运行影子观测compareShadowExecution比较新注册表实现与现有实现的执行结果appendShadowRecord/readShadowLog/summarizeShadowLog记录、读取、汇总影子执行日志resetShadowRegistryCache重置缓存。配合 src/hooks/registry/cutover.tsisFamilyCutoverEnabled、hasHookProtocolDeny、recordDispatchTelemetry、shouldLoosenOrdinaryEnforcement可以推断其设计意图新 Hook 注册表先以影子方式并行观测、对比新旧实现输出确认一致后再灰度切换cutover并随时可收紧/放松强制执行级别。这是低风险重构基础设施的典型模式属于从源码结构推断的实现策略。核心 Hook 实战剖析autopilot全自主执行状态机根据 src/hooks/index.ts 的导出autopilot 的核心流程是initAutopilot初始化 →transitionPhase驱动相位流转expansion/planning/execution/QA/validation→ 各相位调用getExpansionPrompt/getDirectPlanningPrompt/getExecutionPrompt/getQAPrompt/getValidationPrompt生成上下文 →recordValidationVerdict记录验证结论 →transitionToComplete/transitionToFailed收尾。STALE_STATE_MAX_AGE_MS与DEFAULT_CONFIG两个常量定义了陈旧判定与默认参数cancelAutopilot/clearAutopilot对应文档所述的取消处理。ralphPRD 驱动的持久执行ralph 是文档描述最详细的执行模式。从 src/hooks/index.ts 的导出可还原其工作循环PRD 跟踪进度readPrd/writePrd读写结构化 PRDgetPrdCompletionStatus判断完成度amendCriterion/supersedeCriterion支持迭代修订验收标准对应文档中的supports structured PRD format派生 architect 验证startVerification启动验证getArchitectVerificationPrompt生成验证提示detectArchitectApproval/detectArchitectRejection解析验证结论循环直至验证通过incrementRalphIteration累加迭代次数recordArchitectFeedback记录反馈被拒则通过getArchitectRejectionContinuationPrompt生成续作提示形成执行 → 验证 → 反馈 → 再执行闭环陈旧 PRD 调和对应 issue #3669detectStalePrd、reconcileStalePrd、runObservableCheck处理 PRD 与实际情况脱节的问题DEFAULT_STALE_PRD_AFTER_MS定义陈旧阈值。swarmSQLite 任务认领文档明确 swarm 的核心机制SQLite 任务认领、5 分钟超时、原子认领/释放、干净完成检测。这与better-sqlite3外部依赖见文档 Dependencies 表吻合——数据库事务天然提供认领的原子性避免多代理并发抢任务时的竞态。learner技能抽取生命周期learner 对应文档skill extraction的描述实际导出揭示其完整链路processMessageForSkills处理消息 →detectExtractableMoment判断抽取时机 →shouldPromptExtraction决定是否询问 →validateExtractionRequest/validateSkillMetadata质量校验MIN_QUALITY_SCORE门槛→writeSkill写入MAX_SKILL_CONTENT_LENGTH、MAX_SKILLS_PER_SESSION限制→findMatchingSkills后续自动调用。promoteLearning/listPromotableLearnings提供学习记录 → 正式技能的晋升通道。开发指南如何新增一个 Hooksrc/hooks/AGENTS.md 给出了标准化的 Hook 目录结构与新增流程可直接照做标准目录结构hook-name/ ├── index.ts # Main hook implementation ├── types.ts # TypeScript interfaces ├── constants.ts # Configuration constants └── *.ts # Supporting modules新增步骤创建含index.ts、types.ts、constants.ts的 Hook 目录在 src/hooks/index.ts 中导出Hook 统一重导出如需事件路由在 src/hooks/bridge.ts 注册 handler更新 docs/REFERENCE.md 的 Hooks System 章节若是执行模式类 Hook还需创建对应的 skills 下SKILL.md与 commands 下的命令文档。Hook 实现模板文档给出的标准模式// index.ts export interface HookConfig { enabled: boolean; // hook-specific config } export function createHook(config: HookConfig) { return { name: hook-name, event: UserPromptSubmit, // or Stop, PreToolUse, PostToolUse handler: async (context) { // Hook logic return { modified: false }; } }; }状态管理模式import { readState, writeState } from ../features/state-manager; const state readState(autopilot-state); state.phase executing; writeState(autopilot-state, state);事件处理对照// UserPromptSubmit - Before prompt is sent // Stop - Before session ends // PreToolUse - Before tool execution // PostToolUse - After tool execution测试要求定向测试npm test -- --grep hook-name端到端通过技能调用验证执行模式状态持久化验证.omc/state/下的状态文件安全类 Hook遵循 templates/rules/security.md 检查清单。依赖关系内部依赖见 src/hooks/AGENTS.mdsrc/features/state-manager状态持久化src/features/verification验证协议src/agents派生子代理。外部依赖better-sqlite3swarm 任务协调fs、path状态文件操作。结论oh-my-claudecode 的 Hook 体系用 31 个职责单一的模块把 Claude Code 的事件机制改造成了一台完整的行为编排引擎mode-registry管状态仲裁keyword-detector做模式触发persistent-mode以软强制消息注入维持执行recovery/preemptive-compaction保障鲁棒性registry影子模式让体系自身可以低风险演进。理解这套体系既能让你自如使用autopilot/ralph/swarm等执行模式也为你按规范扩展自有 Hook 提供了完整可循的路径——从 src/hooks/AGENTS.md 起步对照 src/hooks/index.ts 的导出清单与 hooks/hooks.json 的挂载配置即可在源码层面逐层深入。【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考