飞书文档API技能

飞书文档(Docx)技能

操作飞书新版文档(Docx)的openClaw技能，基于飞书开放平台 API 实现文档全生命周期管理。

功能特性

环境变量

export FEISHU_APP_ID=cli_xxxxxx          # 飞书应用 App ID
export FEISHU_APP_SECRET=your_app_secret  # 飞书应用 App Secret

也可通过

.env

快速开始

# 安装依赖
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 命令

create

-f

-t

create-with-content

-f

-t

get

-d

update

-d

-c

--content-file

delete

-d

search

-q

list

-f

share

-d

-u

permissions

-d

convert

-t

所有命令均支持

--app-id

--app-secret

API 方法

文档管理

createDocument(folderToken, title)

createDocumentWithContent(folderToken, title, content, contentType)

getDocument(documentId)

getDocumentRawContent(documentId)

deleteDocument(documentId)

文档块操作

getDocumentBlocks(documentId, pageSize, pageToken)

getAllDocumentBlocks(documentId)

updateDocumentBlock(documentId, blockId, updateRequest)

createDocumentBlocks(documentId, blockId, children, index)

deleteDocumentBlock(documentId, blockId)

batchDeleteBlocks(documentId, blockIds)

内容操作

appendToDocument(documentId, content, contentType)

replaceDocumentContent(documentId, content, contentType)

convertContent(contentType, content, userIdType)

文件与搜索

listFolderFiles(folderToken, type)

searchDocuments(query, folderToken)

权限管理

addPermissionMember(token, memberId, memberType, perm)

getPermissionMembers(token)

格式转换（本地）

markdownToBlocks(markdown)

blocksToMarkdown(blocks)

飞书 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 响应导致崩溃

注意事项

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         # 项目说明