gbrain 校准回路（Calibration Loop）开发规范与实践指南

gbrain 校准回路Calibration Loop开发规范与实践指南【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbraingbrain 是一个将「预测性 Take观点/判断」沉淀为可回溯战绩的 AI 大脑它记录你的每一次判断事后用证据裁决对错再根据你的实际命中率反哺到后续每次输出。本指南基于仓库内的 校准回路开发规范结合源码与测试完整讲解校准波calibration wave的五大触点touchpoint、四个 doctor 检查、自动裁决auto-resolve策略、跨脑读取语义D18与测试接缝帮助你在该代码库中新增校准相关功能时选对路径、避开已知的 Bug 类v0.34.1 源码隔离泄漏。校准回路是什么v0.36.1.0校准波的核心思想一句话可概括大脑知道你的历史战绩并且会使用它。它不是一次性计算 Brier 分数就结束的静态报表而是一条持续运转的回路propose_takes周期阶段从对话、会议、日常记录中提取新的 Take带有置信度与权重的主观判断一段时间后默认 6 个月以上grade_takes阶段从大脑中检索证据让判官模型judge model给出correct / incorrect / partial / unresolvable的裁决calibration_profile阶段基于大量已裁决 Take 生成校准画像Brier 分数、各领域命中率、模式总结校准画像反哺到五个面向用户的输出表面模式陈述、实时轻推、预测简介、仪表盘说明、晨间脉冲全程经过语音门voice gate把关措辞。在代码库中三个周期阶段统一继承 BaseCyclePhasepropose_takes、grade_takes、calibration_profile三个新阶段共用一套骨架底层数据表定义在 schema.sql用户侧命令入口是 calibration.ts。五个触点Touchpoints在哪里下手规范文档用一个对照表定义了「你在做什么 → 该用哪个机制」。这张表是新增功能时最常用的决策入口原样保留并补充细节你正在做的……应该这样做新增一个「大脑向用户告知某事」的建言表面advice surface用 gateVoice() 做语音把关从五种模式中选一pattern_statement、nudge、forecast_blurb、dashboard_caption、morning_pulse。只有五种都不合适时才新增模式——那时需要同时扩展 VOICE_GATE_MODES 与 DEFAULT_RUBRICS。编写关于用户历史战绩的用户可见文案口语化而非学术腔像朋友不像医生。用具体数字2 of 3 missed而非抽象指标Brier 0.31。永远不要写 according to your data 这类措辞。详见 DESIGN.md 的 voice 章节。新增一个周期阶段cycle phase继承 BaseCyclePhase天然获得源码作用域透传 预算计量 错误信封 进度上报四件套。必须声明budgetUsdKey与budgetUsdDefault。新增一个读取 source-scoped 数据的 MCP 操作经由 sourceScopeOpts(ctx) 路由。BaseCyclePhase在类型层面强制该透传手工编写的 MCP 处理器必须显式做同样的事。为校准相关新表写 schema每一行都盖上wave_version TEXT NOT NULL DEFAULT v0.36.1.0或当前波次版本号。--undo-wave命令依赖wave_version精确回滚。在 test/fixtures/calibration/ 下新增测试夹具页面只能用合成数据并使用规范化的占位名称alice-example、acme-example、widget-co、fund-a/b/c、meetings/2026-04-03。CI 守卫脚本 scripts/check-synthetic-corpus-privacy.sh 会拦截违规。语音门五个表面、一道闸voice-gate.ts 的模块头注释点明了设计初衷D24五个校准 UX 表面全部导入同一个gateVoice()函数模式相关的调优全部放在门内发给 Haiku 判官的模式 rubric 里而不是分叉成五份各自演进的实现——分叉会让语音 rubric 漂移修好一个表面漏掉另外四个。gateVoice的调用形态来自 VoiceGateOptsgateVoice({ mode: nudge, // 五种模式之一驱动 rubric 调优 generate: async ({ attempt, feedback }) candidateText, // 每次生成一个候选 templateFallback: { fn: nudgeTemplate, slots: { ... } }, // 两次重生成都失败时的兜底 maxAttempts: 2, // 默认 2D11 决策 judge: opts.voiceGateJudge, // 测试注入桩生产走 Haiku rubric: override text, // 极少需要覆盖 })失败回退策略D11值得注意最多重生成 2 次仍不过就回退到 templates.ts 中手写的模板——静默隐藏表面永远不被允许那会让语音质量无声劣化。每次失败都会记录到calibration_profiles行voice_gate_passedfalsevoice_gate_attempts供操作者复盘调优 rubric。模板天然带一点机器人腔是可接受的用户连续两次看到相同形状而不是随机劣化的语音真正口语化的声音来自 LLM 路径。五种模式各自的 rubric 在 DEFAULT_RUBRICS 中逐条可见共同约束是第二人称、具体数字优先于内部字段名禁止不翻译地提 Brier、conviction-bucket、严禁说教与我们建议式措辞、控制字数模式陈述 25 词、nudge 30 词、晨间脉冲 25 词。判官输出解析在 parseJudgeOutput 中实现对 JSON 围栏包裹和前导散文有容错无法恢复的解析失败按academic处理reasonparse_failed让门回退到模板而不是静默放过坏语音。何时向用户弹出校准警告四个 doctor 检查doctor/checks/calibration.ts 中集中了四个校准相关的 doctor 检查规范文档要求开发者在决定该不该弹警告之前先搞清每个检查的定位abandoned_threads信息性统计weight 0.7且已超过 12 个月、既未被取代superseded也未关联后续页面的高置信度 Take。实现见 checkAbandonedThreads永远返回 statusok 只带计数——这是信号而非错误。SQL 中since_date是 TEXT 且可能是月精度YYYY-MM转日期前先归一化补-01避免invalid input syntax for type date这一处理必须与gbrain calibration的 abandoned-threads 明细保持一致。calibration_freshness警告活跃校准画像超过 7 天未更新则告警提示运行gbrain calibration --regenerate。实现见 checkCalibrationFreshness。注意 holder 通过emotional_weight.user_holder配置解析默认self多源大脑每个 source 一行检查取所有 source 中的最新一条。grade_confidence_driftCDX-11 缓解占位v0.37 才会落地「置信度 vs 准确率」相关性数学。当前版本只报告自动应用裁决的计数与 drift math arrives in v0.37 状态见 checkGradeConfidenceDrift。实现里已经预留了applied 30才进入漂移检测的门槛——数学到位前不要在这里加噪音阈值。voice_gate_health警告最近 7 天语音门失败率 ≥ 30% 时告警提示复查 voice-gate.ts 的 rubric。实现见 checkVoiceGateHealth直接统计calibration_profiles行中voice_gate_passedfalse的占比。自动裁决Auto-resolve姿态与单调收紧规范文档D17/D12的关键结论自动裁决默认关闭。操作者信任判官裁决后才通过配置显式打开cycle: grade_takes: auto_resolve: enabled: true在 grade-takes.ts 的process()中可以看到默认值autoResolve opts.autoResolve ?? falseD17 默认关、autoResolveThreshold 0.95D12 保守阈值。开启后按两条路径判定是否自动应用到规范 takes 表单模型路径confidence 0.95集成ensemble路径3/3 全员一致 且 最低置信度 0.85。ensemble 聚合逻辑在 aggregateEnsemble 中实现——平局时unresolvable输给任何其他标签其余按字母序确定性裁决minConfidence取投中获胜标签的模型中的最小值。unresolvable永不自动应用即使 confidence1.0。这在 verdictToResolution 中有结构保证unresolvable直接返回null根本不会产生 resolution。集成触发带ensemble trigger band默认[0.6, 0.95)单模型置信度落在这个区间且非 unresolvable 时触发三模型平局裁决器默认openai:gpt-5.2、anthropic:claude-sonnet-4-6、google:gemini-2.5-flash通过Promise.allSettled并行调用。这些阈值是只允许单调收紧的MONOTONIC TIGHTENING ONLY。配置 schema 会拒绝任何在没有显式--allow-loosen-confidence标志的情况下降低活跃阈值的尝试——因为数据累积之后放宽阈值会静默改变哪些历史裁决算作自动应用从而扭曲后续的置信度-准确率统计。跨脑读取语义D18本地优先、挂载回退、归因、子代理禁止当你在多脑mounted brains如团队脑架构下读取校准画像时cross-brain.ts 实现了 D18 的四条铁律四条规则被 test/cross-brain-calibration.test.ts 钉死本地优先Local first先查本地脑。本地有就直接返回不再查询挂载——避免陈旧挂载覆盖新鲜本地。queryAcrossBrains 中先getLatestProfile(localEngine, ...)。挂载回退Mount fallback仅当本地为空且canReadMountsForCtx(ctx)返回 true 时才回退挂载侧的行还必须满足publishedtrue作者脑通过发布位控制可见性D15 非对称 opt-in。跨脑归因Cross-brain attribution返回的画像携带source_brain_idfrom_mountUI 消费者必须向用户呈现 from mounted brain: X。归因后缀由 attributionSuffix 生成——本地命中返回空串默认即本地挂载命中返回(from mounted brain: id)。子代理禁止Subagent prohibitionctx.viaSubagent !allowedSlugPrefixes的上下文不能读挂载——子代理循环只能看到本地脑。受信任工作区trusted-workspace的周期阶段synthesize/patterns传入非空allowedSlugPrefixes集合则被放行。判定函数 canReadMountsForCtx 的精确语义本地 CLIremotefalse永远放行子代理工具循环viaSubagenttrue只有当allowedSlugPrefixes非空才放行MCP 常规 OAuth 作用域读取放行。这样设计的原因写死在注释里子代理上下文正是 OAuth 令牌跨脑泄漏的暴露面。测试接缝禁止绕过、禁止直呼 gateway每个校准模块都通过 opts 接受测试注入opts.judge/opts.thinkRunner/opts.extractor/opts.evidenceRetriever——证据检索在 grade-takes.ts 的defaultEvidenceRetriever中默认走真实混合检索hybrid searchexpansion 关闭、源码作用域透传、排除 Take 自身页面测试时注入桩。opts.voiceGateJudge——绕过 Haiku 调用生产默认判官见 defaultJudge走TIER_DEFAULTS.utility模型、maxTokens100。opts.preferenceResolver——绕过 A/B 测试台中的交互式提示。规范文档强调测试必须使用这些接缝。校准单元测试中绝不直接调用gateway.chat——那违反测试隔离 R2 规则通过mock.modulemock gateway 模块会在分片进程内跨文件泄漏。要避开的 Bug 类v0.34.1 源码隔离泄漏校准波的结构性防御目标是 v0.34.1 的源码隔离泄漏这一经典 Bug 模式。四层防御在文档和源码中一一对应BaseCyclePhase在类型层面强制sourceScopeOpts(ctx)透传——子类无法直接读ctx.engine忘记透传源码作用域会直接变成 TypeScript 编译错误而非运行时泄漏见 base-phase.ts 的设计说明每个新 schema 表都有source_id NOT NULL REFERENCES sources(id)见 schema.sql 中校准相关建表语句跨脑读取统一走canReadMountsForCtx()分类器测试在 test/cross-brain-calibration.test.ts 钉死全部 4 条 D18 规则。文档给出了一条可操作的自我检查如果你发现自己在校准模块里写ctx.engine.executeRaw(...)却没有经过sourceScopeOpts你就找到了这个 Bug。停下来改走 helper。数据库契约与波次回滚所有校准相关表行都带wave_version戳这是--undo-wave精确回滚的基石。schema.sql 中可以确认calibration_profilesL1452、take_grade_cacheL1520、take_nudge_logL1542等表均声明wave_version TEXT NOT NULL DEFAULT v0.36.1.0且take_grade_cache、take_nudge_log建了(wave_version, ...)前缀索引。gbrain calibration --undo-wave version的实现在 undo-wave.ts四步回滚语义回滚自动应用的 Take 裁决以take_grade_cache中appliedtrue且wave_version匹配的行定位目标take_id仅当takes.resolved_by gbrain:grade_takes该波的自动评级标签时才把resolved_at / resolved_outcome / resolved_quality等列置 NULL——人工裁决如resolved_bygarry保留操作者意图不被覆盖删除该波的calibration_profiles行DELETE WHERE wave_version ?清空该波的take_nudge_log行同样的条件删除可选清洗 gstack learnings传--scrub-gstack时调用gstack-learnings-prune若在 PATH 上删除该波写下的学习条目best-effort失败只记警告不阻断其余步骤。回滚具备幂等性--undo-wave重跑时没有匹配行即为 no-opdryRun: true只计算数量不写库返回与真实回滚相同的 UndoWaveResult 结构操作者能先看到将会回滚什么。实操速查校准画像过期 →gbrain calibration --regeneratecalibration.ts 定义的子命令语义回滚一个波次 →gbrain calibration --undo-wave v0.36.1.0L155 参数解析、L183 动态导入实现新增校准夹具 → 只放合成数据用alice-example、acme-example、widget-co、fund-a/b/c、meetings/2026-04-03占位名现有夹具目录结构见 test/fixtures/calibration/跑 CI 守卫 scripts/check-synthetic-corpus-privacy.sh新增周期阶段 → 继承BaseCyclePhase声明budgetUsdKeybudgetUsdDefault所有 LLM 提交前调this.checkBudget(...)所有源码作用域读取走this.scope()新增用户可见的校准文案 → 走gateVoice()先看五种模式里有没有现成的别急着加新模式。【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考