gbrain Schema Pack 升级机制全解从 gbrain-base1.x 到 gbrain-base-v2 的 onboard 迁移管线【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain本文围绕 gbrain 仓库 pack-upgrade-mechanism.md 所定义的模式包Schema Pack升级机制展开当一个新的模式包声明自己是旧包的“后继者”时整个 onboard 检查、用户确认、unify-types处理器执行与配置翻转的链路如何串联。读者将掌握migration_from契约的写法、版本区间语义、findPackSuccessors的发现逻辑、manual_only应用策略背后的安全考量以及如何亲手编写一个可被自动发现的后继 pack。核心契约migration_from mapping_rules模式包Schema Pack是 gbrain 中定义页面类型page type、链接类型link type、frontmatter 规则与抽取能力的可分发清单格式由api_version: gbrain-schema-pack-v1标识。升级机制的入口是一个可选字段migration_from它声明“本包是哪个包的、哪个版本区间的后继者”api_version: gbrain-schema-pack-v1 name: gbrain-base-v2 version: 1.0.0 migration_from: pack: gbrain-base version: 1.x在源码层面该字段由 manifest-v1.ts 中的MigrationFromSchema校验约束仅两个必填字符串pack源包名与version源版本区间支持通配符见下文“版本区间语义”。同时SchemaPackManifestSchema定义了mapping_rules字段它是一组“声明式迁移规则”由unify-types处理器消费采用 discriminated union 区分三种原语manifest-v1.tskind作用关键字段retype将页面类型从from_type改为to_type可选打上 subtype 并保留 legacy_typefrom_type、to_type、subtype、subtype_field、path_filter、slug_filterpage_to_link将“边形状”页面如 atom-partner-link、symlink 页转成 links 表真实行并软删除源页from_type、link_type、source_slug_from、target_slug_from、inverse、preserve_notespage_to_alias将“重定向形状”页面如 concept-redirect 页转成 slug_aliases 表行并软删除源页不做入站链接改写from_type、canonical_from、alias_slug_from、notes_from需要重点理解的哨兵值from_type: *unknown*catch-all 规则必须放在规则列表最后负责把所有既不在page_types声明中、也不是前面规则目标的页面统一改写subtype: *original_type*配合 catch-all 使用把页面原始类型作为 subtype 值写入subtype_field有严格白名单ALLOWED_SUBTYPE_FIELDSsubtype、legacy_type、origin、format、kind、period、domain。这是安全设计——防止第三方包通过 mapping_rules 覆写title、slug、type等关键 frontmatter 键见 manifest-v1.ts。pack 加载时会执行一组校验manifest-v1.ts 注释明确列出所有 retype 的to_type必须存在于page_types[]所有 page_to_link 的link_type必须存在于link_types[]catch-all 规则必须最后出现retype 规则之间不允许成环如 A→B 与 B→A 同时出现。端到端流程总览升级机制从包作者编写到用户最后看到gbrain onboard --check显示 ok共经历五个阶段┌────────────────────────────────────────────────────────────────┐ │ PACK AUTHORING │ │ │ │ Author declares: migration_from: {pack: P, version: R} │ │ mapping_rules: [retype/page_to_link/page_to_alias] │ │ Pack ships bundled OR via ~/.gbrain/schema-packs/name/ │ └──────────────────────────┬─────────────────────────────────────┘ ↓ ┌────────────────────────────────────────────────────────────────┐ │ ONBOARD CHECK DISCOVERY │ │ │ │ checkPackUpgradeAvailable(engine) at src/core/onboard/ │ │ checks.ts: │ │ 1. Read engine.getConfig(schema_pack) for dbConfig tier │ │ 2. loadActivePack({cfg: null, remote: false, dbConfig}) │ │ 3. findPackSuccessors(active.name, active.version) │ │ → walks BUNDLED_PACK_NAMES ~/.gbrain/schema-packs/ │ │ → matches via _versionRangeMatches(version, range) │ │ → returns ResolvedPack[] sorted by successor version │ │ 4. If successors.length 0, emit OnboardCheckResult │ │ with RemediationStep targeting unify-types handler │ │ protected: true (manual_only via render allowlist) │ └──────────────────────────┬─────────────────────────────────────┘ ↓ ┌────────────────────────────────────────────────────────────────┐ │ USER DECIDES │ │ │ │ gbrain onboard --check shows finding │ │ gbrain onboard --check --explain shows per-cluster narrative │ │ User reviews; if OK, runs: │ │ gbrain jobs submit unify-types \ │ │ --params {target_pack:gbrain-base-v2,apply:true} │ │ (omit apply:true for a dry-run; that is the default) │ │ (Autopilot never auto-fires this; manual_only) │ └──────────────────────────┬─────────────────────────────────────┘ ↓ ┌────────────────────────────────────────────────────────────────┐ │ HANDLER EXECUTION (src/core/schema-pack/unify-types-handler.ts) │ │ │ │ 1. Preflight: load target pack; assert mapping_rules present │ │ 2. Stats snapshot (pre-state for celebration) │ │ 3. Acquire gbrain-unify db-lock (60min TTL) │ │ 4. Apply phases (4): │ │ a. Explicit retype rules (chunked UPDATE 1000/batch) │ │ - frontmatter.legacy_type ALWAYS preserved │ │ - frontmatter.subtype stamped when subtype set │ │ b. Catch-all retype: synthesize per-unknown-type rule │ │ excluding declared types explicit targets page_to_ │ │ link/alias sources │ │ c. Page-to-link: parse bodyfrontmatter, insert link row, │ │ soft-delete source page (per-page atomicity) │ │ d. Page-to-alias: insert slug_aliases row, soft-delete │ │ source page (NO rewriteLinks) │ │ 5. Final sync: path-prefix typing for residual UNTYPED rows │ │ 6. ACTIVE-PACK FLIP: │ │ - engine.setConfig(schema_pack, target_pack) │ │ - saveConfig({...existing, schema_pack: target_pack}) │ │ 7. Verify: re-run stats; warn if ≤ declared 5 violated │ │ 8. Celebration summary to stderr audit JSONL │ │ 9. Release db-lock │ └──────────────────────────┬─────────────────────────────────────┘ ↓ ┌────────────────────────────────────────────────────────────────┐ │ POST-UPGRADE STATE │ │ │ │ • pages.type updated with canonical types │ │ • frontmatter.legacy_type preserved for rollback │ │ • slug_aliases populated for old-slug → canonical lookup │ │ • links table has new partner_of / relates_to rows │ │ • Source pages soft-deleted (72h TTL for restore) │ │ • Active pack flipped to target_pack │ │ • Next gbrain onboard --check shows ok │ └────────────────────────────────────────────────────────────────┘上游发现的源码实现onboard 检查实现在 checks.ts 的checkPackUpgradeAvailable。值得注意的两个实现细节DB 侧配置优先读取它先尝试engine.getConfig(schema_pack)读取数据库层的配置再以loadConfigFileOnly()作为文件平面file-plane回退这样一次unify-types应用完成、配置翻转后即使文件平面配置尚未落盘检查也能立即看到新状态防护式降级整个检查体包裹在 try/catch 中loadActivePack失败或被调用方中断时返回status: okCheck skipped单次失败不会污染整个 onboard 聚合结果。runAllOnboardChecks并行执行 7 项检查其中pack_upgrade_available、type_proliferation、dangling_aliases三项属于 v0.42 引入的“类型统一”Type Unification家族checks.ts。当发现后继包时检查结果携带est_seconds: 600约 10 分钟这是 18.6 万页规模的线上代理值与est_usd_cost: 0——整个迁移是纯 SQL 操作不消耗任何 LLM 预算。其 rationale 明确说明了可逆性保证“72h 软删除 TTL frontmatter.legacy_type 保留”。版本区间语义migration_from.version接受三种形态*是x的别名形式匹配1.0.0精确字面量仅1.0.01.x主版本通配1.0.0、1.5.2、1.99.991.0.x次版本通配1.0.0、1.0.5、1.0.99实现位于 load-active.ts 的_versionRangeMatches当区间不含x/*时退化为精确等值比较否则按.拆分区间与版本号逐段比较区间段为x/*时跳过其余段必须逐一相等且区间段数不能多于版本段数。同文件还提供_versionDescCompareload-active.ts做三段的降序比较由于 Zod 只校验M.m.p三段比较时会把可能的四段版本截断到三段。该行为由 test/schema-pack-find-pack-successors.serial.test.ts 钉住。findPackSuccessors 后继包发现findPackSuccessors是发现机制的核心位于 load-active.ts遍历BUNDLED_PACK_NAMES当前为gbrain-base、gbrain-recommended、gbrain-creator、gbrain-investor、gbrain-engineer、gbrain-everything、gbrain-base-v2与 base 目录 下实际存在的 7 个 yaml 一一对应对每个不同于当前活跃包名字的候选调用loadActivePack({ cfg: null, remote: false, perCall: candidate })加载清单检查候选清单的migration_from.pack activeName且_versionRangeMatches(activeVer, migration_from.version)命中结果按后继包版本降序排序因此多个后继同时声明时“最新的”胜出任何候选加载失败都走“记录并跳过”D4 EMPTY FILTER 契约磁盘上损坏的包不会破坏其他人的升级可用性检查。当前实现的后继检测只覆盖内置bundled包。文档明确标注了未来工作枚举用户安装的~/.gbrain/schema-packs/*/pack.yaml被推迟因为文件系统扫描成本需要先解决 registry.ts 的缓存失效策略。因此若你想让自己的自定义 pack 作为某个包的“后继”被 onboard 自动发现目前需要把它并入内置包列表随 gbrain 发行自定义包仍然可以手动gbrain schema use激活。onboard 检查与 manual_only 应用策略onboard 契约定义了三种apply_policy策略含义auto_applyAutopilot 无人值守直接执行prompt_requiredAutopilot 在--auto-with-prompt模式下向用户询问manual_onlyAutopilot永不自动触发必须由用户显式提交pack_upgrade_available发出的RemediationStep携带protected: truejob: unify-types。渲染层的 render.ts 中MANUAL_ONLY_PROTECTED_JOBS白名单目前包含extract-takes-from-pages与unify-types通过 toOnboardRecommendation 将受保护步骤映射为manual_only——受保护但不在白名单中的步骤则降级为prompt_required可用--yes走--auto --yes执行。为什么 taxonomy 变更必须手动文档给出的 rationale 直击产品本质包升级改变的是大脑的分类体系taxonomy而 taxonomy 是用户的主观判断不是 Autopilot 的职责范围。即使在--auto-with-prompt模式下在正常 tick 中间突然弹出“要不要迁移你的分类体系”也是错误的 UX——用户本意是来修孤儿页面不是被打断去做分类迁移决策。显式提交才是正确的边界。作者如何编写后继 pack以一个给学术研究大脑新增researchercanonical 类型的最小示例文档原例可复制到~/.gbrain/schema-packs/gbrain-academic-v1/pack.yamlapi_version: gbrain-schema-pack-v1 name: gbrain-academic-v1 version: 1.0.0 description: Academic research brain — adds researcher canonical gbrain_min_version: 0.42.0 extends: null migration_from: pack: gbrain-base-v2 version: 1.x page_types: # Inherit gbrain-base-v2s 15 types here (or declare extends: # gbrain-base-v2 and let the merge contract in schema-packs.md merge them) - { name: person, primitive: entity, path_prefixes: [people/], expert_routing: true } - { name: company, primitive: entity, path_prefixes: [companies/], expert_routing: true } # ... all 13 other v2 canonicals ... - { name: note, primitive: concept, path_prefixes: [notes/], extractable: true } # Academic addition: - name: researcher primitive: entity path_prefixes: [researchers/] aliases: [academic, professor, scholar] extractable: false expert_routing: true mapping_rules: # All v2 mapping rules (copy from v2 yaml) # ... ~40 rules ... # Custom: relocate v2-tagged academics to researcher - { kind: retype, from_type: person, to_type: researcher, path_filter: researchers/% } # Catch-all - kind: retype from_type: *unknown* to_type: note subtype_field: legacy_type subtype: *original_type*发布后gbrain schema list可发现该包gbrain schema use gbrain-academic-v1激活它激活后任何仍在gbrain-base-v21.x上的大脑其pack_upgrade_available检查都会触发并浮出指向你包的unify-typesRemediationStep。实际的内置后继包样本是 gbrain-base-v2.yaml它当前版本为1.2.0、gbrain_min_version: 0.42.0声明migration_from: {pack: gbrain-base, version: 1.x}并在page_types中组织 15 个 canonical 类型person、company、media、tweet、social-digest、analysis、atom、concept、source、deal、email、slack、meeting、conversation、writing……以及partner_of、relates_to、supersedes、redirects_to、authored等链接类型最后附带完整的mapping_rules块——这是编写真实迁移规则的最佳参照物。锁与并发gbrain-unify是gbrain_cycle_locks表中一条专用锁行TTL 60 分钟。处理器在任何应用阶段开始前获取该锁并在finally中释放unify-types-handler.ts 头部注释与执行体明确此模式。两个并发的gbrain jobs submit unify-types调用中第二个会在锁获取阶段快速失败并给出清晰报错“could not acquire gbrain-unify db-lock (held by another process). Wait for the other unify run to complete (lock TTL: 60min)”。这与gbrain-sync锁完全同构。同时注意 handler 的入口参数unify-types-handler.tsapply默认false——即默认是 dry-run只统计would_apply而不真正改动数据。onboard 的 RemediationStep 是用户已同意的应用请求因此会在参数里显式携带apply: true见 checks.ts 的注释 #1575worker 默认 applyfalse而 remediation step 是经同意的应用必须显式带上。审计追踪每次 unify 运行都会写入~/.gbrain/audit/schema-unify-YYYY-Www.jsonlISO 周轮转与既有审计通道一致。每条记录包含迁移前后两个 pack 的身份identity格式为nameversionmanifest-sha8各 phase 的计数would_applyapplied含retype_explicit、retype_catch_all、page_to_link、page_to_alias、final_sync分项警告与完成时间戳。隐私设计页面 slug不会批量记录仅保留每条规则的sample_slugs[≤10]抽样用于取证调试的GBRAIN_AUDIT_FULL1逃生门已被提出但尚未接线。升级后的状态与回滚路径升级完成后对应 unify-types-handler.ts 的第 6 步 D13pages.type更新为新的 canonical 类型frontmatter.legacy_type完整保留供回滚使用slug_aliases表填充旧 slug → canonical 的映射slug_aliases是 migrate.ts 的MIGRATIONS数组中新引入的迁移条目links表出现新的partner_of/relates_to行源页面软删除72h TTL 可恢复活跃包通过engine.setConfig(schema_pack, target_pack)saveConfig({...existing, schema_pack: target_pack})翻转下一次gbrain onboard --check显示 ok。尚未支持的能力文档明确列出当前边界避免误用发布门禁publish-gate的子进程沙箱按 source 维度的包升级handler 接受sourceId参数但findPackSuccessors尚未透传对 canonical pack 意见不一致的跨大脑 federated mounts自动回滚当前只能手动 SQL 或gbrain restoreLLM 辅助的 mapping_rules 代码生成提议中的gbrain schema detect-mappings命令。参考索引包文件gbrain-base-v2.yaml清单扩展与迁移契约manifest-v1.ts后继包遍历器load-active.ts 的findPackSuccessorsonboard 检查checks.ts 的checkPackUpgradeAvailable渲染白名单render.ts 的MANUAL_ONLY_PROTECTED_JOBS迁移处理器unify-types-handler.tsslug_aliases 迁移条目migrate.ts类型分类学文档type-taxonomy.md相关技能skills/schema-unify/SKILL.md测试佐证schema-pack-find-pack-successors.serial.test.ts、onboard-pack-upgrade-checks.test.ts、schema-pack-unify-types-handler.test.ts、jobs-unify-types-default-dryrun.test.ts、type-unification-full-flow.test.ts【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 gbrain Schema Pack 升级机制全解：从 gbrain-base@1.x 到 gbrain-base-v2 的 onboard 迁移管线
gbrain Schema Pack 升级机制全解从 gbrain-base1.x 到 gbrain-base-v2 的 onboard 迁移管线【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain本文围绕 gbrain 仓库 pack-upgrade-mechanism.md 所定义的模式包Schema Pack升级机制展开当一个新的模式包声明自己是旧包的“后继者”时整个 onboard 检查、用户确认、unify-types处理器执行与配置翻转的链路如何串联。读者将掌握migration_from契约的写法、版本区间语义、findPackSuccessors的发现逻辑、manual_only应用策略背后的安全考量以及如何亲手编写一个可被自动发现的后继 pack。核心契约migration_from mapping_rules模式包Schema Pack是 gbrain 中定义页面类型page type、链接类型link type、frontmatter 规则与抽取能力的可分发清单格式由api_version: gbrain-schema-pack-v1标识。升级机制的入口是一个可选字段migration_from它声明“本包是哪个包的、哪个版本区间的后继者”api_version: gbrain-schema-pack-v1 name: gbrain-base-v2 version: 1.0.0 migration_from: pack: gbrain-base version: 1.x在源码层面该字段由 manifest-v1.ts 中的MigrationFromSchema校验约束仅两个必填字符串pack源包名与version源版本区间支持通配符见下文“版本区间语义”。同时SchemaPackManifestSchema定义了mapping_rules字段它是一组“声明式迁移规则”由unify-types处理器消费采用 discriminated union 区分三种原语manifest-v1.tskind作用关键字段retype将页面类型从from_type改为to_type可选打上 subtype 并保留 legacy_typefrom_type、to_type、subtype、subtype_field、path_filter、slug_filterpage_to_link将“边形状”页面如 atom-partner-link、symlink 页转成 links 表真实行并软删除源页from_type、link_type、source_slug_from、target_slug_from、inverse、preserve_notespage_to_alias将“重定向形状”页面如 concept-redirect 页转成 slug_aliases 表行并软删除源页不做入站链接改写from_type、canonical_from、alias_slug_from、notes_from需要重点理解的哨兵值from_type: *unknown*catch-all 规则必须放在规则列表最后负责把所有既不在page_types声明中、也不是前面规则目标的页面统一改写subtype: *original_type*配合 catch-all 使用把页面原始类型作为 subtype 值写入subtype_field有严格白名单ALLOWED_SUBTYPE_FIELDSsubtype、legacy_type、origin、format、kind、period、domain。这是安全设计——防止第三方包通过 mapping_rules 覆写title、slug、type等关键 frontmatter 键见 manifest-v1.ts。pack 加载时会执行一组校验manifest-v1.ts 注释明确列出所有 retype 的to_type必须存在于page_types[]所有 page_to_link 的link_type必须存在于link_types[]catch-all 规则必须最后出现retype 规则之间不允许成环如 A→B 与 B→A 同时出现。端到端流程总览升级机制从包作者编写到用户最后看到gbrain onboard --check显示 ok共经历五个阶段┌────────────────────────────────────────────────────────────────┐ │ PACK AUTHORING │ │ │ │ Author declares: migration_from: {pack: P, version: R} │ │ mapping_rules: [retype/page_to_link/page_to_alias] │ │ Pack ships bundled OR via ~/.gbrain/schema-packs/name/ │ └──────────────────────────┬─────────────────────────────────────┘ ↓ ┌────────────────────────────────────────────────────────────────┐ │ ONBOARD CHECK DISCOVERY │ │ │ │ checkPackUpgradeAvailable(engine) at src/core/onboard/ │ │ checks.ts: │ │ 1. Read engine.getConfig(schema_pack) for dbConfig tier │ │ 2. loadActivePack({cfg: null, remote: false, dbConfig}) │ │ 3. findPackSuccessors(active.name, active.version) │ │ → walks BUNDLED_PACK_NAMES ~/.gbrain/schema-packs/ │ │ → matches via _versionRangeMatches(version, range) │ │ → returns ResolvedPack[] sorted by successor version │ │ 4. If successors.length 0, emit OnboardCheckResult │ │ with RemediationStep targeting unify-types handler │ │ protected: true (manual_only via render allowlist) │ └──────────────────────────┬─────────────────────────────────────┘ ↓ ┌────────────────────────────────────────────────────────────────┐ │ USER DECIDES │ │ │ │ gbrain onboard --check shows finding │ │ gbrain onboard --check --explain shows per-cluster narrative │ │ User reviews; if OK, runs: │ │ gbrain jobs submit unify-types \ │ │ --params {target_pack:gbrain-base-v2,apply:true} │ │ (omit apply:true for a dry-run; that is the default) │ │ (Autopilot never auto-fires this; manual_only) │ └──────────────────────────┬─────────────────────────────────────┘ ↓ ┌────────────────────────────────────────────────────────────────┐ │ HANDLER EXECUTION (src/core/schema-pack/unify-types-handler.ts) │ │ │ │ 1. Preflight: load target pack; assert mapping_rules present │ │ 2. Stats snapshot (pre-state for celebration) │ │ 3. Acquire gbrain-unify db-lock (60min TTL) │ │ 4. Apply phases (4): │ │ a. Explicit retype rules (chunked UPDATE 1000/batch) │ │ - frontmatter.legacy_type ALWAYS preserved │ │ - frontmatter.subtype stamped when subtype set │ │ b. Catch-all retype: synthesize per-unknown-type rule │ │ excluding declared types explicit targets page_to_ │ │ link/alias sources │ │ c. Page-to-link: parse bodyfrontmatter, insert link row, │ │ soft-delete source page (per-page atomicity) │ │ d. Page-to-alias: insert slug_aliases row, soft-delete │ │ source page (NO rewriteLinks) │ │ 5. Final sync: path-prefix typing for residual UNTYPED rows │ │ 6. ACTIVE-PACK FLIP: │ │ - engine.setConfig(schema_pack, target_pack) │ │ - saveConfig({...existing, schema_pack: target_pack}) │ │ 7. Verify: re-run stats; warn if ≤ declared 5 violated │ │ 8. Celebration summary to stderr audit JSONL │ │ 9. Release db-lock │ └──────────────────────────┬─────────────────────────────────────┘ ↓ ┌────────────────────────────────────────────────────────────────┐ │ POST-UPGRADE STATE │ │ │ │ • pages.type updated with canonical types │ │ • frontmatter.legacy_type preserved for rollback │ │ • slug_aliases populated for old-slug → canonical lookup │ │ • links table has new partner_of / relates_to rows │ │ • Source pages soft-deleted (72h TTL for restore) │ │ • Active pack flipped to target_pack │ │ • Next gbrain onboard --check shows ok │ └────────────────────────────────────────────────────────────────┘上游发现的源码实现onboard 检查实现在 checks.ts 的checkPackUpgradeAvailable。值得注意的两个实现细节DB 侧配置优先读取它先尝试engine.getConfig(schema_pack)读取数据库层的配置再以loadConfigFileOnly()作为文件平面file-plane回退这样一次unify-types应用完成、配置翻转后即使文件平面配置尚未落盘检查也能立即看到新状态防护式降级整个检查体包裹在 try/catch 中loadActivePack失败或被调用方中断时返回status: okCheck skipped单次失败不会污染整个 onboard 聚合结果。runAllOnboardChecks并行执行 7 项检查其中pack_upgrade_available、type_proliferation、dangling_aliases三项属于 v0.42 引入的“类型统一”Type Unification家族checks.ts。当发现后继包时检查结果携带est_seconds: 600约 10 分钟这是 18.6 万页规模的线上代理值与est_usd_cost: 0——整个迁移是纯 SQL 操作不消耗任何 LLM 预算。其 rationale 明确说明了可逆性保证“72h 软删除 TTL frontmatter.legacy_type 保留”。版本区间语义migration_from.version接受三种形态*是x的别名形式匹配1.0.0精确字面量仅1.0.01.x主版本通配1.0.0、1.5.2、1.99.991.0.x次版本通配1.0.0、1.0.5、1.0.99实现位于 load-active.ts 的_versionRangeMatches当区间不含x/*时退化为精确等值比较否则按.拆分区间与版本号逐段比较区间段为x/*时跳过其余段必须逐一相等且区间段数不能多于版本段数。同文件还提供_versionDescCompareload-active.ts做三段的降序比较由于 Zod 只校验M.m.p三段比较时会把可能的四段版本截断到三段。该行为由 test/schema-pack-find-pack-successors.serial.test.ts 钉住。findPackSuccessors 后继包发现findPackSuccessors是发现机制的核心位于 load-active.ts遍历BUNDLED_PACK_NAMES当前为gbrain-base、gbrain-recommended、gbrain-creator、gbrain-investor、gbrain-engineer、gbrain-everything、gbrain-base-v2与 base 目录 下实际存在的 7 个 yaml 一一对应对每个不同于当前活跃包名字的候选调用loadActivePack({ cfg: null, remote: false, perCall: candidate })加载清单检查候选清单的migration_from.pack activeName且_versionRangeMatches(activeVer, migration_from.version)命中结果按后继包版本降序排序因此多个后继同时声明时“最新的”胜出任何候选加载失败都走“记录并跳过”D4 EMPTY FILTER 契约磁盘上损坏的包不会破坏其他人的升级可用性检查。当前实现的后继检测只覆盖内置bundled包。文档明确标注了未来工作枚举用户安装的~/.gbrain/schema-packs/*/pack.yaml被推迟因为文件系统扫描成本需要先解决 registry.ts 的缓存失效策略。因此若你想让自己的自定义 pack 作为某个包的“后继”被 onboard 自动发现目前需要把它并入内置包列表随 gbrain 发行自定义包仍然可以手动gbrain schema use激活。onboard 检查与 manual_only 应用策略onboard 契约定义了三种apply_policy策略含义auto_applyAutopilot 无人值守直接执行prompt_requiredAutopilot 在--auto-with-prompt模式下向用户询问manual_onlyAutopilot永不自动触发必须由用户显式提交pack_upgrade_available发出的RemediationStep携带protected: truejob: unify-types。渲染层的 render.ts 中MANUAL_ONLY_PROTECTED_JOBS白名单目前包含extract-takes-from-pages与unify-types通过 toOnboardRecommendation 将受保护步骤映射为manual_only——受保护但不在白名单中的步骤则降级为prompt_required可用--yes走--auto --yes执行。为什么 taxonomy 变更必须手动文档给出的 rationale 直击产品本质包升级改变的是大脑的分类体系taxonomy而 taxonomy 是用户的主观判断不是 Autopilot 的职责范围。即使在--auto-with-prompt模式下在正常 tick 中间突然弹出“要不要迁移你的分类体系”也是错误的 UX——用户本意是来修孤儿页面不是被打断去做分类迁移决策。显式提交才是正确的边界。作者如何编写后继 pack以一个给学术研究大脑新增researchercanonical 类型的最小示例文档原例可复制到~/.gbrain/schema-packs/gbrain-academic-v1/pack.yamlapi_version: gbrain-schema-pack-v1 name: gbrain-academic-v1 version: 1.0.0 description: Academic research brain — adds researcher canonical gbrain_min_version: 0.42.0 extends: null migration_from: pack: gbrain-base-v2 version: 1.x page_types: # Inherit gbrain-base-v2s 15 types here (or declare extends: # gbrain-base-v2 and let the merge contract in schema-packs.md merge them) - { name: person, primitive: entity, path_prefixes: [people/], expert_routing: true } - { name: company, primitive: entity, path_prefixes: [companies/], expert_routing: true } # ... all 13 other v2 canonicals ... - { name: note, primitive: concept, path_prefixes: [notes/], extractable: true } # Academic addition: - name: researcher primitive: entity path_prefixes: [researchers/] aliases: [academic, professor, scholar] extractable: false expert_routing: true mapping_rules: # All v2 mapping rules (copy from v2 yaml) # ... ~40 rules ... # Custom: relocate v2-tagged academics to researcher - { kind: retype, from_type: person, to_type: researcher, path_filter: researchers/% } # Catch-all - kind: retype from_type: *unknown* to_type: note subtype_field: legacy_type subtype: *original_type*发布后gbrain schema list可发现该包gbrain schema use gbrain-academic-v1激活它激活后任何仍在gbrain-base-v21.x上的大脑其pack_upgrade_available检查都会触发并浮出指向你包的unify-typesRemediationStep。实际的内置后继包样本是 gbrain-base-v2.yaml它当前版本为1.2.0、gbrain_min_version: 0.42.0声明migration_from: {pack: gbrain-base, version: 1.x}并在page_types中组织 15 个 canonical 类型person、company、media、tweet、social-digest、analysis、atom、concept、source、deal、email、slack、meeting、conversation、writing……以及partner_of、relates_to、supersedes、redirects_to、authored等链接类型最后附带完整的mapping_rules块——这是编写真实迁移规则的最佳参照物。锁与并发gbrain-unify是gbrain_cycle_locks表中一条专用锁行TTL 60 分钟。处理器在任何应用阶段开始前获取该锁并在finally中释放unify-types-handler.ts 头部注释与执行体明确此模式。两个并发的gbrain jobs submit unify-types调用中第二个会在锁获取阶段快速失败并给出清晰报错“could not acquire gbrain-unify db-lock (held by another process). Wait for the other unify run to complete (lock TTL: 60min)”。这与gbrain-sync锁完全同构。同时注意 handler 的入口参数unify-types-handler.tsapply默认false——即默认是 dry-run只统计would_apply而不真正改动数据。onboard 的 RemediationStep 是用户已同意的应用请求因此会在参数里显式携带apply: true见 checks.ts 的注释 #1575worker 默认 applyfalse而 remediation step 是经同意的应用必须显式带上。审计追踪每次 unify 运行都会写入~/.gbrain/audit/schema-unify-YYYY-Www.jsonlISO 周轮转与既有审计通道一致。每条记录包含迁移前后两个 pack 的身份identity格式为nameversionmanifest-sha8各 phase 的计数would_applyapplied含retype_explicit、retype_catch_all、page_to_link、page_to_alias、final_sync分项警告与完成时间戳。隐私设计页面 slug不会批量记录仅保留每条规则的sample_slugs[≤10]抽样用于取证调试的GBRAIN_AUDIT_FULL1逃生门已被提出但尚未接线。升级后的状态与回滚路径升级完成后对应 unify-types-handler.ts 的第 6 步 D13pages.type更新为新的 canonical 类型frontmatter.legacy_type完整保留供回滚使用slug_aliases表填充旧 slug → canonical 的映射slug_aliases是 migrate.ts 的MIGRATIONS数组中新引入的迁移条目links表出现新的partner_of/relates_to行源页面软删除72h TTL 可恢复活跃包通过engine.setConfig(schema_pack, target_pack)saveConfig({...existing, schema_pack: target_pack})翻转下一次gbrain onboard --check显示 ok。尚未支持的能力文档明确列出当前边界避免误用发布门禁publish-gate的子进程沙箱按 source 维度的包升级handler 接受sourceId参数但findPackSuccessors尚未透传对 canonical pack 意见不一致的跨大脑 federated mounts自动回滚当前只能手动 SQL 或gbrain restoreLLM 辅助的 mapping_rules 代码生成提议中的gbrain schema detect-mappings命令。参考索引包文件gbrain-base-v2.yaml清单扩展与迁移契约manifest-v1.ts后继包遍历器load-active.ts 的findPackSuccessorsonboard 检查checks.ts 的checkPackUpgradeAvailable渲染白名单render.ts 的MANUAL_ONLY_PROTECTED_JOBS迁移处理器unify-types-handler.tsslug_aliases 迁移条目migrate.ts类型分类学文档type-taxonomy.md相关技能skills/schema-unify/SKILL.md测试佐证schema-pack-find-pack-successors.serial.test.ts、onboard-pack-upgrade-checks.test.ts、schema-pack-unify-types-handler.test.ts、jobs-unify-types-default-dryrun.test.ts、type-unification-full-flow.test.ts【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考