gbrain 升级楔死Upgrade Wedge回归防线upgrade-from-v0.18 场景、PGLite 种子回放与迁移链验证全解析【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain本指南以 test/fixtures/claw-test-scenarios/upgrade-from-v0.18/seed/README.md 为骨架深入解析 gbrain 用于防御升级楔死upgrade wedge这一历史高频回归 bug 类的端到端测试场景。读者将掌握该场景的种子数据seed如何生成与回放、脚本化与 Live 两种 harness 模式如何驱动并验证迁移链、以及seedPgliteFromFile()/readPgliteSchemaVersion()等底层原语的工作机理从而能在自己的发布流程中复刻同样的升级回归防线。一、为什么要防升级楔死一个反复复发九次的 bug 类upgrade-from-v0.18场景不是为了测一个新功能而是为一段反复发作的历史欠账建立回归闸门。文档明确点出每一次在嵌入的 schema blob 中新增带索引的列column-with-index却没有同步补上 bootstrap 修复的 gbrain 版本都会重新触发同一族升级楔死相关 issue 编号为 #239 / #243 / #266 / #357 / #366 / #374 / #375 / #378 / #395 / #396。升级楔死的典型表现是老版本大脑如 v0.18 时代创建的 PGLite 库在升级到新版本后任何触碰数据库的命令都会在连接阶段卡死或失败——因为迁移链在某个中间 schema 版本上执行 DDL 时遇到了索引引用了尚未创建的列这类前向引用问题而新版二进制又不会自动重放 bootstrap 来补齐。这个 bug 类的破坏性在于它不发生在升级动作本身而是发生在升级之后的每一个gbrain命令里等于整条大脑使用链路被一根楔子钉死。CHANGELOG.md 的 v0.47.5.0 条目印证了这一判断该版本修复了v0.46.35.0 之前创建的 Postgres 大脑无法干净升级的问题并将其定性为升级楔死类的第 4 次复发4th recurrence——新增的构建期 schema 覆盖套件会解析嵌入式 schema 中每一个索引到列的前向引用任何没有配套 bootstrap 修复就引入此类引用的 PR 都会被直接挡下。也就是说upgrade-from-v0.18场景PGLite 侧与构建期 schema 覆盖检查Postgres 侧共同组成了该 bug 类的双保险。二、场景目录结构脚手架优先的种子策略upgrade-from-v0.18场景位于 test/fixtures/claw-test-scenarios/upgrade-from-v0.18/由四部分组成test/fixtures/claw-test-scenarios/upgrade-from-v0.18/ ├── brain/ │ └── people/ │ └── alice-example.md # 供 import/query 使用的最小 fixture 大脑 ├── seed/ │ └── README.md # 本文档种子生成说明本指南主题 ├── BRIEF.md # 交给真实 Agent 的任务简报 └── scenario.json # 场景元数据kind/from_version/oracle2.1 scaffolding-only 的种子状态seed/README.md首先澄清了一个关键前提该目录在 v1 中仅作为脚手架scaffolding随仓库发布。真正的dump.sqlv0.18 形态的 PGLite SQL 转储要到 v1.1 才会随仓库提供在此之前harness 会把缺失的 dump当作 no-op 种子处理——即升级场景在测试闸门上暂时表现得与全新安装fresh-install场景一致。这一设计权衡值得注意它保证了场景骨架、harness 逻辑和验证管线可以先行落地并持续演进不被必须拥有一份真实历史版本转储所阻塞一旦 v1.1 的dump.sql就位同一套代码无需任何改动即可切换到真正的迁移链验证模式。2.2 场景元数据scenario.json 如何声明升级test/fixtures/claw-test-scenarios/upgrade-from-v0.18/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: upgradeharness 据此走升级分支先播种、后迁移验证seed/brain指向场景目录下的子目录名seed下应存放dump.sqloracle验收探针——迁移完成后gbrain query alice必须至少返回 1 条结果证明播种的数据在迁移后依然可查防止迁移成功但数据丢失的假绿。三、生成一份真实的 v0.18 种子六步操作手册当需要把脚手架升级为真实回归闸门时seed/README.md给出了完整的种子生成流程这里逐条展开第 1 步检出 v0.18 发布版本git checkout v0.18.0以 v0.18.0 tag 对应的源码树作为生成源保证转储内容与真实历史版本逐字节一致。第 2 步初始化一个 PGLite 形态的临时大脑gbrain init --pglite --path /tmp/v0.18-seed.pglite--pglite指定使用嵌入式 PGLite 引擎而非 Postgres--path指定数据库文件位置。这一步会创建 v0.18 时期的完整 schema。第 3 步导入一个小型 fixture 大脑以填充数据gbrain import fixture-brain用brain/people/alice-example.md这类最小 fixture见 test/fixtures/claw-test-scenarios/upgrade-from-v0.18/brain/填充真实内容。填充物必须能被后续oracle.queryalice命中否则查询探针会误报失败。第 4 步将 PGLite 转储为 SQL文档给出两条路径首选利用 PGLite 对pg_dump风格导出的支持通过executeRaw(SELECT * FROM pg_dump(...))扩展导出备选直接拷贝数据库文件或使用独立的pglite-tools dumppglite-tools dump /tmp/v0.18-seed.pglite dump.sql第 5 步将dump.sql放入种子目录即放到test/fixtures/claw-test-scenarios/upgrade-from-v0.18/seed/dump.sql。第 6 步校准验收阈值更新expected.json中的min_pages_after_migration字段使其与转储的实际页面page数量匹配。该字段是迁移后最少应有页面数的断言底线防止迁移链把播种的数据悄悄截断而测试仍然通过。注min_pages_after_migration目前仅在本文档中声明在dump.sql正式就位前harness 以 no-op 种子运行因此该阈值尚处于待激活状态。若你的 fork 提前落地真实种子需在仓库相应验收配置中同步补齐该字段。四、harness 如何测试升级seed → init → doctor 三连当dump.sql存在时harness 的执行序列scripted 模式为回放种子调用seedPgliteFromFile()将dump.sql重放到一个全新的tempdir/.gbrain/brain.pglite触发迁移运行gbrain init --pglite让迁移链检测到旧schema_version并逐版本前进到LATEST健康断言运行gbrain doctor --json断言返回status: ok。这段逻辑的源码实现在 src/commands/claw-test.ts 的脚本化分支约 L321-L357harness 先拼接种子 SQL 路径join(scenario.dir, scenario.seedRelative, dump.sql)若文件不存在则记录一条severity: blocker的摩擦日志并直接返回失败码fail 封闭绝不静默跳过存在则调用seedPgliteFromFile回放随后依次执行各阶段命令doctor.db_checks对应gbrain doctor类命令并逐个断言退出码与进度事件。值得强调的纪律是seed-first 顺序源码注释明确写了 Seed ONLY — running init here would walk the migration chain forward and do the very upgrade the agent turn is supposed to perform播种阶段严禁先跑init因为任何 gbrain 连接都会自动应用迁移——如果先 init迁移链就被 staging 提前走完后面 agent/脚本做的就不是升级而是空操作do-nothing的假绿。五、种子回放原语seed-pglite.ts 源码级剖析核心工具模块是 src/core/claw-test/seed-pglite.ts它填补了一个真实缺口既有的迁移测试辅助函数如 test/e2e/helpers.ts 的 Postgres 专用版本只能对真实 Postgres 回卷schema_version并重放PGLite 没有等价能力因此该场景不可复现。模块注释点名了这一设计动机。5.1 seedPglite逐语句回放 错误定位export async function seedPglite(opts: SeedOpts): Promisevoid { const dir dirname(opts.dbPath); if (!existsSync(dir)) mkdirSync(dir, { recursive: true }); const engine new PGLiteEngine(); try { await engine.connect({ engine: pglite, database_path: opts.dbPath }); const statements splitStatements(opts.sql); for (const stmt of statements) { const trimmed stmt.trim(); if (!trimmed) continue; try { await (engine as any).db.exec(trimmed); } catch (e) { const msg e instanceof Error ? e.message : String(e); const preview trimmed.slice(0, 120).replace(/\s/g, ); throw new Error(seedPglite: SQL execution failed at ${preview}…: ${msg}); } } } finally { await engine.disconnect(); } }设计要点逐语句执行而非整体执行种子转储一旦与当前 schema 漂移错误信息能精确到哪一条语句前 120 字符预览而不是一个无法定位的整包异常——这在调试种子漂移时价值极大自动建目录mkdirSync(dir, { recursive: true })保证深层路径如tempdir/.gbrain/无需预先存在finally 保证断开无论成功或失败都调用engine.disconnect()不泄漏连接。配套的seedPgliteFromFile({ dbPath, sqlPath })只是读取文件后转调seedPglite文件缺失时抛出seed SQL not found at path。5.2 splitStatements够用而非完备的 SQL 切分器转储回放依赖一个朴素但严谨的;切分器模块内_internal.splitStatements导出供测试它正确识别单引号字符串含转义撇号与--行注释从而不会在INSERT INTO t VALUES (a;b)或注释内的分号处误切同时明确声明仅适用于规范的 pg_dump 输出并非完整 SQL 解析器。这是典型的以确定输入换取简单实现工程取舍。5.3 readPgliteSchemaVersion不触碰迁移链的版本探针Live 模式升级验收需要一个非变更non-mutating的 schema 版本读取手段。模块注释解释了原因迁移运行器通过setConfig(version, …)即config.key version记录当前位置但用普通 CLI 读版本是非法的——因为每一次 CLI 连接都会经由connectEngine → initSchema自动应用待执行迁移验证器会替什么都没做的 Agent完成升级。因此const rows await (engine as any).db.query(SELECT value FROM config WHERE key version);该探针直接用PGLiteEngine打开数据库文件、只读这一行、然后断开绝不触发迁移链数据库/表/行不存在时返回null。正是这个原语让Agent 是否真的在任务回合内完成了升级可以被诚实度量。六、Live 模式的升级 Oracle把什么都没做判为失败Scripted 模式验证的是确定性命令序列Live 模式gbrain claw-test --live --agent name则把真实的 OpenClaw / Hermes / Grok / Opencode 等 Agent 放进场景用任务简报驱动其自主行动。此时退出码为 0完全不够——一个什么都不做的 Agent 也能退出 0因此 src/commands/claw-test.ts 实现了三级升级 oracle约 L622-L646版本必须可读且前进用readPgliteSchemaVersion在 Agent 回合前后各读一次若postVersion preVersion判定 Agent 从未运行过任何会走迁移链的命令前进必须到顶若postVersion LATEST_VERSION判定 Agent 的迁移链中途夭折——因为任何 gbrain 连接都会迁到最新只前进一步意味着回合中途进程死亡数据必须幸存随后执行声明式oracle如query alice至少 1 条结果确保迁移了 schema 却丢了种子数据同样失败。关键顺序约束源码注释强调版本探针必须在任何声明式查询探针之前执行——查询自身的 CLI 连接会触发迁移从而污染后续的版本读取。此外Live 模式的升级场景同样只播种、不 initsrc/commands/claw-test.ts 的stageLiveScenario约 L552-L575并且通过 PATH shim 让简报里的裸命令gbrain精确解析到本次测试的二进制避免 operator 环境里残留的旧版全局二进制干扰。七、Agent 侧简报BRIEF.md 与摩擦协议Live 模式下test/fixtures/claw-test-scenarios/upgrade-from-v0.18/BRIEF.md 是交给 Agent 的任务书规定四步走先跑gbrain doctor --json记录任何 warning 与修复提示用gbrain init --pglite指向既有数据库路径让迁移链从旧schema_version前进到最新再跑gbrain doctor --jsonstatus应为healthy或warnings绝不允许unhealthy用gbrain query alice验证播种数据仍可检索。配合的是摩擦协议friction protocol任何困惑、缺失、意外尤其是迁移环节——历史最高痛点都应记录为gbrain friction log --severity {confused|error|blocker|nit} --phase which-step --message what-happened [--hint what-could-be-better]简报甚至预列了要重点观察的升级摩擦模式迁移链在某个具体 schema 版本失败记录版本号错误、doctor 给出不可操作的修复提示、init --pglite不识别既有大脑、需要手写 SQL 才能解锁等——这些正是当年九个 issue 的真实症状清单。项目对升级流的调优目标被直白地写成zero-friction。八、迁移链底层MIGRATIONS 数组与 LATEST_VERSION升级场景断言迁移链走到 LATEST其底层依据在 src/core/migrate.ts全部迁移以数组形式注册每个条目形如{ version: N, name: ..., idempotent: true, sql: ... }例如canonical_page_revisions_and_guardsversion 150、durable_concurrent_persistence151、unique_lock_acquisition_tokens152直至index_retained_publication_recovery159。而export const LATEST_VERSION MIGRATIONS.length 0 ? Math.max(...MIGRATIONS.map(m m.version)) : 1;LATEST_VERSION就是数组最大版本号迁移运行器在执行时打印Schema version ${current} → ${LATEST_VERSION} (${pending.length} migration(s) pending)成功后调用engine.setConfig(version, String(m.version))落盘当前版本。upgrade-from-v0.18场景验证的正是播种出的 v0.18 旧版本号 → 逐步应用这批 idempotent 迁移 → 最终等于LATEST_VERSION这一整条链。需要留意的是迁移是否触发不只由init决定——connectEngine → initSchema会在任何 CLI 连接时自动应用待执行迁移这也是为什么播种后第一个doctor就已经在走迁移链。升级场景正是把这一隐式行为显式化、可断言化。九、原语的测试保证seed-pglite.serial.test.ts种子回放原语本身有独立单测test/seed-pglite.serial.test.ts纯 PGLite 内存模式无需真实数据库覆盖五类边界splitStatements分号切分、单引号字符串内的分号不误切、--行注释内的分号不误切、转义撇号正确处理、空输入返回空数组seedPglite回放后重新打开数据库可查询到播种行、非法 SQL 抛出含SQL execution failed的错误、自动创建嵌套父目录、空 SQL 是 no-op仅创建.pglite文件且 public schema 无表seedPgliteFromFile从磁盘读取并回放、缺失文件抛出seed SQL not found。这组测试保证当 v1.1 的真实dump.sql就位时回放原语本身是可信的——出问题只可能是种子内容漂移而不是切分器或引擎层。十、当前状态与后续计划归纳当前仓库的实际状态现在v1seed/仅含本文档无dump.sqlharness 将缺失 dump 视作 no-op 种子升级场景以 fresh-install 形态跑测试闸门但 Live 模式的升级 oracle版本前进 数据幸存与脚本化分支的 fail-closed 检查缺 dump 即 blocker都已生效v1.1dump.sql随仓库提供升级场景升级为真正的老版本 schema → LATEST 迁移链验证长期防线配合 CHANGELOG.md v0.47.5.0 引入的构建期 schema 覆盖检查解析嵌入式 schema 中每个索引到列的前向引用缺配套 bootstrap 修复即拦截 PR从运行时回归闸门 构建期静态闸门两个方向封死 upgrade-wedge 类 bug。对开发者而言这篇文档的价值不只是如何生成一个种子更是一套可复用的升级回归方法论用真实历史版本的 SQL 转储重建旧大脑 → 只播种不预迁移 → 用非变更探针诚实度量版本前进 → 用数据幸存断言兜底。任何涉及嵌入式数据库 schema 演进的系统都可以照此搭建自己的升级楔死防线。延伸阅读场景编排入口 src/commands/claw-test.ts、回放原语 src/core/claw-test/seed-pglite.ts、迁移链 src/core/migrate.ts、原语单测 test/seed-pglite.serial.test.ts、场景简报 test/fixtures/claw-test-scenarios/upgrade-from-v0.18/BRIEF.md 与场景元数据 test/fixtures/claw-test-scenarios/upgrade-from-v0.18/scenario.json。【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考