魔关键词检测——隐式技能激活

学习目标

• 理解魔关键词检测的工作原理
• 设计自己的关键词-技能映射
• 识别关键词歧义和调试困难的问题
• 掌握 Hook 驱动的上下文注入模式

前置知识

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

• Hook 事件驱动安全机制

下文假设你已理解 UserPromptSubmit、PreToolUse 等 Hook 事件的基础概念，直接聚焦 OMC 的 魔关键词检测与隐式技能激活 的具体实现。

项目实践

检测架构

OMC 的魔关键词检测在 UserPromptSubmit Hook 上执行，通过 keyword-detector.mjs 脚本扫描用户输入：

关键词-技能映射

OMC 定义了 14+ 个魔关键词触发器，按优先级排序：

优先级	关键词	激活 Skill	行为
最高	cancelomc / stopomc	cancel	立即停止活跃模式
高	ralph / don't stop	ralph	持久循环模式
高	autopilot / build me	autopilot	自主执行流水线
中	ultrawork / ulw	ultrawork	并行执行模式
中	ccg	ccg	三模型协同
中	ralplan	ralplan	共识规划
低	deep interview	deep-interview	苏格拉底式访谈
低	tdd	TDD 模式	测试驱动开发
低	code review	code-review	全面审查模式
低	ultrathink	think-mode	深度推理模式

双层检测机制

OMC 的关键词检测分为两个来源：

来源	角色	可定制	关键词数
Hook（硬编码）	keyword-detector.mjs	否	11+ 核心触发器
Config（可配置）	config.jsonc 的 magicKeywords	是	4 类（ultrawork、search、analyze、ultrathink）

硬编码的核心关键词（如 ralph、autopilot）确保关键工作流的稳定性；可配置的关键词允许用户扩展自定义触发器。

注入格式

关键词匹配后，OMC 通过 <system-reminder> 标签注入激活指令：

<system-reminder>
[MAGIC KEYWORD: ralph]
</system-reminder>

Claude Code 解析此标签后，对应的 Skill 被激活。

Hook 超时策略

keyword-detector.mjs 在 Hook 中只有 5 秒超时：

hooks/hooks.json

{
  "type": "command",
  "command": "node .../keyword-detector.mjs",
  "timeout": 5
}

如果检测脚本在 5 秒内未完成，Hook 被终止——关键词检测失败但主流程不受影响。

问题与规避

问题 1：关键词歧义

用户输入中可能包含关键词但不是有意触发。例如，用户说 “我在写一个 ralph 模块” 可能并非有意激活 ralph。

规避策略：OMC 使用上下文感知的匹配——不仅检查关键词是否存在，还检查上下文模式。某些触发器（如 team）被设为显式激活（仅通过 /team 触发），不被魔关键词检测。

问题 2：调试困难

隐式激活让用户不知道哪个 Skill 被激活了。

规避策略：<system-reminder> 标签中的 [MAGIC KEYWORD: ...] 告知用户哪个关键词被检测到。用户在对话中可以看到激活信息。

问题 3：Hook 超时导致检测失败

5 秒超时可能导致复杂模式匹配失败。

规避策略：核心关键词使用简单的字符串/正则匹配，确保在 5 秒内完成。复杂匹配留给可配置的 magicKeywords，由主循环而非 Hook 处理。

设计取舍

为什么混合硬编码和可配置？

维度	纯硬编码	纯可配置	混合
稳定性	高——核心触发器不被误改	低——用户可能配置错误	高——核心稳定，扩展灵活
可扩展性	低——修改需要更新代码	高——配置即改	高——核心 + 扩展
调试性	中——需要读代码	高——配置文件易读	高——两者可区分

OMC 的选择：混合模式——核心触发器硬编码保证稳定性，扩展触发器可配置允许定制。

为什么 team 不被魔关键词激活？

team 需要明确的参数（N:agent-type “task”），隐式激活会导致参数解析错误。因此 team 只能通过显式 /team 命令触发。

参考来源

• OMC Architecture - Hooks — Hook 系统的官方文档
• Claude Code Hooks 文档 — 原生 Hook 规范