Feishu Wiki Sync · 飞书知识库同步

简体中文 · English · 版本 1.0.0

Feishu Wiki Sync 是 VS Code 的飞书知识库同步插件，将本地 Markdown、TXT、Word、Excel 和 CSV 单向发布到 Wiki。一个工作区可为多个目录分别配置目标节点，按文件、目录或绑定选择同步范围，无需额外服务器。

支持格式

扩展名不区分大小写。Word、Excel、CSV、TXT 通过飞书官方导入服务转换，无需安装 Office。导入效果取决于飞书对原文件的支持情况。

主要功能

• 多目录绑定：每个本地根目录对应一个 Wiki 根节点，分别保存同步状态与自动同步设置。
• 按需同步：右键目录执行“同步此目录”，右键文件执行“同步当前文件”，自动选择所属绑定；也可右键文件打开对应 Wiki 页面。
• 分组预览：在资源管理器的“飞书 Wiki 同步”面板按绑定查看待更新文件、错误和任务进度。
• 图片与链接：同步 Markdown 引用的本地图片，将同一绑定内指向已支持文件的相对链接改为 Wiki 链接。
• 自动同步：按绑定独立开启，保存本地文件后自动更新；默认关闭。
• 继续与恢复：中断的导入任务可继续执行；手动同步时确认云端页面已删除，可根据本地文件重建。

快速开始

需要 VS Code 1.96+，支持 Windows / macOS 的本地文件夹工作区。

1. 在扩展市场搜索 Feishu Wiki Sync 并安装。使用本地安装包时，选择“扩展 → … → 从 VSIX 安装”，打开 feishu-wiki-sync-1.0.0.vsix。
2. 在飞书开放平台创建企业自建应用，配置下方所需权限并发布应用版本，使应用能够访问目标知识库。
3. 打开文档所在工作区，按 Ctrl+Shift+P（macOS：Cmd+Shift+P），运行 飞书同步：配置向导。
4. 输入绑定名称、App ID 与 App Secret，选择本地根目录，粘贴目标 Wiki 根节点链接。首次绑定请选择没有子页面的目标节点；迁移已有同步内容时先导入原映射。
5. 在“飞书 Wiki 同步”面板预览变化，点击对应分组的上传按钮；也可右键绑定内的目录或文件同步。

再次运行配置向导可以新增、编辑或移除绑定。相同应用可复用已保存的密钥；App Secret 保存在 VS Code 安全存储中。

多目录与局部同步

例如，本地 docs/产品 和 docs/笔记 可以分别绑定到两个 Wiki 节点。只同步 docs/产品/使用指南 时，另一组绑定和该子目录之外的文件保持原状。包含多个绑定的父目录需要先选择具体绑定，不能直接作为同步范围。

每个文件只属于一组绑定：本地根目录不能重叠，目标 Wiki 根节点不能重复。局部同步中引用的其他文档须已有映射；没有映射时请先同步目标文档所在目录。

手动配置

可直接编辑当前工作区的 .vscode/settings.json。应用密钥仍需通过配置向导保存一次。

{
  "feishuSync.appId": "cli_your_app_id",
  "feishuSync.bindings": [
    {
      "id": "product",
      "name": "产品文档",
      "root": "docs/产品",
      "wikiUrl": "https://example.feishu.cn/wiki/YourProductNode",
      "autoSync": false
    },
    {
      "id": "notes",
      "name": "学习笔记",
      "root": "docs/笔记",
      "wikiUrl": "https://example.feishu.cn/wiki/YourNotesNode",
      "autoSync": false
    }
  ],
  "feishuSync.exclude": ["**/.*/**", "**/node_modules/**", "**/drafts/**"]
}

• id 可自行填写，只使用小写英文字母、数字、- 或 _，并以字母或数字开头；在当前工作区文件夹内保持唯一、稳定。
• root 支持相对工作区路径或绝对路径；wikiUrl 填写目标 Wiki 根节点的 HTTPS 链接。
• 绑定内可填写 appId 和 exclude 覆盖共用设置；exclude 会替换默认忽略规则。
• 默认忽略隐藏目录、node_modules、drafts，始终忽略 .feishu-sync 与 Office 临时锁文件，不跟随目录符号链接。

飞书权限

应用需要 Wiki 节点读取与创建、在线文档读写、图片上传、文件导入、Wiki 内移动及移出到云空间等权限。具体权限以对应飞书接口和应用后台为准，新增权限后需要发布应用版本。

同时为应用授予目标知识库的资源访问权限，使其能够在目标节点下创建和编辑文档。运行 飞书同步：检查连接与节点访问 可以检查连接和读取权限，实际写入权限在同步时验证。

同步行为与常见问题

云端结构和名称是什么样的？ 本地目录映射为 Wiki 目录页；Word、Excel、CSV、TXT 在对应目录下各生成一个在线文件，名称与完整本地文件名一致。仅有图片的目录不会生成目录页。

修改本地文件后会怎样？ Markdown 更新保留页面链接。Word、Excel、CSV、TXT 更新会导入新文件，并将旧文件移出 Wiki、保留在应用云空间；新页面链接会变化，原有评论和段落引用不会转移。未变化文件不会重复上传。

删除云端页面后可以重建吗？ 手动同步会检查页面是否存在，确认删除后重建本次范围内的内容。若删除的是配置中的绑定根节点，需要恢复该节点或重新配置有效目标。权限和网络错误会保留原映射并提示处理。

为什么提示路径不属于任何绑定？ 所选路径必须是绑定根目录或其内部路径。检查 root 是否相对于当前工作区填写正确，或通过配置向导新增绑定。

如何处理失败和云端冲突？ 先打开日志检查原因；检查并备份云端内容后，运行 飞书同步：处理冲突或中断。修正权限或本地内容后再次同步。超时、取消的导入任务会保留进度，下次可继续。

换电脑需要保留什么？ 保留每组目录的 .feishu-sync/state.json，或先导出同步映射，再在新电脑配置相同目标并导入。密钥需重新保存。不要复制 sync.lock，同一时刻只在一台电脑同步。

当前限制

• 单向发布到飞书，不会下载云端修改或自动合并冲突。本地删除、移动、重命名及忽略规则变化不会自动删除旧云端页面。
• 手动同步前保存本次范围内的文件；自动同步只读取磁盘上已保存的内容，并且需要工作区保持打开。
• Markdown 支持基础排版，Mermaid / PlantUML 作为代码块展示；不支持网络图片、SVG、原始 HTML 或跨绑定相对链接。单张图片上限 20 MiB，单篇转换后最多 1000 个块。
• Markdown 正文更新会重建内容块，段落评论和块引用可能失效；Word / Excel 文件内部的相对链接不会自动改为 Wiki 链接。
• 暂不支持 PPTX、PDF 等其他格式及 vscode.dev 虚拟工作区。

English

Feishu Wiki Sync 1.0.0 is a VS Code extension that publishes local Markdown, TXT, Word, Excel and CSV files to Feishu Wiki. Bind multiple directories to separate Wiki roots, preview changes by binding, and sync only the files or directories you select. No separate server is required. Right-click a synced file to open its Wiki page.

Supported files

Extensions are case insensitive. TXT, Word, Excel and CSV use Feishu's official import service; no Office installation is required. Import fidelity depends on Feishu's support for the source file.

Quick start

Requires VS Code 1.96+ and a local folder workspace on Windows or macOS. Commands and the extension UI are in Chinese.

1. Install Feishu Wiki Sync from Marketplace, or use Extensions → … → Install from VSIX with feishu-wiki-sync-1.0.0.vsix.
2. Create an enterprise custom app on the Feishu developer platform, grant the permissions described below and publish the app version.
3. Open your document workspace and run 飞书同步：配置向导 (Configure) from the Command Palette.
4. Enter a binding name, App ID and App Secret, select a local root and paste the target Wiki root URL. Use an empty target node for a new binding. Import the existing mapping when migrating previously synced content.
5. Preview changes in 飞书 Wiki 同步, then use the binding's upload button or right-click a bound directory or file to sync it.

Run the wizard again to add, edit or remove bindings. App secrets are stored in VS Code SecretStorage. Auto-sync is off by default and can be enabled for each binding separately.

Sync scope and configuration

Roots cannot overlap and target Wiki roots cannot be duplicated. An ancestor containing multiple bindings is not a sync scope: select a binding or a path inside it. Relative Markdown links within one binding become Wiki links; targets outside a selected subtree must already have mappings.

You can edit .vscode/settings.json directly using the JSON example above. id is a stable identifier unique within the workspace folder: use lowercase letters, numbers, - or _, starting with a letter or number. root accepts workspace-relative or absolute paths, and wikiUrl is the target Wiki root HTTPS URL. Optional binding-level appId and exclude replace the shared defaults. Save app secrets through the wizard rather than in JSON.

Hidden directories, node_modules and drafts are excluded by default. .feishu-sync data and Office temporary lock files are always excluded. Directory symlinks are not followed.

Permissions

The app needs API permissions to read and create Wiki nodes, read and edit documents, upload images, import files, move files within Wiki and move old files out to Drive. Grant resource access to the target Wiki as well. Follow the requirements in the Feishu app console and API documentation, and publish a new app version after adding permissions.

飞书同步：检查连接与节点访问 checks connectivity and read access. Write permissions are checked during sync.

Synchronization and recovery

• Directories become Wiki parent pages; image-only directories do not create pages. TXT, Word, Excel and CSV each map to one online file under their corresponding directory, with the full original filename.
• Markdown updates preserve the Wiki URL. TXT/Office/CSV updates import a replacement, then move the old file to the calling app's Drive root. The replacement has a new URL; comments and paragraph references are not transferred. Unchanged files are not uploaded again.
• Manual sync checks for deleted cloud pages and recreates confirmed missing pages within its scope. A deleted configured Wiki root must be restored or reconfigured. Permission and network errors preserve the mapping.
• Timed-out or cancelled import tasks retain progress. Use 飞书同步：处理冲突或中断 (Resolve conflicts or interruptions) after inspecting and backing up cloud content, then retry sync.
• Keep each binding's .feishu-sync/state.json. When changing computers, export the mapping, configure the same target on the new machine, save the app secret and import the mapping. Do not copy sync.lock; sync from one machine at a time.

Limitations

• Publishing is one way: cloud edits are not downloaded or merged. Local deletion, moves, renames and exclusion changes do not automatically delete old cloud pages.
• Save selected files before manual sync. Auto-sync reads saved disk contents and requires the workspace to stay open.
• Markdown supports basic formatting. Mermaid / PlantUML remain code blocks. Remote images, SVG, raw HTML and cross-binding relative links are not supported. Each image is limited to 20 MiB and each converted document to 1000 blocks.
• Markdown updates rebuild body blocks, so paragraph comments and block references may be lost. Relative links inside Word / Excel are not rewritten.
• PPTX, PDF and other formats, as well as vscode.dev virtual workspaces, are not supported.