OMC Debug 排障指南：深入解析 /oh-my-claudecode:debug 命令的兼容派发与诊断方法论

本篇技术指南聚焦 oh-my-claudecode（下称 OMC）这套为 Claude Code 打造的团队级多智能体编排框架，讲解其内置的 /oh-my-claudecode:debug 命令与同名 debug 技能。读者将掌握：该命令为何以“兼容命令 + 技能派发”的形式存在、它是如何把用户参数经 $ARGUMENTS 占位符注入完整技能指令的、背后 auto-slash-command Hook 的展开机制，以及技能定义的“症状与根因分离 + 最小下一步动作”排障流程，从而能在自己的 OMC/Claude Code 会话中快速定位工作流异常与运行期困惑。

一、先认识 /oh-my-claudecode:debug：一个“兼容派发命令”

在 OMC 仓库中，commands/debug.md 是 debug 命令的兼容入口定义。其 frontmatter 只有空的 description，正文也极短，核心职责写得非常明确：

This compatibility command keeps /oh-my-claudecode:debug available without loading the full debug skill description in every Claude Code session.

也就是说，这个命令文件是一个“占位/派发器”，而非排障逻辑本体。它保证两件事：

1. 用户在任意 Claude Code 会话中仍能以 /oh-my-claudecode:debug 触发调试能力，兼容既有使用习惯；
2. 完整、冗长的 debug 技能说明不会在每个会话启动时都被整体载入上下文，从而避免无谓的 token 占用。

类似的“兼容命令”在 commands/ 目录下成体系存在，例如 commands/ask.md、commands/trace.md、commands/verify.md 等，均采用完全一致的结构：frontmatter + 一段简短的“该命令做什么/为什么不直接载入技能”说明 + ## Dispatch 派发步骤。

二、Dispatch 派发协议：命令如何“找到真正的技能”

commands/debug.md 的 ## Dispatch 章节定义了精确的三步派发流程，这也是整个兼容命令家族共用的协议：

1. Read the full bundled skill instructions from the active OMC plugin/install:
   skills/debug/SKILL.md
2. Follow that SKILL.md exactly, treating the user's arguments as:

$ARGUMENTS

If the file is not directly readable from the current working directory,
locate it under the active CLAUDE_PLUGIN_ROOT / OMC_PLUGIN_ROOT, package
root, or installed OMC plugin directory, then continue.

逐条拆解：

• 第 1 步——定位技能源：先读取当前生效 OMC 插件/安装中捆绑的技能说明文件。仓库内该技能的源文件位于 skills/debug/SKILL.md。执行时优先从当前工作目录读取；若不可读，则依次到以下位置查找：环境变量 CLAUDE_PLUGIN_ROOT / OMC_PLUGIN_ROOT 指向的插件目录、npm 包根目录、已安装的 OMC 插件目录。
• 第 2 步——把用户参数整体交给技能：将用户在 /oh-my-claudecode:debug 之后输入的全部内容，原样作为 $ARGUMENTS 代入技能指令执行。
• 第 3 步——失败兜底：文件仍找不到时，在插件根目录等候选位置继续定位，而不是直接放弃。

这种“命令文件只存指针、不重复技能正文”的设计，在源码中也有旁证：src/installer/index.ts 保留了 loadCommandDefinitions（从 /commands/*.md 读取定义），但注释明确说明 commands/ 目录曾在 v4.1.16 被移除（#582），所有命令现已“插件作用域化”为技能，该函数仅做向后兼容；而第 2523 行附近的注释则写明 “Commands are accessible via the plugin system (${CLAUDE_PLUGIN_ROOT}/commands/)”——这与 Dispatch 协议中按插件根目录定位的行为完全对应。

三、技能本体：debug 的触发场景、目标与完整工作流

真正承载排障方法论的是被派发到的 skills/debug/SKILL.md，其 frontmatter 为：

---
name: debug
description: Diagnose the current OMC session or repo state using logs, traces, state, and focused reproduction
---

它适用于“用户想诊断当前 OMC/Claude Code 会话问题、工作流破坏或令人困惑的运行时行为”的场景。技能明确定义了 Goal：

Find the real failure signal quickly and explain the next corrective step.

——找到真实失败信号并解释下一个纠正步骤，是调试的首要目标。这与“把根因定位出来再谈修复”的工程原则一致。

3.1 Workflow：五步排障流程

完整流程共五步，必须原样遵循：

1. Read the user's issue description carefully.
2. Inspect the most relevant local evidence first:
   - trace tools
   - state tools
   - notepad / project memory when relevant
   - failing tests or commands
3. Reproduce the issue narrowly if possible.
4. Distinguish symptoms from root cause.
5. Recommend the smallest next fix or verification step.

要点解读：

• 先读清问题描述再动手（步骤 1），避免带着预设结论去查证。
• 本地证据优先（步骤 2），证据来源按相关性排序：trace 工具、state 工具、相关时的 notepad/项目记忆、失败测试或命令。OMC 中 trace 能力对应 commands/trace.md 兼容命令及其派发的 skills/trace/SKILL.md，用于跟踪编排与 Hook 调用链；state 工具面向状态面检查，例如工作流/会话/任务状态机。
• 尽量做窄范围复现（步骤 3），缩小问题输入空间。
• 把症状与根因分离（步骤 4），这是排障中最容易跳步的环节。
• 只推荐“最小的下一个修复或验证步骤”（步骤 5），与技能 Rules 中“不要在隔离失败前开大范围重写处方”形成呼应。

3.2 Rules：证据优先的四条纪律

技能共四条规则，属于行为约束：

- Prefer real evidence over guesses.
- Use the trace/state surfaces when the issue involves orchestration, hooks, or agent flow.
- If the issue is actually a product/runtime bug rather than app code, say so plainly.
- Do not prescribe broad rewrites before isolating the failure.

四条规则可归纳为：真凭实据优于猜测；凡涉及编排（orchestration）、Hook 或 Agent 流转的问题，必须使用 trace/state 这类可观测面；若最终判定是产品/运行期缺陷而非应用代码问题，要直言不讳；在隔离失败之前不得建议大范围重写。

3.3 Output：标准化的四段式输出契约

排障结果必须按下述固定四段输出，方便下游决策与归档：

- Observed failure          # 观察到的失败现象
- Root-cause hypothesis     # 根因假设
- Evidence for that hypothesis  # 支撑该假设的证据
- Smallest next action      # 最小的下一步动作

这一输出结构把“现象—假设—证据—动作”显式分离，正好是 Workflow 第 4、5 步在产出物上的落地。

四、从源码看 $ARGUMENTS 展开与命令解析的底层机制

命令与技能的“指挥关系”最终由 OMC 的 auto-slash-command Hook 在运行时兑现，实现位于 src/hooks/auto-slash-command/ 下。其模块头注释说明了能力边界：

Detects and expands slash commands in user prompts. Complements Claude Code's native slash command system by adding: skill-based commands from ~/.claude/skills/ and .claude/skills/; project-level commands from .claude/commands/; template expansion with $ARGUMENTS placeholder.

即该 Hook 补充了 Claude Code 原生 slash 命令之外的技能命令与模板展开能力。关键机制如下。

4.1 检测与去重

src/hooks/auto-slash-command/index.ts 的 processMessage 负责在用户消息中检测命令：

• 匹配行首命令模式，如 /debug、/oh-my-claudecode:debug（SLASH_COMMAND_PATTERN 在 constants.ts 中定义）；
• 展开成功后，注入内容会包上 <auto-slash-command>...</auto-slash-command> 标签，用于后续跳过重复处理；
• 以 sessionId:messageId:command 为键做会话级去重，避免同一命令在同一消息内被二次展开。

4.2 参数占位符替换

命令正文中的 $ARGUMENTS 会在执行期被用户参数替换。executor.ts 的 resolveArguments 实现为：

function resolveArguments(content: string, args: string): string {
  return content.replace(/\$ARGUMENTS/g, args || '(no arguments provided)');
}

注意两点细节：一是未传参数时替换为占位文案 (no arguments provided)，而非空串，便于模型识别“本次无参数”的状态；二是 Dispatch 协议让命令文件本身含 $ARGUMENTS 占位，用户输入的全部尾部内容都会整体进入该位置。

4.3 排除名单：哪些命令不展开

constants.ts 中的 EXCLUDED_COMMANDS 列明了不做自动展开的命令。被排除的 oh-my-claudecode: 前缀命令包括 ralplan、execute、verify、skillify、plan、cancel——注释说明 ralph / ultraqa / learner 已在 5.0.0 退役并由 execute、verify 覆盖；同时 Claude Code 内建命令 help、clear、compact、history、exit、quit 也不展开，防止技能覆盖原生行为。当前仓库未将 debug 列入排除名单，说明 /oh-my-claudecode:debug 依赖兼容命令文件的派发链路生效。

4.4 命令发现与优先级

executor.ts 的 discoverAllCommands 会从多目录聚合命令/技能，包括：~/.claude/commands、项目 .claude/commands、.claude/skills、OMC 根 skills/、.agents/skills、~/.claude/skills，以及 getSkillsDir() 返回的内建技能目录；随后按“项目命令 > 用户命令 > 项目 Claude Code 技能 > 项目 OMC 技能 > 项目兼容技能 > 用户技能 > 内建技能”的优先级去重取首个命中。这意味着用户即便自定义同名命令，也遵循上述有序覆盖规则。

五、实战操作：如何在会话中调用与解读结果

5.1 发起调试

在 Claude Code 会话中直接输入：

/oh-my-claudecode:debug <问题描述>

把 <问题描述> 替换为当前遇到的具体现象，例如：Hook 未按预期触发、某个 workflow/profile 在运行时行为异常、Agent 委托链路断裂、或会话状态与你预期不一致。命令触发后，兼容命令把该描述作为 $ARGUMENTS 代入 skills/debug/SKILL.md，随后按技能的五步流程开始排障。若插件尚未定位到技能文件，参照 Dispatch 第 1 步的兜底查找顺序处理即可。

5.2 依据场景选择证据源

按技能 Workflow 第 2 步，证据源优先级取决于问题类型：

• 编排 / Hook / Agent 流转问题：优先 trace 面（对应 commands/trace.md），查看关键调用链；
• 会话 / 工作流状态问题：优先 state 面，检查状态机当前值是否符合预期；
• 涉及项目上下文或历史决策：在必要时翻阅 notepad 与项目记忆；
• 存在可运行测试或命令：直接复跑失败用例或相关命令，收集第一手输出。

5.3 解读四段式输出

一次典型的调试结果应按如下结构落回：

输出段	含义	良好示范
Observed failure	观察到的失败现象	“某 Agent 子任务在超时后未触发 recovery Hook”
Root-cause hypothesis	根因假设	“状态机在 timeout 分支写入的 state key 与 Hook 订阅的 key 不一致”
Evidence	支撑证据	trace 日志中 Hook 事件缺失、state dump 显示 key 拼写不同
Smallest next action	最小下一步	“先对齐 state key，再重跑最小复现用例验证”

若根因指向产品/运行期缺陷而非用户代码，技能 Rules 要求直说，不把问题包装成用户配置错误。

六、使用边界与注意事项

结合 commands/debug.md 与 skills/debug/SKILL.md，使用时需注意：

• /oh-my-claudecode:debug 是兼容派发命令，逻辑本体始终以插件捆绑的 skills/debug/SKILL.md 为准，仓库内 commands/debug.md 与其余 commands 文件保持同构、随插件一起分发；
• 该命令用于“当前 OMC/Claude Code 会话或仓库状态”的诊断，不承载历史长任务的追查；历史链路分析可参考 trace 技能体系；
• 排障目标是最小化的下一步修复或验证动作，而非一次到位的大范围重构；在失败被隔离前，不宜按技能 Rules 之外的方式激进改写工作流或 Hook 配置；
• 如需在未安装 OMC 插件的裸仓库里手工查看技能原文，可从仓库根目录直接阅读 skills/debug/SKILL.md；安装后则应定位到活动插件的 skills/debug/SKILL.md。

七、小结

/oh-my-claudecode:debug 是 OMC“命令薄化、技能后置”设计哲学的典型样例：用 commands/debug.md 这一极小体积的兼容命令维持命令面可用，把真正的诊断方法论沉淀在 skills/debug/SKILL.md，再借 auto-slash-command Hook 的 $ARGUMENTS 模板展开机制在运行时组装完整指令。其背后是一套清晰可复用的排障契约——证据先行、窄复现、症状与根因分离、最小下一步动作，并以“观察现象 / 根因假设 / 支撑证据 / 最小动作”四段式收口。掌握这套命令—技能—Hook 的联动方式，你不仅能排障，还能举一反三理解 OMC 中 ask、trace、verify 等全部兼容命令的派发与工作模式。