gbrain Doctor 自动修复与评分体系改进：从误报噪声到可观测健康基线

gbrain Doctor 自动修复与评分体系改进从误报噪声到可观测健康基线【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbraingbrain doctor是 GBrain 大脑健康检查的核心命令它聚合数十项检查嵌入覆盖率、提取质量、同步新鲜度、多源漂移、frontmatter 完整性、矛盾探测等并输出健康评分。本篇技术指南基于仓库中的docs/issues/doctor-auto-heal-and-scoring.md设计文档系统讲解该健康检查体系存在的七类误报与能力缺口并给出包括严重级别分级、时间感知矛盾判定、漂移基线、自动修复auto-heal、评分历史追踪与阈值加权在内的完整改进方案。读完本文你将掌握 GBrain 健康检查体系的内部评分机制、各项检查的命令行入口与修复命令以及如何通过配置和.gbrain状态文件把一次性的健康快照升级为可持续观测、可自动修复的运维闭环。背景健康评分体系的误报与缺位GBrain 的gbrain doctor命令在 src/commands/doctor.ts 中实现会执行数十项检查并汇总为健康评分。从该文件的实现看评分机制基于罚分制每项检查的状态分为ok/warn/fail其中fail扣 20 分、warn扣 5 分最终health_score取max(0, 100 - 罚分)见 src/commands/doctor.ts。同时doctor 还会输出一个独立的brain_score——它衡量的是大脑数据构成质量由五个分量加权合成嵌入覆盖35 分、链接密度25 分、时间线密度15 分、孤立页15 分、死链10 分并在总分低于 70 时给出warn见 src/commands/doctor.ts。此外还区分brain_checks_score大脑类目下检查失败数的扣分与category_scores按类目分别计算的分值避免单一数字被某类噪声污染。这套体系的问题在于大量检查确实发现了问题、但问题要么是噪声、要么无法人工修复的情况会让 doctor 常年处于 WARN 状态真正重要的异常反而被淹没。以下七个改进项按影响力排序逐一展开。一、Frontmatter 严重级别分级让 96% 的噪声不再淹没真问题问题定义frontmatter 检查frontmatter_integrity报告的问题中NESTED_QUOTES占了压倒性多数。文档给出的实测证据显示一次检查共报告 7,131 个问题分布如下frontmatter_integrity: 7131 issues across 3 sources default: 7012 (NESTED_QUOTES6922, YAML_PARSE90) media-corpus: 16 (MISSING_OPEN15, YAML_PARSE1) zion-brain: 103 (MISSING_OPEN14, NESTED_QUOTES89)其中真正需要处理的问题只有 280 个约 4%其余 96% 都是NESTED_QUOTES这类外观性 YAML 风格问题——例如title: foo这种引号在技术上并非必需。它们不影响同步、搜索、嵌入或任何功能但当前实现把它们与真正的解析失败YAML_PARSE或缺少数值定界符MISSING_OPEN等同计权导致 frontmatter 检查永远处于 WARN真实问题反而被淹没。从源码侧看frontmatter 验证的完整错误码集合在 src/commands/frontmatter.ts 中定义为MISSING_OPEN、MISSING_CLOSE、YAML_PARSE、SLUG_MISMATCH、NULL_BYTES、NESTED_QUOTES、EMPTY_FRONTMATTER。该文件提供的gbrain frontmatter validate子命令会按错误码分组统计每源数量既可用于 CI也可作为 doctor 的输入见 src/commands/frontmatter.ts。改进方案引入严重级别errorYAML_PARSE、MISSING_OPENvsinfoNESTED_QUOTESdoctor 的 WARN/FAIL 判定只依据 error 级问题info 级问题仅在消息文本中报告不影响检查状态增加可选--pedantic参数将 info 级问题纳入状态判定。测试用例Frontmatter issues严重级别分解期望状态0 个问题无OK仅 50 个 NESTED_QUOTES0 error, 50 infoOK附带说明3 个 YAML_PARSE3 errorWARN6900 NESTED_QUOTES 3 YAML_PARSE3 error, 6900 infoWARN提及 3 个 error这套分级把噪声占比与状态判定解耦配合--pedantic又能让严格模式下的 CI 依然能拦住 style 级问题。二、时间感知的矛盾判定把演化从矛盾中解放出来问题定义矛盾探测contradiction probe会把时间上的演化误判为矛盾。典型场景页面 A4 月“正在考虑方案 X”页面 B5 月“已决定采用方案 Y”这并非矛盾而是同一主题随时间推进的演化。但探测逻辑缺乏时间意识。文档给出的实测数据显示在 50 个查询、top-k15 的一次探测中共检出 120 条矛盾112 条 high、8 条 medium人工复核后发现约 60% 属于时间演化而非真实冲突。而页面本身带有effective_date或created时间戳完全可以用来消歧。源码侧的证据时间感知矛盾判定并非空想——GBrain 的矛盾评估基础设施已经为此预留了接口。在 src/commands/eval-suspected-contradictions.ts 中探测器的判定类型已经是六分类no_contradiction、contradiction、temporal_supersession、temporal_regression、temporal_evolution、negation_artifact并且探测时会把effective_date传给判定侧。在 src/core/eval-contradictions/auto-supersession.ts 中实现会在双方都带日期且 claim 重叠时比较effective_date大小并生成temporal_supersession决议旧页面被新页面取代。该文件还定义了 verdict 驱动的路由temporal_supersession表示后发声明取代先发声明、temporal_regression表示回退、temporal_evolution表示演化见 src/core/eval-contradictions/auto-supersession.ts。文档中还提到该能力已在 PR #993 中设计核心思路是将effective_date/created传入 judge prompt新增temporal_supersession判定当双方都有日期且声明重叠时倾向时间解释。测试用例页面 A 日期页面 A 声明页面 B 日期页面 B 声明期望判定2026-04“Considering X”2026-05“Chose Y”temporal_supersession2026-04“Revenue is $1M”2026-04“Revenue is $500K”contradictionnull“X is true”null“X is false”contradiction2025-01“CEO of Company”2026-01“Former CEO”temporal_supersession值得注意只有当两个页面都有日期且日期不同时才偏向时间解释无日期或同日期的冲突仍按 contradiction 处理——最后一行CEO → Former CEO的案例说明时间解释能正确处理职业状态的合理变化。三、多源漂移基线承认已知不可修复的 4,791 个页面问题定义约 4,791 个页面被标记为多源漂移multi-source drift根因是 v0.30.3 之前的一个putPage路由 bug这些页面存在于default源但本应归属于某个命名源。用于修复该问题的sources rehome命令尚未发布因此每次 doctor 运行都会对约 4,800 个无人能修复的页面持续报 WARN。改进方案允许通过doctor.baselines配置声明已知不可修复的计数基线doctor: baselines: multi_source_drift: 4800当实际漂移数 ≤ 基线时判定为 OK超过基线时才 WARN表示出现了新的漂移。同时将基线持久化到.gbrain/doctor-baselines.json使无配置文件场景也能生效{ multi_source_drift: { count: 4800, acknowledged_at: 2026-05-15, reason: pre-v0.30.3 putPage misroutes } }源码侧的证据多源漂移检查在 src/commands/doctor/schema-pack-checks.ts 中实现其中multiSourceDriftAdvice(count, sampleStr)负责生成修复建议文案该文件注释明确说明早期文本曾指向gbrain sources rehome但该命令从未发布因此建议文本已更正见 src/commands/doctor/schema-pack-checks.ts。此外multiSourceDriftGitRootSkipNote用于标注因slug_root_modegit-root而跳过漂移遍历的页面见 src/commands/doctor/schema-pack-checks.ts这类页面被钉在 git 根目录模式下本就不应参与漂移判定。multi_source_drift检查项也在 src/commands/doctor/report-remote.ts 中被消费说明它同样出现在远程报告路径中。测试用例实际漂移基线期望结果47914800OK49004800WARN“比基线多出 100 个新漂移”47910无基线WARN当前行为基线机制的本质是把已知历史存量与新出现的回归分离存量只记录、不报警新增量才触发告警。四、图片资产确认为故意外置的图片提供出口问题定义当图片文件从磁盘缺失存于外部存储、或被 git 清理时doctor-asset-paths检查会永久性 WARN且没有任何方式声明这些图片是有意外置的。检查逻辑在 src/commands/doctor-asset-paths.ts 中实现。改进方案doctor --acknowledge image_assets将当前缺失数量标记为已接受接受记录存储在.gbrain/doctor-baselines.json中只对超出已接受数量的新增缺失图片报 WARN可选配置image_assets.external_storage: true直接跳过磁盘检查doctor: image_assets: external_storage: true该方案与多源漂移基线共用同一持久化文件形成了统一的acknowledge 基线心智模型先确认存量再关注增量。五、Auto-Heal 自动修复模式让可修复的 WARN 不再需要人工问题定义许多 doctor 警告都有已知的、可安全自动应用的修复方案但当前每次都需要运维人员手动执行。自动修复映射表警告自动修复Supervisor 未运行启动 supervisor嵌入过期stale embeddings提交embed --stale任务提取覆盖率 70%提交extract all --skip-existing任务同步过期提交 sync 任务生效日期漂移运行reindex-frontmatter这些修复命令在当前仓库中均可找到对应实现gbrain embed --stale在 src/commands/embed.ts 中被推荐为外部调度器的常规组合gbrain sync ... gbrain embed --staledoctor 的 embeddings 检查在 src/commands/doctor.ts 中会直接给出 Run:gbrain embed --stale 的建议reindex-frontmatter是独立的 CLI 命令注册于 src/cli.tsdoctor 的生效日期检查在 src/commands/doctor.ts 中会提示运行它来重算。也就是说本文档设计的 auto-heal 实际上是把这些散落在各检查消息里的人工建议编排成自动提交任务。改进方案doctor --auto-heal模式先运行全部检查对可修复的 WARN以**任务job**形式提交修复而非内联执行——统一走任务队列保证可观测、可重试报告哪些已被修复、哪些仍需人工处理幂等先检查队列中是否已有相同任务避免重复提交安全闸门绝不自动修复 FAIL 级问题只处理 WARN。配置文件示例doctor: autoHeal: enabled: true minInterval: 6h skip: - image_assets - multi_source_driftminInterval: 6h用于限制自动修复频率skip列表则把需要人工决策的检查排除在自动修复之外。测试用例检查状态Auto-heal 开启任务已排队期望行为WARN: 嵌入过期是否提交 embed 任务WARN: 嵌入过期是是跳过幂等FAIL: max_crashes是不适用不自动修复 FAILWARN: 嵌入过期否不适用仅报告WARN: image_assets是但在 skip 列表不适用仅报告修复即任务的设计是这一方案的关键自动修复不绕过任务队列因此修复过程可以被监控、限流和审计而skip白名单与minInterval共同保证自动修复不会失控。六、评分增量追踪从快照到趋势问题定义当前每次doctor运行都只是一次独立快照没有历史记录无法判断健康分是在改善还是恶化。改进方案每次运行追加写入.gbrain/doctor-history.jsonl{ts:2026-05-15T12:00:00Z,score:60,brain_score:79,checks:{supervisor:ok,embeddings:ok,...}}doctor --trend展示最近 N 次的分数与增量deltadoctor --json在输出中附带previous_score和delta字段。这条改进与现有--json输出直接兼容。doctor 的 JSON 输出已有稳定的 schemaschema_version2见 src/commands/doctor.ts其中包含health_score、brain_checks_score、category_scores等字段本文档方案是在此基础上增加时间维度让监控工具可以直接消费。--json输出的两个分数口径需要区分health_score是检查类目层面的扣分制总分brain_score是 35/25/15/15/10 加权的大脑数据质量复合分见 src/commands/doctor.ts二者在历史记录中应分别存储因为它们的含义不同、变化模式也不同。七、阈值加权评分让最后一公里被正确衡量问题定义当前评分下嵌入覆盖率从 99% 提升到 100% 的权重与从 50% 提升到 51% 完全相同。但事实上最后 1% 的难度远大于前 50 个 1%——超长页面、限流等因素使得高覆盖率的边际成本极高。改进方案基于阈值的分段评分100% 满分≥95% 获得 90% 的分值≥80% 获得 70% 的分值80% 按比例线性计分例如嵌入覆盖分项满分 35 分brain_score的组件之一若覆盖率为 97%则得 31.5 分而非按 97% 线性折算的 33.95 分——这样既奖励高覆盖又不会让 99% 与 100% 的差距造成与 50% 与 51% 同样大的分值差异分数变化更符合实际改进难度。该改动仅影响评分算法层不影响任何检查的 OK/WARN/FAIL 判定因此风险面极小可作为低优先级的锦上添花项。优先级与实施路线按设计文档给出的顺序改进项的实施优先级如下Frontmatter 严重级别分级——噪声消除收益最高96% 的误报直接消失时间感知矛盾判定——误报消除收益最高且已在 PR #993 中完成设计、当前仓库的六分类判定基础设施src/core/eval-contradictions/auto-supersession.ts已经就位Auto-Heal 模式——长期价值最大把 doctor 从诊断工具升级为诊疗工具评分增量追踪——为监控与趋势分析提供数据基础多源漂移基线——生活质量改进消除约 4,800 个无法修复的常驻 WARN图片资产确认——生活质量改进与漂移基线共用同一持久化机制加权评分——锦上添花风险最低。总结从诊断快照到健康闭环gbrain doctor健康检查体系改进的核心方向是三个维度降噪通过严重级别分级frontmatter与时间感知判定矛盾探测把风格问题和时间演化从真正的故障中剥离可管理通过.gbrain/doctor-baselines.json基线机制多源漂移、图片资产承认历史存量让告警只对新增回归生效自动化与可观测通过 auto-heal 任务编排、.gbrain/doctor-history.jsonl趋势追踪与阈值加权评分让健康检查从一次性的快照进化为可持续观测、可自动修复的运维闭环。这套改进体系完全围绕 GBrain 的既有架构展开检查实现位于 src/commands/doctor.ts 及其剥离出的 src/commands/doctor/ 模块树矛盾判定基础设施在 src/core/eval-contradictions/ 中已预留 verdict 扩展点修复命令embed --stale、extract all --skip-existing、reindex-frontmatter全部存在且已被检查消息引用。任何下游 Agent 或运维人员都可以依据本文档中每个改进项附带的测试用例表验证实现是否满足预期行为。【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考