oh-my-claudecode 特性模块架构指南：模型路由、状态持久化与验证协议的源码级解析

oh-my-claudecode 特性模块架构指南：模型路由、状态持久化与验证协议的源码级解析

【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode

oh-my-claudecode（OMC）是一个面向 Claude Code 的 Teams-first 多智能体编排框架。本文以仓库 src/features/AGENTS.md 为核心脉络，系统拆解其核心特性模块（src/features/目录）——从智能模型路由、计划状态持久化（Boulder State）、证据化验证协议，到 Notepad 知识沉淀与 Magic Keyword 增强，逐一给出 API 用法、状态落盘位置、配置语义与源码级实现依据，帮助你在自己的 Agent 工作流中复用或扩展这些模块。

一、src/features/目录定位：编排增强模块的"原子仓库"

src/features/是 oh-my-claudecode 中承载自包含功能模块（self-contained feature modules）的目录。与直接耦合在 CLI、Hook 或 Agent 中的逻辑不同，这里的每个子目录都聚焦一项可独立复用的编排能力，通过统一入口对外导出。

文档原话：本目录包含增强编排的自包含功能模块（self-contained feature modules that enhance orchestration）。

其声明的核心模块与职责（与 src/features/index.ts 的导出清单一一对应）：

除了上述子目录，目录根部还放置了若干横切能力文件，包括：magic-keywords.ts（magic keyword 检测）、continuation-enforcement.ts（任务完成前禁止停摆）、auto-update.ts（静默版本检查与更新）、background-tasks.ts（后台任务执行模式）与delegation-enforcer.ts（delegation-first 协议强制）。

二、模型路由（model-routing）：按复杂度信号智能选择模型

模型路由是 OMC 编排体系的核心决策引擎：在委派子任务之前，由编排者（通常是 Opus）基于任务提示词与上下文计算复杂度，决定把任务交给 haiku / sonnet / opus（以及更高级的 fable）中的哪一个。

2.1 最小调用范式

文档给出的核心 API 用法如下：

import { routeToModel, extractComplexitySignals } from './model-routing'; const signals = extractComplexitySignals(prompt); const model = routeToModel(signals); // 'haiku' | 'sonnet' | 'opus'

而当前仓库实际导出的入口（src/features/model-routing/index.ts）更完整，真实场景下通常这样调用：

import { routeTask, routeWithEscalation, adaptPromptForTier } from './model-routing'; // 文档头部示例：单次路由 const decision = routeTask({ taskPrompt: "Find where authentication is implemented", agentType: "explore" }); console.log(decision.tier); // 'LOW' console.log(decision.model); // 对应 LOW 档的实际模型 ID // 路由 + 提示词适配一站式调用（index.ts 的 routeAndAdaptTask 便捷函数） const { decision: d, adaptedPrompt } = routeAndAdaptTask( "Refactor the auth module and add unit tests", "executor", 0 // previousFailures );

2.2 复杂度信号：词法 / 结构 / 上下文三类

文档列出了四类信号（代码复杂度、任务关键词、文件数量与范围、错误/风险指标），源码 signals.ts 将其具体化为三组ComplexitySignals：

• 词法信号（LexicalSignals）：纯正则提取、零模型调用。包括词数（wordCount）、提及文件路径数（filePathCount，上限 20）、代码块数（codeBlockCount，统计围栏块与缩进块）、架构/调试/简单/风险关键词命中（hasArchitectureKeywords等）、问题深度（questionDepth：why>how>what>where）以及隐式需求检测（hasImplicitRequirements，识别 "make it better"、"improve"、"clean up" 等模糊表述）。
• 结构信号（StructuralSignals）：需轻量解析。包括预估子任务数（estimatedSubtasks，按列表项、and、then累加并封顶 10）、跨文件依赖（crossFileDependencies）、是否要求测试（hasTestRequirements）、领域特异性（domainSpecificity：generic/frontend/backend/infrastructure/security）、是否需要外部知识（requiresExternalKnowledge）、变更可逆性（reversibility）与影响范围（impactScope：local/module/system-wide）。
• 上下文信号（ContextSignals）：来自会话状态。包括历史失败次数（previousFailures）、对话轮数（conversationTurns）、活动计划任务数与剩余任务数、Agent 委派链深度（agentChainDepth）。

2.3 加权打分与阈值分档

文档提到按复杂度分档，源码 scorer.ts 给出了精确的权重与阈值：

• 阈值：得分 ≥ 8 → HIGH（Opus）；≥ 4 → MEDIUM（Sonnet）；< 4 → LOW（Haiku）。
• 词法权重示例：架构关键词 +3、调试关键词 +2、风险关键词 +2、简单关键词−2、why提问 +2、词数 >200 +2（>500 再 +1）、多个文件路径 +1。
• 结构权重示例：子任务多 +3、跨文件 +2、安全领域 +2、基础设施领域 +1、难回滚 +2、系统级影响 +3。
• 上下文权重示例：每次历史失败 +2（封顶 +4）、委派链深度 ≥3 +2、计划任务 ≥5 +1。

2.4 路由决策的完整优先级

router.ts 的routeTask()按以下优先级产出RoutingDecision（含model、modelType、tier、confidence、reasons、escalated字段）：

1. forceInherit（配置项）：开启后绕过一切路由，返回model: 'inherit'，让子 Agent 继承父模型（issue #1135）。
2. 路由禁用（enabled: false）：使用defaultTier（默认MEDIUM）。
3. 显式模型指定（explicitModel）：尊重用户显式选择，并保留精确的modelType（如fable，issue #3726）。
4. Agent 级覆盖（agentOverrides[agentType]）：按 Agent 类型直接指定档位。
5. 信号 + 规则评估：默认流程，同时计算打分档位与规则档位；两者偏差超过 1 档时，将confidence压到 ≤ 0.5 并取更高档，避免欠配模型。
6. minTier兜底：若最终档位低于配置的最低档，则强制抬升。

同时内置escalateModel()（LOW→MEDIUM→HIGH）与canEscalate()。不过从注释可以推断：反应式升级已被弃用，当前推荐getRoutingRecommendation()的"前置路由"——编排者在委派前一次性选对模型，而不是失败后再补救（routeWithEscalation已标注@deprecated，仅保留兼容）。quickTierForAgent()则提供无需完整分析的快速档位表（architect/planner/critic/analyst → HIGH，explore/writer → LOW，executor/designer 等 → MEDIUM）。

2.5 默认配置与可调关键词

types.ts 中定义了DEFAULT_ROUTING_CONFIG：默认档位MEDIUM，升级关键词包括critical、production、urgent、security、breaking、architecture、refactor、root cause等；降档关键词包括find、list、show、where、search、locate、grep等。AGENT_CATEGORY_TIERS还按角色类别给出了默认档位（exploration/utility → LOW，specialist/orchestration → MEDIUM，advisor/planner/reviewer → HIGH）。模型到档位的映射读取环境变量OMC_MODEL_HIGH/OMC_MODEL_MEDIUM/OMC_MODEL_LOW（见getDefaultTierModels()），并有内置回退值。

2.6 调试利器：explainRouting

当路由结果不符合预期时，可调用explainRouting(context)输出完整诊断文本，逐项列出任务摘要、Agent 类型、全部词法/结构/上下文信号、最终档位、模型与决策原因，非常适合接入日志或 HUD。

三、Boulder State：跨会话的"滚石"计划状态持久化

Boulder State 得名于 OMC 的"滚石"隐喻——那块必须被持续推动的永恒任务（注释原文：the eternal task that must be rolled）。它把活动计划状态持久化到磁盘，保证会话中断后计划进度不丢失。该模块移植自 oh-my-opencode 的 boulder-state。

3.1 文档 API 与真实状态路径

import { readBoulderState, writeBoulderState, hasBoulder } from './boulder-state'; if (hasBoulder()) { const state = readBoulderState(); state.progress.completedTasks++; writeBoulderState(state); }

文档声明的状态路径为.omc/state/boulder.json。结合 constants.ts 可知：BOULDER_FILE = 'boulder.json'，BOULDER_DIR与计划目录（PLANNER_PLANS_DIR）均来自src/lib/worktree-paths.js的OmcPaths，计划文件扩展名为.md。也就是说，OMC 把状态统一收敛到项目工作树内的 OMC 状态根目录（对应 state-manager 的路径标准化逻辑）。

3.2 存储实现要点

storage.ts 揭示了几个值得关注的工程细节：

• 原子写入：writeBoulderState()使用atomicWriteSync（来自 src/lib/atomic-write.mjs）落盘，避免写一半损坏 JSON。
• 文件锁：appendSessionId()通过withFileLockSync（boulder.json.lock）串行化多会话追加，防止并发覆盖——这正对应仓库中shared-memory-concurrency与shared-state-locking等测试的关注点。
• 计划进度解析：getPlanProgress()用正则/^[-*]\s*\[[xX]\]/gm统计 Markdown 勾选框完成数，生成{ total, completed, isComplete }。
• 容错：readBoulderState()对ENOENT返回null，clearBoulderState()对已不存在的文件视为成功（幂等删除）。

createBoulderState(planPath, sessionId)会写入active_plan、started_at、session_ids、plan_name、active与updatedAt。findPlannerPlans()会扫描{project}/.omc/plans/*.md并按修改时间倒序排列，配合getPlanSummaries()可快速生成计划列表。

四、Verification 验证协议：以证据驱动的可复用校验

验证协议被文档描述为"可复用的验证协议"，源码注释进一步说明它提炼自 ralph、ultrawork、autopilot 三条工作流，是验证要求与执行的单一事实源（single source of truth）。

4.1 文档 API 与证据收集

import { createVerificationContext, addEvidence, isVerified } from './verification'; const ctx = createVerificationContext(['BUILD', 'TEST', 'FUNCTIONALITY']); addEvidence(ctx, 'BUILD', { passed: true, output: '...' }); addEvidence(ctx, 'TEST', { passed: true, output: '...' }); if (isVerified(ctx)) { // All checks passed }

文档列出的检查类型为：BUILD、TEST、LINT、FUNCTIONALITY、ARCHITECT、TODO、ERROR_FREE——这与 index.ts 中的STANDARD_CHECKS完全一致。每种检查携带id、name、description、evidenceType、required（默认全部必选）与可选的command。

4.2 现代 API：从"上下文"到"协议/清单"

当前仓库实际导出的 API 更为工程化（index.ts）：createProtocol(name, description, checks, strictMode)创建协议 →createChecklist(protocol)生成待办清单 →runVerification(checklist, options)执行。执行选项包括：

• parallel（默认 true）：并行执行全部检查（Promise.allSettled）；
• failFast：首个失败即停止；
• skipOptional：只跑必选检查；
• timeout：每条命令默认 60 秒（runSingleCheck通过execAsync执行check.command）。

4.3 证据校验的严格规则

• 无证据 → 直接判为 invalid；证据类型不匹配 → 记 issue；证据时间戳早于 5 分钟视为"陈旧证据"（stale），需要重新验证。
• 无命令的手工检查项不会被自动放行（保持passed: false，并在metadata.status中标记pending_manual_review），避免闸门自动通过。
• 结论三态：approved/rejected/incomplete（存在跳过项）；strictMode下只要有失败即 rejected。
• formatReport()可输出 Markdown 或 JSON 报告，validateChecklist()会做整体复核并可挂接customValidator。

五、Notepad Wisdom：计划作用域的知识沉淀

Notepad Wisdom 解决的是"跨会话的知识连续性"：每个计划拥有独立的 Markdown 记事本，记录执行过程中沉淀的经验。

5.1 文档 API 与落盘位置

import { initPlanNotepad, addLearning, addDecision } from './notepad-wisdom'; initPlanNotepad('my-plan'); addLearning('my-plan', 'The API requires auth headers'); addDecision('my-plan', 'Using JWT for authentication');

文档声明的路径为.omc/notepads/{plan-name}/。源码 index.ts 确认：每个计划目录下固定创建 4 个文件——learnings.md、decisions.md、issues.md、problems.md，条目按## YYYY-MM-DD HH:MM:SS时间戳格式追加。

5.2 值得注意的实现细节

• 路径穿越防护：sanitizePlanName()将计划名中的非法字符替换为-（仅保留字母、数字、_、-），防止../式路径注入。
• 读取侧提供readPlanWisdom(planName)（返回四类条目的结构化对象）与getWisdomSummary(planName)（拼接为可注入上下文的文本块）。
• 完整导出还包括addIssue、addProblem，覆盖执行中遇到的问题记录，形成"学习/决策/问题/障碍"四象限记忆。

六、Delegation Categories：语义化任务分类

Delegation Categories 与模型路由互补：它把任务语义化归类，再按类别给出模型档位、temperature 与思考预算，实现"分类即配置"。

import { categorizeTask, getCategoryConfig } from './delegation-categories'; const category = categorizeTask(prompt); // 'ultrabrain' | 'visual-engineering' | etc. const config = getCategoryConfig(category); // { tier: 'HIGH', temperature: 0.3, thinking: 'max' }

从 index.ts 的导出看，该模块能力已演进为：resolveCategory/isValidCategory/getAllCategories、按类别取档位/温度/思考预算（getCategoryTier、getCategoryTemperature、getCategoryThinkingBudgetTokens）、从提示词检测类别（detectCategoryFromPrompt）以及类别增强提示词（enhancePromptWithCategory）。常量CATEGORY_CONFIGS与THINKING_BUDGET_TOKENS支撑{ tier, temperature, thinking }结构。配套文档见 delegation-categories/README.md 与 delegation-categories/INTEGRATION.md。

七、Magic Keywords：search / analyze / ultrathink 三档增强

magic-keywords.ts 是目录根部的横切能力：当提示词中出现特定关键词时，自动注入对应行为指令（该文件明确标注模式移植自 oh-my-opencode）。

• search 模式：触发词含search、find、locate、explore、grep、trace等 16 个，注入[search-mode]指令——并行拉起多个 explore / document-specialist 后台 Agent，配合 Grep / ripgrep / ast-grep，"绝不满足于第一个结果，穷尽式搜索"。
• analyze 模式：触发词含analyze、investigate、diagnose、audit、debug等 19 个，注入[analyze-mode]——先并行收集上下文（explore + document-specialist Agent + LSP/AST 工具），复杂场景（架构级、多系统、失败 ≥2 次）咨询 architect，先综合再行动。
• ultrathink 模式：触发词含ultrathink、think、reason、ponder，注入[ULTRATHINK MODE]——强调穷举方案、识别边界情况与风险、逐步推理、质疑假设，"推理质量优先于速度"。

实现上有两个反误触发的关键点：检测前会先剥离代码块（removeCodeBlocks）；并且isInformationalKeywordContext会检查关键词前 80 字符内是否存在信息性意图（如 "what is"、"how to use"，以及中文"什么是/如何使用/解释"、日文"とは/使い方"、韩文"뭐야/어떻게"等），若是"询问含义"而非"要求执行"则跳过增强。内置三组关键词可通过PluginConfig['magicKeywords']（{ search, analyze, ultrathink }）覆盖触发词，对应测试见 src/features/tests/magic-keywords.test.ts。

八、扩展指南：新增功能与状态路径变更的规范

文档为在src/features/中协作的 AI Agent 给出了两条硬性检查清单，这里结合仓库现状补充落地细节：

8.1 新增一个 Feature 的步骤

1. 创建功能目录，至少包含index.ts（主导出）、types.ts（TypeScript 接口）、constants.ts（配置常量），实现文件按需拆分——文档给出的目录结构在现有模块（如 model-routing）中一一对应。
2. 在 src/features/index.ts 中追加 re-export（注意现有导出均使用.js后缀的 ESM 写法）。
3. 在 docs/FEATURES.md 补充 API 文档。
4. 若架构发生变化，同步更新 docs/AGENTS.md。

8.2 修改状态文件路径时的注意点

1. 先更新state-manager/的路径标准化逻辑（src/features/state-manager/index.ts），保持项目级与用户级（~/.omc/state/）的统一；
2. 为已有状态文件考虑迁移逻辑（state-manager已导出migrateState、listStates、cleanupOrphanedStates等能力）；
3. 在模块 README 或 AGENTS.md 中记录新路径。路径变更同时会牵动paths-consistency.test.ts、omc-state-gitignore-contract.test.ts等一致性测试，修改时需同步回归。

8.3 依赖与测试

• 内部依赖：各 Feature 自包含，但可能引用src/shared/types.ts中的共享类型（如ModelType、MagicKeyword、PluginConfig）。
• 外部依赖：仅fs、path等 Node 内置模块（状态持久化用），另有少量内部库（atomic-write、file-lock、worktree-paths）。
• 测试：文档给出的过滤命令为npm test -- --grep "features"；此外src/features/**/__tests__/下已有针对各模块的单测（model-routing、delegation-categories、magic-keywords、state-manager 等），改动后建议先跑对应目录测试再执行全量回归。

九、模块全景速查

结语

src/features/是 oh-my-claudecode 编排能力的"积木箱"：模型路由解决"把任务交给谁"、Boulder State 解决"计划做到哪一步"、验证协议解决"凭什么说完成"、Notepad Wisdom 解决"踩过的坑如何复用"，而 Magic Keywords 则在提示词层面直接放大搜索、分析与深度思考三类行为。理解这些模块的 API 契约与落盘约定，是在 OMC 之上构建自定义工作流、或将其能力移植到其他 Claude Code 项目的第一块基石——仓库中 docs/FEATURES.md、docs/ARCHITECTURE.md 及各模块自带的 README 可作为继续深入的下一个入口。

【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecode