用途:更新飞书云文档内容,提供 7 种更新模式:append(追加)、overwrite(覆盖)、replace_range(定位替换)、replace_all(全文替换)、insert_before(前插入)、insert_after(后插入)、delete_range(删除)。官方建议优先使用局部更新,慎用 overwrite,因为覆盖会清空文档重写,可能丢失图片、评论等。
定位方式:定位类模式支持两种方式,二选一。selection_with_ellipsis 为内容定位,支持范围匹配(开头内容...结尾内容)与精确匹配(完整内容,不含 ...),建议 10-20 字符确保唯一性;若内容本身含 ...,用 ... 表示字面量三个点。selection_by_title 为标题定位,格式如 ## 章节标题,自动定位从该标题到下一个同级或更高级标题之前的整个章节。
可选参数:new_title 可在更新内容后同步更新文档标题,仅支持纯文本,长度 1-800 字符,可与任何 mode 配合。
返回值:成功返回 success、doc_id、mode、message、warnings、log_id;大文档超时进入异步模式,返回 task_id,需再次调用 update-doc 并仅传 task_id 查询状态;错误返回 error 与 log_id。replace_all 额外返回 replace_count。
使用方式:以 JSON 参数调用,如 append 模式传 doc_id、mode、markdown;replace_range 传 selection_with_ellipsis 或 selection_by_title 与 markdown;delete_range 不需要 markdown 参数。
限制与注意事项:图片、画板、电子表格、多维表格、任务等以 token 形式存储,无法读出后原样写入,替换时应避开这些区域,精确定位纯文本;修改多处建议多次小范围替换;insert 模式扩大定位范围时需确保边界仍是期望插入点;画板写入失败时可根据 warning 中的 whiteboard 标签用 replace_range 替换修正后的代码块。Markdown 支持飞书扩展语法,详见 create-doc 工具文档。