飞书文档(Docx)技能
操作飞书新版文档(Docx)的openClaw技能,基于飞书开放平台 API 实现文档全生命周期管理。
功能特性
| 功能 |
说明 |
| 文档 CRUD |
创建、获取、更新(全量替换)、删除文档 |
| 内容追加 |
向已有文档末尾追加 Markdown/HTML 内容 |
| 内容转换 |
通过飞书服务端 API 将 Markdown/HTML 转换为文档块 |
| 块操作 |
获取文档块列表(自动分页)、插入子块、删除块 |
| 权限管理 |
添加协作者、查看权限成员列表 |
| 文件管理 |
按文件夹列出文件、按关键词搜索文档 |
环境变量
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 命令
| 命令 |
说明 |
必要参数 |
create |
创建文档(有内容时自动使用转换流程) |
-f文件夹token, -t标题 |
create-with-content |
创建文档并通过转换API插入内容 |
-f文件夹token, -t标题 |
get |
获取文档信息 |
-d文档ID |
update |
替换或追加文档内容 |
-d文档ID, -c内容或--content-file |
delete |
删除文档 |
-d文档ID |
search |
搜索文档 |
-q关键词 |
list |
列出文件夹中的文件 |
-f文件夹token |
share |
分享文档给用户 |
-d文档ID, -u用户ID |
permissions |
查看文档权限成员 |
-d文档ID |
convert |
将Markdown/HTML转换为文档块(预览) |
-t内容类型 |
所有命令均支持 --app-id 和 --app-secret 参数覆盖环境变量。
API 方法
文档管理
| 方法 |
说明 |
createDocument(folderToken, title) |
创建空文档 |
createDocumentWithContent(folderToken, title, content, contentType) |
创建文档并插入内容 |
getDocument(documentId) |
获取文档信息 |
getDocumentRawContent(documentId) |
获取文档纯文本内容 |
deleteDocument(documentId) |
删除文档(通过 Drive API) |
文档块操作
| 方法 |
说明 |
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) |
将 Markdown/HTML 转换为文档块 |
文件与搜索
| 方法 |
说明 |
listFolderFiles(folderToken, type) |
列出文件夹下的文件 |
searchDocuments(query, folderToken) |
按关键词搜索文档 |
权限管理
| 方法 |
说明 |
addPermissionMember(token, memberId, memberType, perm) |
添加权限成员 |
getPermissionMembers(token) |
获取权限成员列表 |
格式转换(本地)
| 方法 |
说明 |
markdownToBlocks(markdown) |
Markdown → 飞书块结构(本地转换) |
blocksToMarkdown(blocks) |
飞书块结构 → Markdown(支持数字/字符串 block_type) |
飞书 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 响应导致崩溃
注意事项
- 应用权限:飞书应用需具备
docs:doc、drive:drive、drive:file 等相关权限
- 内容插入:
create 命令含 content 时自动走 convertContent → createDocumentBlocks 流程,确保文档结构正确
- 批量插入限制:每批最多插入 50 个块(飞书 API 限制)
- 表格处理:转换含表格的内容时自动去除
merge_info 字段;block_type 为 31/32 的表格块暂被过滤
- 内容大小:单次转换内容不超过 10MB
项目结构
├── src/api.js # FeishuDocsAPI 类(所有 API 方法 + 格式转换)
├── bin/cli.js # Commander 命令行工具
├── package.json # 依赖:axios, commander, dotenv
├── test-convert.js # 转换接口测试
├── SKILL.md # 本文件
└── README.md # 项目说明
1---2name: feishu-docs-23description: 飞书文档(Docx)API技能。用于创建、读取、更新和删除飞书文档。支持Markdown/HTML内容转换、文档权限管理。4metadata:5 source: https://skillmd.com/skills/johnalbertini14-glitch/feishu-docs-26 clawdbot:7 emoji: 📝8 requires:9 env:10 - FEISHU_APP_ID11 - FEISHU_APP_SECRET12 primaryEnv: FEISHU_APP_ID13---1415# 飞书文档(Docx)技能1617操作飞书新版文档(Docx)的openClaw技能,基于飞书开放平台 API 实现文档全生命周期管理。1819## 功能特性2021| 功能 | 说明 |22|------|------|23| 文档 CRUD | 创建、获取、更新(全量替换)、删除文档 |24| 内容追加 | 向已有文档末尾追加 Markdown/HTML 内容 |25| 内容转换 | 通过飞书服务端 API 将 Markdown/HTML 转换为文档块 |26| 块操作 | 获取文档块列表(自动分页)、插入子块、删除块 |27| 权限管理 | 添加协作者、查看权限成员列表 |28| 文件管理 | 按文件夹列出文件、按关键词搜索文档 |2930## 环境变量3132```bash33export FEISHU_APP_ID=cli_xxxxxx # 飞书应用 App ID34export FEISHU_APP_SECRET=your_app_secret # 飞书应用 App Secret35```3637也可通过 `.env` 文件配置(项目使用 dotenv 自动加载)。3839## 快速开始4041```bash42# 安装依赖43npm install4445# 查看帮助46node bin/cli.js --help4748# 创建文档(含 Markdown 内容)49node bin/cli.js create -f fldxxxxxx -t "项目计划" -c "# 概述\n\n内容..."5051# 获取文档52node bin/cli.js get -d dcnxxxxxx --format markdown --include-content5354# 全量替换文档内容55node bin/cli.js update -d dcnxxxxxx --content-file new-content.md5657# 追加内容58node bin/cli.js update -d dcnxxxxxx --append -c "## 补充\n\n新增内容"5960# 删除文档61node bin/cli.js delete -d dcnxxxxxx62```6364## CLI 命令6566| 命令 | 说明 | 必要参数 |67|------|------|----------|68| `create` | 创建文档(有内容时自动使用转换流程) | `-f`文件夹token, `-t`标题 |69| `create-with-content` | 创建文档并通过转换API插入内容 | `-f`文件夹token, `-t`标题 |70| `get` | 获取文档信息 | `-d`文档ID |71| `update` | 替换或追加文档内容 | `-d`文档ID, `-c`内容或`--content-file` |72| `delete` | 删除文档 | `-d`文档ID |73| `search` | 搜索文档 | `-q`关键词 |74| `list` | 列出文件夹中的文件 | `-f`文件夹token |75| `share` | 分享文档给用户 | `-d`文档ID, `-u`用户ID |76| `permissions` | 查看文档权限成员 | `-d`文档ID |77| `convert` | 将Markdown/HTML转换为文档块(预览) | `-t`内容类型 |7879所有命令均支持 `--app-id` 和 `--app-secret` 参数覆盖环境变量。8081## API 方法8283### 文档管理8485| 方法 | 说明 |86|------|------|87| `createDocument(folderToken, title)` | 创建空文档 |88| `createDocumentWithContent(folderToken, title, content, contentType)` | 创建文档并插入内容 |89| `getDocument(documentId)` | 获取文档信息 |90| `getDocumentRawContent(documentId)` | 获取文档纯文本内容 |91| `deleteDocument(documentId)` | 删除文档(通过 Drive API) |9293### 文档块操作9495| 方法 | 说明 |96|------|------|97| `getDocumentBlocks(documentId, pageSize, pageToken)` | 获取文档块列表(单页) |98| `getAllDocumentBlocks(documentId)` | 获取所有块(自动分页) |99| `updateDocumentBlock(documentId, blockId, updateRequest)` | 更新指定块 |100| `createDocumentBlocks(documentId, blockId, children, index)` | 在指定块下插入子块 |101| `deleteDocumentBlock(documentId, blockId)` | 删除指定块 |102| `batchDeleteBlocks(documentId, blockIds)` | 批量删除块 |103104### 内容操作105106| 方法 | 说明 |107|------|------|108| `appendToDocument(documentId, content, contentType)` | 向文档末尾追加内容 |109| `replaceDocumentContent(documentId, content, contentType)` | 全量替换文档内容 |110| `convertContent(contentType, content, userIdType)` | 将 Markdown/HTML 转换为文档块 |111112### 文件与搜索113114| 方法 | 说明 |115|------|------|116| `listFolderFiles(folderToken, type)` | 列出文件夹下的文件 |117| `searchDocuments(query, folderToken)` | 按关键词搜索文档 |118119### 权限管理120121| 方法 | 说明 |122|------|------|123| `addPermissionMember(token, memberId, memberType, perm)` | 添加权限成员 |124| `getPermissionMembers(token)` | 获取权限成员列表 |125126### 格式转换(本地)127128| 方法 | 说明 |129|------|------|130| `markdownToBlocks(markdown)` | Markdown → 飞书块结构(本地转换) |131| `blocksToMarkdown(blocks)` | 飞书块结构 → Markdown(支持数字/字符串 block_type) |132133## 飞书 API 端点134135代码实际调用的飞书开放平台端点:136137```138POST /docx/v1/documents # 创建文档139GET /docx/v1/documents/{document_id} # 获取文档信息140GET /docx/v1/documents/{document_id}/raw_content # 获取文档纯文本141GET /docx/v1/documents/{document_id}/blocks # 获取文档块列表142PATCH /docx/v1/documents/{document_id}/blocks/{block_id} # 更新块143DELETE /docx/v1/documents/{document_id}/blocks/{block_id} # 删除块144POST /docx/v1/documents/{document_id}/blocks/{block_id}/children # 插入子块145POST /docx/v1/documents/blocks/convert # Markdown/HTML→块146DELETE /drive/v1/files/{file_token}?type=docx # 删除文档147GET /drive/v1/files?folder_token=xxx # 列出文件夹文件148POST /drive/v1/permissions/{token}/members?type=docx # 添加权限成员149GET /drive/v1/permissions/{token}/members?type=docx # 获取权限成员150POST /auth/v3/tenant_access_token/internal/ # 获取 tenant_access_token151```152153## 可靠性机制154155- **Token 缓存与并发控制**:access_token 缓存复用,多个并发请求不会重复刷新156- **自动重试**:401 未授权自动刷新 token 重试;429 限流和 5xx 错误指数退避重试(最多 2 次)157- **Token 过期码识别**:检测飞书错误码 `99991663`/`99991661` 自动刷新 token158- **安全错误处理**:安全访问 `error.response.data`,避免非 JSON 响应导致崩溃159160## 注意事项1611621. **应用权限**:飞书应用需具备 `docs:doc`、`drive:drive`、`drive:file` 等相关权限1632. **内容插入**:`create` 命令含 content 时自动走 `convertContent` → `createDocumentBlocks` 流程,确保文档结构正确1643. **批量插入限制**:每批最多插入 50 个块(飞书 API 限制)1654. **表格处理**:转换含表格的内容时自动去除 `merge_info` 字段;block_type 为 31/32 的表格块暂被过滤1665. **内容大小**:单次转换内容不超过 10MB167168## 项目结构169170```171├── src/api.js # FeishuDocsAPI 类(所有 API 方法 + 格式转换)172├── bin/cli.js # Commander 命令行工具173├── package.json # 依赖:axios, commander, dotenv174├── test-convert.js # 转换接口测试175├── SKILL.md # 本文件176└── README.md # 项目说明177```