SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场feishu-cli-import

feishu-cli-import

办公与效率

查看项目

更新于 10-15 14:57

技能介绍

用途

feishu-cli-import 是 feishu-cli 提供的一项 Markdown 导入技能，主要用途是从本地 Markdown 文件创建飞书云文档，或把 Markdown 追加导入到已有文档。它把 Markdown 作为本地文档与飞书云文档之间的中间态进行转换。

需要注意边界：本技能仅支持 Markdown 源文本导入。若需导入 Word/Excel 等二进制格式，应使用 feishu-cli doc import-file 或 feishu-cli-drive skill 的 drive import。如果目标是把 Markdown 里的表格变成飞书电子表格，应改用 feishu-cli sheet import-md report.md --title "报表"，而不是 doc import。

主要能力

  • 三阶段并发管道：阶段一顺序创建块并收集图表/表格任务；阶段二用 worker 池并发处理图表导入和表格填充；阶段三逆序处理失败图表，删除空画板块并插入代码块降级展示。
  • Mermaid/PlantUML 转飞书画板：mermaid/plantuml/puml 代码块自动转换为飞书画板。
  • 图表故障容错：语法错误自动降级为代码块展示，服务端错误自动重试（默认最多 10 次，可用 --diagram-retries 调整）。
  • 大表格智能处理：行 > 9 时创建 9 行初始表并用 insert_table_row API 追加到同一 block；列 > 9 时按列组拆分并保留首列作为标识。单元格内容填充走 batch_update 批量加速（v1.29+），典型 4×6×8 表从约 70s 降到约 3s。
  • 表格列宽：默认按内容启发式（中文 14px / 英文 8px，最小 80px，最大 400px），可通过紧邻表格上方的注释 <!-- feishu-colwidth: 80,200,*,30% --> 或 CLI flag --table-column-width=auto|fixed|N1,N2,... 覆盖，注释优先级高于 flag。
  • API 限流自动重试：画板创建和图表导入遇到 HTTP 429 时自动重试，读取服务端 x-ogw-ratelimit-reset 响应头精确计算退避时间，采用指数退避，默认最多重试 10 次。
  • 并发控制：图表和表格分别使用独立 worker 池（默认图表 5、表格 3 并发）。
  • 表格单元格图片真嵌入：Markdown 表格单元格内的本地/网络图片，在表格填充完成后真正嵌入为单元格内的 Image 子块。纯图片单元格不会把图片说明串成多余标题文字；嵌入失败或单元格对不齐的图片计入统计 cell_image_failed 并打印；上传失败的空图块会被清理并补占位文本。仅 doc import 走真嵌入，doc add/content-update 等非导入场景的单元格图片降级为 [图片: 说明] 占位文本。JSON 输出新增 cell_image_total/success/failed。

使用方式

前置条件：已安装 feishu-cli（安装方式见 riba2534/feishu-cli）；已配置 App Token（FEISHU_APP_ID + FEISHU_APP_SECRET），无需 auth login；Markdown 文件使用 UTF-8 编码（CLI 会用 utf8.Valid 拒收非法 UTF-8 字节序列，合法 UTF-8 中包含的 U+FFFD 替换字符不会被拦截）。

常用命令：

# 创建新文档
feishu-cli doc import ./document.md --title "文档标题"

# 追加导入到已有文档（不会原地替换）
feishu-cli doc import ./document.md --document-id <existing_doc_id>

# 上传本地图片
feishu-cli doc import ./document.md --title "带图文档" --upload-images

创建新文档的执行流程：验证文件（检查是否存在、预览内容、编码验证）→ 执行导入 → 添加权限（仅 owner 已配置时）→ 转移文档所有权（仅 transfer_ownership=true 时）→ 发送通知。追加导入时，--document-id 不会替换已有内容，只会把 Markdown 转换后的块追加到文档末尾；修改/覆盖已有内容请用 feishu-cli doc content-update。

主要参数：markdown_file（必需）、--title（默认文件名）、--document-id（追加导入）、--upload-images（默认开启）、--image-workers（默认 2）、--folder/-f（目标文件夹 Token，默认根目录）、--diagram-workers（默认 5）、--table-workers（默认 3）、--table-column-width（默认 auto）、--diagram-retries（默认 10）、--verbose。

Owner 规则：创建新文档后如需交付给用户，先解析 FEISHU_OWNER_EMAIL 或配置文件 owner_email。只在解析到 owner 时授予 full_access；只在 transfer_ownership=true 时转移所有权。不要把示例邮箱当成真实接收人。

支持的 Markdown 语法

标题（# ~ ######）、段落文本、无序/有序列表（支持无限深度嵌套、混合嵌套）、任务列表（- [ ] / - [x]）、代码块（带语言标识）、Mermaid/PlantUML 图表（自动转换为飞书画板）、引用块（支持嵌套引用，自动转换为 QuoteContainer）、Callout 高亮块（> [!NOTE]、> [!WARNING] 等 6 种类型）、分割线、图片、表格、粗体、斜体、删除线、行内代码、下划线（<u>文本</u>）、链接、行内公式（$E = mc^2$）、块级公式（$$formula$$ 或独立行 $formula$）。

支持的 Mermaid 图表类型（全部已验证）：flowchart（支持 subgraph 嵌套）、sequenceDiagram、classDiagram、stateDiagram-v2、erDiagram、gantt、pie、mindmap。

Callout 背景色映射：NOTE/INFO 蓝色(6)、WARNING 红色(2)、TIP 黄色(4)、CAUTION 橙色(3)、IMPORTANT 紫色(7)、SUCCESS 绿色(5)。Callout 内部支持子块（段落、列表等）。

此外还识别 HTML 标签形式的扩展语法，用于 roundtrip 场景或精确控制飞书块类型，包括 mention-user、mention-doc、grid 分栏、callout、whiteboard、sheet、bitable、image、file、video 等标签。

适用场景

  • 将本地 Markdown 笔记、会议纪要、博客文章、规格文档等导入为飞书云文档。
  • 把含 Mermaid/PlantUML 图表的 Markdown 转换为带飞书画板的文档。
  • 批量导入多个 Markdown 文件。
  • 需要保留表格结构、公式、Callout 高亮块等复杂格式的导入场景。

限制

  • 仅支持 Markdown 源文本导入，不支持 Word/Excel 等二进制格式。
  • Mermaid 已知限制：{} 花括号会被解析为菱形节点，自动降级为代码块；par...and...end 飞书解析器完全不支持，需用 Note over X: 并行执行 替代；渲染复杂度组合超限（如 10+ participant + 2+ alt 块 + 30+ 长消息标签）服务端返回 500，重试后降级为代码块；Parse error 不重试，直接降级。建议 sequenceDiagram 保持 participant ≤8、alt ≤1、消息标签简短。
  • 超长表格导入耗时显著，主要耗时来自行 > 9 时 insert_table_row API 逐行串行追加（受单文档 3 QPS 节流）；行数极多（200+）时建议改用电子表格（Sheet）承载。
  • 列 > 9 时表格会被拆分为多个 block（每组 ≤ 9 列），首列作为标识在所有组中保留。
  • 图片上传失败时自动创建占位块，不影响整体导入。
  • 文档创建成功但无法编辑，通常是未按 owner 配置添加权限。

已验证功能

大规模测试结果：10,000+ 行 Markdown 可成功导入；127 个 Mermaid 图表全部成功转换；170+ 个表格全部成功；8 种图表类型全部成功；88 个 Mermaid 图表逐个测试 82/88 成功，6 个失败（3 个服务端瞬时错误 + 2 个花括号语法 + 1 个提取异常）。