资源描述
一款专为知识工作者设计的双向同步工作流，实现 Notion AI 生成内容与 Obsidian 本地知识库的自动化协同：自动抓取 Notion 页面中 AI 生成文本、结构化转换为标准 Markdown + YAML frontmatter、同步嵌入附件（图片/PDF）、保留反向链接语义，并支持 Obsidian 编辑后回写至 Notion。适用于构建 AI 增强型第二大脑、学术研究笔记闭环及团队文档轻量协同。
详细内容
# Notion AI → Obsidian Sync 工作流指南
## 工作流概述
本工作流基于社区开源方案（GitHub: `obsidianmd/obsidian-releases/tree/workflow-notion-sync`），通过 CLI 工具 + 配置化脚本，建立 Notion（含 AI 生成内容）与 Obsidian 的**准实时、双向、语义保真**同步通道。核心能力包括：
- 自动识别并提取 Notion 中由 `/ai` 或 `/ask` 指令生成的块（Block）内容；
- 将富文本智能降级为 Markdown，保留标题层级、列表、代码块、引用等结构；
- 注入标准化 YAML frontmatter（含 `notion_id`、`last_edited_time`、`sync_status` 等元字段）；
- 同步内联附件（如截图、PDF）至 Obsidian `assets/` 目录并修正路径；
- 解析 Notion 页面内反向链接（`@PageName`）并映射为 Obsidian `[[PageName]]` 格式。
> ⚠️ 注意：该工作流依赖 Notion API（需开启 Integration、分配权限）及 Obsidian Community Plugin 支持，**非图形界面插件**，需命令行环境运行。
## 分步骤操作说明
### 步骤 1：环境准备与依赖安装
- 安装 Node.js ≥ v18（推荐 LTS 版本）；
- 克隆官方工作流仓库：`git clone --branch workflow-notion-sync https://github.com/obsidianmd/obsidian-releases.git`；
- 进入子目录：`cd obsidian-releases/workflow-notion-sync`；
- 执行依赖安装：`npm install`；
- 确保系统已安装 `python3`（部分附件处理脚本依赖）。
### 步骤 2：配置 Notion Integration
- 登录 [Notion Developer Portal](https://developers.notion.com/) → 创建新 Integration；
- 设置名称（如 `Obsidian-Sync-Bot`），启用 `Pages`、`Blocks`、`Files` 权限；
- 在 Integration 页面复制 `Internal Integration Token`；
- 在 Notion 工作区中，将该 Integration 添加为成员，并授予目标数据库/页面「编辑」权限。
### 步骤 3：初始化同步配置文件
- 复制模板配置：`cp config.example.json config.json`；
- 编辑 `config.json`：
- 填入 `notion_token`（上一步获取的 Token）；
- 设置 `database_id`（Notion 中用于存放 AI 笔记的 Database ID，可通过 URL `https://www.notion.so/.../xxx?v=yyy` 提取 `xxx`）；
- 指定 `obsidian_vault_path`（绝对路径，如 `/Users/name/Documents/ObsidianVault`）；
- 配置 `assets_dir`（默认 `assets/`，需与 Obsidian 设置一致）；
- 开启 `bidirectional_sync: true` 启用回写能力。
### 步骤 4：首次全量同步与验证
- 运行同步命令：`npm run sync`；
- 工具将：
- 扫描 Notion Database 中所有标记为 `AI Generated: Yes`（或含 `/ai` 块）的页面；
- 生成 `.md` 文件（文件名 = Notion 页面 Title，去重+URL-safe）；
- 下载并重命名附件（格式：`{notion_block_id}_{original_name}`）；
- 自动创建 `index.md` 汇总页（含同步状态看板）；
- 检查 Obsidian Vault 根目录是否生成 `notion-sync/` 子目录，打开任意 `.md` 文件确认 frontmatter 和链接渲染正常。
### 步骤 5：启用增量监听与双向回写
- 启动监听服务：`npm run watch`（后台持续轮询 Notion API 变更，间隔 30s）；
- 在 Obsidian 中编辑同步文件后，保存时触发 `on-save` hook（需提前在 Obsidian 设置 → Core Plugins 中启用 `Templates` 插件，并确保 `config.json` 中 `enable_obsidian_hook: true`）；
- 修改将自动打包为 Notion Block Update 请求，仅更新变更段落（非全量覆盖），保留 Notion 原有评论、协作痕迹；
- 查看 `logs/sync.log` 确认回写成功状态（HTTP 200 + `updated_blocks: N`）。
## 注意事项与最佳实践
- ✅ **强制要求**：Notion 页面必须启用 `AI Generated` 属性（Select 类型），值设为 `Yes`，否则不会被纳入同步范围；
- ✅ 推荐在 Obsidian 中使用 `Dataview` 插件查询同步状态：````dataview TABLE file.ctime, notion_id FROM "notion-sync" WHERE file.name != "index" ````；
- ⚠️ 避免手动修改 `.md` 文件中的 `notion_id` 或 `last_edited_time` 字段，将导致冲突检测失效；
- ⚠️ 图片同步依赖 Notion Public Share Link —— 确保 Integration 对应页面已开启「Share to web」或使用企业版 Private API；
- 💡 最佳实践：为 Notion Database 添加 `Status` 属性（Options: `Draft`/`Reviewed`/`Archived`），工作流可配置 `status_filter: ["Draft", "Reviewed"]` 实现分阶段同步。
## 常见问题提示
- **Q：同步后附件显示为 broken link？**
A：检查 `config.json` 中 `assets_dir` 是否与 Obsidian 设置 → `Files & Links` → `Attachment folder` 完全一致（区分大小写、末尾斜杠）；并确认 Notion 图片已发布为公开链接（非登录态受限）。
- **Q：Obsidian 编辑后未回写到 Notion？**
A：确认 `config.json` 中 `enable_obsidian_hook` 为 `true`；检查 Obsidian 控制台（Ctrl+Shift+I → Console）是否有 `NotionSync: Hook registered` 日志；验证 `notion_token` 是否具备对应页面的 `editor` 权限。
- **Q：YAML frontmatter 中 `tags` 为空？**
A：Notion 原生不支持 Tag 属性，需在 Database 中添加 `Tags` 多选属性，并在 `config.json` 中配置 `notion_tag_property: "Tags"` 映射。
- **Q：同步速度慢 / 频繁 429 错误？**
A：Notion API 限频（5 req/sec），请在 `config.json` 中调高 `rate_limit_delay_ms`（默认 200ms），或启用 `batch_mode: true` 减少请求次数。