一、问题背景
在 OpenClaw 项目中，需要实现自动创建飞书文档并发送日报的功能。看似简单的需求，却遇到了两个意想不到的问题。
二、问题一：权限缺失导致写入失败
现象：调用飞书文档 API 的 write 和 append 操作时，返回 400 错误。
解决方案：
- 进入应用管理 → 权限管理
- 添加 docx:document.block:convert 权限
已授予的权限：docx:document、drive:drive
缺失的权限：docx:document.block:convert（文档块转换）
- 提交审核（如需）
验证：添加权限后，write 操作返回成功。
现象：权限问题解决后，文档可以写入了，但内容顺序完全错乱。
排查过程：
- 使用 1. 2. 3. 有序列表 → 顺序错乱
根因：飞书 API 的 document.convert 接口在处理 markdown 时，内部块排序逻辑有 bug。
- 测试不同 markdown 格式，确认是飞书 markdown 转换 API 的 bug
- 使用 list_blocks 查看实际块结构
测试结论：
- 使用 - 无序列表 → 顺序错乱
- 纯文本（无任何 markdown 格式）→ 顺序正确
- 发现飞书 API 返回的 blocks 数组顺序错乱
- 使用 # ## 标题语法 → 顺序错乱
三、问题二：markdown 转换导致内容顺序错乱
四、最终解决方案
方案一：使用纯文本格式（推荐）
不使用任何 markdown 格式符号，直接写纯文本。
优点：简单直接、顺序正确、兼容性好 缺点：没有格式美化（无标题、无列表）
方案二：分多次 append
每次 append 一小段内容，避免一次性转换大量 markdown。
优点：可以使用部分 markdown 格式、顺序可控 缺点：需要多次 API 调用、实现复杂
五、经验总结
第一条：权限问题优先排查 飞书 API 的很多 400 错误都是权限问题，先检查应用权限是否完整。
第二条：不要过度依赖 markdown 转换 飞书的 markdown 转换 API 有 bug，复杂格式容易出问题。简单场景用纯文本更可靠。
第三条：用 list_blocks 验证实际内容 read 接口返回的 content 字段是纯文本，无法反映实际块结构。用 list_blocks 查看真实块顺序。
第四条：记录问题排查过程 把踩过的坑记录下来，下次遇到类似问题可以快速解决。
六、参考代码
const doc = await feishu_doc.create({ title: "工作日报" });
await feishu_doc.write({
doc_token: doc.document_id,
content: "工作日报 - 2026 年 2 月 26 日\n\n【今日工作摘要】\n说明：...\n\n【待改进事项】\n需要建立每日工作记录机制\n确保 memory 文件及时更新\n重要工作内容应及时记录\n\n【备注】\n本日报由系统自动生成"
});
七、后续优化
- 封装飞书文档写入工具，自动处理格式问题
- 添加文档内容验证，确保写入后顺序正确
- 探索飞书 API 的其他写入方式（如直接操作块）
