oh-my-claudecode 架构全解析：Hooks、Skills、Agents 与 State 如何驱动 Claude Code 多智能体编排

oh-my-claudecode（简称 OMC）是一套运行在 Claude Code 之上的智能体编排框架。它通过 Hooks（事件检测）、Skills（行为注入）、Agents（专业执行）、State（跨上下文状态） 四个相互咬合的系统，把普通单次对话升级为可持续到验证完成的多智能体流水线。本文以 docs/ARCHITECTURE.md 为核心，结合仓库源码与实际配置，完整讲解其编排原理、19 个 Agent 的角色分工、技能触发机制、Hook 生命周期、状态持久化设计与验证协议，帮助你理解甚至复刻一整套“任务永不半途而废”的工程化工作流。

一、总体架构：四条系统如何串成一条流水线

oh-my-claudecode 的全部编排能力可以浓缩为一句话：用 Hooks 感知生命周期事件，用 Skills 注入不同行为模式，把专业工作委托给 Agent 执行，再用 State 在上下文被压缩（compact）后找回进度。

官方架构文档用一个端到端例子直观说明其运行方式：

User Input --> Hooks (event detection) --> Skills (behavior injection)
           --> Agents (task execution) --> State (progress tracking)

当用户输入 ultrawork refactor the API 这类自然语言时，OMC 的工作依次展开：

  User Input                      Skill Detection                 Execution
       │                                │                              │
       ▼                                ▼                              ▼
┌─────────────┐              ┌──────────────────┐           ┌─────────────────┐
│  "ultrawork │              │   CLAUDE.md      │           │ SKILL ACTIVATED │
│   refactor  │─────────────▶│   Auto-Routing   │──────────▶│                 │
│   the API"  │              │                  │           │ ultrawork +     │
└─────────────┘              │ Task Type:       │           │ default +       │
                             │  - Implementation│           │ git-master      │
                             │  - Multi-file    │           │                 │
                             │  - Parallel OK   │           │ ┌─────────────┐ │
                             │                  │           │ │ Parallel    │ │
                             │ Skills:          │           │ │ agents      │ │
                             │  - ultrawork ✓   │           │ │ launched    │ │
                             │  - default ✓     │           │ └─────────────┘ │
                             │  - git-master ✓  │           │                 │
                             └──────────────────┘           │ ┌─────────────┐ │
                                                            │ │ Atomic      │ │
                                                            │ │ commits     │ │
                                                            │ └─────────────┘ │
                                                            └─────────────────┘

• Hooks（钩子）：挂在 Claude Code 生命周期事件上自动运行的程序。UserPromptSubmit 触发时会做魔法关键词（magic keyword）检测，命中即激活对应技能。
• Skills（技能）：以 ultrawork（并行）、git-master（提交管理）为代表的“行为注入”。它不替换 Agent，而是在既有 Agent 之上叠加新能力（可组合、可叠加）。
• Agents（智能体）：真正干活的 19 个专业子代理，以 oh-my-claudecode:<agent-name> 形式被 Task 工具调用。
• State（状态）：把任务进度、项目记忆写入 .omc/ 目录，即使上下文窗口因压缩被重置，关键信息也不会丢。

在仓库中，这一“技能检测—激活”机制有清晰代码对应：OMC 的主编排系统提示词定义在 src/agents/definitions.ts 的 omcSystemPrompt，其中明确写着“You are BOUND to your task list. You do not stop.”，并列出 19 个可用子代理与五条编排原则（积极委派、大胆并行、持续到验证、持续沟通、彻底验证），这正是上述架构图背后的“大脑”。

二、Agent 系统：19 个专业代理与四条泳道

2.1 整体划分

OMC 将 19 个专业 Agent 组织成 4 条泳道（lane），每个 Agent 都以 oh-my-claudecode:<agent-name> 命名，并默认运行在匹配其工作量的模型档位上。

在源码层面，全部 Agent 定义收敛于 getAgentDefinitions() 函数（见 src/agents/definitions.ts），它把 19 个 Agent 配置组装成一张注册表，供 Claude Agent SDK 使用。Agent 的提示词并非硬编码在 TypeScript 中，而是通过 loadAgentPrompt() 从 agents/ 目录下与 Agent 同名的 Markdown 文件动态加载——例如 executor 对应 agents/executor.md。该加载器在 src/agents/utils.ts 中实现：优先使用构建期注入的 __AGENT_PROMPTS__ 映射，开发/测试环境回退为运行时文件读取，并且对 Agent 名做了正则白名单校验（^[a-z0-9-]+$）与路径穿越防护，杜绝 ../../etc/passwd 之类的注入。

2.2 Build/Analysis Lane（构建/分析泳道）

覆盖从代码勘探到验证的完整开发生命周期：

Agent	默认模型	职责
explore	haiku	代码库发现，文件/符号映射
analyst	opus	需求分析，发现隐藏约束
planner	opus	任务排序，制定执行计划
architect	opus	系统设计、接口定义、权衡分析
debugger	sonnet	根因分析、构建错误解决
executor	sonnet	代码实现、重构
verifier	sonnet	完成度验证、测试充分性确认
tracer	sonnet	证据驱动的因果追踪、竞争性假说分析

2.3 Review Lane（评审泳道）

交付前的质量闸门，负责拦截正确性与安全性问题：

Agent	默认模型	职责
security-reviewer	sonnet	安全漏洞、信任边界、认证/授权审查
code-reviewer	opus	全面代码评审、API 契约、向后兼容性

2.4 Domain Lane（领域专家泳道）

按需召入的领域专家：

Agent	默认模型	职责
test-engineer	sonnet	测试策略、覆盖率、消除 flaky 测试
designer	sonnet	UI/UX 架构、交互设计
writer	haiku	文档、迁移说明编写
qa-tester	sonnet	通过 tmux 做交互式 CLI/服务运行时验证
scientist	sonnet	数据分析、统计研究
git-master	sonnet	Git 操作、提交、rebase、历史管理
document-specialist	sonnet	外部文档、API/SDK 参考查询
code-simplifier	opus	代码澄清、简化、可维护性改进

2.5 Coordination Lane（协调泳道）

挑战其他 Agent 产出的计划与设计，找不到缺口之前计划不放行：

Agent	默认模型	职责
critic	opus	计划与设计的缺口分析、多角度审查

2.6 模型路由（Model Routing）与三级成本档

OMC 使用三个模型档位，按任务的推理强度与经济性做分级路由：

Tier	模型	特点	成本
LOW	haiku	快速且便宜	低
MEDIUM	sonnet	性能与成本均衡	中
HIGH	opus	最高质量推理	高

默认分配逻辑在源码里有直白体现：查 AgentConfig 中的 model 与 defaultModel 字段即可看到 explore/writer 锚定 haiku，executor/debugger/test-engineer 等锚定 sonnet，而 architect/planner/critic/code-reviewer/code-simplifier 锚定 opus。

值得注意的是路由并非写死。在 getAgentDefinitions()（src/agents/definitions.ts）中，模型解析优先级是：调用方 override → 全局 forceInherit 继承模型 → 用户在配置里为单个 Agent 指定的 model → AgentConfig 内建默认值。也就是说，用户可以通过插件配置中的 agents.<name>.model 覆盖任一 Agent 的档位，这为“复杂重构时把 executor 临时升级到 opus”提供了配置基础。

2.7 委派（Delegation）：通过 Task 工具智能路由

工作通过 Task 工具配合模型路由下发：

Task(
  subagent_type="oh-my-claudecode:executor",
  model="sonnet",
  prompt="Implement feature..."
)

应当委派给 Agent 的场景：

• 需要改动多个文件
• 需要重构
• 需要调试或根因分析
• 需要代码评审或安全评审
• 需要规划或研究

应当直接亲自处理的场景：

• 简单文件查找
• 直白的问题回答
• 单条命令操作

2.8 典型工作流

OMC 系统提示词（omcSystemPrompt）内建了标准工作流：先用 TodoWrite 拆解任务，再按任务类型委派子代理，协调结果、处理问题而不停下，任务仅在验证通过后标记完成，循环直到全部 completed。而泳道配比最经典的链路是：

explore --> analyst --> planner --> critic --> executor --> verifier
(发现)     (分析)     (排序)     (评审)     (实现)     (确认)

omcSystemPrompt 中还内置了多条“Agent 组合拳”，例如 Architect + QA-Tester（诊断→验证闭环）：architect 输出带具体命令与预期输出的测试计划，qa-tester 在 tmux 里执行并抓取真实输出，验证失败就把结果回喂给 architect 重新诊断，循环到验证通过——这被定义为任何需要运行真实服务来验证的 Bug 的首选方案。

2.9 角色边界与任务类型速查

为了防止高层级 Agent 之间职责重叠，OMC 为它们划分了严格边界（同样记录在源码 src/agents/definitions.ts 的注释表中）：

Agent	做什么	不做什么
architect	代码分析、调试、验证	需求收集、规划
analyst	找需求缺口	代码分析、规划
planner	制定任务计划	需求分析、计划评审
critic	评审计划质量	需求分析、代码分析

选择 Agent 时可参考下表快速定位：

任务类型	推荐 Agent	模型
快速查代码	explore	haiku
功能实现	executor	sonnet
复杂重构	executor（model=opus）	opus
简单修 Bug	debugger	sonnet
复杂调试	architect	opus
UI 组件	designer	sonnet
编写文档	writer	haiku
测试策略	test-engineer	sonnet
安全评审	security-reviewer	sonnet
代码评审	code-reviewer	opus
数据分析	scientist	sonnet

三、Skills 系统：三层技能注入与魔法关键词

3.1 什么是“行为注入”

Skills 在 OMC 中不是“换个 Agent”，而是在既有 Agent 之上叠加行为模式。OMC 共提供 31 个技能（28 个可被用户调用 + 3 个内部/流水线技能），具体技能清单可在仓库 skills/ 目录逐一查看（每个技能含一份 SKILL.md）。需要说明的是，不同文档统计口径略有差异，例如 docs/REFERENCE.md 按“含别名”统计为 33 个，本文以架构文档为准。

3.2 技能分层与组合公式

技能在三个层级上叠加（组合），而不是简单并列：

┌─────────────────────────────────────────────────────────────┐
│  GUARANTEE LAYER (可选)                                       │
│  ralph: "Cannot stop until verified done"                   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  ENHANCEMENT LAYER (0-N 个技能)                               │
│  ultrawork (并行) | git-master (提交) | frontend-ui-ux       │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  EXECUTION LAYER (主技能)                                     │
│  default (构建) | orchestrate (协调) | planner (计划)        │
└─────────────────────────────────────────────────────────────┘

组合公式： [Execution Skill] + [0-N Enhancements] + [Optional Guarantee]

实际例子：

Task: "ultrawork: refactor API with proper commits"
Active skills: ultrawork + default + git-master

3.3 如何调用技能

斜杠命令方式：

/oh-my-claudecode:autopilot build me a todo app
/oh-my-claudecode:ralph refactor the auth module
/oh-my-claudecode:team 3:executor "implement fullstack app"

魔法关键词方式——在自然语言中直接包含关键词，技能自动激活：

autopilot build me a todo app      # 激活 autopilot
ralph: refactor the auth module    # 激活 ralph
ultrawork implement OAuth          # 激活 ultrawork

3.4 核心工作流技能

技能	机制	触发词	示例
autopilot	从想法到可用代码的 5 阶段全自主流水线	autopilot、build me、I want a	autopilot build me a REST API with authentication
ralph	反复循环直到验证完成的模式，由 verifier Agent 在循环退出前确认	ralph、don't stop、must complete	ralph: refactor the authentication module
ultrawork	最大化并行，同时启动多个 Agent	ultrawork、ulw	ultrawork implement user authentication with OAuth
team	用 plan → prd → exec → verify → fix 五阶段流水线协调 N 个 Claude Agent	/oh-my-claudecode:team	/oh-my-claudecode:team 3:executor "implement fullstack todo app"
ccg（Claude-Codex-Gemini）	同时分发到 Codex 与 Antigravity，Claude 汇总结果；使用 legacy Gemini CLI 时 Gemini 仍可作为企业/API-key 回退	ccg、claude-codex-gemini	ccg: review this authentication implementation
ralplan	Planner、Architect、Critic 迭代循环直至达成共识的计划制定	ralplan	ralplan this feature

3.5 实用技能一览

Skill	说明	命令
cancel	取消当前执行模式	/oh-my-claudecode:cancel
hud	状态栏配置	/oh-my-claudecode:hud
omc-setup	初始安装向导	/oh-my-claudecode:omc-setup
omc-doctor	诊断安装问题	/oh-my-claudecode:omc-doctor
skillify	从会话中抽取可复用技能（learner 为已弃用别名）	/oh-my-claudecode:skillify
skill	管理本地技能（list/add/remove）	/oh-my-claudecode:skill
trace	证据驱动的因果追踪	/oh-my-claudecode:trace
release	自动化发布工作流	/oh-my-claudecode:release
deepinit	生成分层 AGENTS.md	/oh-my-claudecode:deepinit
deep-interview	苏格拉底式深度访谈	/deep-interview
sciomc	并行 scientist Agent 编排	/oh-my-claudecode:sciomc
external-context	并行 document-specialist 研究	/oh-my-claudecode:external-context
ai-slop-cleaner	清理 AI 套话表达	/oh-my-claudecode:ai-slop-cleaner
writer-memory	写作类项目的记忆系统	/oh-my-claudecode:writer-memory

3.6 魔法关键词参考表

关键词	效果
ultrawork、ulw、uw	并行 Agent 编排
autopilot、build me、I want a、handle it all、end to end、e2e this	自主执行流水线
ralph、don't stop、must complete、until done	循环直至验证完成
ccg、claude-codex-gemini	3 模型编排（使用 Antigravity CLI 时用 antigravity workers）
ralplan	基于共识的规划
deep interview、ouroboros	苏格拉底式深度访谈
code review、review code	综合代码评审模式
security review、review security	安全专项评审模式
deepsearch、search the codebase、find in codebase	代码库搜索模式
deepanalyze、deep-analyze	深度分析模式
ultrathink、think hard、think deeply	深度推理模式
tdd、test first、red green	TDD 工作流
deslop、anti-slop	AI 套话清理
cancelomc、stopomc	取消当前执行模式

3.7 关键词检测的双源架构

关键词在两处被处理，这是理解“哪些词可以配置”的关键：

来源	职责	可否自定义
config.jsonc 的 magicKeywords	4 类（ultrawork、search、analyze、ultrathink）	可以
keyword-detector hook	11+ 触发词（autopilot、ralph、ccg 等）	不可以

其中 autopilot、ralph、ccg 的触发词硬编码在 hook 中，无法通过配置修改——这是为了保证“不停机直到完成”这类核心执行保证不被误关。在真实运行环境中，这些 hook 脚本位于 scripts/ 目录，例如 scripts/keyword-detector.mjs 与 scripts/skill-injector.mjs，后者负责把命中技能的指令注入到对话流中。

四、Hooks：挂在生命周期事件上的编排引擎

4.1 原理概述

Hooks 是响应 Claude Code 生命周期事件自动运行的代码。用户提交提示词、使用工具、会话开始/结束时都会触发。OMC 正是通过这套 Hook 机制实现 Agent 委派、关键词检测与状态持久化——这是三大能力共同的地基。

4.2 生命周期事件与 OMC 用途

Claude Code 提供 11 个生命周期事件，OMC 全部注册了对应 Hook：

事件	触发时机	OMC 用途
UserPromptSubmit	用户提交提示词	魔法关键词检测、技能注入
SessionStart	会话开始	初始设置、项目记忆加载
PreToolUse	使用工具前	权限校验、并行执行提示
PermissionRequest	请求权限时	Bash 命令权限处理
PostToolUse	使用工具后	结果校验、项目记忆更新
PostToolUseFailure	工具失败后	错误恢复处理
SubagentStart	子代理启动	代理追踪
SubagentStop	子代理停止	代理追踪、输出验证
PreCompact	上下文压缩前	保护关键信息（模式、TODO、计划锚点），保存项目记忆；压缩后经 SessionStart 恢复
Stop	Claude 即将停止	持久模式强制、代码简化
SessionEnd	会话结束	会话数据清理

仓库真实的 Hook 注册文件 hooks/hooks.json 完整覆盖了上述事件，其中 SessionStart 事件还根据 matcher（init/maintenance）区分运行 scripts/setup-init.mjs 与 scripts/setup-maintenance.mjs，实现“首次安装引导”与“维护期自检”。

4.3 system-reminder 注入机制

Hooks 通过 <system-reminder> 标签向 Claude 注入附加上下文：

<system-reminder>
hook success: Success
</system-reminder>

各注入模式的语义如下：

模式	含义
hook success: Success	Hook 正常运行，按计划继续
hook additional context: ...	附加上下文信息，请留意
[MAGIC KEYWORD: ...]	检测到魔法关键词，执行对应技能
The boulder never stops	ralph/ultrawork 模式已激活

4.4 关键 Hooks 逐个拆解

keyword-detector（关键词检测）——挂在 UserPromptSubmit 上。从用户输入中检测魔法关键词并激活对应技能。在 hooks/hooks.json 中，它是 UserPromptSubmit 事件下与 skill-injector 并列的第一个命令。

persistent-mode（持久模式）——挂在 Stop 上。当 ralph、ultrawork 等持久模式激活时，阻止 Claude 在验证完成前停下，配合系统提示词中“todo 未清空即失败”的规则使用。

pre-compact（压缩前保护）——挂在 PreCompact 上。在上下文窗口被压缩前，把关键信息（激活的模式、TODO、后台任务，以及 PRD/boulder 引用等持久计划锚点）存成检查点。随后 SessionStart Hook 在 source === "compact" 时恢复最新匹配的检查点，因此计划细节能在自动压缩后幸存（issue #3730）。

subagent-tracker——挂在 SubagentStart/SubagentStop 上。追踪正在运行的代理，停止时校验其输出。hooks/hooks.json 显示 Stop 事件上还并列挂了 scripts/verify-deliverables.mjs，用于校验子代理是否真正交付了成果物。

context-guard-stop——挂在 Stop 上。监控上下文用量，逼近上限时告警。

code-simplifier——挂在 Stop 上，默认关闭。开启后会在 Claude 停止时自动简化被修改过的文件。通过配置启用：

{
  "codeSimplifier": {
    "enabled": true,
    "extensions": [".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs"],
    "maxFiles": 10
  }
}

4.5 Hook 注册结构详解

OMC 的 hooks 声明在 hooks/hooks.json，每个 Hook 是一个带超时的 Node.js 脚本。仓库真实结构如下（比文档示例多了一层 description 顶层字段，并采用 "$CLAUDE_PLUGIN_ROOT" 环境变量定位插件根目录，保证插件安装到任意路径都能找到脚本）：

{
  "UserPromptSubmit": [
    {
      "matcher": "*",
      "hooks": [
        {
          "type": "command",
          "command": "node \"$CLAUDE_PLUGIN_ROOT\"/scripts/run.cjs \"$CLAUDE_PLUGIN_ROOT\"/scripts/keyword-detector.mjs",
          "timeout": 30
        }
      ]
    }
  ]
}

字段语义：

• matcher：Hook 响应的事件匹配模式（* 匹配全部输入；SessionStart 下也可细分 init、maintenance）
• timeout：超时秒数（文档示例为 5 秒，真实文件按任务复杂度给到 3–60 秒不等；重负载如 setup-maintenance 为 60 秒）
• type：恒为 "command"（执行外部命令）；会话结束类 Hook 还带 "async": true，允许异步执行、避免阻塞会话收尾
• 顶层 description：对整组编排 Hook 的说明

4.6 禁用与跳过 Hooks

禁用全部 Hooks：

export DISABLE_OMC=1

跳过指定 Hooks（逗号分隔）：

export OMC_SKIP_HOOKS="keyword-detector,persistent-mode"

五、State 管理：让进度穿越上下文压缩

5.1 目录结构与分层存储

OMC 把任务进度与项目知识存储在 .omc/ 目录下。即便上下文压缩重置了上下文窗口，状态系统仍能保住关键信息。

.omc/
├── state/                    # 各模式的单模式状态文件
│   ├── autopilot-state.json  # autopilot 进度
│   ├── ralph-state.json      # ralph 循环状态
│   ├── team/                 # team 任务状态
│   ├── interop/              # 跨工具任务/消息信封
│   └── sessions/             # 按会话隔离的状态
│       └── {sessionId}/
├── notepad.md                # 抗压缩备忘板
├── project-memory.json       # 项目知识库
├── plans/                    # 执行计划
├── notepads/                 # 按计划捕获知识
│   └── {plan-name}/
│       ├── learnings.md
│       ├── decisions.md
│       ├── issues.md
│       └── problems.md
├── prompts/                  # 持久化的 prompt/response 产物
├── autopilot/                # autopilot 产物
│   └── spec.md
├── research/                 # 研究结果
└── logs/                     # 执行日志

5.2 控制平面与数据平面的分离

OMC 将“编排元数据”与“大体量持久产物”分开存储：

• 控制平面（Control plane）：队列状态、worker 分配、会话状态，以及跨工具任务/消息信封，位于 .omc/state/**。
• 数据平面（Data plane）：计划、规格、提示词、结果、追踪等持久产物，位于 .omc/plans/、.omc/notepads/、.omc/prompts/、.omc/state/interop/artifacts/**。
• 具体的交接示例：
  • 共享 interop 状态把任务/消息元数据内联存放，而超大的任务描述、任务结果、消息体存入 .omc/state/interop/artifacts/**；
  • 提示词持久化把 prompt/response 文件存入 .omc/prompts/**，并把描述符元数据记录在与任务状态并列的位置。

全局状态：~/.omc/state/{name}.json 保存用户偏好与全局配置。旧版位置在读取时会被自动迁移。

这种分离让调度器与状态检查保持轻量，同时让更丰富的产物保持持久、可审计。

5.3 产物描述符与有界交接（Bounded Handoffs）

当交接需要引用大体量产物时，应当用“描述符/句柄”而非把完整负载内联粘贴。规范描述符形状如下：

字段	用途
kind	产物类别（plan、prompt、result、trace 等）
path	产物的持久路径
contentHash?	可选完整性/校验和提示
createdAt	创建时间戳
producer	归属工具、技能或 worker
sizeBytes?	可选负载大小，用于阈值决策
retention	生命周期提示，供清理/归属使用
expiresAt?	短生命周期产物的可选过期时间

有界交接规则：

1. 调用点的显式阈值允许时，小负载内联存放；
2. 负载会撑爆控制平面状态时，切换为“描述符 + 简短可读摘要”；
3. 描述符保留归属/保留元数据，让后续清理与审计保持确定性。

5.4 Notepad 备忘板

文件： .omc/notepad.md

Notepad 能穿越上下文压缩——写入的内容在上下文窗口重置后依然存在。可通过 notepad_write_manual MCP 工具保存笔记，或用 notepad_write_priority 写永久性笔记。

MCP 工具一览：

工具	说明
notepad_read	读取备忘板内容
notepad_write_priority	写高优先级备忘（永久保留）
notepad_write_working	写工作备忘
notepad_write_manual	写手动备忘
notepad_prune	清理旧备忘
notepad_stats	查看备忘板统计

工作机理：

1. PreCompact 事件时将重要信息保存到备忘板；
2. 压缩结束后将备忘板内容重新注入上下文；
3. 各 Agent 借助备忘板恢复此前上下文。

5.5 Project Memory 项目记忆

文件： .omc/project-memory.json

项目记忆是项目级知识的持久库，跨会话存活。

MCP 工具：

工具	说明
project_memory_read	读取项目记忆
project_memory_write	整体覆写项目记忆
project_memory_add_note	添加笔记
project_memory_add_directive	添加指令

生命周期集成（与 4.2 的 Hook 表一一呼应）：

• SessionStart：加载项目记忆并注入上下文；
• PostToolUse：从工具结果抽取项目知识并保存；
• PreCompact：上下文压缩前保存项目记忆。

5.6 会话作用域与会话隔离

路径： .omc/state/sessions/{sessionId}/

状态按会话隔离存储。同一项目的多个会话可以并行运行而互不冲突——这是并行编排（ultrawork/team）能安全落地的状态前提。

5.7 计划级备忘板（按计划捕获知识）

路径： .omc/notepads/{plan-name}/

每个执行计划的学习成果分文件存储：

文件	内容
learnings.md	发现的模式、成功方法
decisions.md	架构决策及理由
issues.md	问题与阻塞项
problems.md	技术债与注意事项

所有条目自动带时间戳。

5.8 集中式状态（可选）

默认状态下存在项目的 .omc/ 目录中，工作树被删除时随之消失。若希望跨工作树删除保留状态，设置 OMC_STATE_DIR 环境变量：

# 加入 ~/.bashrc 或 ~/.zshrc
export OMC_STATE_DIR="$HOME/.claude/omc"

此后状态存于 ~/.claude/omc/{project-identifier}/。项目标识是 Git remote URL 的哈希，因此同一仓库在不同工作树间共享状态。环境变量的完整说明见 docs/REFERENCE.md：它还同时约束了状态目录、并行开关（OMC_PARALLEL_EXECUTION）、以及 Codex/Gemini/Antigravity/Grok 等外部 CLI worker 的默认模型选择。

5.9 持久记忆标签

对关键信息使用 <remember> 标签：

<!-- 保留 7 天 -->
<remember>API endpoint changed to /v2</remember>

<!-- 永久保留 -->
<remember priority>Never access production DB directly</remember>

标签	保留期
<remember>	7 天
<remember priority>	永久

六、验证协议：用证据证明“真的做完了”

OMC 的核心承诺是“不停下直到验证完成”，因此验证必须可被程序化表达。OMC 把 ralph、ultrawork、autopilot 等模式共用的验证逻辑抽成一个单一事实源模块，源码位于 src/features/verification/index.ts，其配套说明见 src/features/verification/README.md。

标准检查项（STANDARD_CHECKS）：

检查项	说明	证据类型
BUILD	编译通过	build_success
TEST	全部测试通过	test_pass
LINT	无 lint 错误	lint_clean
FUNCTIONALITY	功能按预期工作	functionality_verified
ARCHITECT	opus 档架构评审通过	architect_approval
TODO	所有任务完成	todo_complete
ERROR_FREE	无未解决错误	error_free

在 src/features/verification/index.ts 的 checkEvidence() 中，证据有两道硬约束：证据必须新鲜（5 分钟以内），并且必须包含真实命令输出（evidence.passed 为 false、时间戳早于 5 分钟或缺失 command 输出都会判为无效并给出“重新运行验证”的建议）。执行层面支持并行运行（Promise.allSettled 收集全部结果）、failFast 短路与 skipOptional 过滤；每项命令有默认 60 秒超时。报告可输出 Markdown / JSON / Text 三种格式。ralph、ultrawork、autopilot 各自基于这些标准项组装协议（如 ralph 协议 = TODO + BUILD + TEST + FUNCTIONALITY + ARCHITECT，且 strictMode 开启——任一必检失败即整体 rejected）。

七、查阅与深入

• 完整参考：docs/REFERENCE.md（安装方式、环境变量全表、CLI 与技能完整清单）
• 内部 API 与能力面：docs/FEATURES.md
• 用户指南：README.md
• Agent 提示词仓库：agents/（每个 Agent 一份带 frontmatter 的 Markdown）
• Agent 源码注册表与模型解析：src/agents/definitions.ts、src/agents/utils.ts
• Hook 注册结构：hooks/hooks.json
• 验证协议实现：src/features/verification/index.ts 与 src/features/verification/README.md

结语

透过这份架构可以看出，oh-my-claudecode 的工程本质是把“永不放弃直到验证”从一句口号落实为可组合的机制：Hooks 负责在正确的时机介入，Skills 用公式 [Execution Skill] + [0-N Enhancements] + [Optional Guarantee] 组合行为，19 个分级 Agent 承载专业执行，State 则用控制/数据平面分离与检查点机制保证长任务穿越上下文压缩而不失真。读懂这套四系统联动，你就掌握了在 Claude Code 之上搭建自己的多智能体编排层的方法论。