feishu-cli-import

Markdown 导入技能

从本地 Markdown 文件创建飞书云文档，或把 Markdown 追加导入到已有文档。支持 Mermaid/PlantUML 图表转飞书画板、大表格智能处理（行 > 9 单 block API 追加；列 > 9 拆分保留首列）。

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

核心特性

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

核心概念

Markdown 作为中间态：本地文档与飞书云文档之间通过 Markdown 格式进行转换。

边界澄清：本 skill 仅支持 Markdown 源文本导入。若需导入 Word/Excel 等二进制格式，请用 feishu-cli doc import-file 或 feishu-cli-drive skill 的 drive import。

如果用户目标是“把 Markdown 里的表格变成飞书电子表格”，不要走 doc import，改用：

feishu-cli sheet import-md report.md --title "报表"

前置条件

• 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

执行流程

创建新文档

1. 验证文件

   • 检查 Markdown 文件是否存在
   • 预览文件内容
   • 编码验证：CLI 内置 utf8.Valid 校验，遇到非法 UTF-8 字节直接拒绝导入；合法 UTF-8 里残留的 U+FFFD 替换字符不会被拦截，建议导入前先用编辑器全局搜一遍 �

2. 执行导入

   feishu-cli doc import <file.md> --title "<title>" [--upload-images]
   

3. 添加权限（仅 owner 已配置时）

   feishu-cli perm add <document_id> --doc-type docx --member-type email --member-id <owner_email> --perm full_access --notification
   

4. 转移文档所有权（仅 transfer_ownership=true 时）

   feishu-cli perm transfer-owner <document_id> --doc-type docx --member-type email --member-id <owner_email> --notification
   

5. 发送通知 发送飞书消息通知用户文档已创建

追加导入到已有文档

--document-id 不会替换已有内容，只会把 Markdown 转换后的块追加到文档末尾。修改/覆盖已有内容请用 feishu-cli doc content-update（详见 feishu-cli-write skill）。

1. 执行追加导入

   feishu-cli doc import <file.md> --document-id <doc_id> [--upload-images]
   

2. 通知用户

参数说明

参数	说明	默认值
markdown_file	Markdown 文件路径	必需
--title	新文档标题	文件名
--document-id	追加导入到已有文档	创建新文档
--upload-images	上传本地和网络图片到飞书	是（默认开启）
--image-workers	图片并发上传数	2（API 限制 5 QPS）
--folder, -f	新文档的目标文件夹 Token	根目录
--diagram-workers	图表 (Mermaid/PlantUML) 并发导入数	5
--table-workers	表格并发填充数	3
--table-column-width	列宽策略：auto / fixed / N1,N2,...（像素列表，* 走 auto）	auto
--diagram-retries	图表最大重试次数	10
--verbose	显示详细进度信息	否

支持的 Markdown 语法

• 标题（# ~ ######）
• 段落文本
• 无序/有序列表（支持无限深度嵌套、混合嵌套）
• 任务列表（- [ ] / - [x]）
• 代码块（带语言标识）
• Mermaid/PlantUML 图表 → 自动转换为飞书画板
• 引用块（支持嵌套引用，自动转换为 QuoteContainer）
• Callout 高亮块（> [!NOTE]、> [!WARNING] 等 6 种类型）
• 分割线
• 图片（默认通过 --upload-images 自动上传本地和网络图片；无此参数时创建占位块。表格单元格内的图片会真正嵌入为单元格内图片，见核心特性 #164；与文字混排的内联图片统一转为 [图片: 说明] 占位，http(s) 为可点击链接）
• 表格（行 > 9 用 insert_table_row API 追加保持单 block；列 > 9 按列组拆分保留首列；单元格内可放图片，导入后真正嵌入）
• 粗体、斜体、删除线、行内代码、下划线（<u>文本</u>）
• 链接
• 行内公式（$E = mc^2$，支持一段中多个公式）
• 块级公式（$$formula$$ 或独立行 $formula$）

图表示例（推荐使用 Mermaid）

```mermaid
flowchart TD
    A[开始] --> B{判断}
    B -->|是| C[处理]
    B -->|否| D[结束]
```

```plantuml
@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi
@enduml
```

支持的 Mermaid 图表类型（全部已验证）：

• ✅ flowchart（流程图，支持 subgraph 嵌套）
• ✅ sequenceDiagram（时序图）
• ✅ classDiagram（类图）
• ✅ stateDiagram-v2（状态图）
• ✅ erDiagram（ER 图）
• ✅ gantt（甘特图）
• ✅ pie（饼图）
• ✅ mindmap（思维导图）

Callout ハイライトブロックの例

> [!NOTE]
> 这是一个提示信息。

> [!WARNING]
> 这是一个警告信息。

> [!TIP]
> 这是一个技巧提示。

> [!CAUTION]
> 这是一个警示。

> [!IMPORTANT]
> 这是一个重要信息。

> [!SUCCESS]
> 这是一个成功信息。

Callout の内部では子ブロック（段落、リストなど）をサポートしており、自動的に Callout の子ブロックとして作成されます。

背景色のマッピング：

種類	背景色
NOTE/INFO	青 (6)
WARNING	赤 (2)
TIP	黄 (4)
CAUTION	オレンジ (3)
IMPORTANT	紫 (7)
SUCCESS	緑 (5)

数式の例

行内公式：爱因斯坦质能方程 $E = mc^2$ 是最著名的公式。

块级公式（独立行）：
$\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$

• インライン数式は 1 つの段落内で複数の $...$ 数式をサポートします
• ブロック数式は飛書では Text ブロック内の Equation 要素として作成されます
• 数式の内容は LaTeX の原文を保持します

下線の例

这段文本包含 <u>下划线</u> 样式。

出力形式

已导入文档！
  文档 ID: <document_id>
  文档链接: https://feishu.cn/docx/<document_id>
  导入块数: 25

例

# 创建新文档
feishu-cli doc import ./meeting-notes.md --title "会议纪要"

# 追加导入到现有文档
feishu-cli doc import ./updated-spec.md --document-id <document_id>

# 带图片导入（自动上传本地和网络图片）
feishu-cli doc import ./blog-post.md --title "博客文章" --upload-images

# 批量导入（一次循环多个 Markdown）
for f in *.md; do feishu-cli doc import "$f" --title "${f%.md}" --upload-images; done

検証済み機能

上記の「対応している Markdown 構文」に記載されたすべての構文はテストで検証済みであり、すべて正常に動作します。テーブル・画像・動画の具体的な処理の詳細は、上記の「コア機能」および「対応している Markdown 構文」の節を参照してください。以下では大規模テストの結果のみを記載します。

大規模テストの結果

正常にインポートできることを検証済みの大規模ドキュメント：

• 10,000 行以上の Markdown ✓
• 127 個の Mermaid 図 → すべて飛書ボードへの変換に成功 ✓
• 170 個以上のテーブル（17 行 × 5 列の単一 block への連続追加、9 列以上の列分割、列幅の自動計算を含む）→ すべて成功 ✓
• 8 種類の図 → flowchart/sequenceDiagram/classDiagram/stateDiagram/erDiagram/gantt/pie/mindmap すべて成功 ✓
• 88 個の Mermaid 図を 1 つずつテスト → 82/88 成功、6 失敗（3 件のサーバー側一時エラー + 2 件の中括弧構文 + 1 件の抽出異常）

三階段並行パイプラインアーキテクチャ

1. 第 1 段階（順次）：すべてのドキュメントブロックを作成し、図（Mermaid/PlantUML）とテーブルのタスクを収集します
2. 第 2 段階（並行）：worker プールを使用して図のインポートとテーブルの充填を並行処理します。テーブルセルの充填では、まず cellMap をウォームアップし、その後 batch_update API による一括書き込みを行います（single-group cell は 1 バッチあたり ≤ 30 個）。一括処理が失敗した場合にのみ per-cell にフォールバックします。行 > 9 の insert_table_row 追加は依然として 1 行ずつ直列で行われます（単一ドキュメントあたり 3 QPS のスロットリングを受けます）
3. 第 3 段階（逆順）：失敗した図を処理 → 空のボードブロックを削除し、コードブロックをフォールバック表示として挿入します

Mermaid の既知の制限

制限	説明	対応方法
{} 中括弧	Mermaid パーサーが {text} を菱形ノードとして認識します	自動的にコードブロックへフォールバック
par...and...end	飛書のパーサーは par 並行構文をまったくサポートしていません	Note over X: 並行実行 で代替
レンダリング複雑度の組み合わせが上限超過	単一の要因では発生しませんが、10+ participant + 2+ alt ブロック + 30+ 長いメッセージラベルの組み合わせでサーバー側が 500 を返します	リトライ後にコードブロックへフォールバック
サーバー側の一時エラー	散発的な HTTP 500（並行負荷によるもの）	自動リトライ（デフォルト最大 10 回、指数バックオフ）
Parse error はリトライしない	構文エラーは直接フォールバックします	自動的にコードブロックへフォールバック

レンダリング複雑度の安全しきい値（二分法による実測）：

• participant ≤8 または alt ≤1 またはメッセージラベルが短い → 安全
• 10 participant + 2 alt + 30 件の長いメッセージラベル → 上限超過
• 推奨：sequenceDiagram は participant ≤8、alt ≤1、メッセージラベルを短く保つ

技術的な説明

図は飛書ボード API を通じてインポートされます：

• API エンドポイント：/open-apis/board/v1/whiteboards/{id}/nodes/plantuml
• syntax_type=1 は PlantUML 構文、syntax_type=2 は Mermaid 構文を表します
• diagram_type は整数を使用します（0=auto, 6=flowchart など）
• リトライ戦略：指数バックオフ + x-ogw-ratelimit-reset レスポンスヘッダーを読み取って正確にバックオフ、デフォルト最大 10 回。Parse error と Invalid request parameter はリトライしません
• 失敗時のフォールバック：空のボードブロックを削除し、元の位置にコードブロックを挿入します
• 対応するコードブロック識別子：```mermaid、```plantuml、```puml

HTML タグ拡張構文

標準の Markdown 構文に加えて、インポート時には以下の HTML タグ形式の拡張構文も認識されます。これらのタグはエクスポート側で自動生成され、roundtrip（エクスポート→インポートで情報が失われない）をサポートします。

タグ	説明	例
<mention-user id="ou_xxx"/>	@ユーザー	MentionUser 要素を作成
<mention-doc token="xxx" type="docx">タイトル</mention-doc>	@ドキュメント	MentionDoc 要素を作成
<grid cols="2"><column>...</column><column>...</column></grid>	段組レイアウト	Grid Block + GridColumn 子ブロックを作成
<callout type="NOTE">内容</callout>	ハイライトブロック（HTML タグ形式）	> [!NOTE] と同等
<whiteboard type="blank"/>	空白ボード	Board Block を作成
<sheet rows="5" cols="5"/>	スプレッドシート	Sheet Block を作成
<bitable view="table"/>	多次元テーブル	Bitable Block を作成
<image token="xxx" width="800" align="center" caption="説明"/>	属性付き画像	Image Block を作成し、サイズ・配置を保持
<file token="xxx" name="report.pdf" view-type="1"/>	ファイルブロック	File Block を作成
<video src="./demo.mp4" data-name="demo.mp4" data-view-type="1"></video>	動画ブロック（v1.22+）	File Block (type=23) を作成し、mp4/mov/avi/mkv などの拡張子を動画として認識します。src はローカルパスまたはアップロード後の token です。単一ファイル ≤ 20MB は直接アップロード

これらのタグは主に roundtrip のシナリオ（エクスポート後に再インポート）で使用されますが、飛書のブロックタイプを正確に制御するために手動で記述することもできます。

動画インポートの並行処理：画像と worker プールを共有します（デフォルト 2 並行、API 5 QPS の制限を受けます）。インポート統計には video_total/success/failed/skipped が含まれます。verbose モードでは各動画のアップロード進捗が出力されます。

よくある質問

現象	原因	解決方法
認証失敗 / Token の期限切れ	未ログインまたは Token が失効している	feishu-cli auth login を実行して再認証します（Device Flow、offline_access を自動注入）
図がコードブロックへフォールバックされる	Mermaid/PlantUML の構文が飛書のレンダリングエンジンと互換性がない	references/doc-guide.md を参考に構文を調整します（中括弧禁止、par 禁止など）
超長テーブルのインポートに著しく時間がかかる	セル内容の充填は batch_update による一括処理で高速化済み（v1.29+、約 25-30 倍）。主な所要時間は行 > 9 のときに insert_table_row API が同じ block へ 1 行ずつ直列で追加 することによるものです（単一ドキュメントあたり 3 QPS のスロットリングを受け、1 行につき約 1 回の API ラウンドトリップが発生）	正常な動作です。verbose モードでは 5 行ごとに進捗が出力されます。行数が極端に多い（200+）場合は、スプレッドシート（Sheet）での扱いに変更することを推奨します
テーブルが複数の block に分割される	列 > 9 のとき CLI が列グループごとに分割します（各グループ ≤ 9 列）。先頭列は識別子としてすべてのグループで保持されます	正常な動作です。分割後に行を識別できなくなるのを防ぎます
画像のアップロードに失敗する	ネットワークが不通、または画像 URL にアクセスできない	ネットワークの接続性を確認してください。失敗した画像は自動的にプレースホルダーブロックが作成され、インポート全体には影響しません
ドキュメントの作成は成功したが編集できない	owner 設定に応じた権限が追加されていない	FEISHU_OWNER_EMAIL を設定したうえで perm add を実行します。transfer_ownership=true の場合にのみ perm transfer-owner を実行します