飞书云文档同步配置指南
为「微信发布助手」配置飞书同步，实现 Obsidian 笔记一键转换为飞书云文档（docx）。
本同步方案采用安全、稳定的飞书自建应用机器人模式（Bot Identity Mode）进行 API 调用，数据传输均在本地进行，不经过第三方中转，安全放心。
配置项概览
| 输入项 | 对应值说明 | 获取来源 |
|---|---|---|
| App ID | 自建应用的标识（以 `cli_` 开头） | 飞书开放平台 → 凭证与基础信息 |
| App Secret | 自建应用的 API 凭证密钥 | 飞书开放平台 → 凭证与基础信息 |
| 同步目标文件夹 Token | 飞书云盘中某个文件夹链接末尾的字符 | 云盘文件夹的浏览器 URL 尾部 |
| 用户 ID (User ID) | 您个人的飞书用户标识（如 `abc1234`） | 飞书管理后台 → 组织架构 → 成员与部门 |
第一步：创建飞书自建应用
1. 打开并登录 飞书开放平台开发者后台。
2. 点击右上角 「创建自建应用」。
3. 填写应用名称（例如：`微信发布助手`），上传图标并完成创建。
4. 创建成功后，进入 「凭证与基础信息」，复制 App ID 和 App Secret，并填入本插件的飞书设置项中。
第二步：开启「机器人」能力
1. 在应用详情页的左侧菜单，点击 「应用功能」 → 「机器人」。
2. 点击 「启用机器人」 开关。这一步是为了让应用获得「群机器人」的身份权限。
⚠️ 许多用户因为漏掉此步，导致后面调用 API 时报 403 错误。
第三步：开通云空间及云文档权限
1. 进入左侧菜单中的 「权限管理」。
2. 在应用权限列表中，依次搜索并勾选开通以下两个最重要的权限项（同时勾选应用身份和用户身份）：
drive:drive：查看、编辑云空间所有文件（使应用能够读写云盘）docs:document:import：导入为文档（允许应用创建 docx 云文档）
第四步：创建应用版本并发布上线
⚠️ 极高频遗漏步骤！权限在被保存后，必须伴随版本发布才能真正生效！
1. 点击左侧菜单 「版本管理与发布」 → 「创建版本」。
2. 填写应用版本号（例如 `1.0.0`）及必要的描述，点击保存。
3. 点击右上角 「申请发布」 按钮。
4. 登录您企业的 飞书管理后台，在 「工作台」 → 「应用审核」 中批准通过自建应用的发布审核。
第五步：新建文件夹并获取 Token
1. 打开飞书云盘，并在其中新建一个用于接收同步笔记的空文件夹。
2. 点击并进入该文件夹。查看浏览器地址栏中的 URL。
3. 链接的尾部一串字符即为 文件夹 Token（例如：`https://feishu.cn/drive/folder/fldcnXXXXXXXX` 的 Token 是 `fldcnXXXXXXXX`）。将其填入插件配置中。
第六步：获取您的 User ID
因为机器人创建的文档默认归机器人所有，如果不转移所有权，文档无法出现在您的“我创建的”列表中。插件会通过 User ID 将所有权转移给您本人。
1. 打开飞书管理后台，进入 「组织架构」 → 「成员与部门」。
2. 搜索并点击您自己的名字，打开详情弹板。
3. 复制其中的 User ID（格式通常为字母加数字，如 `abc1234`），并填入插件配置。
⚠️ 必须是 `user_id` 格式，切勿填写以 `ou_` 开头的 open_id 或以 `on_` 开头的 union_id。
第七步：飞书客户端建群并对文件夹授权
这是整个配置中最反直觉、最关键的一步。
原理：飞书文档的协作面板不认识“应用机器人”，仅支持分享给“人”或“群”。我们需要把自建的机器人拉进群，再对群分享文件夹，机器人就能顺利访问到文件夹了。
1. 打开飞书客户端，新建一个群聊（随便起什么名字，单人建群也可以）。
2. 点击群设置 → 「群机器人」 → 「添加机器人」，在搜索框中搜索您在第一步中创建的自建应用，并添加。
3. 回到飞书云盘，找到您在第五步新建的文件夹，点击 「共享」 → 「协作者」。
4. 在输入框中搜索并选择您刚创建的那个群聊，在权限下拉菜单中选择 「可管理」 权限并邀请保存。
常见错误排查
1. 测试连接提示 403 权限拒绝：
大概率是自建应用勾选权限后，没有通过「版本管理与发布」重新发布应用新版本，或者管理员没有在后台通过审批。也请确保第七步中文件夹已经分享给了包含机器人的群，且权限是「可管理」。
2. 转移文档所有权失败：
如果同步成功，但提示转移文档所有权失败，请检查 User ID 填写是否正确（格式例如 `abc1234`），或者管理员有没有限制自建应用转移所有权权限。此时文档已经被成功创建在文件夹里，不影响日常协作使用。