feishu-update-doc

feishu__update_doc

Update Feishu cloud document content, supporting 7 update modes. Prefer partial updates (replace_range/append/insert_before/insert_after), and use overwrite with caution (it clears the document and rewrites it, which may lose images, comments, etc.).

Positioning methods

Positioning modes (replace_range/replace_all/insert_before/insert_after/delete_range) support two positioning methods; choose one:

selection_with_ellipsis - content positioning

Supports two formats:

1. Range matching：开头内容...结尾内容

   • Matches all content from the beginning to the end (including the content in between)
   • 10-20 characters are recommended to ensure uniqueness

2. Exact matching：完整内容(excluding ...）

   • Matches the complete text content
   • Suitable for replacing short text, keywords, etc.

Escaping notes: If the content to be matched itself contains ..., use \.\.\. to represent a literal three dots.

Example:

• 你好...世界 → matches any content between "你好" and "世界"
• 你好\.\.\.世界 → matches the literal "你好...世界"

Recommendation: If the document contains multiple ..., it is recommended to use a longer context for precise positioning to avoid ambiguity.

selection_by_title - title positioning

Format:## 章节标题(with or without the # prefix)

Automatically positions the entire section (from that heading to before the next heading of the same level or higher).

Example：

• ## 功能说明 → positions the level-2 heading "功能说明" and all content under it
• 功能说明 → positions the "功能说明" heading at any level and its content

Optional parameters

new_title

Update the document title. If this parameter is provided, the document title will be updated synchronously after the document content is updated.

Features：

• Only plain text is supported; rich text formatting is not supported
• Length limit: 1-800 characters
• Can be used with any mode
• The title update is performed after the content update

Return value

Success

{
  "success": true,
  "doc_id": "文档ID",
  "mode": "使用的模式",
  "message": "文档更新成功（xxx模式）",
  "warnings": ["可选警告列表"],
  "log_id": "请求日志ID"
}

Asynchronous mode (large document timeout)

{
  "task_id": "async_task_xxxx",
  "message": "文档更新已提交异步处理，请使用 task_id 查询状态",
  "log_id": "请求日志ID"
}

Use the returned task_id to call update-doc again (passing only the task_id parameter) to query the status.

Error

{
  "error": "[错误码] 错误消息\n💡 Suggestion: 修复建议\n📍 Context: 上下文信息",
  "log_id": "请求日志ID"
}

---

Usage examples

append - append to the end

{
  "doc_id": "文档ID或URL",
  "mode": "append",
  "markdown": "## 新章节\n\n追加的内容..."
}

replace_range - targeted replace

Use selection_with_ellipsis：

{
  "doc_id": "文档ID或URL",
  "mode": "replace_range",
  "selection_with_ellipsis": "## 旧章节标题...旧章节结尾。",
  "markdown": "## 新章节标题\n\n新的内容..."
}

Use selection_by_title(replace the entire section):

{
  "doc_id": "文档ID或URL",
  "mode": "replace_range",
  "selection_by_title": "## 功能说明",
  "markdown": "## 功能说明\n\n更新后的功能说明内容..."
}

replace_all - full-text replace

Similar to replace_range, but supports replacing multiple occurrences at the same time (replace_range requires a unique match):

{
  "doc_id": "文档ID或URL",
  "mode": "replace_all",
  "selection_with_ellipsis": "张三",
  "markdown": "李四"
}

Return valueContains the replace_count field, indicating the number of replacements:

{
  "success": true,
  "replace_count": 4,
  "message": "文档更新成功（replace_all模式，替换4处）"
}

Note：

• Unlike replace_range ,replace_all allows multiple matches
• If no matching content is found, an error will be returned
• markdown can be an empty string, indicating deletion of all matching content

insert_before - insert before

{
  "doc_id": "文档ID或URL",
  "mode": "insert_before",
  "selection_with_ellipsis": "## 危险操作...数据丢失风险。",
  "markdown": "> **警告**：以下操作需谨慎！"
}

insert_after - insert after

{
  "doc_id": "文档ID或URL",
  "mode": "insert_after",
  "selection_with_ellipsis": "```python...```",
  "markdown": "**输出示例**：\n```\nresult = 42\n```"
}

delete_range - delete content

Use selection_with_ellipsis：

{
  "doc_id": "文档ID或URL",
  "mode": "delete_range",
  "selection_with_ellipsis": "## 废弃章节...不再需要的内容。"
}

Use selection_by_title(delete the entire section):

{
  "doc_id": "文档ID或URL",
  "mode": "delete_range",
  "selection_by_title": "## 废弃章节"
}

Note: The delete_range mode does not require a markdown parameter.

Update the title and content at the same time

You can add new_title to any update mode to update the document title at the same time:

{
  "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": "项目文档（已更新）"
}

overwrite - fully overwrite

⚠️ This will clear the document and then rewrite it, possibly losing images, comments, etc. Use it only when the document needs to be completely rebuilt.

{
  "doc_id": "文档ID或URL",
  "mode": "overwrite",
  "markdown": "# 新文档\n\n全新的内容..."
}

---

Best practices

Small-grained precise replacement

When modifying document content,the smaller the targeted range, the safer it is. Especially for nested blocks such as tables and columns, you should precisely target the text that needs to be modified to avoid affecting other content.

Example: A table cell contains an image and text, and only the text needs to be modified

• ❌ Replace the entire table or the entire row → may break image references
• ✅ Target only the text that needs to be modified → other content such as images is unaffected

Protect content that cannot be rebuilt

Content such as images, whiteboards, spreadsheets, Base, and tasks is stored as tokens,and cannot be written back exactly as read。

Protection strategy：

• Avoid areas containing this content when replacing
• Precisely target plain text parts for modification

Step-by-step updates are better than full overwrites

When modifying multiple places:

• ✅ Make multiple small-range replacements and modify step by step
• ⚠️ Use overwrite to rewrite the entire document with caution, unless you believe the risk is fully controllable

Reason: Partial updates preserve the original media, comments, and collaboration history, and are safer and more reliable.

When expanding the targeting range in insert mode, pay attention to the insertion position

When using insert_before or insert_after , if the target content appears repeatedly, you need to expand the selection_with_ellipsis range to locate it uniquely.

Key: The insertion position is based on theboundary：

• insert_after → insert after theendof the matching range
• insert_before → insert before thestartof the matching range

When expanding the range, make sure the boundary is still the desired insertion point.

Fix whiteboard syntax errors

When create-doc or update-doc returns a warning that whiteboard writing failed:

1. The warning contains a whiteboard tag (such as <whiteboard token="xxx"/>）
2. Analyze the error message and fix the Mermaid/PlantUML syntax
3. Replace with replace_range :selection_with_ellipsis Use the whiteboard tag in the warning,markdown Provide the corrected code block
4. Resubmit for verification

---

Notes

• Markdown syntax: Supports Feishu extended syntax. For details, see the create-doc tool documentation