GBrain 通用数据迁移实战指南：将 Obsidian、Notion、Logseq 等任意笔记系统无损迁入

GBrain 通用数据迁移实战指南将 Obsidian、Notion、Logseq 等任意笔记系统无损迁入【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain本篇技术指南围绕 GBrain 仓库内建的数据迁移技能plugin/skills/migrate/SKILL.md展开它面向“从任意 wiki、笔记工具或知识大脑系统迁入 GBrain”这一场景Obsidian、Notion、Logseq、纯 Markdown 目录、CSV、JSON、Roam 均可作为迁移源。读完本文你将掌握一套可复制的六阶段迁移流水线评估 → 映射规划 → 样例测试 → 批量导入 → 验证 → 建链理解 wikilink、block ref、tag 等跨系统引用如何被转换为 GBrain 的原生链接并能通过gbrain extract links与 MCP 工具put_page、add_link、add_tag、query 等独立完成一次带健康检查与往返验证的完整迁移。迁移技能定位一个技能、多种来源、同一契约在 GBrain 的技能体系中migrate是一个声明式技能包其前置元数据定义在 SKILL.md 的文件头name: migrate description: Universal migration from Obsidian, Notion, Logseq, markdown, CSV, JSON, Roam triggers: - migrate from - import from obsidian - import from notion tools: - put_page - search - add_link - add_tag - sync_brain mutating: truemutating: true明确标注这是一项会写入数据的操作tools列表限定了迁移过程中可调用的能力集合全部对应 GBrain 的 MCP 工具层见 src/mcp/dispatch.ts 中的工具分发实现。触发词migrate from、import from obsidian、import from notion使其能在对话中按意图被自动唤起。迁移契约四条不可违反的铁律无论源系统是哪种迁移都必须满足以下契约Contract源数据永不修改或删除迁移只做加法additive only。迁移过程可能并行处理数千个文件任何对源库的写操作都会让“失败后可重来”变成“数据已破坏”。每个迁移页面都需经过往返验证写入 GBrain → 读回 → 抽查。不是写完即完事而是确保写入的内容能够被完整读回且没有丢失字段。源系统的交叉引用必须转换为 GBrain 等价物wikilink、block ref、tag 是知识图谱的“边”丢弃它们等于丢弃图谱本身。批量执行前必须在样例5–10 个文件上测试迁移结束后必须做健康检查核对页面数量、链接完整性与 embedding 覆盖率。这四条契约与 GBrain 底层“知识图谱优先”的存储模型一致页面pages之外links表承载 typed 边、timeline_entries承载时间线迁移是否成功不只看文件数还看图谱结构是否完整。支持的源系统矩阵技能内置了七类源系统及对应的迁移策略源格式策略ObsidianMarkdown [[wikilinks]]直接导入将 wikilink 转换为 GBrain 链接Notion导出的 Markdown 或 CSV解析 Notion 的导出目录结构Logseq带((block refs))的 Markdown将 block ref 转换为页面链接纯 Markdown任意 .md 目录将目录直接导入 GBrainCSV表格数据将列映射到 frontmatter 字段JSON结构化数据将键映射到页面字段RoamJSON 导出将 block 结构转换为页面从实现角度看Obsidian/Logseq/纯 Markdown 都落在同一条路径上Markdown 目录导入 链接抽取。真正区分它们的是链接语法的差异——这正对应源码中多套正则的并存详见下文 Obsidian 章节。六阶段迁移流水线SKILL.md 将任何一次迁移规范为六个阶段评估源Assess the source什么格式多少文件目录结构如何规划映射Plan the mapping源字段如何映射到 GBrain 字段——type、title、tags、compiled_truth、timeline 等。样例测试Test with a sample导入 5–10 个文件从 GBrain 读回并导出验证。批量导入Bulk import将整个目录导入 GBrain。验证Verify检查 GBrain 健康状态与统计信息抽查页面。建链Build links从内容中抽取交叉引用在 GBrain 中创建 typed 链接。其中第 3 阶段是成本关键清理数百个错误页面的代价远高于先花几分钟验证 10 个文件。第 6 阶段是价值关键导入的 markdown 只是“文档”抽取出的 typed 链接才是“知识图谱”。Obsidian 迁移wikilink 原生解析的实现内幕Obsidian vault 本质上是带[[wikilinks]]的 Markdown 目录因此迁移分为两步第一步导入 vault 目录将 vault 目录作为 Markdown 目录导入 GBrain对应“纯 Markdown”路径。这一步通过 put_page / sync_brain 等写工具完成页面落库。第二步用 extract links 织图v0.12.1 原生支持gbrain extract links --source db --dry-run | head -20 # preview gbrain extract links --source db # commit--dry-run先预览将要创建的边而不落库head -20只取前 20 条核对效果确认无误后再正式提交。该命令的完整形态定义在 src/commands/extract.ts 的头部注释中gbrain extract links [--source fs|db] [--dir brain] [--dry-run] [--json] [--type T] [--since DATE] gbrain extract timeline [--source fs|db] [--dir brain] [--dry-run] [--json] [--type T] [--since DATE] gbrain extract all [--source fs|db] [--dir brain] [--dry-run] [--json] [--type T] [--since DATE]--source有两个取值fs默认直接遍历磁盘上的 Markdown 文件和db从引擎迭代页面适用于没有本地 checkout 的场景例如运行中的 MCP server。extract links会原生解析两种 wikilink 形式——[[relative/path]]与[[relative/path|Display Text]]——同时兼容标准 Markdown 链接text。源码层面FS 路径的语法解析集中在extractMarkdownLinkssrc/commands/extract.ts 中extractMarkdownLinks一节标准 Markdown 链接走\[([^\]])\]\(([^)#]\.md)(?:#[^)]*)?\)正则要求目标以.md结尾wikilink 走\[\[([^|\]]?)(?:\|[^\]]*?)?\]\]正则|之后的文本作为显示名两者都会剥离#heading段内锚点、跳过含://的外部 URLwikilink 缺.md后缀时自动补上.mdsuffix is inferred automatically兼容 ObsidianuseMarkdownLinks模式下百分号编码的目标路径如Alice先做decodeURIComponent再解析。祖先搜索宽容解析省略../的 wiki 库维基类知识库中作者常常“以 wiki 根为参照”书写相对路径省略一个或多个前导../。resolveSlugsrc/commands/extract.ts 中resolveSlug一节实现了宽容解析命中顺序如下精确路径join(fileDir, relTarget)按书写原样解析祖先搜索ancestor-search逐级剥掉当前页面目录fileDir的前导路径段后重试直到找到匹配 slug 或剥到根目录。解析时还会同时尝试“原样候选”与“同步 slugify 后的候选”slugifyPath以兼容 Obsidian 原始路径与 GBrain 规范化 slug 之间的差异例如[[llm-wiki/entities/AI 3.0]]→llm-wiki/entities/ai-3.0。当祖先搜索仍失败时可开启global_basename回退到 basename 全库匹配——这由link_resolution.global_basename配置控制默认关闭以保持向后兼容。DB 路径与 typed 链接推断当使用--source db时抽取走的是 src/core/link-extraction.ts 中的extractPageLinks它包含多轮pass正则Pass 1Name标准链接支持任意../深度与引擎 slug 形式Pass 1b同目录链接Name、Name等Pass 2a限定源 wikilink[[source-id:dir/slug|Display]]v0.17.0用于多源拓扑Pass 2b常规 wikilink[[dir/slug]]/[[dir/slug|Display]]受DIR_PATTERN白名单约束people、companies、meetings、concepts、deal、project、media 等规范顶层目录Pass 2c通用[[bare-name]]wikilink无目录门禁需经 SlugResolver 的 basename 匹配解析v0.40.8.2 之后对带斜杠的裸 wikilink 也直接产出 typed 候选Pass 3frontmatter 字段驱动的 typed 边如key_people、investors等字段 → 图边。抽取出的每条边还会经过确定性、零 LLM 的链接类型推断WORKS_AT_RE、INVESTED_RE、FOUNDED_RE、ADVISES_RE等一组正则根据链接上下文语义worked at、invested in、founder of、advises判定边类型works_at、invested_in、founded、advises、mentions 等并配合页面角色先验partner/investor/advisor/employee 页级描述提升推断准确率同时支持中文模式如任职|就职|担任→ works_at。这意味着从 Obsidian 迁入后[[公司名]]这类链接不只会成为普通引用还会被自动类型化为知识图谱上有语义的边。Obsidian 特有映射#tag标签 → GBrain 标签add_tagFrontmatter 属性 → GBrain frontmatter附件图片、PDF被记录但不随正文导入由独立的文件存储机制另行处理。Notion 迁移导出结构与 UUID 清理Notion 的迁移路径与 Obsidian 不同因为导出物是“目录结构”而非“vault 约定”从 Notion 导出Settings Export Markdown CSVNotion 导出会产生嵌套目录且文件名中带 UUID如Page-Name-1a2b3c4d.md从文件名剥离 UUID以获得干净的 slug——否则 slug 会被 32 位随机串污染影响链接可读性与检索这与 GBrain 的 slug 规范见 src/core/sync.ts 的slugifyPath/slugifySegment一致slug 应当是可读、确定、无随机尾巴的将 Notion 的 database 属性映射到 frontmatter导入清理后的目录。关键点在第 3 步不要依赖“导出即正确”UUID 剥离是 Notion 迁移中必须的预处理步骤它决定后续所有链接能否落到可读 slug 上。CSV 迁移表格数据 → frontmatter 页面对于 CRM 导出、联系人列表等表格数据CSV 的每一行创建一个页面列值作为 frontmatter指定一个列为 slug例如 name指定另一个列为 compiled_truth例如 notes将每个页面存入 GBrain。这一映射思路对 JSON 同样适用键 → 页面字段区别只是数据源的嵌套结构不同。Logseq 与 Roamblock 引用体系的转换Logseq使用((block refs))语法block 引用需要被转换为指向页面的链接——迁移时识别((id))形式的引用并解析到其宿主页面RoamJSON 导出以 block 树结构组织需将 block 结构扁平化为页面。这两类源与 Obsidian 共享同一条“建链”终点所有交叉引用最终都会成为 GBrain 的 typed 链接只是语法解析规则不同。迁移后验证五步健康检查任何迁移完成后必须执行以下验证Verification核对统计检查 GBrain 统计信息确认页面数量与源一致get_stats健康检查检查孤儿页面与缺失的 embeddingget_health往返验证从 GBrain 导出页面核对内容往返无损抽查从 GBrain 读回 5–10 个页面逐一检查get_page搜索测试在 GBrain 中搜索“你知道确实存在于数据中的某人/某物”确认检索可用query。最后一步尤其容易被忽略导入成功 ≠ 检索可用。embedding 未生成、frontmatter 未索引都会导致“数据在里面但搜不到”。这一步与源码中extract/embed命令的分工相呼应——extract只负责抽链接与时间线embedding 覆盖率的检查由健康检查与统计类工具负责。反模式清单跳过样例测试直接批量导入在 5–10 个文件上验证之前绝不导入全量数据清理数百个错误页面的代价是巨大的破坏源数据迁移只做加法绝不修改、移动或删除源文件忽略交叉引用源系统的 wikilink、block ref、tag 必须转换为 GBrain 等价物丢弃它们等于丢掉知识图谱跳过验证没有导入后健康检查、页面数对比与抽查读回的迁移是不完整的。迁移报告输出格式每次迁移都应产出一份结构化报告SKILL.md 给出了标准模板MIGRATION REPORT -- [source] - GBrain Source: [format] ([file count] files, [size]) Mapping: [field mapping summary] Sample Test (N files): - Imported: N/N - Round-trip verified: N/N - Cross-refs converted: N Bulk Import: - Total imported: N - Skipped (duplicates/errors): N - Links created: N - Tags migrated: N Verification: - Page count match: [yes/no] - Health check: [pass/fail] - Search test: [query] - [result count] hits该模板将六阶段流水线压缩为三段可审计的数字样例测试结果、批量导入统计、最终验证结论。任何一步的 “N/N” 不齐或 “pass/fail” 为 fail都应回退排查而不是宣布完成。底层工具集与源码对应技能依赖的工具全部落在 GBrain 的 MCP 工具层分发实现在 src/mcp/dispatch.ts工具职责迁移阶段put_page写入/更新页面样例与批量导入get_page从 GBrain 读回页面往返验证、抽查add_link在实体间创建链接建链add_tag给页面打标签标签迁移get_stats获取 GBrain 统计页面数核对get_health健康检查孤儿、缺失 embedding验证query搜索 GBrain搜索测试sync_brain同步大脑目录 → 库批量导入注意工具列表与mutating: true的配合put_page、add_link、add_tag、sync_brain 均为写操作因此技能被明确标记为 mutating任何触发都会在写路径上接受常规防护。结语从 Obsidian 的[[wikilinks]]到 Notion 的 UUID 命名、从 CSV 的列映射到 Roam 的 block 树GBrain 的 migrate 技能用“同一套契约 分源策略 统一的 typed 链接终点”覆盖了几乎所有主流笔记系统。它的核心价值不在于“搬文件”而在于把源系统里隐式的引用关系显式化为 GBrain 知识图谱上的 typed 边——这正是 src/commands/extract.ts 与 src/core/link-extraction.ts 两处实现反复打磨的宽容的 wikilink 解析、祖先搜索、零 LLM 的确定性类型推断以及可审计的批处理与验证。迁移完成后旧笔记不再是一个待检索的文档堆而是一张可直接查询、可被query命中的知识图谱。【免费下载链接】gbrainGarrys Opinionated OpenClaw/Hermes Agent Brain项目地址: https://gitcode.com/gh_mirrors/gb/gbrain创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考