飞书文档API技能

飞书文档(Docx)技能

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

功能特性 功能 说明 文档 CRUD 创建、获取、更新（全量替换）、删除文档 内容追加 向已有文档末尾追加 Markdown/HTML 内容 内容转换 通过飞书服务端 API 将 Markdown/HTML 转换为文档块 块操作 获取文档块列表（自动分页）、插入子块、删除块 权限管理 添加协作者、查看权限成员列表 文件管理 按文件夹列出文件、按关键词搜索文档 环境变量 导出 FEISHU_应用_ID=命令行工具_xxxxxx # 飞书应用 应用 ID 导出 FEISHU_应用_SECRET=your_应用_secret # 飞书应用 应用 Secret

也可通过 .env 文件配置（项目使用 dotenv 自动加载）。

快速开始 # 安装依赖 npm 安装

# 查看帮助 node bin/命令行工具.js --help

# 创建文档（含 Markdown 内容） node bin/命令行工具.js 创建 -f fldxxxxxx -t "项目计划" -c "# 概述\n\n内容..."

# 获取文档 node bin/命令行工具.js 获取 -d dcnxxxxxx --格式化 markdown --include-content

# 全量替换文档内容 node bin/命令行工具.js 更新 -d dcnxxxxxx --content-file new-content.md

# 追加内容 node bin/命令行工具.js 更新 -d dcnxxxxxx --应用end -c "## 补充\n\n新增内容"

# 删除文档 node bin/命令行工具.js 删除 -d dcnxxxxxx

命令行工具 命令 命令 说明 必要参数 创建 创建文档（有内容时自动使用转换流程） -f文件夹令牌, -t标题 创建-with-content 创建文档并通过转换API插入内容 -f文件夹令牌, -t标题 获取 获取文档信息 -d文档ID 更新 替换或追加文档内容 -d文档ID, -c内容或--content-file 删除 删除文档 -d文档ID 搜索 搜索文档 -q关键词 列出 列出文件夹中的文件 -f文件夹令牌 分享 分享文档给用户 -d文档ID, -u用户ID 权限s 查看文档权限成员 -d文档ID convert 将Markdown/HTML转换为文档块（预览） -t内容类型

所有命令均支持 --应用-id 和 --应用-secret 参数覆盖环境变量。

API 方法 文档管理 方法 说明 创建Document(folder令牌, title) 创建空文档 创建DocumentWithContent(folder令牌, title, content, contentType) 创建文档并插入内容 获取Document(documentId) 获取文档信息 获取DocumentRawContent(documentId) 获取文档纯文本内容 删除Document(documentId) 删除文档（通过 Drive API） 文档块操作 方法 说明 获取DocumentBlocks(documentId, pageSize, pa获取oken) 获取文档块列表（单页） 获取AllDocumentBlocks(documentId) 获取所有块（自动分页） 更新DocumentBlock(documentId, blockId, 更新请求) 更新指定块 创建DocumentBlocks(documentId, blockId, children, 索引) 在指定块下插入子块 删除DocumentBlock(documentId, blockId) 删除指定块 batch删除Blocks(documentId, blockIds) 批量删除块 内容操作 方法 说明 应用endToDocument(documentId, content, contentType) 向文档末尾追加内容 replaceDocumentContent(documentId, content, contentType) 全量替换文档内容 convertContent(contentType, content, userIdType) 将 Markdown/HTML 转换为文档块 文件与搜索 方法 说明 列出FolderFiles(folder令牌, type) 列出文件夹下的文件 搜索Documents(查询, folder令牌) 按关键词搜索文档 权限管理 方法 说明 添加权限Member(令牌, memberId, memberType, perm) 添加权限成员 获取权限Members(令牌) 获取权限成员列表 格式转换（本地） 方法 说明 markdownToBlocks(markdown) Markdown → 飞书块结构（本地转换） blocksToMarkdown(blocks) 飞书块结构 → Markdown（支持数字/字符串 block_type） 飞书 API 端点

代码实际调用的飞书开放平台端点：

POST /docx/v1/documents # 创建文档 获取 /docx/v1/documents/{document_id} # 获取文档信息 获取 /docx/v1/documents/{document_id}/raw_content # 获取文档纯文本 获取 /docx/v1/documents/{document_id}/blocks # 获取文档块列表 补丁 /docx/v1/documents/{document_id}/blocks/{block_id} # 更新块 删除 /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→块 删除 /drive/v1/files/{file_令牌}?type=docx # 删除文档 获取 /drive/v1/files?folder_令牌=xxx # 列出文件夹文件 POST /drive/v1/权限s/{令牌}/members?type=docx # 添加权限成员 获取 /drive/v1/权限s/{令牌}/members?type=docx # 获取权限成员 POST /auth/v3/tenant_访问_令牌/internal/ # 获取 tenant_访问_令牌

可靠性机制 令牌 缓存与并发控制：访问_令牌 缓存复用，多个并发请求不会重复刷新 自动重试：401 未授权自动刷新 令牌 重试；429 限流和 5xx 错误指数退避重试（最多 2 次） 令牌 过期码识别：检测飞书错误码 99991663/99991661 自动刷新 令牌 安全错误处理：安全访问 error.响应.data，避免非 JSON 响应导致崩溃 注意事项 应用权限：飞书应用需具备 docs:doc、drive:drive、drive:file 等相关权限 内容插入：创建 命令含 content 时自动走 convertContent → 创建DocumentBlocks 流程，确保文档结构正确 批量插入限制：每批最多插入 50 个块（飞书 API 限制） 表格处理：转换含表格的内容时自动去除 merge_信息 字段；block_type 为 31/32 的表格块暂被过滤 内容大小：单次转换内容不超过 10MB 项目结构 ├── src/API.js # FeishuDocsAPI 类（所有 API 方法 + 格式转换） ├── bin/命令行工具.js # Commander 命令行工具 ├── package.json # 依赖：axios, commander, dotenv ├── test-convert.js # 转换接口测试 ├── 技能.md # 本文件 └── README.md # 项目说明