larkDocx2md

将飞书文档、电子表格转换为 Markdown 文件的命令行工具。

支持：

• 飞书文档：https://*.feishu.cn/wiki/*
  • Markdown 类型中的标题、列表、基础文字等常见的文本样式
  • 飞书文档中的内嵌画板、电子表格
  • ...见下表‘支持的内容块类型’
• 飞书电子表格：https://*.feishu.cn/sheets/*（支持 ?sheet=<sheetId> 指定子表）、https://*.feishu.cn/wiki/*

使用

命令所需权限见下 ‘飞书自创应用需要的权限’

npx -y lark-docx2md@latest download --url https://xxx.feishu.cn/wiki/xxx --app-id cli_xxx --app-secret xxxx

download 命令支持别名 dl，以下写法等效：

npx -y lark-docx2md@latest dl --url https://xxx.feishu.cn/wiki/xxx --app-id cli_xxx --app-secret xxxx

或先设置环境变量（命令行参数可省略）：

export LARK_DOCX2MD_APP_ID=<APP_ID>
export LARK_DOCX2MD_APP_SECRET=<APP_SECRET>
npx -y lark-docx2md@latest download --url <url>

参数

| 参数 | 说明 | 环境变量 | 默认值 | |--------------------------|-------------------------------------------|------------------------------|-----------------------| | --url <url> | 飞书文档链接（https://*.feishu.cn/wiki/* 或 /sheets/*，支持 ?sheet=<sheetId> 指定子表） | — | — | | --app-id <id> | 飞书应用 App ID | LARK_DOCX2MD_APP_ID | — | | --app-secret <secret> | 飞书应用 App Secret | LARK_DOCX2MD_APP_SECRET | — | | -o, --output <dir> | 输出目录 | LARK_DOCX2MD_OUTPUT | ./larkDocx2mdOutput | | --agent [mode] | Agent 模式：日志 ERROR。不传值（或 =stdout）为在线模式，Markdown 输出到 stdout；传 local 则落盘后输出引导 AI 读取的提示词 | LARK_DOCX2MD_AGENT=stdout\|local | false | | --image-mode <mode> | 图片处理模式：local（下载到本地）或 online（24h 临时链接） | LARK_DOCX2MD_IMAGE_MODE | local | | --filter-title <title> | 按标题过滤：仅转换匹配标题及其下级内容（匹配到同级或更高级标题时截止） | — | — | | --filter-title-block-id <id> | 按 heading 块 id 精确过滤（无同名歧义），通常配合 get-titles 子命令获取；与 --filter-title 互斥 | — | — | | --max-output-lines <n> | 未指定标题过滤时允许输出的最大 Markdown 行数；超过会报错并提示补充标题过滤参数 | LARK_DOCX2MD_MAX_OUTPUT_LINES | — | | --wb-format <format> | 画板输出格式：base64、inline-svg、svg、yaml | LARK_DOCX2MD_WB_FORMAT | svg（agent 下默认 yaml） | | --wb-bg <style> | 画板 SVG 背景：none、dot 或颜色值如 #fff | LARK_DOCX2MD_WB_BG | none | | --wb-image-mode <mode> | 画板图片模式：online、base64 或 local | LARK_DOCX2MD_WB_IMAGE_MODE | local |

参数联动规则

• --agent（在线）：强制 --image-mode=online、--wb-image-mode=online；--wb-format 默认 yaml，仅允许 inline-svg / yaml；转换完成后 Markdown 直接通过 stdout 输出。
• --agent local：强制 --image-mode=local、--wb-image-mode=local（Markdown、图片、画板中的图片均落盘）；--wb-format 默认 yaml，仅允许 inline-svg / yaml；stdout 输出引导 AI 读取文件的提示词（包含绝对路径）。
• 非 agent 模式下 --wb-format yaml 时：--wb-image-mode 强制为 online。
• --filter-title：按标题文本精确匹配（忽略前后空格），收集该标题及其所有子级块，遇到同级或更高级标题时停止。同名标题取首个；未匹配时错误信息附全文标题 text 清单。
• --filter-title-block-id：按 heading 块 id 严格相等匹配，适用于同名标题或脚本化场景；通常先用 get-titles 查出目标 blockId 再传入。与 --filter-title 互斥。
• --max-output-lines：仅在未指定 --filter-title / --filter-title-block-id 时生效；纯 Markdown 阶段先检查一次，图片、画板、表格等解析完成后再检查一次。超过限制时直接报错，提示先用 get-titles 获取标题，再补充标题过滤参数重试。
• 命中深层标题时自动注入父级标题（仅 heading 块本身）：两个过滤参数均会按文档顺序补齐包含路径上的顶层→该标题的所有祖先标题，以保留章节层级上下文；不会引入旁支兄弟或伪造跳级。

子命令：get-titles

列出 docx/wiki 文档全部标题（不支持 sheets），配合 --filter-title-block-id 使用可避开同名歧义。

npx -y lark-docx2md@latest get-titles --agent --url <url>

| 参数 | 说明 | 默认值 | |-----------------------|------------------------------------------------------------------------------------------|--------| | --url <url> | 飞书 wiki/docx URL | — | | --max-level <n> | 仅输出 level <= n 的标题（1~9） | 9 | | --format <format> | 输出格式：text（YAML front matter + ## [blockId] 标题） | yaml（嵌套） | text | | --agent [mode] | 同 dl，降低日志级别 | — |

text 格式文件开头包含 YAML front matter 格式说明；正文用 # 数量保留标题层级，并把 blockId 放在标题旁，便于 AI 直接选择目标章节。

功能

• 支持飞书 Wiki 文档下载
• 转换 20+ 种块类型
• 输出标准 Markdown 文件
• 支持飞书画板，输出格式：base64（data URI 内嵌）、inline-svg（SVG 标签内嵌）、svg（独立文件）、yaml（AI 友好结构化数据）。详见 画板支持说明
• 支持飞书电子表格（独立 sheet URL 或 docx 内嵌 sheet 块），输出 GFM 表格，自动展开合并单元格；支持 ?sheet=<sheetId> 仅处理指定子表。详见 电子表格支持说明

支持的内容块类型

| 块类型 | 说明 | Markdown 输出 | |---------------------|---------|----------------------------| | Page | 页面 | # 标题 + 子块 | | Text | 文本段落 | 纯文本 | | Heading1 ~ Heading9 | 1-9 级标题 | ## ~ ######### | | Bullet | 无序列表 | - 内容（支持嵌套） | | Ordered | 有序列表 | 1. 内容（自动计算序号） | | Code | 代码块 | ```lang ```（支持 67 种语言） | | Quote | 引用 | > 内容 | | Equation | 公式 | $$ 公式 $$ | | Todo | 待办事项 | - [x] / - [ ] | | Callout | 高亮块 | >[!TIP] + 子块 | | Divider | 分割线 | --- | | Image | 图片 | ![图片](url) | | Table / TableCell | 表格 | GFM 管道表格（合并单元格按值展开） | | QuoteContainer | 引用容器 | > 子块内容 | | Grid / GridColumn | 分栏布局 | 展平为子块内容 | | Sheet | 电子表格 | GFM 表格（合并单元格自动展开） |

支持的行内样式

| 样式 | Markdown 输出 | |------|-------------| | 加粗 | **文本** | | 斜体 | _文本_ | | 删除线 | ~~文本~~ | | 下划线 | <u>文本</u> | | 行内代码 | `代码` | | 链接 | [文本](url) | | 行内公式 | $公式$ | | @用户 | 用户 ID | | @文档 | [标题](url) |

未支持的块类型（如文件附件、视频等）会被静默忽略。

开发

# 直接运行（无需构建），download 可使用别名 dl
pnpm dev download --app-id <APP_ID> --app-secret <APP_SECRET> --url <url>

# 或使用环境变量
LARK_DOCX2MD_APP_ID=<APP_ID> LARK_DOCX2MD_APP_SECRET=<APP_SECRET> pnpm dev dl --url <url>

# 构建为 JS
pnpm build

飞书自创应用需要的权限

使用飞书开发平台的权限管理-批量导入/导出权限 导入下面的配置即可。

{
  "scopes": {
    "tenant": [
      "base:app:read",
      "bitable:app",
      "bitable:app:readonly",
      "board:whiteboard:node:read",
      "contact:user.employee_id:readonly",
      "docs:document.media:download",
      "docx:document",
      "docx:document:readonly",
      "wiki:node:read",
      "wiki:wiki",
      "wiki:wiki:readonly",
      "sheets:spreadsheet.meta:read",
      "sheets:spreadsheet:readonly"
    ],
    "user": []
  }
}

License

ISC

🙏 致谢

本项目开发过程中获得了 LINUX DO 社区佬友的帮助，本产品会在社区发布，感谢社区的支持。