Description

飞书文档(Docx)API技能。用于创建、读取、更新和删除飞书文档。支持Markdown/HTML内容转换、文档权限管理。

README (SKILL.md)

飞书文档(Docx)技能

Name: Feishu Docs 1.1.1
Author: binbin

操作飞书新版文档(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 "# 概述\
\
内容..."

# 获取文档
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 "## 补充\
\
新增内容"

# 删除文档
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         # 项目说明

Usage Guidance

This package appears coherent for its stated purpose, but exercise normal cautions before installing: 1) Only provide FEISHU_APP_SECRET to skills you trust; avoid committing .env files. 2) Inspect package-lock.json (and the resolved registry URLs) if you require strict supply-chain provenance; consider running npm install using your preferred registry or in an isolated environment. 3) Verify the skill's upstream source (homepage is missing and registry owner metadata has a minor mismatch) — if you need stronger assurance, request the canonical repository or author contact. 4) Test the CLI in a sandbox with a minimally privileged Feishu app (grant only needed scopes) and rotate the App Secret after testing if appropriate.

Capability Analysis

Type: OpenClaw Skill Name: feishu-docs-1-1-1 Version: 1.0.0 The skill bundle provides a legitimate and well-structured integration with the Feishu (Lark) Docs API for document lifecycle management. It includes a CLI tool (`bin/cli.js`) and a core API library (`src/api.js`) that support CRUD operations, Markdown/HTML to Docx block conversion, and permission management. All network communication is directed to the official Feishu API endpoint (open.feishu.cn), and sensitive credentials (App ID/Secret) are handled via environment variables or CLI arguments without evidence of exfiltration. The code follows standard practices for API clients, including token caching and retry logic, and lacks any indicators of malicious intent or obfuscation.

Capability Assessment

✓ Purpose & Capability

Name/description (Feishu Docx API) match the requested environment variables (FEISHU_APP_ID, FEISHU_APP_SECRET) and the code's behavior: the CLI and src/api.js call Feishu open-apis endpoints for document CRUD, block conversion, listing, and permissions. The required items (axios, commander, dotenv) are appropriate for a Node CLI/API client. Minor note: repository metadata in _meta.json has an ownerId that differs from the registry metadata ownerId; this is an administrative inconsistency, not a functional one.

✓ Instruction Scope

SKILL.md and README describe only expected actions: calling Feishu API endpoints, optionally reading local content files when the CLI --content-file option is used, and loading credentials from env or .env. There are no instructions to read unrelated system files or to transmit data to unknown external endpoints. The code uses only the Feishu API base URL and standard npm packages.

ℹ Install Mechanism

There is no automated install spec in the registry entry (install is manual via npm install). Dependencies are standard npm packages (axios, commander, dotenv). package-lock shows packages resolved from a mirror (registry.npmmirror.com) — this is not inherently malicious but worth noting: npm install will fetch third‑party packages; review package-lock or install from your preferred registry if you require provenance guarantees.

✓ Credentials

The skill requires only FEISHU_APP_ID and FEISHU_APP_SECRET, which are the expected credentials for the Feishu open platform. The code does not read other environment variables or require unrelated service credentials. The primaryEnv is correctly set to FEISHU_APP_ID.

✓ Persistence & Privilege

The skill is not marked always:true and does not request to modify other skills or system-wide agent settings. It may be invoked autonomously by the agent (default behavior) but that is normal for skills and not combined with other concerning privileges.

Version History

v1.0.0

飞书文档(Docx)API技能首次发布：便捷管理与操作新版飞书文档。 - 支持创建、读取、更新（全量/追加）和删除飞书文档 - 提供 Markdown/HTML 内容与飞书块互转，以及文档权限管理 - 完善文档块操作（列举、插入、删除、更新） - CLI 命令丰富，参数友好，支持环境变量与命令参数覆盖 - 自动处理 access_token 缓存、重试机制和限流 - 详细文档与上手示例，项目结构清晰

Metadata

Slug feishu-docs-1-1-1

Version 1.0.0

License MIT-0

All-time Installs 0

Active Installs 0

Total Versions 1

Frequently Asked Questions

What is Feishu Docs 1.1.1?

飞书文档(Docx)API技能。用于创建、读取、更新和删除飞书文档。支持Markdown/HTML内容转换、文档权限管理。 It is an AI Agent Skill for Claude Code / OpenClaw, with 185 downloads so far.

How do I install Feishu Docs 1.1.1?

Run "/install feishu-docs-1-1-1" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is Feishu Docs 1.1.1 free?

Yes, Feishu Docs 1.1.1 is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does Feishu Docs 1.1.1 support?

Feishu Docs 1.1.1 is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created Feishu Docs 1.1.1?

It is built and maintained by Beta (@binbin); the current version is v1.0.0.

More Skills

Feishu Docs 1.1.1