Feishu Wiki Sync

by guanxu chen
5
4
3
2
1
Score: 30/100

Description

Obsidian与飞书、Notion进行同步的插件

Reviews

No reviews yet.

Stats

4
stars
62
downloads
0
forks
51
days
3
days
3
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
3
total issues
3
open issues
0
closed issues
12
commits

Latest Version

4 days ago

Changelog

0.1.3

  • 同步计划界面重构:上传到飞书、从飞书下载、存在冲突三块清晰分区
  • 冲突支持手动合并、上传、下载三种处理方式,不再自动生成副本
  • 预览与执行改为受控并发,真实预览 36.2s → 3.9s(66 篇)
  • 笔记属性(frontmatter)上行转为引用块,避免属性被当成正文
  • 精简默认授权范围,切换同步模式自动匹配最小权限
  • 启动时自动清理旧版遗留的冲突副本

安装

下载 main.js、manifest.json、styles.css 放入 .obsidian/plugins/feishu-wiki-sync/,或使用 ZIP 手动安装。

README file from

Github

Feishu Wiki Sync

将 Obsidian 仓库中的 Markdown 笔记与飞书知识库双向同步。当前维护版 0.1.3;下载安装包。

仅支持 Obsidian 桌面版 1.13.7 及以上,连接中国版飞书(open.feishu.cn)。当前不包含 Notion、飞书多维表格或国际版 Lark 接入,也没有发布到 Obsidian 社区插件市场。

从 0.1.2 起,以本轮核验的官方稳定版 1.13.7 作为支持基线,不再承诺尚未验证的 1.4.0 兼容性。历史版本及其标签保留。

隐私与网络访问

  • 插件免费、无遥测、不收集任何数据;联网只用于你配置的飞书服务:accounts.feishu.cn(登录与授权)和 open.feishu.cn(知识库、文档、文件与图片 API)。
  • 同步范围内笔记的标题与正文会传给你配置的飞书知识库;文档模式还会上传笔记引用的本地图片,正文里的外部图片链接会随内容发送。排除规则可缩小范围,首次同步前建议检查预览。
  • App Secret、用户令牌和同步映射保存在仓库 .obsidian/plugins/feishu-wiki-sync/data.json(未加密,请勿公开);自动授权会临时监听本机回调端口,完成或超时后关闭。撤销本地授权不会删除飞书中已同步的文档。
  • 调试日志(.obsidian/feishu-sync/sync.log)可能含笔记路径与接口错误信息,分享前请检查。

选择同步模式

模式 飞书中保存的内容 适合用途 边界
文档模式 可阅读、可编辑的飞书新版文档 在 Obsidian 写作,在飞书阅读和协作 会转换排版,不保证 Markdown 源码逐字不变
文件镜像(默认) 原始 .md 文件 保留原始 Markdown 内容 不上传附件,飞书侧的展示取决于 Markdown 文件预览

两种模式都支持预览、双向同步、单向推送/拉取和冲突手动合并。只同步 .md 笔记;文档模式会另行处理笔记引用的本地图片。

安装

使用构建好的安装包

  1. 从 0.1.3 Release 下载并解压 feishu-wiki-sync-0.1.3.zip,得到 feishu-wiki-sync 文件夹。

  2. 关闭 Obsidian,将该文件夹放入目标仓库的 .obsidian/plugins/ 下。最终应为:

    你的仓库/
    └── .obsidian/
        └── plugins/
            └── feishu-wiki-sync/
                ├── main.js
                ├── manifest.json
                └── styles.css
    
  3. 重启 Obsidian,在 设置 → 第三方插件 中关闭限制模式,启用 Feishu Wiki Sync。

  4. 打开该插件的设置,按下文完成飞书授权与同步目标配置。

从源码构建

需要 Node.js 20 或以上及 npm。在本仓库目录运行:

npm ci
npm run package

package 依次进行发布元数据检查、类型检查、生产构建和打包。成功后输出:

dist/
├── feishu-wiki-sync/
│   ├── main.js
│   ├── manifest.json
│   └── styles.css
├── feishu-wiki-sync-0.1.3.zip
└── SHA256SUMS

安装包只包含三个运行文件,不包含 TypeScript 源码、测试数据、账号或笔记。main.js 为可审阅的 JavaScript,内含项目及第三方许可声明。SHA256SUMS 提供文件和压缩包校验值。只需编译时运行 npm run build,输出安装目录并更新仓库根目录的 main.js。

不做离线假环境的模拟测试;验证一律在真实仓库上跑:npm run real:check -- "/完整路径/你的仓库" 用插件同一套代码读取真实笔记与真实飞书知识库,生成只读的同步计划预览(不写入任何一边),作为发布前的真实环境检查。

也可在关闭 Obsidian 后直接安装到本地仓库:

npm run install:vault -- "/完整路径/你的仓库"

脚本会先构建,再检查仓库是否已有 .obsidian 目录,备份原有的三个安装文件到插件目录内的 .backup-时间戳/,最后替换文件;账号、映射与规则不变。没有指定路径时直接报错,不会猜测安装位置。也支持通过 OBSIDIAN_VAULT 指定仓库;自定义 Obsidian 配置目录可使用 OBSIDIAN_CONFIG_DIR(相对仓库路径)。

配置飞书应用

1. 创建并发布自建应用

在 飞书开发者后台 创建企业自建应用,从“凭证与基础信息”取得 App ID 与 App Secret。

在“权限管理”中申请下列权限,与插件默认授权范围保持一致(文件镜像 3 项、文档模式 4 项):

权限标识 插件用途 需要的场景
wiki:wiki 列出知识空间、读取和创建目录节点、移动文档到知识库 两种模式必需
drive:drive Markdown 文件上传与下载、图片素材上传/下载、查询元数据,以及用户开启后的删除传播 两种模式必需
docx:document 文档模式中的创建、读取、编辑文档与图片块 仅文档模式
offline_access 用户授权后获取刷新凭证,维持登录 用户授权(应用身份无需)

素材类细粒度权限 docs:document.media:download 与 docs:document.media:upload 的作用被 drive:drive 覆盖(官方接口两者二选一即可),默认授权范围不再单独要求;如果你更倾向细粒度授权,可以在插件“授权范围”里自行加上,与后台保持一致。切换同步模式时,插件会把没有修改过的默认授权范围自动换成对应模式的最小集合。

使用“用户授权”时,需开通相应的用户身份权限;使用“应用身份”时,需开通相应的应用身份权限,且无需 offline_access。后台若提示管理员审批,完成审批后再继续。

在应用的安全设置中登记重定向 URL,默认值必须逐字一致:

http://localhost:7634/callback

在“版本管理与发布”中创建并发布版本,应用可用范围需要包含你自己的飞书账号。之后更改权限或可用范围也需要重新发布;增加用户授权范围后,需要在插件中重新授权。

文档模式的 Markdown 接口与 飞书官方 CLI 的文档实现 保持相同请求格式;插件直接调用 API,不需要安装 CLI。

2. 在 Obsidian 中授权

进入 设置 → Feishu Wiki Sync → 飞书应用与授权:

  1. 选择 用户授权(推荐),填写 App ID、App Secret。
  2. 保留上述重定向地址及默认“授权范围”。若你调整了后台权限,同步调整范围,两边必须一致;切换同步模式后默认授权范围可能已自动更新,同样保持两边一致。
  3. 点击 授权飞书账号,在浏览器中选择有权限访问目标知识库的账号并同意授权。
  4. 返回 Obsidian,确认授权成功,再点击 连接测试。

自动授权会临时启动本机回调服务,最多等待五分钟。若端口被占用,可将插件与飞书后台的回调地址同时改到另一个本机端口。也可以使用 手动粘贴授权码:浏览器完成授权后,即使回调页面无法打开,仍可复制地址栏中带 code 的完整地址或授权码到插件。

“应用身份”适合已有应用管理配置的团队:需让应用身份拥有目标知识空间及文档的权限。接口权限和知识库内容权限是两件事;开通 API 权限并不自动获得所有文档的访问权。

App Secret 和授权令牌保存在本仓库 .obsidian/plugins/feishu-wiki-sync/data.json,未额外加密。不要公开此文件,也不要在多台设备间共用正在刷新的用户令牌。界面的“撤销授权”仅清除本机保存的授权信息。

3. 选择同步目标

设置 填写方式
知识空间 space_id 推荐点击 拉取列表 后选择。手填使用知识空间 ID,不能把 /wiki/节点令牌 页面链接当作 space_id
同步根节点 推荐先在飞书建立一个专用页面,把它的 /wiki/… 链接或 node_token 填到这里;只同步其下的内容
根目录页面标题 仅根节点留空时使用;存放仓库根目录散装笔记的页面名称,留空使用仓库名
笔记同步形态 需要在飞书美观阅读与编辑时选 文档模式;需要原始源码时选 文件镜像
目录层级 推荐 镜像目录:本地文件夹对应知识库目录页面

根节点留空时会扫描整个知识空间:本地一级文件夹成为空间一级页面,根目录笔记放入“根目录页面”;空间顶层已有的笔记也可能被拉回本地。首次使用建议选择专用根节点,先检查预览范围。

切换知识空间、根节点、同步模式或目录编码设置后,会清空旧映射并重新对接。同名内容不一致时保留双方并报告冲突;这不是将原有远端内容自动迁移到新目标。

首次同步与日常使用

  1. 先选择模式、目标和排除规则,保留 同步前预览计划 开启。
  2. 打开命令面板,运行 Feishu Wiki Sync: 预览同步计划。
  3. 检查上传、拉取、删除及冲突分组,确认路径和数量。
  4. 点击 执行全部,或选择 仅拉取(不推送);查看完成报告。

发布时必须让 GitHub Release 标签与 manifest.json 的 version 完全一致(例如 0.1.3),并分别上传 main.js、manifest.json、styles.css;ZIP 供手动安装使用,不能替代这三个附件。以后更新需同步修改 package.json、锁文件、manifest.json 和 versions.json,重新构建后创建新版本。

许可证与致谢

本项目采用 MIT License,是独立社区插件,与 Obsidian、飞书或 Lark 无官方隶属关系。飞书文档和图片接口实现参考了 Lark CLI 的请求格式与素材处理流程;上游版权及许可见 第三方声明,声明同时保留在发布的 main.js 中。构建工具和类型声明不打入插件运行文件。