# Feishu Wiki Sync

将 Obsidian 仓库中的 Markdown 笔记与飞书知识库双向同步。当前维护版 **0.1.2**；[下载安装包](https://github.com/chenqaq123/ObsidianSync/releases/tag/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/`。日志可能含笔记路径和接口错误信息，分享前请检查。
- **回调和文件访问**：自动授权临时监听本机回调端口，完成、取消或超时后关闭。插件运行时读写仓库内的笔记、附件与上述配置文件，不主动扫描仓库外的文件；“打开规则文件”仅将仓库内的规则文件交给系统默认程序。
- **数据收集**：插件没有开发者后台，不收集或发送遥测、统计及广告数据；不会自行安装或更新插件或依赖。联网同步仅用于用户配置的飞书服务。撤销本地授权不会删除飞书中已同步的文档。

## 选择同步模式

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

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

## 安装

### 使用构建好的安装包

1. 从 [0.1.2 Release](https://github.com/chenqaq123/ObsidianSync/releases/tag/0.1.2) 下载并解压 `feishu-wiki-sync-0.1.2.zip`，得到 `feishu-wiki-sync` 文件夹。
2. 关闭 Obsidian，将该文件夹放入目标仓库的 `.obsidian/plugins/` 下。最终应为：

   ```text
   你的仓库/
   └── .obsidian/
       └── plugins/
           └── feishu-wiki-sync/
               ├── main.js
               ├── manifest.json
               └── styles.css
   ```

3. 重启 Obsidian，在 **设置 → 第三方插件** 中关闭限制模式，启用 **Feishu Wiki Sync**。
4. 打开该插件的设置，按下文完成飞书授权与同步目标配置。

### 从源码构建

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

```sh
npm ci
npm run package
```

`package` 依次进行类型检查、全部离线测试、生产构建和打包。成功后输出：

```text
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 后直接安装到本地仓库：

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

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

## 配置飞书应用

### 1. 创建并发布自建应用

在 [飞书开发者后台](https://open.feishu.cn/app) 创建企业自建应用，从“凭证与基础信息”取得 **App ID** 与 **App Secret**。

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

| 权限标识 | 插件用途 |
| --- | --- |
| `drive:drive` | 文件读写、查询元数据，以及用户开启后的删除传播 |
| `wiki:wiki` | 列出知识空间、读取和创建目录节点、移动文档到知识库 |
| `docx:document` | 文档模式中的创建、读取、编辑文档与图片块 |
| `docs:document.media:download` | 下载文件和文档图片素材 |
| `docs:document.media:upload` | 文档模式上传图片素材 |
| `offline_access` | 用户授权后获取刷新凭证，维持登录 |

使用“用户授权”时，需开通相应的**用户身份权限**；使用“应用身份”时，需开通相应的应用身份权限，且无需 `offline_access`。后台若提示管理员审批，完成审批后再继续。上述是本插件默认使用的权限集合，不是按单一功能裁剪的最小权限集合。

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

```text
http://localhost:7634/callback
```

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

文档模式的 Markdown 接口与 [飞书官方 CLI 的文档实现](https://github.com/larksuite/cli/tree/main/shortcuts/doc) 保持相同请求格式；插件直接调用 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. 点击 **执行全部**，或选择 **仅拉取（不推送）**；查看完成报告。

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

## 许可证与致谢

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