gbrain 版本升级回归指南:v0.18 脑库原地迁移到最新 schema 的 Claw-test 全流程

发布时间:2026/11/16 16:38:04

gbrain 版本升级回归指南:v0.18 脑库原地迁移到最新 schema 的 Claw-test 全流程 人工智能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),仅供参考
延伸阅读

更多相关文章

2026/11/16 16:38:04

宅男宅女电视剧开发避坑速查手册:3步搞定环境配置

宅男宅女电视剧开发避坑速查手册:3步搞定环境配置 配置环境就卡半天,这是无数后端开发者入门时的噩梦。你明明照着文档一步步来,结果终端报错信息像天书一样,重启电脑、重装依赖、换版本,折腾一下午还是没跑通。别急,这份 速查手册…

2026/11/15 11:10:43

审计署是干什么的:3年老兵拆解高频面试题

审计署是干什么的:3年老兵拆解高频面试题 版本升级后 API 全变了,这种痛感在技术圈太常见,但在考公或国企面试中,面对“审计署是干什么的”这类高频面试题,很多考生却像面对一个未更新文档的旧接口,脑子一片空白。…

2026/11/15 13:12:43

桌面显卡天梯图渲染卡顿?5步性能优化方案

桌面显卡天梯图渲染卡顿?5步性能优化方案 很多开发者手里攥着Python或JS语法书,背得滚瓜烂熟,一上手做项目就卡壳。特别是像“桌面显卡天梯图”这种需要实时交互、大量数据可视化的前端或后端项目,页面一开就掉帧,用户骂娘,自己抓瞎。这不仅仅…

2026/11/16 16:34:50

庄河高压电工证多少钱怎么报名才不被坑

庄河高压电工证多少钱怎么报名才不被坑 你是不是正愁不知道庄河高压电工证多少钱?又怕报名时被那些黑中介骗钱?其实现在很多人都有这种想法,特别是像你这样刚开始接触特种作业证书的新人。别急,这篇文章就来帮你理清庄河高压电工证报名的全盘信息,从哪儿…

2026/11/16 16:34:50

海口市装修电工证怎么考?2026河南最新政策下必须知道的5个关键点

海口市装修电工证怎么考?2026河南最新政策下必须知道的5个关键点 你是不是正被“急需特种作业证才能上岗找工作”这个问题逼得焦头烂额?尤其是现在,2026河南最新政策对特种作业操作证的报考要求和管理更加严格,没有正规的电工证,连工地门都进不…

2026/11/16 16:34:50

电工证皮套防水怎么选?上岗必备证件别因小事耽误工期

电工证皮套防水怎么选?上岗必备证件别因小事耽误工期 工地太忙根本没时间复习考试,尤其是像你这种刚转岗的济源从业者,白天忙得脚不沾地,晚上还得熬夜看电工证考试资料,压力山大。偏偏这个证件又是 上岗必备…

2026/11/16 16:34:50

电工证实操考试心里没底怕挂科?武汉电工证补贴报名攻略来了

电工证实操考试心里没底怕挂科?武汉电工证补贴报名攻略来了 实操考试心里没底怕挂科?尤其是像你这种三门峡房建工程的从业者,电工证可是上岗的“通行证”,但很多小伙伴对考试流程、考试内容、补贴政策都不太清楚,导致报名时手忙脚乱,甚至错失补贴机会。…

2026/11/16 7:29:52

电工证考试口诉怎么准备值不值得考

电工证考试口诉怎么准备值不值得考 实操考试心里没底怕挂科,这是大多数准备考电工证的人心里最真实的感受。尤其是面对【电工证考试口诉】环节,很多人不知道该怎么准备,甚至担心自己说不好就被淘汰。其实,只要掌握方法, 值不值得考…

2026/11/16 5:30:20

桑植县考电工证千万别踩坑!报名全流程教你避坑

桑植县考电工证千万别踩坑!报名全流程教你避坑 你是不是也遇到过这种情况:想考个电工证,但不知道从哪儿下手,怕被中介坑,怕花冤枉钱,更怕考了证还不能用?别急,这正是你该看这篇文章的原因。在桑植县考电工证,确实有很多人被坑过,但只要你知道流程、…

2026/11/16 0:00:11

黎城电工证查询报名费多少钱 内部消息告诉你怎么避开中介陷阱

黎城电工证查询报名费多少钱 内部消息告诉你怎么避开中介陷阱 你是不是也和我一样,想考电工证,但不知道去哪报名,怕被中介坑?最近网上有不少人问“黎城电工证查询报名费多少钱”,结果一查,信息五花八门,真假难辨。别担心,今天我就从一线从业者的角度…

2026/11/16 0:00:11

青岛崂山区电工证培训通过率揭秘:外省证书怎么转过来?

青岛崂山区电工证培训通过率揭秘:外省证书怎么转过来? 之前考的证在外省能不能转过来?这个问题困扰着很多在外地打工的电工,尤其是像南阳卧龙区的建筑工人,他们常年在工地作业,手上持有电工证是基本要求,但很多人因为工作流动性大,担心证书不能转到本…

2026/11/15 4:46:37

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

在智慧养宠时代,基于视觉的宠物身份识别技术正逐步从实验室走向家庭应用。然而,与配合度高的人类不同,宠物是典型的“非合作生物识别对象”——它们不会主动配合摄像头调整姿态,更无法控制光照环境。实际应用中,我们常…

2026/11/16 3:17:47

SSM电子书店源码全解析:结构、原理、部署与排错实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑