插件架构与 Claude Code Hook 集成

学习目标

• 理解 Claude Code Plugin 系统的注册与加载流程
• 掌握 OMC 作为 Plugin 的事件注册策略
• 设计自己的 Claude Code 插件
• 识别 Plugin Root 路径解析和缓存损坏的陷阱

前置知识

Hook 事件类型与生命周期拦截已在通用知识中介绍：

• Hook 事件驱动安全机制

下文假设你已理解 PreToolUse、PostToolUse、SessionStart 等 Hook 事件的基础概念，直接聚焦 OMC 的 插件架构与 Hook 集成。

项目实践

Claude Code Plugin 系统

OMC 作为 Claude Code 的插件运行，通过以下两种路径安装：

路径一：Marketplace 插件安装（推荐）

/plugin marketplace add https://github.com/Yeachan-Heo/oh-my-claudecode
/plugin install oh-my-claudecode

路径二：npm 全局安装

npm i -g oh-my-claude-sisyphus@latest

Plugin 生命周期

OMC 的加载流程：

11 点 Hook 事件注册

OMC 在 hooks/hooks.json 中注册了 Claude Code 的全部 11 个生命周期事件：

事件	Hook 脚本	超时	用途
UserPromptSubmit	keyword-detector.mjs + skill-injector.mjs	5s + 3s	魔关键词检测 + 技能注入
SessionStart	session-start.mjs + project-memory-session.mjs + wiki-session-start.mjs	5s × 3	会话初始化、项目记忆加载
PreToolUse	pre-tool-enforcer.mjs	3s	工具执行前验证
PermissionRequest	permission-handler.mjs	5s	Bash 权限处理
PostToolUse	post-tool-verifier.mjs + project-memory-posttool.mjs + post-tool-rules-injector.mjs	3s × 3	工具结果验证 + 项目记忆更新
PostToolUseFailure	post-tool-use-failure.mjs	3s	工具失败恢复
SubagentStart	subagent-tracker.mjs start	3s	Agent 开始追踪
SubagentStop	subagent-tracker.mjs stop + verify-deliverables.mjs	5s + 5s	Agent 停止追踪 + 产出验证
PreCompact	pre-compact.mjs + project-memory-precompact.mjs	10s + 5s	压缩前信息保存
Stop	context-guard-stop.mjs + persistent-mode.mjs + code-simplifier.mjs	5s + 10s + 5s	上下文保护 + 持久模式
SessionEnd	session-end.mjs + wiki-session-end.mjs	30s × 2	会话清理

Plugin 根路径解析

OMC 通过两种方式获取 Plugin Root 路径：

1. 环境变量：$CLAUDE_PLUGIN_ROOT（Claude Code 原生注入）
2. 推导：从脚本文件的位置向上推导（fallback）

// keyword-detector.mjs 中的路径解析
const _omcRoot = process.env.CLAUDE_PLUGIN_ROOT ||
  join(dirname(fileURLToPath(import.meta.url)), '..');

Plugin 缓存与修复

OMC 提供了缓存修复机制：

• scripts/repair-plugin-cache.mjs：修复损坏的 Plugin 缓存
• /omc-doctor：诊断安装问题的 CLI 命令

问题与规避

问题 1：Plugin Root 路径解析失败

当通过 --plugin-dir 而非 marketplace 安装时，$CLAUDE_PLUGIN_ROOT 可能不正确。

规避策略：OMC 使用推导逻辑作为 fallback——从脚本文件位置向上推导出 OMC Root。

问题 2：插件缓存损坏

更新 OMC 后，旧缓存可能包含过时的 Hook 配置。

规避策略：/omc-doctor 命令可以清除旧缓存并重建。

问题 3：多版本冲突

同时通过 npm 和 marketplace 安装 OMC 可能导致行为不一致。

规避策略：OMC 的版本检查机制（getInstalledVersion）检测并警告版本冲突。

设计取舍

为什么选择 Plugin 而非独立进程？

维度	Plugin 模式	独立进程
安装侵入性	低——跟随 Claude Code 的 Plugin 系统	高——需要独立安装和配置
生命周期绑定	高——自动与 Claude Code 同步启动/停止	低——需要管理独立进程
性能	高——无需进程间通信	中——需要 IPC
独立性	低——依赖 Claude Code 的 Plugin API	高——可以独立升级

OMC 的选择：Plugin 模式——牺牲独立部署能力，换取无缝集成和零安装侵入性。

参考来源

• Claude Code Plugin 文档 — Plugin 系统的官方规范
• Claude Code Hooks 文档 — Hook 系统的官方规范
• OMC REFERENCE.md — OMC 的完整功能文档