教程概述

oh-my-claudecode 的 Magic Keywords 让你用自然语言就能触发复杂的 AI 工作流。配合 Deep-Interview 的苏格拉底式提问，从模糊想法到清晰计划变得前所未有的简单。

你将学到

• ✅ Magic Keywords 完整列表
• ✅ 触发机制和优先级
• ✅ Pre-Execution Gate 工作原理
• ✅ Deep-Interview 需求澄清流程
• ✅ 实际案例演示

Magic Keywords 概述

什么是 Magic Keywords？

Magic Keywords 是 OMC 的自然语言触发器。你只需要在提示词中包含这些关键词，OMC 就会自动识别并启动对应的执行模式。

flowchart LR
    A["ralph: fix all tests"] --> B{关键词检测}
    B --> C[识别: ralph]
    C --> D[启动 Ralph 模式]
    D --> E[执行任务]

    style A fill:#e1f5ff
    style D fill:#e8f5e9

为什么需要 Magic Keywords？

Magic Keywords 完整列表

编排模式关键词

规划与访谈关键词

控制关键词

触发位置

关键词可以出现在提示词的任何位置：

# 开头（推荐）
ralph: fix all failing tests

# 中间
please use ralph mode to fix the tests

# 结尾
fix all failing tests - use ralph

触发机制详解

检测流程

flowchart TD
    A[用户输入] --> B[Hook 拦截]
    B --> C{包含关键词？}
    C -->|是| D[识别模式]
    C -->|否| E[普通对话]

    D --> F{是否明确？}
    F -->|是| G[启动模式]
    F -->|否| H[Pre-Execution Gate]

    H --> I{通过 Gate？}
    I -->|是| G
    I -->|否| J[重定向到 ralplan]

    style A fill:#e1f5ff
    style G fill:#e8f5e9
    style J fill:#fff3e0

优先级规则

当多个关键词同时出现时：

flowchart TD
    A[多个关键词] --> B{检查优先级}
    B -->|cancel/stop| C[取消模式 - 最高优先级]
    B -->|ralplan| D[规划模式]
    B -->|team| E[Team 模式]
    B -->|ralph| F[Ralph 模式]
    B -->|ulw| G[Ultrawork 模式]
    B -->|autopilot| H[Autopilot 模式]

    style C fill:#ffebee
    style D fill:#fff3e0

Pre-Execution Gate

为什么需要 Gate？

执行模式会启动重量级的多代理编排。如果任务描述模糊，代理会浪费时间在范围探索上，导致部分完成或需要返工。

Gate 的作用：

• 拦截模糊的执行请求
• 重定向到 ralplan 进行规划
• 确保代理有清晰的目标

好提示词 vs 坏提示词

✅ 通过 Gate（具体明确）：

❌ 被 Gate 拦截（模糊不清）：

Gate 检测信号

Gate 会自动通过以下任一信号：

flowchart TD
    A[Gate 检测] --> B{有文件路径？}
    B -->|是| C[✅ 通过]
    B -->|否| D{有 Issue/PR 编号？}
    D -->|是| C
    D -->|否| E{有函数/类名？}
    E -->|是| C
    E -->|否| F{有测试目标？}
    F -->|是| C
    F -->|否| G{有验收标准？}
    G -->|是| C
    G -->|否| H{有错误信息？}
    H -->|是| C
    H -->|否| I{有代码块？}
    I -->|是| C
    I -->|否| J[❌ 重定向到 ralplan]

    style C fill:#e8f5e9
    style J fill:#fff3e0

绕过 Gate

如果你确定知道自己在做什么：

# 方式 1：force 前缀
force: ralph refactor the auth module

# 方式 2：感叹号前缀
! autopilot optimize everything

Deep-Interview 深度访谈

什么是 Deep-Interview？

Deep-Interview 是一个苏格拉底式需求澄清工具。当你有模糊想法时，它会通过一系列问题帮你理清思路，最终输出清晰的 PRD 文档。

触发方式

# 方式 1：关键词触发
deep-interview "I want to build a task management app"

# 方式 2：显式调用
/oh-my-claudecode:deep-interview "I want to build a task management app"

访谈流程

flowchart TD
    A[模糊需求] --> B[Deep-Interview 启动]
    B --> C[第一轮：核心问题]
    C --> D{清晰度评分}
    D -->|< 70%| E[第二轮：细节问题]
    E --> F{清晰度评分}
    F -->|< 80%| G[第三轮：边界问题]
    G --> H{清晰度评分}
    H -->|>= 90%| I[生成 PRD]
    D -->|>= 70%| E
    F -->|>= 80%| I

    style A fill:#ffebee
    style I fill:#e8f5e9

清晰度维度

实际案例

输入：

deep-interview "I want to build a task management app"

访谈过程：

## 第一轮：核心问题

**Q1**: 这个任务管理应用的主要用户是谁？
- A: 个人用户，主要是程序员

**Q2**: 核心功能有哪些？
- A: 创建任务、设置截止日期、标记完成

**Q3**: 需要协作功能吗？
- A: 不需要，这是个人工具

## 第二轮：细节问题

**Q4**: 任务需要分类或标签吗？
- A: 需要，支持项目和标签两种分类

**Q5**: 需要提醒功能吗？
- A: 需要，截止日期前提醒

**Q6**: 数据存储方式？
- A: 本地存储优先，可选云同步

## 第三轮：边界问题

**Q7**: 需要移动端吗？
- A: 暂时只需要 Web 端

**Q8**: 预计任务数量？
- A: 单用户最多 1000 个任务

---

清晰度评分: 92%

输出 PRD：

# 任务管理应用 PRD

## 产品定位
面向程序员的个人任务管理工具

## 核心功能
1. 任务 CRUD
2. 截止日期管理
3. 提醒通知
4. 项目和标签分类

## 技术方案
- 前端：React + TypeScript
- 存储：LocalStorage + 可选云同步
- 提醒：Web Notifications API

## 验收标准
- [ ] 创建/编辑/删除任务
- [ ] 设置截止日期
- [ ] 截止日期前 1 小时提醒
- [ ] 按项目/标签筛选
- [ ] 本地存储正常工作

## 边界
- 单用户应用
- 不支持协作
- Web 端优先

实战案例

案例 1：从模糊到具体

场景：想给博客添加评论功能

# Step 1: 使用 deep-interview 澄清需求
deep-interview "I want to add comments to my blog"

# Step 2: 完成访谈后，使用 ralplan 规划
ralplan implement the comment system based on the PRD

# Step 3: 规划通过后，使用 team 执行
/team 3:executor "implement the comment system"

案例 2：快速修复

场景：修复测试失败

# 直接使用 ralph，因为有明确目标
ralph: fix all failing tests in tests/auth.test.ts

案例 3：批量重构

场景：重构整个 API 层

# 先用 ralplan 规划
ralplan refactor the API layer to use repository pattern

# 规划通过后，用 ultrawork 批量处理
ulw apply the refactoring plan to all API files

最佳实践

1. 关键词使用建议

# ✅ 推荐：关键词在开头，冒号分隔
ralph: fix all tests
autopilot: build user registration

# ✅ 可接受：自然语言中包含关键词
please use ralph to fix the tests

# ❌ 不推荐：关键词混在复杂句子中
I was thinking maybe we could use ralph or something to fix those tests that are failing

2. Gate 规避技巧

# ❌ 被 Gate 拦截
ralph fix this

# ✅ 通过 Gate - 添加具体信息
ralph fix the null pointer exception in UserService.ts:45

# ✅ 通过 Gate - 添加验收标准
ralph add pagination - acceptance: 20 items per page, prev/next buttons

3. Deep-Interview 使用时机

# ✅ 适合使用 Deep-Interview
- "我想做一个 X 功能"
- "需要重构 Y 模块"
- "性能需要优化"

# ❌ 不需要 Deep-Interview
- 具体文件和行号的修复
- 有明确 issue 编号的任务
- 有现成设计文档的任务

常见问题

Q1：关键词不触发怎么办？

# 检查 1：关键词是否正确
ralph vs ralf  # 拼写错误

# 检查 2：是否被 Gate 拦截
# 添加更多具体信息

# 检查 3：显式调用
/oh-my-claudecode:ralph "your task"

Q2：Deep-Interview 问题太多？

# 可以随时结束访谈
# 输入 "that's enough" 或 "skip remaining questions"

# 也可以直接跳到输出
# 输入 "just give me the PRD"

Q3：如何查看当前触发状态？

# 查看 OMC 状态
omc status

# 查看活跃模式
omc active

小结

Magic Keywords 和 Deep-Interview 让自然语言成为强大的控制接口：

Magic Keywords 要点

• ✅ 关键词触发复杂工作流
• ✅ 自然语言中识别模式
• ✅ Gate 保护模糊请求

Deep-Interview 要点

• ✅ 苏格拉底式提问
• ✅ 多维度清晰度评分
• ✅ 输出结构化 PRD

工作流建议

flowchart LR
    A[模糊想法] --> B[Deep-Interview]
    B --> C[PRD 文档]
    C --> D[ralplan 规划]
    D --> E[实现计划]
    E --> F[Team/Ralph 执行]

    style A fill:#ffebee
    style C fill:#e8f5e9
    style F fill:#e1f5ff

系列导航：

• ← 上一篇：教程 4：编排模式详解
• → 下一篇：教程 6：32 个专业代理与智能路由
• 返回：教程系列索引