【开源推广】飞书文档转 Markdown 支持画板

问题描述：

本帖使用社区开源推广，符合推广要求。我申明并遵循社区要求的以下内容：

• 我的帖子已经打上 开源推广 标签： 是
• 我的开源项目完整开源，无未开源部分： 是
• 我的开源项目已链接认可 LINUX DO 社区： 是
• 我帖子内的项目介绍，AI生成、润色内容部分已截图发出： 是
• 以上选择我承诺是永久有效的，接受社区和佬友监督： 是

以下为项目介绍正文内容，AI生成、润色内容已使用截图方式发出

---

项目地址：GitHub - Byte-n/larkDocx2md: 飞书（lark）文档导出未 Markdown 格式，支持文档内的画板数据导出。AI 友好，支持 Agent Skill · GitHub

在将飞书文档转换为 Markdown 的场景中，文本、表格、图片等常规块类型的处理在之前以及完成。但在日常接触的业务需求中，有一部分产品的业务流程图是放在飞书的需求文档的画板中，在此之前都依赖截图或人工转述的方式投喂给 Agent 。

lark-docx2md@0.2.0 版本的核心目标:

• Markdown 转换架构调整，更好扩展、维护。
• 支持文档中内嵌的画板块的识别和转换。

架构重构

之前的代码中采用的是单文件的解析器直接输出 Markdown 字符串，后续的块转换也都是字符串在操作。这种方式在新增块类型或处理异步资源（如图片下载、画板接口请求）时，耦合严重、难以扩展。每次新增一种块类型，都需要修改核心解析逻辑，且同步和异步处理混在一起，代码可维护性较差。

飞书 API ───▶ Parser ───▶ Transformer ───▶ Serializer 原始数据 (AST 构建) (异步处理) (Markdown) 同步、纯函数 网络请求 字符串输出

Parser 阶段： 仅将飞书的响应数据转换为 AST 的结构。

**Transformer **：AST + 外部资源集合调用各块的转换器，执行 AST → 字符串的转换

Serializer 阶段： 整个 AST 序列化为最终的 Markdown 字符串

如果后续需要支持新的块，只需要增加对应块类型的转换器即可！

画板的支持

lark-docx2md 支持识别并转换飞书文档中的画板内容：

• 流程图

• 脑图

• 涂鸦

• 表情

• 表格

• 泳道

• Any … 几乎大部分 99% 的内容

矢量绘制，无限缩放不失真，项目中已有 lark-docx2md Skill 的可以直接尝试，不需要做任何更改。

Agent 调用此 Skill，画板数据会以 yaml 格式输出（AI 友好，人类不友好）
人类友好形式：npx lark-docx2md@latest download --wb-format “svg” --wb-bg “#fff” xxx
然后你可以在输出日志中找到对应的图片，类似：

{时间} [INFO] [converter] Downloaded markdown file to larkDocx2mdOutput/xx.md

画板支持输出格式：

• base64 在 Markdown 中通过图片语法引用（data URI ）

npx lark-docx2md@latest download --wb-format “base64” --wb-bg “#fff” xxx

• inline-svg：SVG 标签内嵌，大部分 Markdown 渲染器都支持直接渲染内嵌的 HTML 标签。

npx lark-docx2md@latest download --wb-format “inline-svg” --wb-bg “#fff” xxx
这里会将笔触、表情等视觉内容（非逻辑部分）移除，因为此部分一般不会影响 Agent 理解此画板的内容，但此部分一般都是由大量坐标、svg 代码构成，十分浪费 tokens。

• svg：输出到磁盘 .svg 文件中，在 Markdown 中通过图片语法引用

npx lark-docx2md@latest download --wb-format “svg” --wb-bg “#fff” xxx
这里包含全量的信息，不会移除任何内容。相比 base64，这里是矢量图片，无限缩放不失真。

• yaml：AI 友好结构化数据。

此部分输出的格式，人类极度不友好，Agent 专用友好格式（比 svg 遥遥领先）。
npx lark-docx2md@latest download --wb-format “yaml” --wb-bg “#fff” xxx
这里会将笔触、表情等视觉内容（非逻辑部分）移除，因为此部分一般不会影响 Agent 理解此画板的内容，但此部分一般都是由大量坐标、svg 代码构成，十分浪费 tokens。

Agent 模式

--agent 标志，开启时将转换后的文档输出到标准流中，并且会强制：

• image-mode=online（避免本地文件依赖）
• wb-image-mode=online（避免本地文件依赖）
• wb-format=yaml（输出 AI 友好的结构化数据）

作为库调用

import { convert } from 'lark-docx2md'; const result = await convert({ url: 'https://your-domain.feishu.cn/wiki/xxx', appId: 'your_app_id', appSecret: 'your_app_secret', output: './output', wbFormat: 'yaml', agent: true, }); console.log(result.markdown); // Markdown内容 console.log(result.docToken); // 文档Token 网友解答：

---

--【壹】--：

这个确实有用啊，之前只能导出doc和pdf这种，确实不方便，支持一下，一会去公司试试

---

--【贰】--：

非常感谢！刚好最近有这个需求，再搬其他文档到自己知识库的时候都是手动保存，然后一个一个移动，太浪费时间了

---

--【叁】--：

真是解决了我的大问题 之前老是把飞书文档整页复制给ai 效果不理想 这下彻底的解决了我的问题

---

--【肆】--：

larksuite.com 的可以吗佬友

---

--【伍】--：

好像需要额外支出一下。这里的链接格式不一样，获取文档token → 获取文档块列表。这里的‘获取文档token’ 这个步骤应该轻度适配一下就可以了。提个 isuus ，给个示例链接格式（无法访问也可以）

---

--【陆】--：

有其他的文档块 需要转换可以提 isuss。

---

--【柒】--：

佬友 牛的，这么实用的案例。mark一下~~~

---

--【捌】--：

可以申请试试，说明情况、原因就好了。

• 这个工具并没有涉及自动扫描知识库、子文档、文档列表等操作。
• 仅会读取 lark-docx2md download http://*.feishu.cn/wiki/* 指定的链接对应的文档中的内容。
• 开源代码，可审查，你也可以 copy 一份到你公司的私有仓库中，构建私有的包，完全掌握，就不用担心安全问题了（记得 Star， 有好的改动也可以 PR）

---

--【玖】--：

需要申请飞书的自建应用，需要的权限在github readme 中有列出，一键导入就可以了，最小范围的只读权限。

---

--【拾】--：

啊，需要自建应用，公司估计有点难了，权限收的比较紧，不允许个人申请，那估计完犊子了

---

--【拾壹】--：

这个项目很实用，画板转Markdown解决了飞书文档迁移的痛点，支持多种格式输出很贴心。