Obsidian Feishu Sync

智能双向同步 Obsidian 笔记与飞书（Lark）云文档。 Two-way smart sync between Obsidian Markdown notes and Feishu / Lark Docs.

这是什么

把你 Obsidian vault 里的 Markdown 笔记同步到飞书云文档。不是单向上传：插件按文件 mtime 自动判定该不该再传，把同一份本地笔记和它的飞书文档对上号，改动只走原位覆写——飞书侧的 URL 不变、分享链接不断、权限保留。

支持单文件、整目录递归（镜像目录结构）、批量恢复。

---

主要功能

✅ 智能同步（per-file）

• mtime + size 双指纹比对，未变化 → 静默跳过，不打飞书 API
• 已同步过 + 内容改了 + 飞书侧文档存活 → 原位覆写（保 URL）
• 已同步过 + 飞书侧已删 → 弹窗"重建？"
• 没同步过 → 调一次同名查重；冲突时弹决策框（默认保守新建）

✅ 文件夹同步（镜像）

• 右键 vault 文件夹 → "智能同步该文件夹"
• 递归收集所有 .md，自动在飞书侧动态创建子目录保留层级
• 子目录 token 缓存到 data.json，不会重复建
• 完成后弹结果汇总（🆕 新建 / 🔄 更新 / ⏭ 跳过 / ❌ 失败 + 失败明细）

✅ 原位覆写（in-place overwrite）

• 真的"原位"：删除飞书 docx 根级所有 block → 重新转 Markdown 为 block → 插入到原 docToken 下
• URL / 分享链接 / 权限不变
• 大于 4MB 的文档会自动报错，让你切换"删旧建新"路径
• 失败半路（旧块已删但新块未插）时降级提示，让用户选择是否改用"删旧建新"

✅ 批量恢复（rebuildSyncMapFromFeishu）

• 命令："扫描飞书重建同步映射 (修复重复文档/丢映射问题)"
• 自动扫飞书目标文件夹 + 所有缓存子目录
• 按 basename 把本地文件认领回对应飞书文档（多个同名取最新）
• 适合"早期版本累计了重复文档"的迁移场景

✅ 详细错误诊断

• 飞书 API 返回的 code / msg 全部直接透传到错误消息和开发者控制台
• HTTP 4xx 失败时打印 status + 响应体
• 同名查重失败（如缺权限）会用 console.warn 醒目告知

---

安装

手动安装

1. 在你的 vault 内进入 .obsidian/plugins/
2. 新建文件夹 obsidian-feishu-sync
3. 把本仓库的 main.js、manifest.json、styles.css 三个文件放进去
4. Obsidian → 设置 → 第三方插件 → 启用 "Feishu Sync"

从 Release 安装（推荐）

• 下载最新 release 里的 main.js、manifest.json、styles.css
• 同上放到 .obsidian/plugins/obsidian-feishu-sync/

---

配置

到设置面板"基础设置"区，只需 3 项：

字段	说明
App ID	飞书自建应用的 App ID
App Secret	飞书自建应用的 App Secret
飞书文件夹	把飞书云文档目标文件夹的链接整段粘进来即可（如 https://xxx.feishu.cn/drive/folder/fldbcXXXX），也支持纯 token

创建飞书自建应用（一次性）

1. 进 飞书开放平台
2. 创建企业自建应用 → 拿到 App ID / App Secret
3. 凭据与基础信息 → 应用功能 → 启用机器人（可选）
4. 权限管理 → 添加以下权限：
   • drive:drive —— 创建/查看/修改云文档
   • drive:drive:readonly —— 列表 / 同名查重
   • docx:document —— 编辑 docx 块（用于原位覆写）
5. 应用发布 → 创建版本并申请上线（自建应用通常自动通过）
6. 把目标飞书文件夹与该应用共享（在文件夹的"共享"面板加 App 为"可编辑"角色）

---

使用

命令面板

命令	行为
Feishu Sync: 智能同步当前文档到飞书	当前打开的 .md 走 smart-sync
Feishu Sync: 智能同步当前文件所在文件夹	当前文件父目录递归同步
Feishu Sync: 扫描飞书重建同步映射	修复重复 / 丢映射
Feishu Sync: 分享当前文档到飞书	强制创建新文档（兼容老用法）

右键菜单

• 右键 Markdown 文件 → "智能同步该页面"
• 右键文件夹 → "智能同步该文件夹 (镜像)"

自动决策

情形	动作
内容未变	跳过（不打 API）
已映射 + 内容变 + 飞书存活	静默原位覆写
已映射 + 飞书侧已删	弹"重建？"
未映射 + 同名 0 个	静默新建
未映射 + 同名 1 个	弹"覆盖 / 新建"
未映射 + 同名多个	弹候选列表

---

关于权限设置

v2.0.0 起完全移除"文档权限设置"功能。原因：

• 99% 的用户只需要"同步"本身
• 转移所有权 / 改公开权限走的是飞书 drive/v1/permissions API，权限要求复杂、出错时难以排查
• 把这部分剥离后，配置门槛从 4 项降到 3 项，错误面也小很多

如需公开 / 转移所有权，请直接到飞书云文档手工设置，或在飞书后台批量管理。

---

数据存储

data.json 保存在插件目录，结构（合成示例）：

{
  "appId": "<encrypted>",
  "appSecret": "<encrypted>",
  "folderToken": "<encrypted>",
  "uploadHistory": [],
  "syncMap": {
    "Notes/Foo.md": {
      "docToken": "doxcxxxx",
      "url": "https://xxx.feishu.cn/docx/doxcxxxx",
      "mtime": 1714000000000,
      "size": 1234,
      "syncedAt": "2026-05-08 17:00",
      "title": "Foo"
    }
  },
  "folderMap": {
    "Notes/Sub": {
      "folderToken": "fldbxxxx",
      "createdAt": "2026-05-08 17:00"
    }
  },
  "uploadCount": 0,
  "apiCallCount": 0,
  "agreedToTerms": true,
  "enableDoubleLinkMode": true,
  "debugLoggingEnabled": false
}

• 敏感字段（appId / appSecret / folderToken）用设备密钥（AES-GCM）加密
• syncMap / folderMap 不加密——只是本地索引，无凭据敏感性
• 请勿把 data.json 推到 GitHub——已写进 .gitignore

---

已知限制

1. 更新路径预处理简化：原位覆写时只剥 YAML frontmatter，Mermaid / SVG / 复杂 Wiki Link 在更新路径下保真度不如"分享当前文档"（创建新文档）路径
2. 大文档（>4MB）不能原位覆写：自动建议改用"删旧建新"
3. 空目录不在飞书侧建
4. 串行执行：大文件夹批量同步会慢，但避开飞书限频
5. getDocumentBlocks 不分页：根级子块超过 500 的极大文档可能漏算（Obsidian 笔记基本不会出现）

---

排查

启用"调试日志"后，飞书 API 错误的 code / msg 会打到开发者工具控制台（macOS Cmd+Option+I）。常见错误码：

错误码	含义	怎么办
1062xxx	folder_token 无效 / 无权限	检查飞书应用是否被加到目标文件夹
1069902	file_extension 不被接受	文件名扩展不支持，飞书只接受常见扩展
1254005 / 1254013 / 1254030	docx 文档不存在 / 已删	让插件按"重建？"弹窗处理
HTTP 403 列表失败	应用缺 drive:drive:readonly 权限	去飞书后台加权限范围

---

License

MIT License — 详见 LICENSE。

致谢

Forked from the original obshare plugin by xigua. v2.0 重构 / 新增智能同步 / 文件夹镜像 / 原位覆写 / 移除权限模块由后续维护者完成。