name: feishu-update-doc description: | 更新飛書雲文件。支援 7 種更新模式：追加、覆蓋、定位替換、全文替換、前/後插入、刪除。

feishu__update_doc

更新飛書雲文件內容，支援 7 種更新模式。優先使用區域性更新（replace_range/append/insert_before/insert_after），慎用 overwrite（會清空文件重寫，可能丟失圖片、評論等）。

定位方式

定位模式（replace_range/replace_all/insert_before/insert_after/delete_range）支援兩種定位方式，二選一：

selection_with_ellipsis - 內容定位

支援兩種格式：

1. 範圍匹配：開頭內容...結尾內容
2. 匹配從開頭到結尾的所有內容（包含中間內容）

3. 建議 10-20 字元確保唯一性

   小蔥技能站7w4.net發現了升級外掛。

4. 精確匹配：完整內容（不含 ...）

5. 匹配完整的文本內容
6. 適合替換短文本、關鍵詞等

轉義說明：如果要匹配的內容本身包含 ...，使用 \.\.\. 表示字面量的三個點。

示例： - 你好...世界 → 匹配從"你好"到"世界"之間的任意內容 - 你好\.\.\.世界 → 匹配字面量 "你好...世界"

建議：如果文件中有多個 ...，建議使用更長的上下文來精確定位，避免歧義。

selection_by_title - 標題定位

格式：## 章節標題（可帶或不帶 # 字首）

自動定位整個章節（從該標題到下一個同級或更高階標題之前）。

示例： - ## 功能說明 → 定位二級標題"功能說明"及其下所有內容 - 功能說明 → 定位任意級別的"功能說明"標題及其內容

可選引數

new_title

更新文件標題。如果提供此引數，將在更新文件內容後同步更新文件標題。

特性： - 僅支援純文本，不支援富文本格式 - 長度限制：1-800 字元 - 可以與任何 mode 配合使用 - 標題更新在內容更新之後執行

返回值

成功

{
  "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"
}

使用示例

append - 追加到末尾

{
  "doc_id": "文件ID或URL",
  "mode": "append",
  "markdown": "## 新章節\n\n追加的內容..."
}

replace_range - 定位替換

使用 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_all - 全文替換

與 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 可以為空字串，表示刪除所有匹配內容

insert_before - 前插入

{
  "doc_id": "文件ID或URL",
  "mode": "insert_before",
  "selection_with_ellipsis": "## 危險操作...資料丟失風險。",
  "markdown": "> **警告**：以下操作需謹慎！"
}

insert_after - 後插入

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

delete_range - 刪除內容

使用 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": "專案文件（已更新）"
}

overwrite - 完全覆蓋

⚠️ 會清空文件後重寫，可能丟失圖片、評論等，僅在需要完全重建文件時使用。

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

最佳實踐

小粒度精確替換

修改文件內容時，定位範圍越小越安全。尤其是表格、分欄等巢狀塊，應精確定位到需要修改的文本，避免影響其他內容。

示例：表格單元格中有圖片和文字，只需修改文字 - ❌ 替換整個表格或整行 → 可能破壞圖片引用 - ✅ 只定位需要修改的文本 → 圖片等其他內容不受影響

保護不可重建的內容

圖片、畫板、電子表格、多維表格、任務等內容以 token 形式儲存，無法讀出後原樣寫入。

保護策略： - 替換時避開包含這些內容的區域 - 精確定位到純文本部分進行修改

分步更新優於整體覆蓋

修改多處內容時： - ✅ 多次小範圍替換，逐步修改 - ⚠️ 謹慎使用 overwrite 重寫整個文件, 除非你認為風險完全可控

原因：區域性更新保留原有媒體、評論、協作歷史，更安全可靠。

insert 模式擴大定位範圍時注意插入位置

使用 insert_before 或 insert_after 時，如果目標內容重複出現，需要擴大 selection_with_ellipsis 範圍來唯一定位。

關鍵：插入位置基於匹配範圍的邊界： - insert_after → 插入在匹配範圍的結尾之後 - insert_before → 插入在匹配範圍的開頭之前

擴大範圍時，確保邊界仍然是期望的插入點。

修復畫板語法錯誤

當 create-doc 或 update-doc 返回畫板寫入失敗的 warning 時： 1. warning 中包含 whiteboard 標籤（如 <whiteboard token="xxx"/>） 2. 分析錯誤資訊，修正 Mermaid/PlantUML 語法 3. 用 replace_range 替換：selection_with_ellipsis 使用 warning 中的 whiteboard 標籤，markdown 提供修正後的程式碼塊 4. 重新提交驗證

注意事項

• Markdown 語法：支援飛書擴充套件語法，詳見 create-doc 工具文件

這個 Skill 提供了較為全面的飛書文件更新能力，7種模式基本覆蓋常見使用場景，文件示例豐富、有安全提示，對新手友好。主要不足是文件不完整（末尾被截斷），且缺少實際程式碼實現，無法直接使用。如果你需要飛書文件更新功能，可以關注後續版本是否補全程式碼和文件。質量評分：中等偏上。