feishu-doc-long-content

Create Feishu Docs by first creating an empty doc, then write content in chunks under 800 bytes to avoid truncation or errors.

飞书文档长内容写入实战经验，解决 content 超长截断问题

问题背景

飞书文档工具 feishu_doc 的 write / create action 对单次 content 长度有限制（约 1KB），超出后会：

• 直接返回 400 错误
• 或部分写入后截断（显示空白）

核心要点

1. create 只是创建空白文档

{
  "action": "create",
  "title": "新文档"
}

返回 doc_id，但文档内容是空的。

2. 必须用 write 写入内容

{
  "action": "write",
  "doc_token": "ABC123",
  "content": "# 标题\n内容..."
}

3. content 必须控制在 1KB 以内

经验值：

• < 800 字节：安全写入
• 800-1500 字节：可能失败
• > 1500 字节：基本失败

4. 长内容解决方案

方案A：拆分章节 将内容拆成多个小文档，每个 < 800 字节：

文档1：第1-2章
文档2：第3-4章
文档3：第5-6章
文档4：第7-8章

方案B：多次 append 创建文档后，分多次 append（但 append 也有累积限制）

方案C：先存本地文件 将内容写入本地 md 文件，让用户自己查看或转换

正确流程

// 1. 创建文档
{ "action": "create", "title": "笔记 Ch1" }
// → { "doc_id": "ABC123", "url": "..." }

// 2. 写入内容（控制 < 800 字节）
{ "action": "write", "doc_token": "ABC123", "content": "精简版内容..." }

// 3. 验证
{ "action": "read", "doc_token": "ABC123" }

常见错误

错误表现	原因	解决方案
文档创建后空白	create 后没写 content	用 write 写入
write 返回成功但内容截断	content 超过 1KB	拆分内容
write 返回 400 错误	content 过长	精简内容或拆分

判断内容长度

在写入前估算：

• 纯文本：约 1 字符 = 1 字节
• Markdown：约 1 字符 = 1 字节（含格式符）
• 经验：800 字符约等于 800 字节（中文英文混合时略大）

最佳实践

1. 先在本地写 md 文件，确认内容完整
2. 写入飞书前精简，移除冗余格式和重复内容
3. 分章节输出，每章一个文档
4. 写入后立即验证，用 read 检查 block_count

---

经验来源：2026-02-25 初级会计实务笔记输出实战