name: feishu-docs description: 飛書文件(Docx)API技能。用於建立、讀取、更新和刪除飛書文件。支援Markdown/HTML內容轉換、文件許可權管理。 metadata: {"clawdbot":{"emoji":"📝","requires":{"env":["FEISHU_APP_ID","FEISHU_APP_SECRET"]},"primaryEnv":"FEISHU_APP_ID"}}

飛書文件(Docx)技能

操作飛書新版文件(Docx)的openClaw技能，基於飛書開放平臺 API 實現文件全生命週期管理。

功能特性

環境變數

export FEISHU_APP_ID=cli_xxxxxx          # 飛書應用 App ID
export FEISHU_APP_SECRET=your_app_secret  # 飛書應用 App Secret

也可通過 .env 檔案配置（專案使用 dotenv 自動載入）。

快速開始

# 安裝依賴
npm install

# 檢視幫助
node bin/cli.js --help

# 建立文件（含 Markdown 內容）
node bin/cli.js create -f fldxxxxxx -t "專案計劃" -c "# 概述\n\n內容..."

# 獲取文件
node bin/cli.js get -d dcnxxxxxx --format markdown --include-content

# 全量替換文件內容
node bin/cli.js update -d dcnxxxxxx --content-file new-content.md

# 追加內容
node bin/cli.js update -d dcnxxxxxx --append -c "## 補充\n\n新增內容"

# 刪除文件
node bin/cli.js delete -d dcnxxxxxx

CLI 命令

所有命令均支援 --app-id 和 --app-secret 引數覆蓋環境變數。

API 方法

文件管理

文件塊操作

內容操作

檔案與搜尋

許可權管理

格式轉換（本地）

飛書 API 端點

程式碼實際呼叫的飛書開放平臺端點：

POST   /docx/v1/documents                                    # 建立文件
GET    /docx/v1/documents/{document_id}                      # 獲取文件資訊
GET    /docx/v1/documents/{document_id}/raw_content          # 獲取文件純文本
GET    /docx/v1/documents/{document_id}/blocks               # 獲取文件塊列表
PATCH  /docx/v1/documents/{document_id}/blocks/{block_id}    # 更新塊
DELETE /docx/v1/documents/{document_id}/blocks/{block_id}    # 刪除塊
POST   /docx/v1/documents/{document_id}/blocks/{block_id}/children  # 插入子塊
POST   /docx/v1/documents/blocks/convert                     # Markdown/HTML→塊
DELETE /drive/v1/files/{file_token}?type=docx                # 刪除文件
GET    /drive/v1/files?folder_token=xxx                      # 列出資料夾檔案
POST   /drive/v1/permissions/{token}/members?type=docx       # 新增許可權成員
GET    /drive/v1/permissions/{token}/members?type=docx       # 獲取許可權成員
POST   /auth/v3/tenant_access_token/internal/                # 獲取 tenant_access_token

可靠性機制

• Token 快取與併發控制：access_token 快取複用，多個併發請求不會重複重新整理
• 自動重試：401 未授權自動重新整理 token 重試；429 限流和 5xx 錯誤指數退避重試（最多 2 次）
• Token 過期碼識別：檢測飛書錯誤碼 99991663/99991661 自動重新整理 token
• 安全錯誤處理：安全訪問 error.response.data，避免非 JSON 響應導致崩潰

注意事項

本技能來自小蔥技能站7w4.net。

1. 應用許可權：飛書應用需具備 docs:doc、drive:drive、drive:file 等相關許可權
2. 內容插入：create 命令含 content 時自動走 convertContent → createDocumentBlocks 流程，確保文件結構正確
3. 批次插入限制：每批最多插入 50 個塊（飛書 API 限制）
4. 表格處理：轉換含表格的內容時自動去除 merge_info 欄位；block_type 為 31/32 的表格塊暫被過濾
5. 內容大小：單次轉換內容不超過 10MB

專案結構

├── src/api.js        # FeishuDocsAPI 類（所有 API 方法 + 格式轉換）
├── bin/cli.js        # Commander 命令列工具
├── package.json      # 依賴：axios, commander, dotenv
├── test-convert.js   # 轉換介面測試
├── SKILL.md          # 本檔案
└── README.md         # 專案說明

這個技能質量較好，功能豐富實用，文件說明詳細，命令列操作簡單易懂。優點是支援建立、讀取、修改、刪除飛書文件，還能把Markdown內容自動轉換格式，支援文件分享和搜尋。不足是部分說明文件不完整，有幾處示例路徑寫死了不方便直接使用。建議補充完整說明並修復示例文件的模板問題。