更新飞书云文档内容,支持 7 种更新模式。优先使用局部更新(replace_range/append/insert_before/insert_after),慎用 overwrite(会清空文档重写,可能丢失图片、评论等)。
定位模式(replace_range/replace_all/insert_before/insert_after/delete_range)支持两种定位方式,二选一:
支持两种格式:
范围匹配:开头内容...结尾内容
精确匹配:完整内容(不含 ...)
转义说明:如果要匹配的内容本身包含 ...,使用 \.\.\. 表示字面量的三个点。
示例:
你好...世界 → 匹配从"你好"到"世界"之间的任意内容你好\.\.\.世界 → 匹配字面量 "你好...世界"建议:如果文档中有多个 ...,建议使用更长的上下文来精确定位,避免歧义。
格式:## 章节标题(可带或不带 # 前缀)
自动定位整个章节(从该标题到下一个同级或更高级标题之前)。
示例:
## 功能说明 → 定位二级标题"功能说明"及其下所有内容功能说明 → 定位任意级别的"功能说明"标题及其内容更新文档标题。如果提供此参数,将在更新文档内容后同步更新文档标题。
特性:
{
"success": true,
"doc_id": "文档ID",
"mode": "使用的模式",
"message": "文档更新成功(xxx模式)",
"warnings": ["可选警告列表"],
"log_id": "请求日志ID"
}
{
"task_id": "async_task_xxxx",
"message": "文档更新已提交异步处理,请使用 task_id 查询状态",
"log_id": "请求日志ID"
}
使用返回的 task_id 再次调用 update-doc(仅传 task_id 参数)查询状态。
{
"error": "[错误码] 错误消息\n💡 Suggestion: 修复建议\n📍 Context: 上下文信息",
"log_id": "请求日志ID"
}
{
"doc_id": "文档ID或URL",
"mode": "append",
"markdown": "## 新章节\n\n追加的内容..."
}
使用 selection_with_ellipsis:
{
"doc_id": "文档ID或URL",
"mode": "replace_range",
"selection_with_ellipsis": "## 旧章节标题...旧章节结尾。",
"markdown": "## 新章节标题\n\n新的内容..."
}
使用 selection_by_title(替换整个章节):
{
"doc_id": "文档ID或URL",
"mode": "replace_range",
"selection_by_title": "## 功能说明",
"markdown": "## 功能说明\n\n更新后的功能说明内容..."
}
与 replace_range 类似,但支持多处同时替换(replace_range 要求匹配唯一):
{
"doc_id": "文档ID或URL",
"mode": "replace_all",
"selection_with_ellipsis": "张三",
"markdown": "李四"
}
返回值包含 replace_count 字段,表示替换的次数:
{
"success": true,
"replace_count": 4,
"message": "文档更新成功(replace_all模式,替换4处)"
}
注意:
replace_range 不同,replace_all 允许多个匹配markdown 可以为空字符串,表示删除所有匹配内容{
"doc_id": "文档ID或URL",
"mode": "insert_before",
"selection_with_ellipsis": "## 危险操作...数据丢失风险。",
"markdown": "> **警告**:以下操作需谨慎!"
}
{
"doc_id": "文档ID或URL",
"mode": "insert_after",
"selection_with_ellipsis": "```python...```",
"markdown": "**输出示例**:\n```\nresult = 42\n```"
}
使用 selection_with_ellipsis:
{
"doc_id": "文档ID或URL",
"mode": "delete_range",
"selection_with_ellipsis": "## 废弃章节...不再需要的内容。"
}
使用 selection_by_title(删除整个章节):
{
"doc_id": "文档ID或URL",
"mode": "delete_range",
"selection_by_title": "## 废弃章节"
}
注意:delete_range 模式不需要 markdown 参数。
可以在任何更新模式中添加 new_title 参数来同时更新文档标题:
{
"doc_id": "文档ID或URL",
"mode": "overwrite",
"markdown": "# 项目文档 v2.0\n\n全新的内容...",
"new_title": "项目文档 v2.0"
}
{
"doc_id": "文档ID或URL",
"mode": "append",
"markdown": "## 更新日志\n\n2025-12-18: 新增功能...",
"new_title": "项目文档(已更新)"
}
⚠️ 会清空文档后重写,可能丢失图片、评论等,仅在需要完全重建文档时使用。
{
"doc_id": "文档ID或URL",
"mode": "overwrite",
"markdown": "# 新文档\n\n全新的内容..."
}
修改文档内容时,定位范围越小越安全。尤其是表格、分栏等嵌套块,应精确定位到需要修改的文本,避免影响其他内容。
示例:表格单元格中有图片和文字,只需修改文字
图片、画板、电子表格、多维表格、任务等内容以 token 形式存储,无法读出后原样写入。
保护策略:
修改多处内容时:
overwrite 重写整个文档, 除非你认为风险完全可控原因:局部更新保留原有媒体、评论、协作历史,更安全可靠。
使用 insert_before 或 insert_after 时,如果目标内容重复出现,需要扩大 selection_with_ellipsis 范围来唯一定位。
关键:插入位置基于匹配范围的边界:
insert_after → 插入在匹配范围的结尾之后insert_before → 插入在匹配范围的开头之前扩大范围时,确保边界仍然是期望的插入点。
当 create-doc 或 update-doc 返回画板写入失败的 warning 时:
<whiteboard token="xxx"/>)replace_range 替换:selection_with_ellipsis 使用 warning 中的 whiteboard 标签,markdown 提供修正后的代码块