feishu-update-doc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

feishu__update_doc

更新飞书云文档内容，支持 7 种更新模式。优先使用局部更新（replace_range/append/insert_before/insert_after），慎用 overwrite（会清空文档重写，可能丢失图片、评论等）。

Update Feishu Cloud Docs content with support for 7 update modes. Prefer partial updates (replace_range/append/insert_before/insert_after), use overwrite with caution (it will clear and rewrite the document, which may cause loss of images, comments, etc.).

定位方式

Positioning Methods

定位模式（replace_range/replace_all/insert_before/insert_after/delete_range）支持两种定位方式，二选一：

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

selection_with_ellipsis - 内容定位

selection_with_ellipsis - Content Positioning

支持两种格式：

范围匹配：
```
开头内容...结尾内容
```
- 匹配从开头到结尾的所有内容（包含中间内容）
- 建议 10-20 字符确保唯一性
精确匹配：
```
完整内容
```
（不含
```
...
```
）
- 匹配完整的文本内容
- 适合替换短文本、关键词等

转义说明：如果要匹配的内容本身包含

...

，使用

\.\.\.

表示字面量的三个点。

示例：

```
你好...世界
```
→ 匹配从"你好"到"世界"之间的任意内容
```
你好\.\.\.世界
```
→ 匹配字面量 "你好...世界"

建议：如果文档中有多个

...

，建议使用更长的上下文来精确定位，避免歧义。

Supports two formats:

Range Matching:
```
start content...end content
```
- Matches all content from the start to the end (including intermediate content)
- It is recommended to use 10-20 characters to ensure uniqueness
Exact Matching:
```
complete content
```
(without
```
...
```
)
- Matches the exact text content
- Suitable for replacing short text, keywords, etc.

Escape Instructions: If the content to be matched itself contains

...

, use

\\.\\.\\.

to represent the literal three dots.

Examples:

```
你好...世界
```
→ Matches any content between "你好" and "世界"
```
你好\\.\\.\\.世界
```
→ Matches the literal string "你好...世界"

Recommendation: If there are multiple

...

in the document, it is recommended to use longer context for precise positioning to avoid ambiguity.

selection_by_title - 标题定位

selection_by_title - Title Positioning

格式：

## 章节标题

（可带或不带 # 前缀）

自动定位整个章节（从该标题到下一个同级或更高级标题之前）。

示例：

```
## 功能说明
```
→ 定位二级标题"功能说明"及其下所有内容
```
功能说明
```
→ 定位任意级别的"功能说明"标题及其内容

Format:

## Chapter Title

(with or without the # prefix)

Automatically locates the entire chapter (from the title to before the next sibling or higher-level title).

Examples:

```
## Feature Description
```
→ Locates the level 2 title "Feature Description" and all its content
```
Feature Description
```
→ Locates the "Feature Description" title of any level and its content

可选参数

Optional Parameters

new_title

更新文档标题。如果提供此参数，将在更新文档内容后同步更新文档标题。

特性：

仅支持纯文本，不支持富文本格式
长度限制：1-800 字符
可以与任何 mode 配合使用
标题更新在内容更新之后执行

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

Features:

Only supports plain text, does not support rich text formatting
Length limit: 1-800 characters
Can be used with any mode
Title update is executed after content update

返回值

Return Values

成功

Success

json

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

json

{
  "success": true,
  "doc_id": "Document ID",
  "mode": "Mode Used",
  "message": "Document updated successfully (xxx mode)",
  "warnings": ["Optional warning list"],
  "log_id": "Request Log ID"
}

异步模式（大文档超时）

Asynchronous Mode (Timeout for Large Documents)

json

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

使用返回的

task_id

再次调用 update-doc（仅传 task_id 参数）查询状态。

json

{
  "task_id": "async_task_xxxx",
  "message": "Document update has been submitted for asynchronous processing, please use task_id to query status",
  "log_id": "Request Log ID"
}

Use the returned

task_id

to call update-doc again (only pass the task_id parameter) to query the status.

错误

Error

json

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

json

{
  "error": "[Error Code] Error Message\n💡 Suggestion: Fix Suggestion\n📍 Context: Context Information",
  "log_id": "Request Log ID"
}

使用示例

Usage Examples

append - 追加到末尾

append - Append to End

json

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

json

{
  "doc_id": "Document ID or URL",
  "mode": "append",
  "markdown": "## New Chapter\n\nAppended content..."
}

replace_range - 定位替换

replace_range - Targeted Replacement

使用

selection_with_ellipsis

：

json

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

使用

selection_by_title

（替换整个章节）：

json

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

Using

selection_with_ellipsis

json

{
  "doc_id": "Document ID or URL",
  "mode": "replace_range",
  "selection_with_ellipsis": "## Old Chapter Title...Old Chapter End.",
  "markdown": "## New Chapter Title\n\nNew content..."
}

Using

selection_by_title

(replace entire chapter):

json

{
  "doc_id": "Document ID or URL",
  "mode": "replace_range",
  "selection_by_title": "## Feature Description",
  "markdown": "## Feature Description\n\nUpdated feature description content..."
}

replace_all - 全文替换

replace_all - Full-text Replacement

与 replace_range 类似，但支持多处同时替换（replace_range 要求匹配唯一）：

json

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

返回值包含

replace_count

字段，表示替换的次数：

json

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

注意：

与
```
replace_range
```
不同，
```
replace_all
```
允许多个匹配
如果没有找到匹配内容，会返回错误
```
markdown
```
可以为空字符串，表示删除所有匹配内容

Similar to replace_range, but supports simultaneous replacement in multiple locations (replace_range requires unique matches):

json

{
  "doc_id": "Document ID or URL",
  "mode": "replace_all",
  "selection_with_ellipsis": "张三",
  "markdown": "李四"
}

Return Value includes the

replace_count

field, indicating the number of replacements:

json

{
  "success": true,
  "replace_count": 4,
  "message": "Document updated successfully (replace_all mode, 4 replacements made)"
}

Notes:

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, which means deleting all matching content

insert_before - 前插入

insert_before - Insert Before

json

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

json

{
  "doc_id": "Document ID or URL",
  "mode": "insert_before",
  "selection_with_ellipsis": "## Dangerous Operations...Risk of Data Loss.",
  "markdown": "> **Warning**: Please proceed with caution for the following operations!"
}

insert_after - 后插入

insert_after - Insert After

json

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

json

{
  "doc_id": "Document ID or URL",
  "mode": "insert_after",
  "selection_with_ellipsis": "```python...```",
  "markdown": "**Output Example**: \n```\nresult = 42\n```"
}

delete_range - 删除内容

delete_range - Delete Content

使用

selection_with_ellipsis

：

json

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

使用

selection_by_title

（删除整个章节）：

json

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

注意：delete_range 模式不需要 markdown 参数。

Using

selection_with_ellipsis

json

{
  "doc_id": "Document ID or URL",
  "mode": "delete_range",
  "selection_with_ellipsis": "## Obsolete Chapter...Content No Longer Needed."
}

Using

selection_by_title

(delete entire chapter):

json

{
  "doc_id": "Document ID or URL",
  "mode": "delete_range",
  "selection_by_title": "## Obsolete Chapter"
}

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

同时更新标题和内容

Update Title and Content Simultaneously

可以在任何更新模式中添加

new_title

参数来同时更新文档标题：

json

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

json

{
  "doc_id": "文档ID或URL",
  "mode": "append",
  "markdown": "## 更新日志\n\n2025-12-18: 新增功能...",
  "new_title": "项目文档（已更新）"
}

You can add the

new_title

parameter to any update mode to update the document title at the same time:

json

{
  "doc_id": "Document ID or URL",
  "mode": "overwrite",
  "markdown": "# Project Document v2.0\n\nBrand new content...",
  "new_title": "Project Document v2.0"
}

json

{
  "doc_id": "Document ID or URL",
  "mode": "append",
  "markdown": "## Update Log\n\n2025-12-18: New features added...",
  "new_title": "Project Document (Updated)"
}

overwrite - 完全覆盖

overwrite - Full Overwrite

⚠️ 会清空文档后重写，可能丢失图片、评论等，仅在需要完全重建文档时使用。

json

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

⚠️ It will clear and rewrite the document, which may cause loss of images, comments, etc. Use only when you need to completely rebuild the document.

json

{
  "doc_id": "Document ID or URL",
  "mode": "overwrite",
  "markdown": "# New Document\n\nBrand new content..."
}

最佳实践

Best Practices

小粒度精确替换

Granular Exact Replacement

修改文档内容时，定位范围越小越安全。尤其是表格、分栏等嵌套块，应精确定位到需要修改的文本，避免影响其他内容。

示例：表格单元格中有图片和文字，只需修改文字

❌ 替换整个表格或整行 → 可能破坏图片引用
✅ 只定位需要修改的文本 → 图片等其他内容不受影响

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

Example: A table cell contains images and text, only need to modify the text

❌ Replace the entire table or entire row → May break image references
✅ Only locate the text that needs to be modified → Images and other content remain unaffected

保护不可重建的内容

Protect Non-reconstructible Content

图片、画板、电子表格、多维表格、任务等内容以 token 形式存储，无法读出后原样写入。

保护策略：

替换时避开包含这些内容的区域
精确定位到纯文本部分进行修改

Content such as images, whiteboards, spreadsheets, base tables, and tasks are stored as tokens, which cannot be read and written back in their original form.

Protection Strategies:

Avoid areas containing such content when replacing
Precisely locate plain text parts for modification

分步更新优于整体覆盖

Step-by-step Updates Are Better Than Full Overwrite

修改多处内容时：

✅ 多次小范围替换，逐步修改
⚠️ 谨慎使用
```
overwrite
```
重写整个文档, 除非你认为风险完全可控

原因：局部更新保留原有媒体、评论、协作历史，更安全可靠。

When modifying multiple parts of content:

✅ Perform multiple small-range replacements and modify gradually
⚠️ Use
```
overwrite
```
to rewrite the entire document with caution, unless you consider the risk completely controllable

Reason: Partial updates retain original media, comments, and collaboration history, making them safer and more reliable.

insert 模式扩大定位范围时注意插入位置

Pay Attention to Insertion Position When Expanding Positioning Range in Insert Mode

使用

insert_before

或

insert_after

时，如果目标内容重复出现，需要扩大

selection_with_ellipsis

范围来唯一定位。

关键：插入位置基于匹配范围的边界：

```
insert_after
```
→ 插入在匹配范围的结尾之后
```
insert_before
```
→ 插入在匹配范围的开头之前

扩大范围时，确保边界仍然是期望的插入点。

When using

insert_before

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 the boundary of the matching range:

```
insert_after
```
→ Insert after the end of the matching range
```
insert_before
```
→ Insert before the start of the matching range

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

修复画板语法错误

Fix Whiteboard Syntax Errors

当 create-doc 或 update-doc 返回画板写入失败的 warning 时：

warning 中包含 whiteboard 标签（如
```
<whiteboard token="xxx"/>
```
）
分析错误信息，修正 Mermaid/PlantUML 语法
用
```
replace_range
```
替换：
```
selection_with_ellipsis
```
使用 warning 中的 whiteboard 标签，
```
markdown
```
提供修正后的代码块
重新提交验证

When create-doc or update-doc returns a warning about whiteboard writing failure:

The warning contains a whiteboard tag (e.g.,
```
<whiteboard token="xxx"/>
```
)
Analyze the error message and correct the Mermaid/PlantUML syntax
Use
```
replace_range
```
to replace:
```
selection_with_ellipsis
```
uses the whiteboard tag from the warning,
```
markdown
```
provides the corrected code block
Resubmit for verification

注意事项

Notes

Markdown 语法：支持飞书扩展语法，详见 create-doc 工具文档

Markdown Syntax: Supports Feishu extended syntax, see the create-doc tool documentation for details