人工智能RAGAgent 记忆MCP 服务知识管理【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址https://gitcode.com/gh_mirrors/gb/gbrain点击查看免费下载将 v0.18 遗留脑库原地升级到最新 schema是 gbrain 历史摩擦最集中的回归点嵌入式 schema 的每次演进都可能让老库卡在旧schema_version上无法前进。本指南以仓库自带的 Claw-test 升级场景 upgrade-from-v0.18 为主线逐步讲解先摸底、再迁移、复检、查数据的完整升级验证路径并结合源码说明迁移链、种子重放与摩擦上报协议背后的实现原理。读完你将掌握一套可复现的升级回归门禁方法并能在升级遇阻时用gbrain friction log把问题精确钉下来供项目方调优。场景解剖一个专门测升级卡死的 Claw-test在 scenario.json 中升级场景被声明为{ kind: upgrade, from_version: 0.18.0, description: Pre-v0.18 brain shape replayed via PGLite SQL dump; migration chain walks forward to LATEST, expected_phases: [doctor.db_checks], seed: seed, brain: brain, oracle: { query: alice, min_results: 1 } }几个关键设计意图kind: upgrade与同目录的 fresh-install 场景 形成对照fresh-install 测从零建库upgrade 测旧库前进两者走的是完全不同的代码路径from_version: 0.18.0明确被测起点harness 会把一个 v0.18 形状的 PGLite SQL dump 重放到全新数据库中模拟你继承了一个别人留下的旧脑库expected_phases: [doctor.db_checks]是断言基线流程跑完后harness 必须从 stderr 捕获到doctor.db_checks进度事件否则判为失败对应 claw-test.ts 中的verifyExpectedPhases逻辑oracle: { query: alice, min_results: 1 }是真相检验迁移完成后查询alice必须命中至少 1 条结果证明升级没有丢数据。场景自带的脑库只有一个页面 brain/people/alice-example.md其 frontmatter 注明该页面与 fresh-install 场景内容相同本场景测的是升级流程而非摄取从而保证两类场景的差异只在于库是怎么来的。升级四步走从摸底到验证任务书 BRIEF.md 给出了四条明确指令这也是任何真实 gbrain 用户升级旧脑库时应遵循的操作顺序。第一步升级前体检——gbrain doctor --json对继承来的旧脑库先运行gbrain doctor --json目的有二一是记录升级前的基线状态二是把旧库本身已有的健康问题与迁移引入的问题区分开。注意观察输出中的 warnings 与 fix-hints——若升级后出现同样的问题说明并非迁移所致若出现新问题则要怀疑迁移链本身。从源码看doctor是 gbrain 的全科体检入口doctor.ts 将检查按类别拆分为 core-health、calibration、queue-jobs、graph-embedding、routing-federation、search-eval、extraction-sync、consolidation-cycle、pglite-worker 等模块最终汇总为一个三元状态status: healthy | warnings | unhealthy;见 doctor.ts。升级场景的验收标准正是基于这个三元模型结果必须是healthy或warnings绝不能是unhealthy。这与 harness 的断言逻辑一致——claw-test.ts 对非healthy/warnings的状态直接判失败。第二步原地升级——gbrain init --pglite带上既有数据库路径执行gbrain init --pglite --path existing-brain-path--pglite明确选择本地 PGLite 引擎对应 init.ts 中的isPGLite分支--path指定数据库文件位置。迁移链会检测库中的旧schema_version然后沿迁移列表一步步前进到最新版本全程无需手工导出再导入。从源码看src/core/migrate.ts 是整个升级的引擎每个迁移是MIGRATIONS数组中的一步最新版本号直接由数组推导LATEST_VERSION MIGRATIONS.length 0 ? …migrate.ts执行时先对比当前schema_version与LATEST_VERSION打印形如Schema version ${current} → ${LATEST_VERSION} (${pending.length} migration(s) pending)的进度migrate.ts每个迁移在事务内运行成功才提交并回写schema_version失败则回滚、版本停留在原值migrate.ts——这是失败不产生半迁移状态的保障。另外 init.ts 中有几个对升级场景至关重要的行为--migrate-only走纯 schema 升级路径、完全不触碰既有配置init.ts--force重新初始化时若未显式指定引擎会保留已配置的引擎init.ts避免把 postgres 配置静默改写成 pglite 而孤立掉原有数据。第三步升级后复检——gbrain doctor --json迁移完成后再跑一次体检验收标准同上status必须为healthy或warnings永远不应出现unhealthy。两次体检的对比是迁移干净的直接证据第一次发现的问题应当被迁移解决或至少不恶化。第四步数据可用性验证——gbrain query alicegbrain query alice这一步验证的不只是表还在而是检索仍能命中旧数据升级前已入库的内容例如people/alice-example.md这条 person 页面在迁移后必须可被查询到。这正是 scenario.json 中oracle: { query: alice, min_results: 1 }的由来——若查询结果为空说明迁移链虽跑通但数据或索引出了问题同样算回归。摩擦上报协议把升级痛点钉下来任务书特别强调迁移步骤是全项目历史痛苦最高的回归点。因此升级验证过程中任何令人困惑、缺失、意外或错误的情况都应通过摩擦日志上报gbrain friction log --severity {confused|error|blocker|nit} --phase which-step --message what-happened [--hint what-could-be-better]若某一步顺利通过同样可以上报 delight——项目方正在把升级流程调优到零摩擦。从 src/commands/friction.ts 的实现看该命令带有完整的类型约束与五个子命令类型校验--kind只能是friction | delight | phase-marker | interrupted--severity只能是confused | error | blocker | nitfriction.ts非法值直接报错并以退出码 2 结束必填参数--phase与--message缺一不可friction.ts--hint可选但强烈建议填写怎样做会更好五个子命令log追加一条记录、render将一次运行渲染为 Markdown 或 JSON--json控制格式Markdown 默认开启--redact脱敏、list按运行列出计数、summary并排展示 friction 与 delight 汇总、diff对比两次运行或两个 agent之间各自独有与共有但变化的条目来源标记harness 场景中写入时source: claw便于区分真人上报与自动化 harness 上报。值得留意的是上报入口本身是降级可用的即使升级失败、数据库处于半迁移状态摩擦记录仍能正常写入不会因为库坏了而丢失库坏了这个证据。常见升级摩擦模式与排查要点任务书点名的四个高频摩擦模式对应四条排查线索迁移链在某个具体 schema 版本失败——务必同时记录失败时的schema_version与报错信息。由于每个迁移在独立事务中执行见上文 migrate.ts失败迁移不会污染其他步骤修正后重试是安全的Doctor 标出问题但 fix-hint 不可执行——上报时在--hint里写清你期望的可执行建议这类反馈直接驱动 doctor 修复提示的优化gbrain init --pglite没认出既有脑库——检查--path是否指向真实存在的 PGLite 文件以及数据库目录是否被--force等参数误伤需要手工 SQL 才能解卡——任何必须手写 SQL 的情况都是迁移链设计缺陷的信号应作为blocker级摩擦上报。种子机制升级场景如何造出一个真实旧库升级场景无法像 fresh-install 那样凭空建库——它必须有一个真实的 v0.18 形状数据库来触发迁移链。这正是 seed/README.md 讲述的内容。当前仓库中该目录仅是脚手架占位dump.sql尚不存在场景在测试门禁上按 fresh-install 行为处理v1.1 将放入真实 dump。制作真实种子的标准流程检出 v0.18 版本源码git checkout v0.18.0用gbrain init --pglite --path /tmp/v0.18-seed.pglite对小规模 fixture 脑库初始化用gbrain import fixture-brain灌入数据将 PGLite 以 SQL 形式导出通过executeRaw(SELECT * FROM pg_dump(...))扩展、直接拷贝文件或pglite-tools dump /tmp/v0.18-seed.pglite dump.sql把dump.sql放入 seed 目录同步更新expected.json中的页面计数使其与实际 dump 页数一致。当dump.sql存在时harness 的执行路径对应 claw-test.ts 的 upgrade 预相位为先用动态导入的seedPgliteFromFile()把 dump 重放到tempdir/.gbrain/brain.pglite随后执行gbrain init --pglite让迁移链从旧schema_version走到 LATEST最后断言gbrain doctor --json返回status: ok。重放实现的细节值得展开。在 src/core/claw-test/seed-pglite.ts 中seedPglite()打开一个全新的 PGLite 文件用splitStatements()把 dump 切分成独立语句后逐条exec——逐条执行是为了让 SQL 错误能精确定位到出错的语句错误信息会带上前 120 字符的语句预览便于排查种子漂移splitStatements()是刻意朴素的分号切分器只识别单引号字符串与--行注释不依赖完整 SQL 解析器对规范pg_dump输出足够seed-pglite.ts同文件还提供readPgliteSchemaVersion()——一个非变更式的版本探针直接打开 PGLite 读config表中key version的行不经过迁移链。注释特别解释了为什么必须这么做CLI 每次连接都会走connectEngine → initSchema自动应用待迁移项若用常规 CLI 读版本验证器自身就执行了被测的升级得到的通过毫无意义seed-pglite.ts。注意一个刻意设计dump 缺失是响亮失败LOUD failure而非跳过。源码注释写得很清楚——跳过会在当前版本上新建数据库制造一个从未真正执行过迁移的假绿色升级结果claw-test.ts。这保证了测试门禁不会自欺欺人。回归门禁的价值一个 bug 家族的教训seed README 揭示了这套场景要防的到底是什么upgrade-wedge bug 家族#239/#243/#266/#357/#366/#374/#375/#378/#395/#396——每当 gbrain 在嵌入式 schema blob 中新增带索引的列、却没有相应重触发 bootstrap 时就会复现同一类升级楔死问题。这一长串编号说明这类问题在过去反复出现、反复修复因此才需要一条专门的自动化回归防线。upgrade-from-v0.18 场景正是这条防线它把旧库能否一路迁移到 LATEST变成每次测试必须通过的硬性断言从源头拦截发布即升级失败。相关资源导航场景任务书本次升级验证的完整操作指令场景元数据kind、oracle、expected_phases 等断言配置种子制作与测试说明v0.18 dump 的生成、重放与 upgrade-wedge bug 家族背景示例脑库页面查询验证用的标准数据对照场景与升级场景配对的新装基线迁移链核心实现schema_version检测、LATEST_VERSION 推导与事务化迁移init 命令实现--pglite/--path/--migrate-only/--force等升级相关参数doctor 实现healthy | warnings | unhealthy三元健康状态claw-test harnessupgrade 场景的 seed 重放与相位断言种子重放实现seedPglite、readPgliteSchemaVersion与语句切分器摩擦上报 CLIlog/render/list/summary/diff 五个子命令赞分享人工智能RAGAgent 记忆MCP 服务知识管理【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址https://gitcode.com/gh_mirrors/gb/gbrain点击查看免费下载相关推荐Unity Test版本升级指南从旧版本迁移到最新版Unity Test版本升级指南从旧版本迁移到最新版 Unity Test是C语言单元测试的终极解决方案让开发者能够快速验证代码质量。随着项目迭代升级到最测试嵌入式终极Aimeos升级与迁移指南10步安全升级到最新版本终极Aimeos升级与迁移指南10步安全升级到最新版本 Aimeos是基于Laravel 10和Aimeos电子商务框架构建的集成在线商店系统专为超快速在线电商后端前端AndroidAutoLayout版本迁移指南从旧版本升级到最新版本的完整流程AndroidAutoLayout版本迁移指南从旧版本升级到最新版本的完整流程 AndroidAutoLayout是一款强大的Android屏幕适配方案能够移动开发UI组件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
