Notion 与 Logseq / 思源笔记(SiYuan)深度架构对比与双向链接知识库无损迁移实战:从大纲块引擎解析、EDN/JSON 数据清洗到 Formula 2.0 迁移质检看板
一、核心痛点与底层架构对比:为什么从 Logseq / 思源笔记迁往 Notion? #
在个人知识管理(PKM)与团队知识协同领域,Logseq 凭借基于本地 Markdown/Org-mode 文件的大纲(Outliner)与块级双向引用深受极客喜爱,思源笔记(SiYuan) 则以本地 SQLite + .sy JSON 块引擎、端到端加密与强大的本地离线检索在国内拥有大量用户。然而,当知识积累迈向跨成员协作、多维项目关系管理、SaaS 外部集成与结构化数据大盘时,纯本地大纲工具往往会遭遇三大瓶颈:
- 协作与权限颗粒度受限:Logseq 依赖 Git 或第三方网盘同步,多人同时编辑同一日记或长文档极易产生冲突;思源笔记虽支持自建服务端与云端同步,但缺乏 Notion 原生的单页访客权限(Guest)、团队空间隔离(Teamspaces)与细粒度数据库属性视图;
- 非结构化大纲难以直接驱动复杂业务流:在 Logseq 中用
#tag或property:: value标记的读书笔记、任务与客户线索,虽然能通过 Datalog 查询展示,但远不如 Notion 数据库的 Relation 双向关联、Rollup 穿透与 Formula 2.0 动态计算直观易用; - 跨平台连接生态差距:Notion 原生支持官方 REST API、Webhook、Notion Forms 表单与海量第三方自动化平台联动(如对比桌面本地 Markdown 工具,也可参考 Notion 与 Obsidian 深度架构对比实战 与 Notion 与 Wolai / FlowUs 无损迁移实战)。
如果直接将 Logseq 的 pages/ 目录或思源笔记导出的 Markdown 压缩包拖拽进 Notion 原生导入器,会出现满屏 id:: 65a1... 冗余属性代码、((UUID)) 块引用沦为死文本、[[页面双链]] 全部失活、以及本地 assets/ 图片相对路径断裂等问题。因此,必须采用 「两阶段预处理清洗 + Notion API 幂等写入 + Formula 2.0 质检审计」 工程化管线。
| 架构维度 | Notion | Logseq | 思源笔记(SiYuan) |
|---|---|---|---|
| 底层数据模型 | 云端关系型 Block + 多维 Database(JSON 对象树) | 本地纯文本大纲(Markdown / Org-mode + EDN 索引) | 本地块级 JSON(.sy 文件)+ SQLite 全文索引 |
| 存储与隐私模式 | 云端托管为主,企业级支持 SAML SSO 与审计日志 | 100% 本地明文文件夹,依赖 iCloud / Git 同步 | 本地优先 + 支持私有对象存储与端到端加密 |
| 双链与块引用机制 | @页面引用、Backlinks 与 Synced Block 同步块 | [[Page]] 双链与 ((block-uuid)) 任意块嵌入 | ((id '锚文本')) 块引用与虚线双向链接图谱 |
| 结构化数据能力 | 原生 Relation / Rollup / Formula 2.0 / 多视图 | 页面属性 key:: value + Datalog 高级查询 | 数据库(Attribute View)+ SQL 嵌入式查询块 |
| 外部集成与生态 | 官方 REST API、Webhook、AI Connectors 全生态 | 本地插件系统(JS)+ 开源社区生态 | 本地 Kernel HTTP API + 集市插件生态 |
二、迁移前语法映射规范:大纲块、双链与任务状态的无损对齐 #
在编写清洗脚本前,务必确立源平台专有语法向 Notion 原生 Block 与数据库属性的映射契约(更多导入基础参阅 导入数据基础指南 与 双向链接官方指南):
| 源平台语法(Logseq / 思源笔记) | 典型特征示例 | Notion 无损映射目标 | 脚本清洗与转换动作 |
|---|---|---|---|
| Logseq 块级 UUID 与折叠状态 | id:: 64f2... / collapsed:: true | 清理或转为 Toggle 折叠块 | 正则剥离 id:: 与 logbook 耗时区块;折叠项转为 toggle Block |
| Logseq 页面属性头 | tags:: #PKM, #效率 / author:: 某作者 | Notion Database 原生 Multi-select / Text 属性 | 解析文件顶部 key:: value 键值对写入页面 properties |
| Logseq 任务标记与优先级 | TODO [#A] 整理文献 / DONE | Notion to_do 块或数据库 Status 属性 | DONE 映射为 checked: true,其余转为未勾选状态并保留优先级标签 |
双链 [[Page]] 与块引用 ((id)) | 参考 [[Zettelkasten]] / ((202305-abc)) | Notion @Mention 页面提及或标准超链接 | 两阶段映射:先建页收集 Title -> Page URL 字典再回填替换 |
| 思源笔记导出标签与块属性 | {: id="2024..."} / #标签# | 清理 IAL 属性后缀,提取 #标签# 至 Tags 列 | 正则剔除 Kramdown IAL 花括号属性块,统一提取分类标签 |
| 本地附件与图片路径 |  | Notion 托管图片或外部永久图床 URL | 扫描本地相对路径,上传至 OSS/R2 CDN 后重写为 HTTPS 图链 |
三、分步骤实操:两阶段脚本清洗与 Notion API 批量入库 #
步骤 1:在 Notion 建立迁移验收总库(DB_PKM_Migration_Hub) #
在 Notion 开发者后台创建一个内部集成(参阅 创建 Notion API 集成指南),并在目标工作区参照 企业级数据库架构规范 新建 DB_PKM_Migration_Hub 数据库,包含以下核心属性:
| Notion 属性名 | 属性类型 | 迁移与质检用途 | 校验要求 |
|---|---|---|---|
笔记标题 | Title | 原 Logseq 文件名或思源文档 H1 标题 | 去除 .md 后缀及 URL 编码字符 |
Source_Key | Text | 幂等防重主键(如 logseq:pages/zettelkasten) | 写入前查重,确保脚本重跑零重复建页 |
源平台 | Select | Logseq / 思源笔记 / Journals日记 | 区分笔记来源便于分类筛选 |
知识标签 | Multi-select | 从原文件 tags:: 或 #标签# 自动提取的分类标签 | 自动去除 # 号并拆分为标准数组 |
关联引用页面 | Relation | 自关联(Self-Relation),记录解析 [[双链]] 命中的页面 | 构建 Notion 原生双向图谱 |
未解析双链数 | Number | 正文中仍残留的未命中 [[...]] 或 ((...)) 数量 | 大于 0 时在质检视图亮灯人工复核 |
失效本地图链数 | Number | 脚本未在 assets/ 中找到实体文件的图片数量 | 防止静默丢图导致知识资产受损 |
正文有效字数 | Number | 清洗掉元数据与空行后的纯文本字符长度 | 用于识别空壳索引页 |
迁移验收状态 | Status | 待质检 / 已人工复核 / 已归入正式库 | 驱动迁移验收闭环 |
步骤 2:运行 Python 两阶段清洗与 API 写入脚本 #
以下脚本完成核心第一阶段清洗与入库:读取 Logseq / 思源笔记导出目录 -> 剥离 id::、collapsed:: 与 Kramdown {: ...} 冗余属性 -> 解析页面属性与双链数量 -> 按每段 ≤ 2000 字符、单次 ≤ 100 块安全调用 Notion API 写入(限流避坑详情参阅 Notion API 速率限制与容错架构 与 通用跨平台迁移实战):
# migrate_outliner_to_notion.py
import os
import re
import time
import glob
import requests
NOTION_TOKEN = os.environ["NOTION_TOKEN"]
DATABASE_ID = os.environ["NOTION_MIGRATION_DB_ID"]
SOURCE_DIR = "./export_markdown" # Logseq pages/ 或 思源导出目录
CDN_BASE_URL = "https://cdn.example.com/pkm-assets" # 预先同步 assets/ 后的对象存储前缀
HEADERS = {
"Authorization": f"Bearer {NOTION_TOKEN}",
"Notion-Version": "2022-06-28",
"Content-Type": "application/json",
}
def notion_request(method, endpoint, payload=None):
url = f"https://api.notion.com/v1{endpoint}"
for attempt in range(4):
resp = requests.request(method, url, headers=HEADERS, json=payload, timeout=20)
if resp.status_code == 429:
wait = int(resp.headers.get("Retry-After", 2))
time.sleep(wait)
continue
resp.raise_for_status()
time.sleep(0.35) # 遵守 3 req/s 平均速率上限
return resp.json()
raise RuntimeError(f"Notion API 请求多次限流失败: {endpoint}")
def clean_outliner_markdown(raw_text, local_assets_set):
"""清洗 Logseq 属性行、思源 IAL 标记,并统计未解析双链与缺失图片"""
tags = []
body_lines = []
unresolved_links = 0
missing_images = 0
for line in raw_text.splitlines():
# 1. 提取 Logseq 顶部属性 tags::
m_tags = re.match(r"^\s*tags::\s*(.+)$", line)
if m_tags:
found = [t.strip().lstrip("#") for t in re.split(r"[,,\s]+", m_tags.group(1)) if t.strip()]
tags.extend(found)
continue
# 2. 剔除 Logseq 内部块元数据(id::, collapsed::, :LOGBOOK: 等)
if re.match(r"^\s*(id|collapsed|heading|background-color)::\s*", line):
continue
if line.strip() in (":LOGBOOK:", ":END:") or line.strip().startswith("CLOCK:"):
continue
# 3. 剔除思源笔记 Kramdown IAL 属性后缀 {: id="xxx" ...}
line = re.sub(r"\{:\s*[^}]+\}", "", line)
# 4. 转换 Logseq 任务语法 "- TODO " / "- DONE "
line = re.sub(r"^(\s*)-\s+(?:TODO|LATER|NOW|DOING)\s+", r"\1- [ ] ", line)
line = re.sub(r"^(\s*)-\s+DONE\s+", r"\1- [x] ", line)
# 5. 检查本地图片相对路径并重写为永久图床 URL
def replace_img(match):
nonlocal missing_images
alt, img_path = match.group(1), match.group(2).strip()
filename = os.path.basename(img_path.split("?")[0])
if img_path.startswith("http"):
return match.group(0)
if filename in local_assets_set:
return f""
missing_images += 1
return f"[缺失图片: {filename}]"
line = re.sub(r"!\[([^\]]*)\]\(([^)]+)\)", replace_img, line)
# 6. 统计残留未映射的 ((block-uuid)) 或 [[双链]]
unresolved_links += len(re.findall(r"\(\([0-9a-f-]{8,}\)\)", line))
body_lines.append(line)
cleaned = "\n".join(body_lines).strip()
return cleaned, list(dict.fromkeys(tags)), unresolved_links, missing_images
def text_to_notion_blocks(cleaned_text):
"""将清洗后文本拆分为合规 Notion Block(单段严格 <= 1900 字符)"""
blocks = []
for line in cleaned_text.splitlines():
s = line.rstrip()
if not s:
continue
# 剥离大纲前导 "- " 转换为 bulleted_list_item
stripped = s.lstrip()
if stripped.startswith("- [ ] ") or stripped.startswith("- [x] "):
checked = stripped.startswith("- [x] ")
content = stripped[6:][:1900]
blocks.append({"object": "block", "type": "to_do", "to_do": {"checked": checked, "rich_text": [{"text": {"content": content}}]}})
elif stripped.startswith("- "):
blocks.append({"object": "block", "type": "bulleted_list_item", "bulleted_list_item": {"rich_text": [{"text": {"content": stripped[2:][:1900]}}]}})
elif stripped.startswith("## "):
blocks.append({"object": "block", "type": "heading_2", "heading_2": {"rich_text": [{"text": {"content": stripped[3:][:1900]}}]}})
else:
blocks.append({"object": "block", "type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": stripped[:1900]}}]}})
return blocks
def run_migration():
assets_dir = os.path.join(SOURCE_DIR, "assets")
local_assets = set(os.listdir(assets_dir)) if os.path.isdir(assets_dir) else set()
for md_path in glob.glob(os.path.join(SOURCE_DIR, "**", "*.md"), recursive=True):
rel_key = f"pkm:{os.path.relpath(md_path, SOURCE_DIR)}"
title = os.path.splitext(os.path.basename(md_path))[0]
with open(md_path, "r", encoding="utf-8") as f:
raw = f.read()
cleaned, tags, unresolved, missing_imgs = clean_outliner_markdown(raw, local_assets)
blocks = text_to_notion_blocks(cleaned)
# 幂等查重
q = notion_request("POST", f"/databases/{DATABASE_ID}/query", {
"filter": {"property": "Source_Key", "rich_text": {"equals": rel_key}}
})
if q.get("results"):
continue
# 写入首批最多 90 个块,超长部分循环 append
created = notion_request("POST", "/pages", {
"parent": {"database_id": DATABASE_ID},
"properties": {
"笔记标题": {"title": [{"text": {"content": title[:200]}}]},
"Source_Key": {"rich_text": [{"text": {"content": rel_key}}]},
"源平台": {"select": {"name": "Logseq"}},
"知识标签": {"multi_select": [{"name": t[:50]} for t in tags[:10]]},
"未解析双链数": {"number": unresolved},
"失效本地图链数": {"number": missing_imgs},
"正文有效字数": {"number": len(cleaned)},
"迁移验收状态": {"status": {"name": "待质检"}},
},
"children": blocks[:90],
})
for idx in range(90, len(blocks), 90):
notion_request("PATCH", f"/blocks/{created['id']}/children", {"children": blocks[idx:idx + 90]})
if __name__ == "__main__":
run_migration()
第二阶段图谱回填提示:完成首轮全量写入并获取所有页面的
{title: page_id}字典后,二次遍历正文中的[[PageName]],通过pages.update将命中的关联页面写入关联引用页面(Relation 属性),即可在 Notion 中重建出结构化的知识网络。
四、Formula 2.0 迁移质检门禁与知识资产健康度看板 #
面对数千篇迁移入库的笔记,不可能逐篇人工翻阅。在 DB_PKM_Migration_Hub 中配置 Formula 2.0 属性 迁移质检门禁(语法详查 Notion 公式基础 与 Formula 2.0 速查手册),自动识别断链、丢图、空壳页面与孤岛节点:
lets(
linksBroken, prop("未解析双链数"),
imgsBroken, prop("失效本地图链数"),
wordCount, prop("正文有效字数"),
relCount, prop("关联引用页面").length(),
status, prop("迁移验收状态"),
ifs(
imgsBroken > 0,
style("🚨 存在 " + imgsBroken + " 张本地图片缺失 · 严禁删除原本地库", "red", "bold"),
linksBroken > 0,
style("🟠 残留 " + linksBroken + " 处未解析块引用 ((uuid)) · 需人工补链", "orange", "bold"),
wordCount < 30 && relCount == 0,
style("🟡 空壳或纯索引孤岛页(仅 " + wordCount + " 字)· 建议合并或清理", "orange"),
status == "已归入正式库" && relCount >= 1,
style("🟢 迁移完好 · 图链完整且已建立 " + relCount + " 条双链关联", "green", "bold"),
status == "已归入正式库",
style("🔵 内容完好 · 建议补充至少 1 条关联关系消除知识孤岛", "blue"),
style("⏳ 待人工抽检核验 · 图文指标初步正常", "gray")
)
)
五、迁移高频故障排查与双平台共存建议(Checklist) #
在执行 Logseq 或思源笔记向 Notion 迁移及后续日常运维时,若遇以下典型异常可快速排查(更多报错参阅 Notion 常见故障排查手册):
- Logseq
pages/目录包含大量带有%2F编码的文件名(如React%2FHooks.md)导致双链无法匹配:- 根因:Logseq 使用斜杠表示命名空间层级(Namespace),在文件系统存储时会将
/自动转义为%2F; - 解法:在解析
title与构建双链映射字典时先调用urllib.parse.unquote(title)还原真实命名空间路径,并在 Notion 中按顶级命名空间归档至对应目录或 Tag。
- 根因:Logseq 使用斜杠表示命名空间层级(Namespace),在文件系统存储时会将
- 思源笔记导出 Markdown 后,公式块与代码块高亮错乱或出现成串
$$换行异常:- 根因:思源笔记内部采用行内块渲染部分行间 LaTeX 公式且带有缩进,与 Notion
equation块规范不完全一致; - 解法:在清洗脚本中匹配独立成段的
$$\n...\n$$块,将其显式映射为 Notion 原生equationBlock 对象而非普通段落文本。
- 根因:思源笔记内部采用行内块渲染部分行间 LaTeX 公式且带有缩进,与 Notion
- 导入超深嵌套的大纲列表(超过 4~5 级缩进)时 Notion API 报错
400 validation_error:- 根因:Notion API 单次请求限制最多嵌套 2 层
children子块(即父块 -> 子块 -> 孙块),直接提交 5 层嵌套 JSON 会被网关拒绝; - 解法:将 3 层及以上的深层大纲先拆平或先创建顶级页面,再递归按子块
block_id逐层调用PATCH /blocks/{id}/children挂载,或者将折叠长分支收口进 Notiontoggle切换块(用法参考 切换器官方指南)。
- 根因:Notion API 单次请求限制最多嵌套 2 层
- 思源笔记 / Logseq 重度用户如何与 Notion 长期混合共存?
- 最佳实践:将 隐私草稿、离线科研笔记、千行大纲头脑风暴 留在本地 Logseq/思源,仅将 已完成沉淀的常青笔记(Evergreen Notes)、团队协作 SOP 与项目台账 通过上述单向增量脚本(锚定
Source_Key幂等更新)同步至 Notion 对外协作空间,兼顾本地隐私安全与云端协同效率。
- 最佳实践:将 隐私草稿、离线科研笔记、千行大纲头脑风暴 留在本地 Logseq/思源,仅将 已完成沉淀的常青笔记(Evergreen Notes)、团队协作 SOP 与项目台账 通过上述单向增量脚本(锚定
核心手册与速查工具矩阵
高频速查手册与生产力工具直达常见问题与答疑 (FAQ)
高频疑难解析与避坑指南完全不需要。绝大多数核心功能在免费 Free 计划中均可完整体验与实操练习,无需额外付费购买 Plus 或团队版。