gbrain v0.18.0 多源大脑（Multi-source Brains）迁移与配置实战：一个数据库承载多个知识仓库

人工智能RAGAgent 记忆MCP 服务知识管理【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址https://gitcode.com/gh_mirrors/gb/gbrain点击查看免费下载本指南以 skills/migrations/v0.18.0.md 迁移文档为核心骨架结合仓库源码src/core/source-resolver.ts、src/commands/sources.ts、src/commands/migrations/v0_18_0.ts与配套实战指南 docs/guides/multi-source-brains.md系统讲解 gbrain 的sources一等公民原语从自动迁移、CLI 命令面、六级解析优先级、联邦federation语义到面向 Agent 的引用契约。读完你将在单个 gbrain 后端上同时运行统一知识大脑与用途隔离大脑并让cd ~/yc-media gbrain query X这类按目录自动定位 source 的体验直接可用。一、v0.18.0 迁移文档讲了什么sources 成为一等公民v0.18.0该迁移说明正文沿用旧版编号内部 schema 迁移为 v16/v17将source提升为数据库中的一等公民原语一个 gbrain 后端可以同时持有多个知识仓库如wiki、gstack、yc-media、garrys-list彼此拥有干净的边界。核心变化有三条行级作用域每一行pages、files、ingest_log都归属于一个sources(id)行。Slug 按 source 唯一slug 不再全局唯一而是(source_id, slug)复合唯一——两个 source 可以各自拥有topics/ai且它们是不同的页面。联邦开关federatedtrue升级后默认 source 的取值加入跨源召回池参与无前缀的默认搜索federatedfalse是隔离态仅在被--source id显式点名时才会被搜到。这同时支撑统一知识大脑wiki gstack 都联邦与用途分离大脑yc-media garrys-list 都隔离两种形态并存于同一数据库。配套的完整用户指南位于 docs/guides/multi-source-brains.md本文以迁移说明为主线同时并入该指南的可操作细节。二、机械迁移自动执行、幂等、无需人工操作迁移说明明确gbrain upgrade会链式调用gbrain apply-migrations --yes随后自动运行两条内部迁移migration v16—— 创建sources表以{federated: true}配置种子化default行并把升级前的sync.repo_path与sync.last_commit继承到default行中。该迁移是纯新增additive-only不破坏任何既有引擎代码。migration v17—— 给pages增加source_id TEXT NOT NULL DEFAULT default REFERENCES sources(id)将全局UNIQUE(slug)约束替换为复合UNIQUE(source_id, slug)同时引擎的 upsert 路径同步改为ON CONFLICT (source_id, slug)保证约束替换与写入路径原子落地。两条迁移均幂等可安全重跑。源码侧src/commands/migrations/v0_18_0.ts 中的编排器将这次升级拆成三个阶段Phase Aschema调用runMigrateOnlyCore()执行迁移链Phase Bstorage backfill检查file_migration_ledger是否存在存在则调用runStorageBackfill按台账重写存储对象PGLite 因无 files 表直接跳过该阶段在 Step 7 存储回填落地前预期可能为skippedPhase Cverify断言sources(default)行存在若已安装pages_source_slug_key复合约束还会校验不存在source_id IS NULL的脏行。最终状态由 schema 与 verify 阶段共同决定complete/partial/failed并写入已完成的迁移记录。迁移文档同时预告了后续小版本的内容v0.17.1 将基于调用方身份原语做 ACL 强制现在已随 JSONB 槽位下发access_policy强制留待身份机制设计完成v0.18.0 会同时落地会话注入.jsonl转录、容量上限提升、session PageType与按 source 的 retention/TTL。三、sourcesCLI 子命令全解迁移文档给出了完整的命令面src/commands/sources.ts 的实现与之对应gbrain sources add id --path p [--name n] [--federated|--no-federated] gbrain sources list [--json] gbrain sources remove id [--yes] [--dry-run] [--keep-storage] gbrain sources rename id new-display-name gbrain sources default id gbrain sources attach id # 在 CWD 写入 .gbrain-source gbrain sources detach # 移除 .gbrain-source gbrain sources federate id gbrain sources unfederate idSource ID 规则迁移文档规定 id 必须匹配a-z0-9?——以小写字母或数字开头结尾、中间可含连字符、最长 32 字符。源码 src/commands/sources.ts 与 src/core/source-id.ts 共享同一正则SOURCE_ID_RE校验失败会抛出可读错误如Invalid source id Wiki. Must be 1-32 lowercase alnum chars...。id 在创建后不可变rename只改显示名它被用作[source:slug]引用中的稳定引用键。list --json会输出每个 source 的页面数与联邦状态对应SourceListEntry的id / name / local_path / federated / page_count / last_sync_at字段。补充配套指南还列出了sources add的另两种形态——--url git-url一键克隆注册远程仓库以及archive / restore / archived / purge软删除 TTL 体系详见后文进阶小节。四、按目录默认.gbrain-source点文件与六级解析优先级迁移文档的核心体验承诺是像 kubectl / terraform / git 一样按上下文定位在~/.gstack/内执行gbrain sources attach gstack会写入一个只含单词gstack的.gbrain-source点文件之后在该目录或其任何子目录运行 gbrain 命令都会自动选中gstack作为默认 source。gbrain sources detach则移除该点文件。任何命令解析目标 source 时的完整优先级为显式--source id标志GBRAIN_SOURCE环境变量CWD 或任一祖先目录中的.gbrain-source点文件向上逐级查找注册 source 中local_path包含 CWD 者最长前缀胜出——嵌套的~/gstack与~/gstack/plans在更深层时解析到plans通过gbrain sources default id设置的脑级默认字面default向后兼容兜底。这套逻辑在源码 src/core/source-resolver.ts 的resolveSourceId中原样落地注释明确写着为 CLI 命令解析 source id该文件头注释标注为 v0.18.0。几个值得注意的实现细节点文件信任校验readDotfileWalk使用lstatSync而非statSync检查点文件防止符号链接被静默跟随isTrustedDotfile拒绝符号链接、他属主与世界可写文件避免多用户主机上共享目录被植入伪造点文件见 src/core/source-resolver.ts。点文件容错非法内容如下划线旧 id、手改带空白静默落入下一级而不是抛错——因为点文件常被运维手改宽容语义能保住解析链其余部分。显式层严格--source与GBRAIN_SOURCE两个显式层则相反非法值会直接抛出SourceTargetError。并发 realpath第 4 级对所有注册local_path与 CWD 做并行 realpath 解析Promise.all避免单个慢路径网络挂载、macOS 按访问安全扫描串行拖垮整个解析层成本上界是最慢的单个 source而非其总和见 src/core/source-resolver.ts。归档优先性第 4 级中活跃 source 优先于已归档 source 参与前缀匹配归档树的更深注册不会遮蔽活跃父级。resolveSourceWithTiersrc/core/source-resolver.ts返回{ source_id, tier, detail }供gbrain sources current在任何破坏性操作前展示解析到了哪个 source、为什么。此外源码还实现了resolveSourceIdEngineFree无引擎的瘦客户端走显式/环境变量/点文件三层与resolveSourceForRepoPath针对sync --repo dir以仓库目录为锚点解析而非调用方 cwd。五、联邦语义跨源召回是显式选择每个 source 行的 JSONB config 中存储federated布尔值语义如下表值含义true参与无前缀gbrain search X的结果默认 source 升级后即为此值false新 source 默认仅当通过--source id或带限定的引用时才会被检索交互式gbrain sources add会提示选择联邦状态非交互模式用--federated/--no-federated。之后可用gbrain sources federate id/unfederate id随时翻转。源码中localFederatedSourceIdssrc/core/source-resolver.ts把这个承诺转成检索作用域给定已解析 source 与命中的 tier返回[已解析source, ...其他联邦source]的展开集合但当调用方显式点名flag/env/dotfile tier或已解析 source 本身被显式隔离federatedfalse时不做展开——隔离源无论在哪个方向都不会被混入跨源读取。相关行为有test/local-federated-search-scope.test.ts与test/recall-federated-search-scope.test.ts覆盖。六、Agent 引用契约[source-id:slug]多源搜索结果天然需要可定位的引用。迁移文档规定当 Agent 拿到多源搜索结果时必须以[source-id:slug]形式引用页面。示例你提到的蒸馏协议——参见 [wiki:topics/ai] 与 [gstack:plans/multi-repo] 的出处。引用键是sources.id不可变绝不使用sources.name可变的显示名。因此即使用户执行gbrain sources rename既有引用依然有效。七、三大典型场景统一、分离与混合迁移文档将完整场景指引指向 docs/guides/multi-source-brains.md其中给出三个规范场景的可复制命令场景 1统一知识召回wiki gstack# 注册 gstack 并联邦使其加入跨源搜索 gbrain sources add gstack --path ~/.gstack --federated # 钉住目录让 gbrain sync 知道在走哪个 source cd ~/.gstack gbrain sources attach gstack # 首次同步 gbrain sync --source gstack # 此后 gbrain search retry budgets 会同时命中 wiki 与 gstack # 每个结果都带 source_id 供 Agent 正确引用结果wiki 页面与 gstack 计划分属不同source_id、不同 slug 命名空间但共享搜索面。场景 2用途分离大脑yc-media garrys-list# 两个 source 都隔离federatedfalse gbrain sources add yc-media --path ~/yc-media --no-federated gbrain sources add garrys-list --path ~/writing --no-federated # 分别钉住各自目录 (cd ~/yc-media gbrain sources attach yc-media) (cd ~/writing gbrain sources attach garrys-list) # 各自独立同步 gbrain sync --source yc-media gbrain sync --source garrys-list效果在两个目录之外搜索只返回default主脑在~/yc-media内搜索只返回 yc-media在~/writing内只返回 garrys-list。联邦是显式选择不会泄漏。需要临时跨源检索时gbrain search tech layoffs --source yc-media,garrys-list场景 3混合wiki 联邦 会话隔离# 联邦 source gbrain sources add gstack --path ~/.gstack --federated # 会话转录走隔离 source避免主导每次搜索结果 gbrain sources add sessions --path ~/.claude/sessions --no-federated八、写入保护无前缀写入默认防错解析器从不在歧义时静默选源——它会以清晰可修的错误终止。迁移配套指南进一步给出无前缀写入的防护在存在至少一个非 default source且default之外页面多于default内页面的脑上无前缀gbrain sync会拒绝执行需--source id重定向gbrain import会警告MCP stdio 在写入实际落到 default 层时打印一次进程内提示。gbrain sync --dry-run只预览不改写并输出同样的路由指引。GBRAIN_ALLOW_DEFAULT_WRITE1是脚本化流水线确需写入default时的逃生舱。源码中的assessDefaultWriteGuardsrc/core/source-resolver.ts正是这一策略的实现当nonDefaultSources 1 nonDefaultPages defaultPages时判定需要守卫deleted_at IS NULL过滤掉软删除页避免墓地分布扭曲判定查询失败则 fail-open守卫绝不能成为合法写入失败的原因。assessDefaultWriteGuardOnce用 WeakMap 按引擎记忆进程内评估结果避免大量无前缀写入反复全表聚合。九、v0.18.0 尚未包含的内容迁移文档明确列出了本次发布范围之外、将随本发布周期后续 Step 落地的能力ingest_log.source_id—— 随 Step 5 同步重写落地links.resolution_type与限定[[source:slug]]wikilink 解析 —— 随 Step 4 链接抽取重写落地files.page_slug → page_id外键重写 file_migration_ledger 存储对象前缀化 —— 随 Step 7 存储回填落地源感知的搜索去重 —— 随 Step 3 落地gbrain sources import-from-github url—— 推迟到管道稳定后的补丁版本。既有调用方继续以defaultsource 工作Agent 无需任何行为变更新能力全部通过新增的sourcesCLI 面以 opt-in 方式使用。十、宿主仓库动作与升级既有脑迁移文档明确宿主仓库无需任何动作。若宿主 Agent 通过标准gbrain sync流程管理大脑它继续作用于 default source行为无变化。要开始使用多源# 注册新 source gbrain sources add gstack --path ~/.gstack --no-federated # 钉住目录免去每次 --source 标志 cd ~/.gstack gbrain sources attach gstack # 摄取 gbrain sync --source gstack配套指南补充了两个易踩的坑git 要求--pathsource 必须是 git 仓库或仓库内子目录且路径下要有已提交的跟踪文件——git init后即使--allow-empty提交也不够注册校验读的是git ls-tree HEAD作用域内的真实跟踪内容。未满足时sources add会直接拒绝并给出可操作错误。--force跳过该校验适用于注册时自动化管道还没 git init的场景gbrain 不会替你自动git init。若同步锚点last_commit因 force-push / 历史重写 / 从零 init 而失效gbrain sync会自动检测并恢复完整重导入或对孤儿书签做树到树 diff无需手工重置。升级既有脑只需两步gbrain sources add gstack --path ~/.gstack --federated与cd ~/.gstack gbrain sources attach gstack gbrain sync——现有defaultsource 完全不受影响。十一、进阶归档、耐久性与更广阔的坐标系配套指南 docs/guides/multi-source-brains.md 还在 sources 之上提供了更多可组合能力按 source 保留/软删除gbrain sources archive id软删除并隐藏于搜索TTL 宽限期内保留数据、archived列出过期项、purge永久删除过期归档仍被 OAuth 客户端引用的 source 会以Blocked:报告需先gbrain auth revoke-client id。一键远端引导gbrain sources add wiki --url git-url --pat-file pat克隆 注册 自动加固auto-harden一次完成本地 auto-push 钩子、scripts/brain-commit-push.sh、AGENTS.md/RESOLVER.md 中的耐久性规则、30 分钟拉取 cron 与仓库级凭证harden/unharden/pull可随时审计与拆除。安全边界推送自动化只装在本机、token 按仓库接线、绝不落入仓库/远端 URL/日志/JSON 报告。坐标系区分source 是数据库内轴若需连接整个独立数据库团队发布、带独立访问策略的脑那是gbrain mounts add的brain轴两轴拓扑见 docs/architecture/brains-and-sources.md。总结v0.18.0 的 multi-source brains 是一套一个数据库、多个知识仓库、干净隔离、显式联邦的完整原语。迁移全自动且幂等CLI 面覆盖注册到耐久性全生命周期六级解析优先级复刻了 kubectl/git 的上下文习惯而[source-id:slug]引用契约保证了 Agent 在多源召回下仍能稳定、可重命名地引用来源。把本文中的命令与源码路径src/core/source-resolver.ts、src/commands/sources.ts、src/commands/migrations/v0_18_0.ts对照阅读即可在既有单源脑上无痛切换到多源拓扑。赞分享人工智能RAGAgent 记忆MCP 服务知识管理【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址https://gitcode.com/gh_mirrors/gb/gbrain点击查看免费下载相关推荐gbrain 多源大脑Multi-Source Brains实战在单一数据库中组织、联邦与隔离多个知识库gbrain 多源大脑Multi Source Brains实战在单一数据库中组织、联邦与隔离多个知识库 gbrain 允许在 一个数据库内 同时管理多个人工智能RAGAgent 记忆MCP 服务知识管理GBrain 知识组织双轴模型Brains 与 Sources 的数据库/仓库路由、拓扑设计与联邦检索实战GBrain 知识组织双轴模型Brains 与 Sources 的数据库/仓库路由、拓扑设计与联邦检索实战 GBrainGarrys Opinionate人工智能RAGAgent 记忆MCP 服务知识管理Nx 多仓库批量迁移实战指南用 nx migrate 编排器与 Agent 一次性升级多个仓库Nx 多仓库批量迁移实战指南用 nx migrate 编排器与 Agent 一次性升级多个仓库 nx migrate 是 Nx 官方提供的一键迁移命令而本仓开发工具构建工具MonorepoCLI上一篇MTKClient项目MT6765设备DAA签名验证失败问题分析与解决下一篇解决Owncast直播平台Logo缓存难题从根源到优化的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考