GBrain Subagent 路由规范深度解析：原生 Subagent 与 Minions 的决策机制、配置与源码实现

人工智能RAGAgent 记忆MCP 服务知识管理【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址https://gitcode.com/gh_mirrors/gb/gbrain点击查看免费下载GBrainOpenClaw/Hermes Agent Brain为后台任务提供了两条执行通道零配置、低延迟的原生 Subagent与基于 Postgres 持久化队列的 GBrain Minions。本指南围绕skills/conventions/subagent-routing.md中定义的 Subagent Routing Convention系统讲解 agent 在每次发起后台工作前应遵循的决策流程——先读用户的minion_mode偏好再依据三种模式、五类疼痛信号与内联/后台判定表做路由选择并深入源码preferences.ts、apply-migrations.ts说明配置项的落地机制。读完你将掌握一套可直接落地的 Subagent/Minions 混合路由策略以及切换、校验、并发控制的具体操作。规范定位一条贯穿所有后台工作的路由约定Subagent Routing Convention 是一份面向 Agent 的运行时行为约定convention不是机械强制的代码约束。它回答一个核心问题当 agent 准备派生后台工作时应该在原生 Subagent 与 GBrain Minions 之间如何选择。该规范以技能文档形式存在于技能树中本变体包内subagent-routing.md仓库主技能树中的同一规范subagent-routing.md规范的核心规则只有一句话每次 spawn Subagent 或提交 Minion 之前先读取用户的模式偏好。这条规则也被 minion-orchestrator SKILL 引用为路由策略的权威定义并在 v0.11.0 迁移时被写入宿主仓库的AGENTS.md见 v0_11_0.ts 中## Subagent routing (gbrain v0.11.0)标记以确保所有下游 Agent 都知道该约定。第一步每次决策前读取用户模式无论任务看起来多么简单发起后台工作前都必须先确认用户当前的路由偏好cat ~/.gbrain/preferences.json 2/dev/null该文件的minion_mode字段取值三选一always、pain_triggered、off。如果文件不存在默认按pain_triggered处理。源码层面minion_mode的类型定义与默认回退逻辑可以在以下位置直接验证preferences.tsexport type MinionMode always | pain_triggered | off;三个合法值被硬编码为VALID_MODES常量autopilot.tsconst mode loadPreferences().minion_mode ?? pain_triggered;即未配置时回退到pain_triggered的默认值v0_11_0.ts迁移器在非交互环境下同样Defaulting minion_modepain_triggered。需要注意的是偏好文件的物理路径并非写死的~/.gbrain。preferences.ts通过gbrainPath()解析目录preferences.ts因此设置GBRAIN_HOME环境变量时实际路径为$GBRAIN_HOME/.gbrain/preferences.json未设置时回退到home/.gbrain。在脚本化或 CI 环境排查路由行为时这一点值得留意。三种模式详解读取模式后按以下三种分支决策。Mode Aalways——一切后台工作走 Minions用户显式选择把所有后台 Agent 工作交给 Minions 队列submit_job成为默认提交通道绝不回退到sessions_spawn且runtime: subagent的原生方案。该模式适合对持久化、可观测性要求极高的用户。具体作业管理能力提交、监控、转向、生命周期控制参考 minion-orchestrator SKILL其中submit_job、get_job、list_jobs、get_job_progress、send_job_message、pause_job、resume_job、cancel_job、replay_job均为 MCP 可调用工具。Mode Bpain_triggered默认——先原生疼了再切换默认优先使用原生 Subagent零额外配置、低延迟足以覆盖大多数任务。但当以下疼痛信号任意一个触发时应考虑切换到 Minions信号判定特征Gateway 重启中断任务Subagent 运行中 gateway 崩溃或重启无法恢复该任务状态丢失用户询问what happened to the agent或why did you forget what you were doing根因是 Subagent 运行时丢失上下文并行度超过 3任务需要超过 3 个并发 Agent原生 Subagent 在该宽度下开始掉队drop长运行预计运行超过 5 分钟用户会想查看进度而轮询 Subagent 无法提供get_job_progress那样的结构化进度用户明确表达挫败用户说出诸如this keeps breaking、the agent keeps losing track、why is this so flaky、can we do this in the background properly当 ≥1 个信号触发时暂停并向用户提议切换规范给出了可直接使用的转换话术Subagents keep dropping state on you. GBrain Minions is a durable queue for the same work — it survives gateway restarts, every job has progress tracking and a transcript, and you can pause / resume / steer running agents. Want me to flip this task to Minions? (~10s, no extra setup.)用户同意后以相同的 prompt将任务作为 Minion job 提交同时可以顺带提议把默认模式翻转为always见下文切换模式。Mode Coff——永不建议 Minions用户已明确选择退出 Minions永不主动建议 Minions一切后台工作使用原生 Subagent尊重用户的决定。这一约束在 cron 场景同样生效——cron-via-minions.md 明确说明minion_mode: off的用户继续使用agentTurn不做自动改写。内联 vs 后台适用于所有模式的通用判定即使默认模式是alwaysMode A也并非所有工作都该进队列。以下判定表在三种模式下通用条件动作单次工具调用 30s内联总是只读查询内联用户实时等待答案内联多步骤、用户可以走开Minion并行 2 条流Minion父 子需要扛过重启Minion用户想要进度更新Minion研究 / 批量操作Minion经验法则如果用户可能会问搞定了吗就用 Minion。这条判定与 minion-orchestrator SKILL 中的请求路由表互为印证单次简单操作约 30 秒内先考虑内联执行确定性命令/脚本走 shell jobCLIgbrain jobs submit shell ...研究/推理/迭代型任务走 subagent jobgbrain agent run而需要重启持久性或可观测性的任务一律提交为 Minion job。意图不明确时只追问一次澄清你要的是一个确定性的 shell 命令 job还是一个 LLM agent job并发预算提交批量任务前的检查清单在批量提交任务之前先确认队列负载通过list_jobs --status activeMCP 可调用或gbrain jobs statsCLI检查当前活跃队列深度若活跃任务 5用delay参数错开新任务避免一次性拥塞队列资源 governor 会自动节流但不要把 20 个任务一次性倒进队列。这一约定与 minion-orchestrator 的反模式清单完全一致不要在未先检查gbrain jobs stats的情况下派发超过 5 个并发 Agent。gbrain jobs submit --help暴露的队列/生命周期参数包括--queue、--priority、--delay、--max-attempts、--max-stalled、--backoff-type、--backoff-delay、--backoff-jitter、--timeout-ms、--idempotency-key、--dry-run——其中--delay正是错峰提交的直接工具。切换模式编辑 preferences.json 而非 DB 配置用户随时可以改变主意。minion_mode存放在~/.gbrain/preferences.json中不是 DB 配置——gbrain config set minion_mode会被当作未知键拒绝。正确做法是直接编辑文件{ minion_mode: always }要点合法值仅always|pain_triggered|off保留文件中已有的其他键不要整体覆盖另一种免提示写入方式gbrain apply-migrations --mode always|pain_triggered|off该约定每次决策都会重新读取文件因此改动在下一个工具调用立即生效无需重启。源码级机制为什么直接编辑是安全的preferences.json的读写实现在 src/core/preferences.ts 中几个设计细节解释了规范为何敢让 Agent 直接改文件与引擎配置分离preferences.json独立于src/core/config.ts引擎配置两者可以各自演进互不污染原子写入savePreferences使用同文件系统临时文件 rename的方式落盘preferences.ts避免读者看到半写状态权限收紧写入后强制chmod 0o600仅属主可读写保护这份含行为偏好的文件前向兼容接口定义为[key: string]: unknownpreferences.ts保存时保留未知键规范要求的保留其他键由此得到保证严格校验validateMinionMode对写入值做白名单校验preferences.ts非法值直接抛错并列出允许值savePreferences在写入前调用该校验preferences.tsGBRAIN_HOME 感知与旧布局迁移文件头注释与copyForwardLegacyFile说明了从旧$GBRAIN_HOME布局到$GBRAIN_HOME/.gbrain的一次性复制迁移逻辑且迁移失败时宁可降级读取旧文件也绝不静默丢失minion_mode: off这样的显式退出选择preferences.ts。免提示写入的 CLI 通道gbrain apply-migrations --mode always|pain_triggered|off在 apply-migrations.ts 中定义为无需提示设置 minion_mode。迁移器的 Phase C 模式解析v0_11_0.ts遵循优先采用显式 flag非交互环境默认pain_triggered若偏好文件中已存在minion_mode则原样保留mode${existing.minion_mode} (preserved)。Minions 能力速览为什么切换是值得的当疼痛信号触发时Minions 相比原生 Subagent 提供了五类可验证的增量能力详见 minion-orchestrator SKILL持久化Job 以 Postgres 为后端gateway 重启后工作照常由 worker 接续不丢状态可观测性每个 job 都有结构化进度step count、总步数、消息、token 用量、最近调用的工具、token 记账tokens_input/tokens_output/tokens_cache_read与会话转录可转向运行中的 job 通过 inbox 消息接收指令send_job_message仅父 job 或管理员可发送下一条迭代即注入上下文生命周期pause_job/resume_job/cancel_job/replay_job全部 MCP 可调用replay_job还支持data_overrides修改参数重跑并行编排父子 DAG如gbrain agent run --fanout-manifest支持 N 个子任务 1 个聚合器子任务 token 自动汇总到父 job。监控入口对照轻量检查用get_job_progress结构化快照完整细节用get_job ID队列健康看gbrain jobs statsCLI或get_job_statsMCP。与 cron-via-minions 规范的协同Subagent Routing Convention 负责即席非 cron工作的路由cron 调度场景由 cron-via-minions.md 管辖。两份文档共用同一个preferences.json机制cron 触发的定时工作应提交为 Minion job带基于周期槽位的 idempotency key队列层去重重叠运行而不是调用 OpenClaw 原生agentTurn300s 超时、无持久化、无转录同样尊重minion_mode: off——这类用户继续使用agentTurn不做自动改写两者协同构成完整的后台执行策略即席任务按疼痛信号路由定时任务一律走队列。反模式清单结合 minion-orchestrator SKILL 的反模式章节与 Subagent 路由最直接相关的红线如下单个搜索查询不要派生 Minion直接用 search 工具不要 fire-and-forget 后不检查结果未先检查gbrain jobs stats不要派发超过 5 个并发 AgentMinions 可用时subagent 工作不要使用sessions_spawnruntime: subagent应改用gbrain agent run不要紧循环轮询get_job轻量检查应使用get_job_progress。延伸阅读minion-orchestrator SKILLMinions 的完整作业管理契约提交、监控、转向、生命周期、durable execution 阶梯cron-via-minions.mdcron 调度工作的 Minion 化约定与 idempotency-key 用法minions-shell-jobs.mdshell job 的执行模式Postgres daemon 与 PGLite --follow与前置条件preferences.tsminion_mode偏好文件的读取、校验与原子写入实现apply-migrations.ts--mode免提示写入选项赞分享人工智能RAGAgent 记忆MCP 服务知识管理【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址https://gitcode.com/gh_mirrors/gb/gbrain点击查看免费下载相关推荐Atmosphere-stable整合包新手指南5步部署、金手指、超频与排错一次讲透Atmosphere stable整合包新手指南5步部署、金手指、超频与排错一次讲透 Atmosphere stable 是热门 Switch 自制固件「大气人工智能RAGAgent 记忆MCP 服务知识管理gbrain 模型路由体系全解析四层 tier 系统、subagent 分派与 key-aware 默认值机制gbrain 模型路由体系全解析四层 tier 系统、subagent 分派与 key aware 默认值机制 本文围绕 gbrain 仓库中的 Model人工智能RAGAgent 记忆MCP 服务知识管理深入解析Code Review GPT的SubAgent工具机制与应用深入解析Code Review GPT的SubAgent工具机制与应用 概述 在自动化代码审查领域Code Review GPT项目引入了一个强大的SubAg上一篇手撕包菜网站开源DHT与搜索引擎技术的完美结合下一篇PPTAgent多模态生成技术文本、图像与布局的完美融合创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考