飞书 Markdown 转区块（Feishu Markdown to Blocks）

通过区块转换（block convert）+ 后代插入（descendant）API，将 Markdown 内容（包括表格）插入飞书文档中。

适用场景

• feishu_doc 的 write 操作会**完全替换**整篇文档；本工具用于在指定位置**插入**内容
• feishu_doc 的 create_table_with_values 在处理较大表格时存在限制
• 你需要向已有文档中插入表格、代码块或结构复杂的嵌套内容

使用方法

# 从文件插入（追加到文档末尾）
python3 /scripts/md2blocks.py  content.md

# 从标准输入插入
echo "| A | B |\n|---|---|\n| 1 | 2 |" | python3 /scripts/md2blocks.py  -

# 插入到指定区块之后
python3 /scripts/md2blocks.py  content.md --after 

# 替换全部内容
python3 /scripts/md2blocks.py  content.md --replace

工作原理

1. 调用 POST /docx/v1/documents/blocks/convert 将 Markdown 转换为区块结构
2. 移除表格区块中的 merge_info 字段（该字段为只读，若保留会导致插入失败）
3. 调用 POST /docx/v1/documents/{doc}/blocks/{parent}/descendant 插入生成的区块

后代 API（/descendant）可正确处理嵌套结构（例如表格单元格内含文本），而更简单的 /children API 无法支持此类结构。

位置控制

--after 参数会在指定区块后立即插入内容；脚本会自动查找出该区块在文档中的索引位置。

关键细节： /descendant API 的 index 参数必须置于请求体（request body）中，不可作为 URL 查询参数传递。若在 URL 中以 ?index=N 方式传入，该参数将被静默忽略（内容默认追加至文档末尾）。本脚本已正确实现该逻辑。

支持的 Markdown 语法

文本、标题（h1–h9）、无序列表、有序列表、代码块、引用块、表格、待办事项（todo items）、分隔线（dividers）。

限制条件

• Markdown 中的图片不会自动上传；需单独调用上传接口 + patch 更新操作
• 单次插入最多支持 1000 个区块；如文档过大，请自行拆分
• 飞书应用需具备 docx:document.block:convert 权限
• 文档编辑频率限制：每篇文档最多 3 次操作/秒

参考文档

如需完整的区块级 API 参考，请查阅 feishu-block-ops 技能，其涵盖以下内容：

• 全部区块相关 API（创建/读取/更新/删除/批量操作）
• 区块类型参考、文本元素类型说明
• 表格操作模式（批量编辑、合并单元格等）
• 常见使用模式与注意事项（gotchas）