oh-my-claudecode 特性模块架构指南模型路由、状态持久化与验证协议的源码级解析【免费下载链接】oh-my-claudecodeTeams-first Multi-agent orchestration for Claude Code项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-claudecodeoh-my-claudecodeOMC是一个面向 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 的导出清单一一对应模块职责状态落盘位置model-routing/按任务复杂度智能路由 Haiku/Sonnet/OpusN/A无状态boulder-state/计划状态与进度持久化.omc/state/boulder.jsonverification/可复用的证据化验证协议内存态notepad-wisdom/计划作用域的学习/决策/问题记录.omc/notepads/delegation-categories/语义化任务分类模型/温度选择N/A无状态task-decomposer/任务拆解以支持并行执行内存态state-manager/状态文件路径标准化.omc/state/、~/.omc/state/context-injector/提示词上下文增强注入内存态background-agent/后台任务并发管理内存态rate-limit-wait/API 限流检测与等待.omc/state/rate-limits.jsonbuiltin-skills/内置技能定义—除了上述子目录目录根部还放置了若干横切能力文件包括magic-keywords.tsmagic keyword 检测、continuation-enforcement.ts任务完成前禁止停摆、auto-update.ts静默版本检查与更新、background-tasks.ts后台任务执行模式与delegation-enforcer.tsdelegation-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等、问题深度questionDepthwhyhowwhatwhere以及隐式需求检测hasImplicitRequirements识别 make it better、improve、clean up 等模糊表述。结构信号StructuralSignals需轻量解析。包括预估子任务数estimatedSubtasks按列表项、and、then累加并封顶 10、跨文件依赖crossFileDependencies、是否要求测试hasTestRequirements、领域特异性domainSpecificitygeneric/frontend/backend/infrastructure/security、是否需要外部知识requiresExternalKnowledge、变更可逆性reversibility与影响范围impactScopelocal/module/system-wide。上下文信号ContextSignals来自会话状态。包括历史失败次数previousFailures、对话轮数conversationTurns、活动计划任务数与剩余任务数、Agent 委派链深度agentChainDepth。2.3 加权打分与阈值分档文档提到按复杂度分档源码 scorer.ts 给出了精确的权重与阈值阈值得分 ≥ 8 → HIGHOpus≥ 4 → MEDIUMSonnet 4 → LOWHaiku。词法权重示例架构关键词 3、调试关键词 2、风险关键词 2、简单关键词−2、why提问 2、词数 200 2500 再 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字段forceInherit配置项开启后绕过一切路由返回model: inherit让子 Agent 继承父模型issue #1135。路由禁用enabled: false使用defaultTier默认MEDIUM。显式模型指定explicitModel尊重用户显式选择并保留精确的modelType如fableissue #3726。Agent 级覆盖agentOverrides[agentType]按 Agent 类型直接指定档位。信号 规则评估默认流程同时计算打分档位与规则档位两者偏差超过 1 档时将confidence压到 ≤ 0.5 并取更高档避免欠配模型。minTier兜底若最终档位低于配置的最低档则强制抬升。同时内置escalateModel()LOW→MEDIUM→HIGH与canEscalate()。不过从注释可以推断反应式升级已被弃用当前推荐getRoutingRecommendation()的前置路由——编排者在委派前一次性选对模型而不是失败后再补救routeWithEscalation已标注deprecated仅保留兼容。quickTierForAgent()则提供无需完整分析的快速档位表architect/planner/critic/analyst → HIGHexplore/writer → LOWexecutor/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 → LOWspecialist/orchestration → MEDIUMadvisor/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.jsonBOULDER_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()通过withFileLockSyncboulder.json.lock串行化多会话追加防止并发覆盖——这正对应仓库中shared-memory-concurrency与shared-state-locking等测试的关注点。计划进度解析getPlanProgress()用正则/^[-*]\s*\[[xX]\]/gm统计 Markdown 勾选框完成数生成{ total, completed, isComplete }。容错readBoulderState()对ENOENT返回nullclearBoulderState()对已不存在的文件视为成功幂等删除。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.tscreateProtocol(name, description, checks, strictMode)创建协议 →createChecklist(protocol)生成待办清单 →runVerification(checklist, options)执行。执行选项包括parallel默认 true并行执行全部检查Promise.allSettledfailFast首个失败即停止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 Keywordssearch / 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 的步骤创建功能目录至少包含index.ts主导出、types.tsTypeScript 接口、constants.ts配置常量实现文件按需拆分——文档给出的目录结构在现有模块如 model-routing中一一对应。在 src/features/index.ts 中追加 re-export注意现有导出均使用.js后缀的 ESM 写法。在 docs/FEATURES.md 补充 API 文档。若架构发生变化同步更新 docs/AGENTS.md。8.2 修改状态文件路径时的注意点先更新state-manager/的路径标准化逻辑src/features/state-manager/index.ts保持项目级与用户级~/.omc/state/的统一为已有状态文件考虑迁移逻辑state-manager已导出migrateState、listStates、cleanupOrphanedStates等能力在模块 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 等改动后建议先跑对应目录测试再执行全量回归。九、模块全景速查Feature目的状态位置核心导出节选model-routing智能模型选择N/A无状态routeTask、routeAndAdaptTask、getModelForTask、explainRoutingboulder-state计划进度跟踪.omc/state/boulder.jsonreadBoulderState、writeBoulderState、hasBoulder、getPlanSummariesverification证据化验证内存态createProtocol、runVerification、checkEvidence、formatReportnotepad-wisdom知识捕获.omc/notepads/initPlanNotepad、addLearning、addDecision、getWisdomSummarydelegation-categories任务分类N/A无状态resolveCategory、getCategoryTier、enhancePromptWithCategorytask-decomposer并行化拆解内存态decomposeTask、assignFileOwnership、identifySharedFilesstate-manager路径标准化.omc/state/、~/.omc/state/getStatePath、migrateState、cleanupOrphanedStatescontext-injector提示词增强内存态injectPendingContext、createContextInjectorHookbackground-agent并发控制内存态getBackgroundManager、ConcurrencyManagerrate-limit-wait限流处理.omc/state/rate-limits.json限流检测与等待 daemonbuiltin-skills内置技能—createBuiltinSkills、listBuiltinSkillNames结语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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考