飞书文档全生命周期自动化管理 - 飞书文档API技能

飞书官方API封装技能，支持文档CRUD、Markdown/HTML转换、权限管理及协作，适合企业文档自动化工作流。

基本信息

• 技能名称?飞书文档API技能
• 中文名称?飞书文档全生命周期自动化管理
• 作者?stevenlikewatermelon
• 分类?专业技能
• 版本?1.1.1
• 标签?feishu, lark, document-management, markdown-conversion, api-sdk, enterprise-collaboration, permission-management, content-automation

使用方法

使用说明
核心用法
飞书文档(Docx)技能基于飞书开放平台官方API，提供文档全生命周期管理能力。用户可通过环境变量配置 FEISHU_APP_ID 和 FEISHU_APP_SECRET 完成认证，支持CLI命令行与API方法两种调用模式。
文档操作 ：创建空文档、带内容文档（自动Markdown/HTML转换）、获取文档信息及纯文本内容、全量替换或追加内容、删除文档。
内容转换 ：核心亮点是调用飞书服务端 /docx/v1/documents/blocks/convert 接口将 Markdown/HTML 转为飞书文档块结构，同时提供本地轻量转换方法 markdownToBlocks / blocksToMarkdown 。
块级操作 ：支持获取文档块列表（自动分页）、插入子块、更新块、删除单块或批量删除。
权限与协作 ：添加协作者（用户/群组/部门）、查看权限成员列表、按关键词搜索文档、列出文件夹文件。
可靠性设计 ：access_token缓存复用避免并发刷新；401未授权自动刷新token重试；429限流和5xx错误指数退避重试；专门识别飞书错误码 99991663 / 99991661 处理token过期。
显著优点
官方API背书 ：直接调用飞书开放平台接口，数据格式与功能迭代与飞书官方同步
双模式支持 ：既提供完善的CLI工具快速上手，也暴露丰富API方法供程序集成
智能内容处理 ：自动处理Markdown到飞书块的转换，含表格时自动去除 merge_info 字段，批量插入自动分片（每批≤50块）
健壮的错误处理 ：安全访问 error.response.data 避免非JSON响应崩溃；多层重试机制保障调用稳定性
权限管理完善 ：支持细粒度权限控制，满足企业协作场景
潜在局限
依赖企业应用 ：必须使用飞书自建应用获取 App ID/Secret，个人用户无法直接使用
权限配置门槛 ：需在飞书管理后台配置 docs:doc 、 drive:drive 等权限，对非管理员用户有学习成本
表格支持不完整 ：block_type 为31/32的表格块被过滤，复杂表格结构可能丢失格式
内容大小限制 ：单次转换内容不超过10MB，超大文档需分片处理
仅限Docx格式 ：不支持旧版飞书文档格式
适合人群
需要批量创建/更新飞书文档的DevOps工程师
构建企业知识库自动化同步的开发者
希望将外部内容（如GitHub、Notion）迁移至飞书的团队
需要程序化管理文档权限的企业管理员
常规风险
Token泄露风险 ：App Secret需妥善保管，硬编码或日志泄露可能导致企业数据暴露
权限过度授予 ：应用权限过大可能意外访问敏感文档，建议遵循最小权限原则
并发限制 ：飞书API存在频率限制，超量调用可能触发429限流
内容转换偏差 ：Markdown到飞书块的转换并非100%保真，复杂样式可能丢失