Feishu Wiki Sync

Feishu Wiki Sync

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

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

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

隐私与网络访问

• 账户与费用：插件本身免费，无广告或付费解锁；需要飞书账号、企业自建应用及目标知识库的访问权限。飞书自身的服务费用、容量和 API 配额由飞书决定。
• 联网范围：accounts.feishu.cn 用于浏览器登录、授权和刷新令牌；open.feishu.cn 用于知识库、文档、文件及图片 API。下载可能由飞书重定向至其素材服务。文档中的外部图片链接会随正文发送给飞书，飞书可能按其规则加载这些链接。
• 上传内容：同步范围内笔记的标题、目录与正文会传给所配置的飞书知识库；文档模式还上传笔记引用的本地图片。排除规则可缩小范围；第一次同步前应检查预览。文档会由飞书云服务处理和存储，包括文档模式使用的 docs_ai 接口。
• 本地存储：App Secret、用户令牌和同步映射通过 Obsidian 插件配置保存，默认位置为 .obsidian/plugins/feishu-wiki-sync/data.json，未额外加密。自定义配置目录时，data.json 随 Obsidian 的配置目录存放；规则、冲突副本和调试日志仍位于仓库内 .obsidian/feishu-sync/。日志可能含笔记路径和接口错误信息，分享前请检查。
• 回调和文件访问：自动授权临时监听本机回调端口，完成、取消或超时后关闭。插件运行时读写仓库内的笔记、附件与上述配置文件，不主动扫描仓库外的文件；“打开规则文件”仅将仓库内的规则文件交给系统默认程序。
• 数据收集：插件没有开发者后台，不收集或发送遥测、统计及广告数据；不会自行安装或更新插件或依赖。联网同步仅用于用户配置的飞书服务。撤销本地授权不会删除飞书中已同步的文档。

选择同步模式

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

安装

使用构建好的安装包

1. 从 0.1.2 Release 下载并解压 feishu-wiki-sync-0.1.2.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.2.zip
└── SHA256SUMS

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

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

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

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

配置飞书应用

1. 创建并发布自建应用

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

在“权限管理”中申请下列权限，与插件默认授权范围保持一致：

使用“用户授权”时，需开通相应的用户身份权限；使用“应用身份”时，需开通相应的应用身份权限，且无需 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. 选择同步目标

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

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

首次同步与日常使用

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

社区提交准备及本轮兼容性验证见 社区上架说明。发布时必须让 GitHub Release 标签与 manifest.json 的 version 完全一致（例如 0.1.2），并分别上传 main.js、manifest.json、styles.css；ZIP 供手动安装使用，不能替代这三个附件。以后更新需同步修改 package.json、锁文件、manifest.json 和 versions.json，重新构建后创建新版本。

许可证与致谢

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