Oh-My-OpenAgent 配置加载管线6 阶段 ConfigHandler 与 Agent 排序机制的源码级解析【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent导读本文围绕 Oh-My-OpenAgent 插件中config钩子的核心处理器ConfigHandler展开它是插件把内置 Agent、工具权限、MCP 服务与命令/技能注册进 OpenCode 的总装配线。全文以 packages/omo-opencode/src/plugin-handlers/AGENTS.md 为骨架结合plugin-handlers目录下 14 个非测试源文件的真实实现逐一剖析 6 阶段顺序管线、Agent 排序sort shim机制的来龙去脉、工具权限矩阵与多级配置合并规则。读完你将能理解 OmO 的配置是如何从用户文件一路被加工成 OpenCode 可识别的 Agent/Tool/MCP/Command 的以及为什么sisyphus → hephaestus → prometheus → atlas的默认 Agent 顺序需要三个协同机制共同保障。一、ConfigHandler 是什么一次配置钩子的总装配线Oh-My-OpenAgentOmO作为 OpenCode 插件通过实现config钩子处理器ConfigHandler在每次配置生效时把内置能力与用户配置统一编排后注册进宿主。该目录下共有 14 个非测试文件实现这一逻辑入口编排在 config-handler.ts约 200 行其余文件分别承担插件组件发现、Agent 装配、MCP 合并、命令合并、工具权限、Provider 缓存等子任务。从源码看createConfigHandler返回的异步处理函数按严格顺序执行 6 个阶段并附带若干贯穿全局的副作用管理如 formatter 缓存清理、MCP 环境变量白名单注入、OpenGateway Provider 配置、Agent 排序默认项设定、已注册 Agent 名单登记最后输出一段结构化日志统计agentCount与commandCountlog([config-handler] config handler applied, { agentCount: Object.keys(agentResult).length, commandCount: Object.keys((config.command as Recordstring, unknown) ?? {}).length, });二、6 阶段管线总览原文档给出如下阶段总表本文原样继承并逐阶段结合源码展开PhaseHandlerPurpose1applyProviderConfigCache model context limits, detect anthropic-beta headers2loadPluginComponentsDiscover Claude Code plugins (10s timeout, error isolation)3applyAgentConfigLoad agents from 5 sources, skill discovery, plan demotion4applyToolConfigAgent-specific tool permissions5applyMcpConfigMerge builtin CC plugin MCPs6applyCommandConfigMerge commands/skills from 9 parallel sources各阶段在config-handler.ts中的实际调用顺序为applyProviderConfig→loadPluginComponents→applyHookConfig插件钩子合并紧随 Phase 2 之后→applyAgentConfig含缓存命中分支→applyToolConfig→applyMcpConfig→applyCommandConfig→可选applyRuntimeSkillSourceConfig。三、逐阶段源码解析Phase 1applyProviderConfig —— Provider 配置与模型缓存实现在 provider-config-handler.ts约 80 行。它的职责是读 Provider、写缓存上下文窗口缓存遍历config.provider下每个 Provider 的models把limit.context写入modelContextLimitsCachekey 为${providerID}/${modelID}并在进入阶段时先clear()保证配置热更新后缓存不残留旧值anthropic-beta 头检测读取providers.anthropic.options.headers[anthropic-beta]若包含context-1m则把anthropicContext1MEnabled置为true这是 1M 上下文能力开关的判定来源视觉能力模型缓存凡是modelConfig.modalities.input包含image或capabilities.input.image true的模型都会进入visionCapableModelsCache此外还会把collectTrustedVisionCapableModels()来自agents[multimodal-looker].model且含/的字符串解析为{ providerID, modelID }追加进缓存供后续多模态 Agent 路由复用。Phase 2loadPluginComponents —— Claude Code 插件发现实现在 plugin-components-loader.ts约 100 行。核心要点开关claude_code.plugins默认true关闭时直接返回空组件10 秒超时experimental.plugin_load_timeout_ms默认10000通过Promise.race([loadAllPluginComponents(...), timeoutPromise])实现超时即 reject 并清理定时器错误隔离loadAllPluginComponents来自oh-my-opencode/claude-code-compat-core/claude-code-plugin-loader返回{ commands, skills, agents, mcpServers, hooksConfigs, plugins, errors }结构任何异常都会通过addConfigLoadError({ path: plugin-loading, ... })记录并返回带retryableLoadFailure: true的空组件而不是让整条配置管线崩溃支持claude_code.plugins_override与claude_code.anthropic_provider透传。紧随其后的是 hook-config-handler.ts 中的applyHookConfig它把插件钩子配置写入setPluginHooksConfigs(process.cwd(), ...)。值得注意的是该函数特意按process.cwd()而非ctx.directory键控——注释指出早期版本按ctx.directory键控在 worktree、launcher chdir、开发沙箱等两者不一致的场景下会静默丢弃所有插件钩子对应 issue #4001 / #4179这是一个非常典型的宿主目录与进程目录分叉陷阱。Phase 3applyAgentConfig —— Agent 装配核心实现在 agent-config-handler.ts约 300 行内部再拆分为三个子模块来源加载agent-source-loader.ts原文档说5 sources而从当前源码看实际加载了 8 路来源用户级、项目级、OpenCode 全局、OpenCode 项目、插件级、agent_definitions、OpenCode 配置文件readOpencodeConfigAgents以及宿主config.agent。其中前两路受claude_code.agents默认true门控。所有非插件来源的 Agent 在合并前会经过filterProtectedAgentOverrides保护内置 Agent 名不允许被自定义源覆盖并且未显式声明mode的默认补为subagent内置 Agent 构建createBuiltinAgents接收迁移后的禁用名单、自定义 Agent、技能发现结果、browser_automation_engine.provider默认playwright、team_mode.enabled、experimental.disable_omo_env等参数装配与定稿agent-config-assembly.ts agent-config-finalizer.tsassembleSisyphusEnabledConfig会固定装配sisyphus → hephaestus → prometheus → atlas → sisyphus-junior的骨架其中prometheus由 prometheus-agent-config-builder.ts约 140 行构建仅在sisyphus_agent.planner_enabled默认true时注入plan 降级demotion当planner_enabled sisyphus_agent.replace_plan默认true时config.agent.plan被替换为 plan-model-inheritance.ts 生成的{ mode: subagent, hidden: true, ...modelSettings }其中modelSettings从 plan 覆盖项与 prometheus 配置中继承model / reasoning / variant / temperature / top_p / maxTokens / thinking / reasoningEffort / textVerbosity / providerOptions / fallback_models共 11 个键——这就是plan 继承模型设置含 fallback_models的实现buildAgent 被强制为{ mode: subagent, hidden: true }默认 Agentconfig.default_agent未配置时回退为sisyphus见applyDefaultAgent配置了则先经getAgentConfigKey规范化再写入。prometheus 模型解析值得单独展开buildPrometheusAgentConfig依次读取插件覆盖pluginConfig.agents.prometheus与用户分类pluginConfig.categories经 category-config-resolver.ts 的用户分类优先、否则内置默认分类查找再结合AGENT_MODEL_REQUIREMENTS[prometheus]的 fallback 链、已连接 Provider 缓存与fetchAvailableModels通过resolveModelPipeline确定最终模型与 variant。判断当前模型是否可直接复用依赖isModelInFallbackChain只有当前模型命中 prometheus 需求 fallback 链时才把currentModel作为uiSelectedModel传入。prometheus 的prompt会拼接prompt/prompt_append覆盖项经resolvePromptAppend解析文件 URI。Phase 4applyToolConfig —— 工具权限矩阵实现在 tool-config-handler.ts约 100 行详情见第五节工具权限矩阵。Phase 5applyMcpConfig —— MCP 合并实现在 mcp-config-handler.ts约 150 行。合并顺序后者覆盖前者createBuiltinMcps(...) → Claude Code .mcp.jsonloadMcpConfigs→ 用户 config.mcp → 插件 mcpServers用户配置中的同名 server 若与.mcp.json冲突会打印 warning 并以后者用户配置为准用户在config.mcp里显式写{ enabled: false }的 server合并后会被强制打上enabled: false而非删除disabled_mcps数组中的名字在合并后会被直接delete门控开关为claude_code.mcp默认true。Phase 6applyCommandConfig —— 命令/技能合并实现在 command-config-handler.ts约 200 行。原文档概括为9 parallel sources而从当前源码看Promise.all实际并发加载了 12 组来源包括配置源技能、宿主技能、用户/项目命令、OpenCode 全局/项目命令、用户技能、全局/项目 Agent 技能、项目技能、OpenCode 全局/项目技能再加上内置命令loadBuiltinCommands、内置技能命令resolveActiveBuiltinSkills与宿主config.command、插件组件命令/技能最终按固定展开顺序合并进config.command。其余要点disabled_commands会从内置技能命令中逐个删除disabled_skills含别名归一化见collectDisabledSkillAliases通过isDisabledSkillAlias/isDisabledSkillName过滤所有技能类命令检测到外部技能插件冲突时会输出getSkillPluginConflictWarning警告合并完成后remapCommandAgentFields会把命令上的agent字段从配置键统一重映射为列表展示名getAgentListDisplayName保证命令与重命名后的 Agent 指向一致。贯穿机制Agent 配置缓存与副作用重放config-handler.ts中还有一个容易被忽略的缓存层createAgentConfigCacheKey只对agent / default_agent / model / skills四个字段做JSON.stringify作为缓存键命中且插件加载未失败时直接深拷贝上次的 Agent 快照cloneAgentConfig并通过replayAgentConfigSideEffects重放副作用setDefaultAgentForSort 清空并重登记 Agent 名。这意味着applyAgentConfig这类较重装配在配置未变化时会被完全跳过。四、Agent 排序机制CRITICAL 部分默认顺序与 agent_order 覆盖默认 Agent 顺序为sisyphus → hephaestus → prometheus → atlas。用户可通过agent_order覆盖运行时顺序agent_order缺失或不全时遗漏的核心 Agent 回退到默认顺序。这一语义由 agent-ordering.ts 中的validateAgentOrder保证它逐项 trim、经getAgentConfigKey归一化、校验是否属于已知 Agent 键集合AGENT_DISPLAY_NAMES的键、剔除重复项最后把DEFAULT_AGENT_ORDER中尚未出现的核心 Agent 按默认顺序追加补齐。三个协同机制原文档指出该顺序由三个相互配合的机制共同强制DEFAULT_AGENT_ORDERagent-ordering.tsagent_order缺失或不完整时的回退顺序来源reorderAgentsByPriority()agent-priority-order.ts控制applyAgentConfig产出的 Agent 对象键插入顺序并给每个核心 Agent 注入order字段index 1非核心 Agent 键按localeCompare排序追加。该文件还导出CANONICAL_CORE_AGENT_ORDER DEFAULT_AGENT_ORDER作为唯一的规范化顺序常量installAgentSortShim()agent-sort-shim.ts在插件入口、任何 Agent 注册之前安装一次收窄Array.prototype.toSorted与Array.prototype.sort使排序数组内含 ≥2 个被排序的 Agent 对象时OpenCode 的Agent.list()及任何其他排序点都返回当前配置/默认顺序其 rank 映射agentRank在插件配置加载完成后由setAgentSortOrder更新。为什么要一个 Sort ShimOpenCode 1.4.x 通过 RemedasortBy仅按agent.name排序原生字符串/比较不是localeCompare完全忽略 Agent 的order字段上游 issuesst/opencode#19127。因此在Agent.list()这一关光靠对象键插入顺序是守不住的。此前所有给名字加不可见字符偏置排序键的方案全部失败ZWSPU200BBun.stringWidth返回 0但 Ghostty、WezTerm、Alacritty 及部分 Windows Terminal 版本会将其渲染为 1 个单元格宽——状态栏出现可见空隙、Agent 选择器列被截断#3259U2060 WORD JOINER、U00AD SOFT HYPHEN、ANSI 转义属于同一类宽度不一致问题去掉前缀、纯靠插入顺序则退化为字母序 Atlas → Hephaestus → Prometheus → Sisyphus。Shim 的安全设计Cubic P1 缓解sort shim 只拦截它关心的狭窄场景并用严格激活守卫避免全局原型补丁的误伤激活谓词isAgentArray要求arr.length 2、每个元素都是带字符串.name的非空对象、且至少 2 个元素的.name被当前顺序收录通过AGENT_ARRAY_SENTINELS哨兵集判定。混合类型数组数字、字符串、无.name的普通对象会被拒绝从而保持原生.sort()/.toSorted()语义防御性比较器agentComparator通过extractAgentName安全提取.name未收录的名字取UNRANKED Number.MAX_SAFE_INTEGER同 rank 时回退到用户传入的compareFn绝不因混合输入抛错幂等安装installed标志保证installAgentSortShim()只生效一次补丁通过Object.defineProperty以configurable/writable且enumerable: false注入。此外setDefaultAgentForSort会把默认 Agent 的 rank 置为 0其余顺延 1确保默认 Agent 始终排在最前。历史脉络Agent 排序问题累计产生 15 次提交、8 个 PR 与多次回滚原文档记录的关键里程碑#3260已合并移除 ZWSP 注入随后被0d5b08744回滚因为 OpenCode 1.4.x 忽略order仅移除 ZWSP 会导致字母序回退Atlas → Hephaestus → Prometheus → Sisyphus#3329已合并引入CANONICAL_CORE_AGENT_ORDER并锁定策略但仅靠插入顺序仍无法扛过Agent.list()的排序#3267已关闭后复活最初提出 sort shim当时因假设 #3329 已足够而关闭本次提交中以 Cubic P1 缓解防御性比较器、严格激活谓词、幂等安装复活。结论src/shared/agent-sort-shim.ts是当前唯一受支持的运行时排序机制一旦 OpenCode 尊重 Agentorder字段sst/opencode#19127 落地应立即移除该 shim。禁止模式Forbidden Patterns原文档明确列出以下做法一律禁止相关 PR 将被拒绝在 Agent 名、显示名或对象键中引入 ZWSP、U2060、U00AD、ANSI 转义或其他不可见/控制字符在 Agent 名上添加 ASCII 空格或其他可见排序前缀在DEFAULT_AGENT_ORDER/CANONICAL_CORE_AGENT_ORDER之外另立排序常量或绕过validateAgentOrder的排序代码依赖Object.entries()迭代顺序的代码跳过getAgentConfigKey/stripInvisibleAgentCharacters的 Agent 名字符串比较历史 ZWSP 数据必须继续可解析。五、工具权限矩阵原文档给出核心权限总表本文完整继承AgentGrantedDeniedLibrariangrep_app_*-Atlas, Sisyphus, Prometheustask, task_*, teammate-Hephaestustask-Default (all others)-grep_app_, task_, teammate, LSP结合 tool-config-handler.ts 的源码这张表还有更细的落地细节全局默认工具策略config.tools统一把grep_app_*、LspHover、LspCodeActions、LspCodeActionResolve、task_*、teammate置为falseconfig.permission则把webfetch、external_directory置为allow、task置为deny任务系统联动isTaskSystemEnabled开启时额外禁用todowrite/todoread宿主已把permission.skill置为deny时额外禁用skill、skill_mcpquestion 权限四层判定disabled_tools含question→deny宿主OPENCODE_CONFIG_CONTENT中permission.question deny→denyOPENCODE_CLI_RUN_MODE true→deny否则allow子 Agent 的 task 拒绝名单librarian、explore、oracle、multimodal-looker、metis、momus的permission.task被强制deny防止这些只读/专用子代理被当作通用任务代理误用逐 Agent 精细化multimodal-looker额外拒绝look_atatlas拒绝call_omo_agent但放行task/task_*/teammatesisyphus拒绝call_omo_agent并写入动态question权限prometheus在 Atlas/Sisyphus 的基础上再拒绝bash与interactive_bash规划 Agent 不直接执行命令sisyphus-junior放行task_*与teammate。六、多级配置合并MULTI-LEVEL CONFIG MERGE原文档给出的合并流水线如下用户配置为基底、项目配置叠加、最后由 Zod 默认值兜底User (~/.omo/omo.jsonc) ↓ deepMerge Project (.omo/omo.jsonc) ↓ Zod defaults Final Config具体规则agents、categories、claude_code三类键走deep merge所有disabled_*数组如disabled_agents、disabled_mcps、disabled_commands、disabled_skills、disabled_tools走Set 并集——任何一级配置中出现的禁用项都会生效。这解释了为什么 Phase 3 的applyAgentConfig开头要先做禁用名单迁移disabled_agents中的旧名会经AGENT_NAME_MAP归一化随后同时用于过滤内置 Agent 与所有自定义来源保证多级合并后的禁用语义一致。七、测试覆盖该目录为关键行为配齐了单测可作为行为契约查阅管线级config-handler.test.ts、config-handler-cache.test.ts缓存命中分支、config-handler-formatter.test.ts、config-handler.opengateway.test.ts各阶段agent-config-handler.test.ts 与 agent-config-handler-agents-skills.test.ts、mcp-config-handler.test.ts、mcp-config-handler-collision.test.ts、command-config-handler.test.ts、tool-config-handler.test.ts、tool-config-handler-display-name.test.ts、tool-config-handler-task-deny.test.ts、provider-config-handler.test.ts、hook-config-handler.test.tsAgent 装配细节agent-config-finalizer.test.ts、agent-priority-order.test.ts、agent-key-remapper.test.ts、plan-model-inheritance.test.ts、prometheus-agent-config-builder.test.ts。八、小结如何阅读与排查这条管线当你在使用 OmO 时遇到Agent 没出现/顺序不对/某个工具被误禁/MCP 未生效之类的问题可以按如下线索快速定位Agent 缺失或顺序异常→ 检查agent_order是否被覆盖确认命中 agent-ordering.ts 的校验逻辑怀疑Agent.list()排序异常时核对 agent-sort-shim.ts 是否在插件入口被安装且isAgentArray是否误判工具权限不符合预期→ 到 tool-config-handler.ts 核对默认 deny 名单与逐 Agent 覆盖注意question权限的四层判定与OPENCODE_CLI_RUN_MODE的影响MCP/命令合并结果异常→ 对照 Phase 5/6 的合并顺序后者覆盖前者确认disabled_*并集语义与enabled: false的差异插件相关组件整体缺失→ 检查claude_code.plugins开关与experimental.plugin_load_timeout_ms超时超时/异常会被隔离并打上retryableLoadFailure进而使 Agent 缓存失效配置管线会强制重跑applyAgentConfig。掌握这条 6 阶段管线的装配顺序与合并规则是理解 Oh-My-OpenAgent 一切运行时行为Agent 路由、权限边界、工具可见性的前提。【免费下载链接】oh-my-openagentOmO: Just type mass ulw keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考