尧图网页设计 
GBrain Cron via Minions 约定将定时任务从 agentTurn 迁移到持久化 Minion 任务队列【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain本篇技术指南讲解 GBrain 项目中定时任务cron的执行层规范当主机调度器OpenClaw cron、crontab、Railway cron 等触发时定时工作应作为Minion 任务提交到持久化队列而不是调用 OpenClaw 原生agentTurn。读完本文你将掌握 cron 清单的改写方法Postgres 与 PGLite 两种形态、主机侧自定义 handler 的注册契约、v0.11.0 迁移编排器的自动改写流程以及minion_mode: off退出通道等关键边界。为什么 cron 触发的工作必须走 Minion 队列GBrain 的cron-via-minions约定见 plugin/skills/conventions/cron-via-minions.md是一条铁律定时器触发时应当提交 Minion 任务而不是调用agentTurn。理由源于agentTurn的三个固有缺陷固定 300 秒超时长任务如收件箱清扫、简报生成会直接被超时掐断无持久性网关重启后任务状态丢失无从恢复无转录任务执行过程没有任何记录可供事后审计。同样不能走另一条歧路为 cron 启动一个与网关争抢资源的隔离会话。正确的做法是把工作交给 GBrain Minions——Postgres 原生的持久化任务队列。从源码结构看这条约定与 skills/minion-orchestrator/SKILL.md 的durable execution持久化执行信条一脉相承凡是预计运行超过约 2 分钟、用户之后可能会追问做完了吗的工作都应该路由到队列而非裸后台进程。两种引擎形态下的 cron 改写模板原约定给出了两种部署形态下完全不同的提交写法二者都必须完整保留Postgres 形态fire-and-forget 幂等键{ schedule: */30 * * * *, kind: shell, cmd: gbrain jobs submit ea-inbox-sweep --params {\slot\:\$(date -u %Y-%m-%dT%H:%M)\} --idempotency-key ea-inbox-sweep:$(date -u %Y-%m-%dT%H:%M) }要点拆解--params中把slot绑定为当前时间槽UTC 精确到分钟作为本次运行的数据载荷--idempotency-key也以时间槽命名幂等键由队列在数据库层去重cron 在上一次调用仍在运行时再次触发会产生一个 no-op而不是堆叠出重复任务。PGLite 形态内联执行 --follow{ schedule: */30 * * * *, kind: shell, cmd: gbrain jobs submit ea-inbox-sweep --params {} --follow }为什么 PGLite 不能用 Postgres 那种后台 worker 守护进程模式因为 PGLite 使用独占文件锁无法并行运行一个独立的 worker 守护进程所以 cron 只能直接内联执行任务用--follow等待并流式输出结果。两种写法对应了 skills/cron-scheduler/SKILL.md 第 4 阶段的注册规则每个注册的 cron 条目应通过 Minions 执行而不是agentTurn。为什么值得这么做持久性、可观测性、可转向、并发安全约定文档列出了四条核心收益持久性Durability任务执行中途网关重启worker 在下次启动时会重新领取任务状态不丢失可观测性Observabilitygbrain jobs list与gbrain jobs get id能展示每一次运行、运行时长、完整转录与 token 消耗——注意get_job会返回tokens_input、tokens_output、tokens_cache_read等结构化字段见 skills/minion-orchestrator/SKILL.md可转向Steering运行中的任务可以接收收件箱inbox消息——跳过新闻稿线程聚焦紧急 DM这类指令会作为上下文注入下一次迭代源码层面由MinionJobContext.readInbox()支撑见 src/core/minions/types.ts并发安全Concurrency safety幂等键落在时间槽上5 分钟的 cron 跑 8 分钟的任务时队列层会把重叠触发变成 no-op。如果不加幂等键稳态下会堆积出 4 份重叠副本——这是并发失控的直接后果。内置 handler 与主机自定义 handler谁来注册关键边界在于GBrain 只会改写 handler 名称匹配 gbrain 内置集的 cron 条目。内置集包括sync、embed、lint、import、extract、backlinks、autopilot-cycle等——这些正是 src/commands/jobs.ts 中registerBuiltinHandlers注册的集合文档层面 docs/guides/plugin-handlers.md 称之为注册表的真相来源此外还包括shell、subagent、orphans、integrity及 dream-cycle 各阶段。而对于主机自定义 handlerea-inbox-sweep、morning-briefing或你部署里跑在 cron 上的任何东西由主机平台以代码形式携带 handler。GBrain 不会替你注册这些名字。一个实用的诊断技巧用gbrain jobs submit 未知名字 --follow提交未知任务名CLI 会打印出完整的内置注册列表该行为也记录在 docs/guides/plugin-handlers.md。插件契约如何注册主机自定义 handler主机 worker 引导代码遵循如下契约TypeScript 示例与约定文档一致import { MinionQueue, MinionWorker } from gbrain/minions; const worker new MinionWorker(engine, { queue: default }); worker.register(ea-inbox-sweep, async (ctx) { // 主机特定的 agent 回合调用主机拥有的 LLM 工具。 // ctx.data 携带 cron slot 载荷返回一个结果对象。 }); await worker.start();几个必须遵守的细节必须在start()之前完成全部注册。worker 的 stall 检测器会忽略未在注册集合中的任务名引导代码要随主机仓库发布。Autopilot 会以子进程方式拉起 worker主机可以把自定义 worker 二进制或一个副作用模块让标准 worker 启动时自动加载注册 handlerHandler 即代码不是数据文件没有handlers.json式的数据文件因为每个条目是 worker 认领任务时 exec 的 shell 命令这种数据文件是持久化的 RCE 面——一个 agent 可写的文件却能派生任意 shell。docs/guides/plugin-handlers.md 明确解释了为什么用代码而非数据这一设计决策。每个 handler 收到的MinionJobContext承载如下关键字段规范定义见 src/core/minions/types.ts字段含义id/name任务 id 与任务类型名data任务参数cron 提交时传入的任何载荷attempts_made已尝试次数signal协作式取消信号超时、取消、暂停或锁丢失时触发shutdownSignal仅 worker 进程收到 SIGTERM/SIGINT 时触发deadlineAtMs认领时timeout_at刻印的绝对墙上时钟截止时间updateProgress()/updateTokens()/log()结构化进度、token 累计与转录写入isActive()任务锁是否仍被持有readInbox()读取发送给本任务的未读收件箱消息成功返回可序列化对象失败则抛出异常——worker 会按max_attempts记录并重试。中止协作ctx.signal.aborted变为 true 时应优雅收尾worker 会等 30 秒再 SIGKILL长耗时的 LLM 调用应把 signal 透传给所用网络库。幂等队列在数据库层强制唯一idempotency_key因此你不必为cron 在上次运行未结束时再次触发这种双重提交操心。v0.11.0 迁移编排器如何驱动改写GBrain 的迁移流程由gbrain apply-migrations驱动运行时真相来源为 src/commands/migrations/v0_11_0.ts对 cron 条目做两类处理内置 handler机械式自动改写为gbrain jobs submit ...主机自定义 handler原样保留清单但向~/.gbrain/migrations/pending-host-work.jsonl追加一条结构化 TODO完整形状见 docs/guides/plugin-handlers.md{ type: cron-handler-needs-host-registration, handler: ea-inbox-sweep, cron_schedule: 0 */30 * * *, manifest_path: /path/to/cron/jobs.json, current_cmd: agentTurn ea-inbox-sweep, recommendation: Add a handler registration for ea-inbox-sweep in your host worker bootstrap per docs/guides/plugin-handlers.md. Once registered, re-run gbrain apply-migrations to auto-rewrite this entry., status: pending }主机 agent 随后按 skills/migrations/v0.11.0.md 的四步闭环完成迁移读取~/.gbrain/migrations/pending-host-work.jsonl对每条cron-handler-needs-host-registration行按上文插件契约在主机 worker 引导代码中注册 handler部署更新后的 workerworker 启动时会把已注册名字写入 discovery 文件重跑gbrain apply-migrations --yes——编排器识别出新近可注册的 handler将 cron 条目改写为gbrain jobs submit并把 JSONL 行标记为status: complete。v0.11.0 迁移文档强调每个 handler 的迁移是一次完整的 skillify而非顺手加个 handler插件契约、引导代码发布、handler 单元测试mock LLM覆盖快乐路径/空输入/网络超时/LLM 失败、集成测试提交真实任务并断言任务完成、副作用发生、结果形状符合消费者预期、LLM 评测快乐/边界/对抗各一例、解析器触发词更新与触发评测、E2E 冒烟、brain 归档brain/RESOLVER.md补条目、gbrain check-resolvable全部通过且scripts/skillify-check.ts handler-code-path必须 10/10 通过JSONL 行才会被标记 complete。退出门尊重minion_mode: off的用户约定明确要求用户在~/.gbrain/preferences.json中设置minion_mode: off时继续使用agentTurn不自动改写。这是一条用户意愿优先的边界有效取值always|pain_triggered|off文件不存在时默认pain_triggered详见 skills/conventions/subagent-routing.md该键不在 DB 配置中——gbrain config set minion_mode会被当作未知键拒绝只能直接编辑~/.gbrain/preferences.json也可以用gbrain apply-migrations --mode always|pain_triggered|off免提示写入约定在每次做决策时重新读取该文件因此修改立即生效同一套 preferences.json 机制同时服务 cron 定时工作本文与 ad-hoc 后台工作subagent-routing 约定两条路由。前瞻原生调度循环仍未上线最后是一个重要的现状澄清约定文档的 Forward notegbrain jobs work内部的原生调度循环——直接持有 cron 表达式、无需主机调度器转交——自 v0.11.1 起一直在路线图上但尚未发布。因此主机调度器继续按原计划触发这一约定只替换执行层——cron 触发后做什么——不替换调度层在原生调度上线之前cron 表达式依然由 OpenClaw cron、crontab 或进程管理器持有。相关技能与文档地图skills/conventions/subagent-routing.md — 非定时ad-hoc工作下原生 subagent 与 Minion 的路由决策pain_triggered默认值与切换信号skills/minion-orchestrator/SKILL.md — 任务进入队列后的提交、监控、转向、暂停/恢复/重放以及超过 2 分钟操作的持久化执行阶梯skills/cron-scheduler/SKILL.md — 调度层面的指导错峰、静默时段、幂等现已引用本约定skills/migrations/v0.11.0.md — GBrain 如何将现有主机 cron 清单迁移到本约定含十项 skillify 门槛docs/guides/plugin-handlers.md — 主机自定义 handler 的完整插件契约、MinionJobContext字段说明与信任边界handler 代码以 worker 进程权限运行无运行时沙箱按生产代码标准评审。【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 GBrain Cron via Minions 约定：将定时任务从 agentTurn 迁移到持久化 Minion 任务队列
GBrain Cron via Minions 约定将定时任务从 agentTurn 迁移到持久化 Minion 任务队列【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain本篇技术指南讲解 GBrain 项目中定时任务cron的执行层规范当主机调度器OpenClaw cron、crontab、Railway cron 等触发时定时工作应作为Minion 任务提交到持久化队列而不是调用 OpenClaw 原生agentTurn。读完本文你将掌握 cron 清单的改写方法Postgres 与 PGLite 两种形态、主机侧自定义 handler 的注册契约、v0.11.0 迁移编排器的自动改写流程以及minion_mode: off退出通道等关键边界。为什么 cron 触发的工作必须走 Minion 队列GBrain 的cron-via-minions约定见 plugin/skills/conventions/cron-via-minions.md是一条铁律定时器触发时应当提交 Minion 任务而不是调用agentTurn。理由源于agentTurn的三个固有缺陷固定 300 秒超时长任务如收件箱清扫、简报生成会直接被超时掐断无持久性网关重启后任务状态丢失无从恢复无转录任务执行过程没有任何记录可供事后审计。同样不能走另一条歧路为 cron 启动一个与网关争抢资源的隔离会话。正确的做法是把工作交给 GBrain Minions——Postgres 原生的持久化任务队列。从源码结构看这条约定与 skills/minion-orchestrator/SKILL.md 的durable execution持久化执行信条一脉相承凡是预计运行超过约 2 分钟、用户之后可能会追问做完了吗的工作都应该路由到队列而非裸后台进程。两种引擎形态下的 cron 改写模板原约定给出了两种部署形态下完全不同的提交写法二者都必须完整保留Postgres 形态fire-and-forget 幂等键{ schedule: */30 * * * *, kind: shell, cmd: gbrain jobs submit ea-inbox-sweep --params {\slot\:\$(date -u %Y-%m-%dT%H:%M)\} --idempotency-key ea-inbox-sweep:$(date -u %Y-%m-%dT%H:%M) }要点拆解--params中把slot绑定为当前时间槽UTC 精确到分钟作为本次运行的数据载荷--idempotency-key也以时间槽命名幂等键由队列在数据库层去重cron 在上一次调用仍在运行时再次触发会产生一个 no-op而不是堆叠出重复任务。PGLite 形态内联执行 --follow{ schedule: */30 * * * *, kind: shell, cmd: gbrain jobs submit ea-inbox-sweep --params {} --follow }为什么 PGLite 不能用 Postgres 那种后台 worker 守护进程模式因为 PGLite 使用独占文件锁无法并行运行一个独立的 worker 守护进程所以 cron 只能直接内联执行任务用--follow等待并流式输出结果。两种写法对应了 skills/cron-scheduler/SKILL.md 第 4 阶段的注册规则每个注册的 cron 条目应通过 Minions 执行而不是agentTurn。为什么值得这么做持久性、可观测性、可转向、并发安全约定文档列出了四条核心收益持久性Durability任务执行中途网关重启worker 在下次启动时会重新领取任务状态不丢失可观测性Observabilitygbrain jobs list与gbrain jobs get id能展示每一次运行、运行时长、完整转录与 token 消耗——注意get_job会返回tokens_input、tokens_output、tokens_cache_read等结构化字段见 skills/minion-orchestrator/SKILL.md可转向Steering运行中的任务可以接收收件箱inbox消息——跳过新闻稿线程聚焦紧急 DM这类指令会作为上下文注入下一次迭代源码层面由MinionJobContext.readInbox()支撑见 src/core/minions/types.ts并发安全Concurrency safety幂等键落在时间槽上5 分钟的 cron 跑 8 分钟的任务时队列层会把重叠触发变成 no-op。如果不加幂等键稳态下会堆积出 4 份重叠副本——这是并发失控的直接后果。内置 handler 与主机自定义 handler谁来注册关键边界在于GBrain 只会改写 handler 名称匹配 gbrain 内置集的 cron 条目。内置集包括sync、embed、lint、import、extract、backlinks、autopilot-cycle等——这些正是 src/commands/jobs.ts 中registerBuiltinHandlers注册的集合文档层面 docs/guides/plugin-handlers.md 称之为注册表的真相来源此外还包括shell、subagent、orphans、integrity及 dream-cycle 各阶段。而对于主机自定义 handlerea-inbox-sweep、morning-briefing或你部署里跑在 cron 上的任何东西由主机平台以代码形式携带 handler。GBrain 不会替你注册这些名字。一个实用的诊断技巧用gbrain jobs submit 未知名字 --follow提交未知任务名CLI 会打印出完整的内置注册列表该行为也记录在 docs/guides/plugin-handlers.md。插件契约如何注册主机自定义 handler主机 worker 引导代码遵循如下契约TypeScript 示例与约定文档一致import { MinionQueue, MinionWorker } from gbrain/minions; const worker new MinionWorker(engine, { queue: default }); worker.register(ea-inbox-sweep, async (ctx) { // 主机特定的 agent 回合调用主机拥有的 LLM 工具。 // ctx.data 携带 cron slot 载荷返回一个结果对象。 }); await worker.start();几个必须遵守的细节必须在start()之前完成全部注册。worker 的 stall 检测器会忽略未在注册集合中的任务名引导代码要随主机仓库发布。Autopilot 会以子进程方式拉起 worker主机可以把自定义 worker 二进制或一个副作用模块让标准 worker 启动时自动加载注册 handlerHandler 即代码不是数据文件没有handlers.json式的数据文件因为每个条目是 worker 认领任务时 exec 的 shell 命令这种数据文件是持久化的 RCE 面——一个 agent 可写的文件却能派生任意 shell。docs/guides/plugin-handlers.md 明确解释了为什么用代码而非数据这一设计决策。每个 handler 收到的MinionJobContext承载如下关键字段规范定义见 src/core/minions/types.ts字段含义id/name任务 id 与任务类型名data任务参数cron 提交时传入的任何载荷attempts_made已尝试次数signal协作式取消信号超时、取消、暂停或锁丢失时触发shutdownSignal仅 worker 进程收到 SIGTERM/SIGINT 时触发deadlineAtMs认领时timeout_at刻印的绝对墙上时钟截止时间updateProgress()/updateTokens()/log()结构化进度、token 累计与转录写入isActive()任务锁是否仍被持有readInbox()读取发送给本任务的未读收件箱消息成功返回可序列化对象失败则抛出异常——worker 会按max_attempts记录并重试。中止协作ctx.signal.aborted变为 true 时应优雅收尾worker 会等 30 秒再 SIGKILL长耗时的 LLM 调用应把 signal 透传给所用网络库。幂等队列在数据库层强制唯一idempotency_key因此你不必为cron 在上次运行未结束时再次触发这种双重提交操心。v0.11.0 迁移编排器如何驱动改写GBrain 的迁移流程由gbrain apply-migrations驱动运行时真相来源为 src/commands/migrations/v0_11_0.ts对 cron 条目做两类处理内置 handler机械式自动改写为gbrain jobs submit ...主机自定义 handler原样保留清单但向~/.gbrain/migrations/pending-host-work.jsonl追加一条结构化 TODO完整形状见 docs/guides/plugin-handlers.md{ type: cron-handler-needs-host-registration, handler: ea-inbox-sweep, cron_schedule: 0 */30 * * *, manifest_path: /path/to/cron/jobs.json, current_cmd: agentTurn ea-inbox-sweep, recommendation: Add a handler registration for ea-inbox-sweep in your host worker bootstrap per docs/guides/plugin-handlers.md. Once registered, re-run gbrain apply-migrations to auto-rewrite this entry., status: pending }主机 agent 随后按 skills/migrations/v0.11.0.md 的四步闭环完成迁移读取~/.gbrain/migrations/pending-host-work.jsonl对每条cron-handler-needs-host-registration行按上文插件契约在主机 worker 引导代码中注册 handler部署更新后的 workerworker 启动时会把已注册名字写入 discovery 文件重跑gbrain apply-migrations --yes——编排器识别出新近可注册的 handler将 cron 条目改写为gbrain jobs submit并把 JSONL 行标记为status: complete。v0.11.0 迁移文档强调每个 handler 的迁移是一次完整的 skillify而非顺手加个 handler插件契约、引导代码发布、handler 单元测试mock LLM覆盖快乐路径/空输入/网络超时/LLM 失败、集成测试提交真实任务并断言任务完成、副作用发生、结果形状符合消费者预期、LLM 评测快乐/边界/对抗各一例、解析器触发词更新与触发评测、E2E 冒烟、brain 归档brain/RESOLVER.md补条目、gbrain check-resolvable全部通过且scripts/skillify-check.ts handler-code-path必须 10/10 通过JSONL 行才会被标记 complete。退出门尊重minion_mode: off的用户约定明确要求用户在~/.gbrain/preferences.json中设置minion_mode: off时继续使用agentTurn不自动改写。这是一条用户意愿优先的边界有效取值always|pain_triggered|off文件不存在时默认pain_triggered详见 skills/conventions/subagent-routing.md该键不在 DB 配置中——gbrain config set minion_mode会被当作未知键拒绝只能直接编辑~/.gbrain/preferences.json也可以用gbrain apply-migrations --mode always|pain_triggered|off免提示写入约定在每次做决策时重新读取该文件因此修改立即生效同一套 preferences.json 机制同时服务 cron 定时工作本文与 ad-hoc 后台工作subagent-routing 约定两条路由。前瞻原生调度循环仍未上线最后是一个重要的现状澄清约定文档的 Forward notegbrain jobs work内部的原生调度循环——直接持有 cron 表达式、无需主机调度器转交——自 v0.11.1 起一直在路线图上但尚未发布。因此主机调度器继续按原计划触发这一约定只替换执行层——cron 触发后做什么——不替换调度层在原生调度上线之前cron 表达式依然由 OpenClaw cron、crontab 或进程管理器持有。相关技能与文档地图skills/conventions/subagent-routing.md — 非定时ad-hoc工作下原生 subagent 与 Minion 的路由决策pain_triggered默认值与切换信号skills/minion-orchestrator/SKILL.md — 任务进入队列后的提交、监控、转向、暂停/恢复/重放以及超过 2 分钟操作的持久化执行阶梯skills/cron-scheduler/SKILL.md — 调度层面的指导错峰、静默时段、幂等现已引用本约定skills/migrations/v0.11.0.md — GBrain 如何将现有主机 cron 清单迁移到本约定含十项 skillify 门槛docs/guides/plugin-handlers.md — 主机自定义 handler 的完整插件契约、MinionJobContext字段说明与信任边界handler 代码以 worker 进程权限运行无运行时沙箱按生产代码标准评审。【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考