飞书文档协作方案评估¶

评估日期：2026-02-18

状态：待团队讨论目的：评估如何利用飞书做内部文档 review，选定协作方案 当前发布渠道：GitHub → Cloudflare Pages（docs.retaintive.ai）

1. 背景¶

文档目前托管在 GitHub，通过 MkDocs Material 构建，自动部署到 Cloudflare Pages。团队日常沟通用飞书，但文档 review 缺少便捷的评论和讨论机制。

当前文档资产：

类型	数量	说明
站点发布文档	31 篇	在 `mkdocs.yml` nav 中，Cloudflare Pages 可见
内部参考文档	~280 篇	`cloudaudioai-design/` 下，未发布
Draw.io 架构图	8 个	`.drawio` 源文件，MkDocs 插件直接渲染
SVG 导出图	9 个	文档中 `![](../images/xxx.svg)` 引用
DBML Schema	1 个	DynamoDB 表定义

核心挑战：我们的文档不是纯文字——包含 drawio 架构图、DBML schema、SVG 导出图、Mermaid 图表、MkDocs admonitions（!!! warning）。任何集成方案都需要考虑这些工程文档特有的内容类型。

2. 行业现状：Git + Markdown 文档同步到协作平台¶

在评估飞书方案之前，先看看其他平台的成熟度：

平台	Git 同步方式	成熟度	关键工具
GitBook	原生双向 Git Sync	最好	内置，开箱即用
Confluence	第三方工具	成熟	`kovetskiy/mark`（1.1k stars）
Notion	GitHub Actions	尚可	`git-notion`（218 stars）
飞书 / Lark	无现成方案	几乎空白	社区工具极少

关键发现：整个开源生态在飞书方向上几乎是反向的——成熟工具都是飞书 → Markdown（feishu2md 2000 stars、feishu-pages 274 stars），而 Markdown → 飞书方向基本空白。

3. 飞书 API 能力评估¶

我们已配置了 Lark MCP Server，以下是实际可用的工具和限制：

能力	可用？	工具/API
导入单个 .md 为飞书文档	YES	`docx_builtin_import`（传入 Markdown 字符串，2 秒完成）
批量导入多个文档	YES	顺序调用，31 篇约 2 分钟
创建 Bitable 跟踪表	YES	完整 CRUD，可追踪 review 状态
分享给团队群聊	YES	`drive_v1_permissionMember_create`
控制目标文件夹位置	NO	文档只能落在"我的空间"根目录
创建 Wiki 知识库结构	NO	Wiki 工具只有读取，没有写入
更新已有文档内容	NO	无 patch/update API
删除旧版文档	NO	无删除工具

4. 三个方案对比¶

方案 A：Git 为主 + 按需推送飞书（推荐）¶

Git 保持 source of truth，需要 review 时单独推送文档到飞书做评论。

Git (.md + drawio + svg)
 ├── push → GitHub Actions → Cloudflare Pages（完整渲染）
 │
 └── 需要 review 时：
      ├── docx_builtin_import → 推送到飞书文档
      ├── 团队在飞书中划词评论、@讨论
      ├── 讨论完毕 → 作者回 Git 改源文件
      └── push → Cloudflare Pages 更新

具体做法：

读取本地 .md 文件内容
调用 Lark MCP 的 docx_builtin_import（传入 Markdown 字符串，2 秒完成）
拿到飞书文档 URL，分享给团队

POC 验证：已测试，将 relational-db-migration.md（348 行，17 张表格，SQL 代码块）推送到飞书，文档链接：https://ljprwpnmsg2d.jp.larksuite.com/docx/V4IudwkOTobtFQxetKUjcJhgpWd

优点	缺点
Git 保持 source of truth，drawio/svg/dbml 全部保留	飞书文档是纯文字副本，图表不显示
按需推送，不需要维护同步流水线	单向推送，飞书上的修改不回 Git
飞书原生评论体验（划词、@、线程）	每次文档更新需重新推送（新建文档）
零额外基础设施成本	无文件夹组织（文档落在"我的空间"根目录）

方案 B：GitHub → 飞书群聊通知（轻量补充）¶

最轻量的方案，作为方案 A 的补充。

push to main → GitHub Actions → 飞书群聊 Bot 发通知卡片
                                    ↓
                           团队点链接到 Cloudflare Pages 阅读
                           在飞书群聊中讨论

具体做法：

在飞书群聊中添加自定义 Bot，获取 webhook URL
GitHub Actions 监听 docs/**/*.md 变更，推送通知卡片到群聊
卡片包含：变更文件列表 + Cloudflare Pages 链接

优点	缺点
5 分钟搭好，零维护	没有 inline commenting，讨论和文档分离
每次 push 自动通知，不遗漏	群聊讨论容易被淹没，不如文档评论有条理
不产生额外文档副本	团队需要到 Cloudflare Pages 上阅读

方案 C：飞书写作 → MkDocs 发布（远期可选）¶

反转 source of truth。团队在飞书 Wiki 中写文档，定时导出到 GitHub 构建发布。

团队在飞书 Wiki 写/改文档
    ↓
feishu-pages 定时导出为 Markdown + 下载图片
    ↓
git commit & push → GitHub Actions → mkdocs build → Cloudflare Pages

具体做法：

在飞书创建 Wiki 知识库，按现有目录结构组织文档
配置 longbridge/feishu-pages（274 stars）定时导出
GitHub Actions 将导出结果提交到 Git，触发 MkDocs 构建

优点	缺点
团队在飞书原生环境写作，门槛最低	Source of truth 从 Git 转移到飞书
feishu-pages 工具链最成熟（274 stars，持续维护）	drawio 源文件无法在飞书中维护
Wiki 目录结构可映射到 MkDocs nav	需要将现有 31 篇文档迁移到飞书 Wiki
图片自动下载到本地	不是实时同步，是定时批量导出

feishu-pages 已知限制（来自 GitHub issues）：

问题	Issue	状态
代码块内出现多余 `<em>` 标签	#30	未修复
文档间内部链接导出后 404	#31	未修复
同步块在非源文档中导出为空	#34	飞书 API 限制
不支持的 block 类型静默丢弃（无警告）	—	设计如此

飞书中完全无法导出的内容：多维表格 (Bitable)、流程图 (Diagram)、思维导图 (MindNote)、文字颜色。

三方案总览¶

维度	方案 A：按需推飞书	方案 B：群聊通知	方案 C：飞书写作
Source of truth	Git	Git	飞书
评论能力	飞书 inline 评论	群聊讨论	飞书 inline 评论
图表保留	Cloudflare Pages 完整	Cloudflare Pages 完整	drawio/DBML 丢失
搭建成本	已验证，开箱即用	5 分钟	1-2 周迁移
维护成本	无	无	需维护 feishu-pages 流水线
适合场景	深度 review 个别文档	通知团队有更新	团队更习惯飞书写作

5. 格式兼容性对比¶

元素	Cloudflare Pages	飞书文档
标题、粗体、列表	完美	完美
表格	Material 主题美化	飞书原生表格
代码块	语法高亮 + 行号 + 复制按钮	代码块，可能无语法高亮
`!!! warning` admonition	彩色警告/提示框	变为普通文字
Mermaid 图表	交互式渲染	不渲染
`![](../images/xxx.svg)` 图片	正常显示	不显示（本地路径，飞书无法访问）
`.drawio` 嵌入	drawio 插件直接渲染	不支持
内部链接 `[text](other-doc.md)`	可跳转	链接失效（指向本地路径）

图片是双向断裂的

Git → 飞书：![](../images/xxx.svg) 推送后飞书看不到图（本地路径无法解析）
飞书 → Git：飞书中插入的图片存在飞书 CDN，不会自动出现在本地 images/ 文件夹

6. 飞书评论能力¶

飞书文档的 review 体验：

功能	说明
划词评论	选中任意文字，评论锚定到具体位置
@提及	评论中 @团队成员，收到即时 IM 通知
评论线程	可回复、可 emoji 反应
标记已解决	讨论完毕后折叠评论，保留历史
关注更新	订阅后收到编辑变更汇总

关键限制：飞书评论不能导出到 Markdown。评论和文档正文在飞书 API 层面是完全隔离的两套系统——所有导出工具（feishu-pages、feishu2md）都不处理评论。讨论的结论需要作者手动反映到 Git 源文件中。

7. 建议¶

推荐方案 A + B 组合：Git 保持 source of truth，方案 B（群聊通知）让团队知道有更新，方案 A（按需推飞书）用于需要深度 review 的文档。

理由：

我们的文档包含大量工程内容（drawio 架构图、DBML schema、Mermaid 图表），这些在飞书中无法维护。如果反转 source of truth 到飞书（方案 C），这些最有价值的部分会丢失。
方案 A 已通过 POC 验证，核心 Markdown 内容（标题、表格、代码块、列表）在飞书中可读性好，满足评论讨论的需求。
方案 B 零成本搭建，解决"团队不知道文档更新了"的问题。
方案 C 作为远期备选保留——如果未来文档逐渐转向纯文字内容（减少架构图依赖），或团队强烈偏好在飞书写作，可以重新评估。

8. 讨论点¶

需要团队确认：

是否同意 A + B 组合方案？Git 为主，飞书做评论和通知。
哪些文档需要优先推送到飞书做 review？建议从改进计划（improvement-plans）开始，这些文档变动频繁、需要决策讨论。
飞书群聊通知的范围？所有文档更新都通知，还是只通知特定目录的变更？

9. 参考链接¶

资源	链接
feishu-pages（飞书 Wiki → Markdown 导出）	github.com/longbridge/feishu-pages
Lark Open Platform 文档导入 API	open.larksuite.com
POC 测试文档（飞书）	DynamoDB 迁移分析 — 飞书版
当前文档站点	docs.retaintive.ai