gbrain 测量优先排障法：measure-before-you-fix 技能全解析-平芜编程栈

人工智能
RAG
Agent 记忆
MCP 服务
知识管理

【免费下载链接】gbrain

Garry's Opinionated OpenClaw/Hermes Agent Brain

项目地址：https://gitcode.com/gh_mirrors/gb/gbrain

本文聚焦 gbrain 仓库中measure-before-you-fix技能（位于 plugin-variants/gbrain-coding/skills/measure-before-you-fix/SKILL.md，主技能位于 skills/measure-before-you-fix/SKILL.md）的核心思想与完整操作流程。该技能面向所有"时间类"运维告警（数据陈旧、超时、卡死、进度落后等），规定在任何超时上调、阈值修改或管道重写之前，必须先用手表亲自测量被指控的步骤。读完本文，你将掌握一套"秒表优先于改动"的运维排障纪律：如何定位精确测量对象、如何对比测量值与预算值、如何识别阈值错配这一高频故障模式，并学会输出标准化的测量结论（Measurement Verdict）。

一、技能定位：它是谁，服务于哪些告警

measure-before-you-fix是 gbrain 技能体系中一个只读（mutating: false）、不写脑页（writes_pages: false）的排障守门技能。其 frontmatter 中upstream: measure-before-you-fix@fc834ee表明它与上游版本保持对齐。技能的触发词覆盖了运维中常见的"时间类"抱怨：

triggers: - "keeps timing out" - "ETIMEDOUT" - "why is this data stale" - "freshness alert" - "wedged" - "job is slow" - "sync is stuck" - "raise the timeout"

凡是告警的断言是时间性的——"X 陈旧"、"步骤超时"、"管道卡死"、"任务缓慢"、"落后 N 小时"——就应路由到此技能。这类告警天然引诱排障者立刻做结构性修复（调高超时、拆分步骤、重排管道），而技能的核心主张是：先测量，再动手。测量几乎总是比修复便宜，而且常常直接推翻修复方案。

在 gbrain 的具体表面上，本技能覆盖的告警来源包括：

gbrain doctor的陈旧性检查（如 sync freshness、cycle freshness）；
autopilot 周期告警；
sync 停滞看门狗（reason: 'stall_timeout'）；
以及构建在这些机制之上的任何 cron 监控。

二、核心规则与契约

规则

在被指控的步骤上进行一次秒表测量，然后再做任何代码改动。

如果一个人无法说出他声称"很慢"的那个东西的实测耗时，那么他还不了解根因，此时写出的任何修复都只是"披着 diff 外衣的猜测"。

契约（该技能承诺的保证）

结构性修复前置测量：任何结构性修复（超时上调、步骤拆分、管道重排、包装脚本重写）在提出之前，必须存在对被指控步骤的实测耗时。
精确到实体：测量必须针对告警点名的具体实体，而非聚合体——--all会掩盖到底是哪个成员慢。
阈值对齐校验：在宣布系统不健康之前，必须将告警阈值与权威阈值（gbrain doctor的 warn/fail 行）进行对比。
结论二选一明确区分：结论必须明确区分"需要更多时间"与"真的卡死了"——二者修复方向相反。
只读承诺：本技能不改任何超时、阈值或代码，只产出测量结论；修复本身是另一项"现在已被告知信息"的独立改动。

三、五步操作流程（Procedure）

第 1 步：先读告警自身的数字

告警里自带的数字往往已经与你的理论矛盾。例如Locks: none意味着不是锁竞争——记下这一点，直接剪掉这条排查分支。告警对症状报告得准确，但对原因的归因常常是错的。

第 2 步：直接对可疑步骤计时

把告警所指向的最小单元隔离出来，用时钟跑一遍：

time gbrain sync --source source-a --no-embed

关键点在于针对具体被点名的实体运行，而不是聚合体。全脑运行会掩盖哪个成员慢；--source source-a才能回答问题。--no-embed跳过嵌入计算，让"导入/同步"这一步本身的耗时独立可见（该标志在 src/commands/sync.ts 与 src/commands/import.ts 中解析）。随后用gbrain sources status交叉核对状态——这是 v0.40 引入的按源仪表盘（sync lag、embed coverage），其入口注册在 src/cli.ts，实现位于 src/commands/sources.ts。

第 3 步：对比测量值与预算值

不要只看辅助函数签名里的默认值，要把包装脚本或 cron 脚本里每一个超时都 grep 出来：

grep -n "timeoutMs\|timeout:" <the wrapper or cron script>

一个慷慨的按调用点覆盖参数，会让辅助函数的默认值变得无关紧要——在责怪默认值之前，先检查调用点。

第 4 步：用权威阈值校验告警阈值

在断定系统坏了之前，先确认告警器与审计者对"什么算坏"的口径一致。gbrain doctor的 sync-freshness 检查默认是24h warn / 72h fail，可通过环境变量GBRAIN_SYNC_FRESHNESS_WARN_HOURS/GBRAIN_SYNC_FRESHNESS_FAIL_HOURS覆盖。这一实现事实可以在 src/commands/doctor/checks/extraction-sync.ts（阈值注释与_resolveSyncFreshnessHours('GBRAIN_SYNC_FRESHNESS_WARN_HOURS', 24)/('GBRAIN_SYNC_FRESHNESS_FAIL_HOURS', 72)的调用）、src/commands/doctor.ts 与 src/commands/doctor/report-remote.ts 中得到印证。

这些环境变量经由 src/core/env-number.ts 的resolveHoursEnv解析：非法值（NaN、≤0）会回退到默认值并每进程告警一次（见 src/commands/doctor/checks/extraction-sync.ts 的注释说明）。

由此得出结论：一个在 12h 就分页的 cron 监控，实际上是在权威 warn 线之下"发言"。监控在行动线上提前行动是正确的；监控在行动线上开口讲话，则是误报发生器。

第 5 步：只有现在才设计修复

修复必须对着你实测出来的数字设计，而不是对着猜测。

四、高频故障模式：阈值错配（Threshold Mismatch）

cron 监控合理地比 doctor fail 更早行动，目的是防止漂移滑入 FAIL 区域——这是好设计。真正的 bug 是把行动阈值复用为告警阈值：介于"行动"与"warn"之间的所有状态都会变成对健康系统的反复分页。

正确的做法是分离这两个常量：在激进的行行动，在权威的行开口：

const ACT_HOURS = Number(env.MONITOR_ACT_HOURS || 12); // act early — fine const ALERT_HOURS = Math.max(ACT_HOURS, DOCTOR_WARN_HOURS); // speak at the audit's line

要能瞬间识别的症状是：一个重复出现的告警，其数字低于 doctor 自己的 warn 线，而直接查询底层资源时一切正常。

五、你在"空想"而非"诊断"的红旗信号

你有了根因，却没有实测耗时；
你的修复是一次重写，而你没有把该步骤跑过一次；
你在两次修订之间没有重新测量，就修改了两遍理论；
告警声称"没有正在进行的恢复"——在相信它之前先验证恢复是否真的在跑（用ps查看 worker、检查启动标志、用gbrain jobs list查看排队任务）；
步骤输出显示 "Already up to date"——那个步骤根本不是你的瓶颈。

六、反模式清单（Anti-Patterns）

用调高超时来修复卡死（stall）。如果步骤真的挂死了，更大的预算只会让它挂得更久。先测量，再在"需要更多时间"与"真的卡死"之间做决定——二者修复方向相反。
基于未测量的饥饿理论重写管道。为并不存在的饥饿拆分步骤，只会增加表面积，什么也修不了。
相信告警的因果断言。告警对症状报告准确、对原因归因很差：陈旧数字是真实的，附在上面的原因是一个猜测。
把未测量的根因技能化或持久化。一个信心满满但错误的诊断被烘焙进 playbook，比原始 bug 更糟。

关于第 1 条，值得展开的是 gbrain 自身的实现哲学：sync 与 embed 的停滞看门狗天然区分"慢"与"卡死"，它们以"前进进度"（forward progress）而非"墙钟时间"为键。见 src/commands/sync.ts：#1950事件是一起 sync 卡死约 29 分钟但进程"活着"的 incident——锁心跳照常刷新（它按自己的定时器触发）、墙钟截止时间还没到，导致只能手动pkill。修复方案就是这条以导入进度为键的看门狗：若在resolveStallAbortSeconds()秒内没有文件完成，就 abort，且 partial result 报stall_timeout而非timeout，以与用户主动--timeout/SIGINT 区分。embed 侧有同构实现（#4599，见 src/core/embed-stall.ts 与 src/commands/embed.ts）。这正好印证了技能中"needs more time 与 wedged 修复方向相反"的论断——gbrain 原生就在做这件事。

七、已处理的已知故障模式（实战复盘）

新鲜度告警上的三重错误诊断

一个 cron 监控反复对两个源（source-a、source-b）分页，报告它们落后数小时。在任何测量之前，排障者先后断言了三个根因，并批准了一次包装脚本重写。而测量结果如下：

time gbrain sync --source source-a --no-embed # 个位数秒内完成，输出 "Already up to date" time gbrain sync --source source-b --no-embed # 同样如此 gbrain sources status # 所有源当天早上均已同步

所有理论瞬间死亡。真正的原因是：监控在其行动阈值处告警，比gbrain doctor的权威 warn 线低了数小时。修复只有两行（ALERT_HOURS = max(ACT_HOURS, WARN_HOURS)），而不是重写。教训：当一个页面反复报告一个实测健康的系统时，先怀疑阈值，再怀疑系统。

竞争理论推论（同一轮中被抓住）

对一个被降级（nice化）步骤的 CPU 竞争担忧同样毫无根据——在主宿主机处于持续并发负载下时，该步骤数秒内就完成了。竞争理论需要与陈旧理论相同的秒表。

八、输出格式：测量结论（Measurement Verdict）

本技能的输出是会话级的测量结论，不写任何脑页。只有在结论产出之后，才提出针对实测数字规模化的修复方案：

## Measurement verdict - Alert: <the alert text and which monitor emitted it> - Claim: <the temporal claim, e.g. "source-a 14h stale"> - Measured: <exact command> → <duration> (<key output, e.g. "Already up to date">) - Budgeted: <timeout constant + any call-site override, file:line> - Thresholds: monitor act-line <X>h vs doctor warn-line <Y>h → <match | MISMATCH> - Verdict: false page on healthy system | needs more time | wedged | genuine regression - Fix: <the change, justified by the measured number — or "none; adjust the alert line">

这份模板的价值在于：它强制排障者交代测量命令、测量结果、预算值与阈值口径，任何一环缺失都意味着结论尚未成立。

九、技能边界与去重（Dedup）

为避免与其他技能职责重叠，本技能划定了清晰的边界：

相邻技能	职责	与本技能的边界
GStack`investigate`	代码 bug 的系统化调试（"为什么坏了"、500 错误、输出错误）	`investigate`根因定位代码行为；本技能是时间类运维告警（stale/timeout/freshness/wedged）在动任何超时或阈值之前的测量门。若秒表确认了真实缓慢或回归，带上实测数字移交给`investigate`
skills/maintain/SKILL.md	运行脑健康检查与修复（doctor、extraction、dream cycle）	`maintain`产出并作用于健康输出；本技能规定当其中某项检查分页时、在改预算或包装脚本之前应如何响应
smoke-test（宿主机侧）	二进制重启后的健康检查与自动修复	smoke-test 回答"重启后是否存活"；本技能回答"这条慢/陈旧断言是否为真"
skills/cron-scheduler/SKILL.md	调度监控与任务	cron-scheduler 决定监控何时运行；本技能提供其阈值必须编码的 act-line 与 alert-line 规则
skills/conventions/test-before-bulk.md	批量写入前的试运行	同一精神（先证据后行动），不同对象：该约定门控批量写入；本技能门控超时/阈值/管道变更

此外，技能的 frontmatter 中引用了 conventions/brain-first.md（同名副本存在于 plugin-variants/gbrain-coding/skills/conventions/brain-first.md、plugin/skills/conventions/brain-first.md 与 plugin-variants/gbrain-daily/skills/conventions/brain-first.md）：在重新推导诊断之前，先在脑中search同一告警的历史事件——重复出现的告警通常已有记录的结论。

十、为什么这条纪律在 gbrain 上成立

把技能与实现对照，可以看到 gbrain 为"测量优先"提供了完整的基础设施：

权威阈值明确：gbrain doctor的 freshness 检查把 warn/fail 线作为单一事实来源（src/commands/doctor/checks/extraction-sync.ts），并刻意设计为纯 SQL 陈旧性检查（只读sources.last_sync_at，不碰文件系统），让阈值可以被可靠引用；
停滞 vs 缓慢的原生区分：sync 的#1950与 embed 的#4599看门狗都以"前进进度"为键，与技能"needs more time 与 wedged 修复相反"的告诫同构；
精确到源的测量入口：gbrain sync --source <id>与gbrain sources status提供"点名具体实体"的测量能力；
告警输出的复制即修复：doctor 的失败消息内嵌source.id，让gbrain sync --source <id>与用户复制粘贴的内容精确对应（src/commands/doctor/checks/extraction-sync.ts）。