核心用法
飞书文档(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%保真，复杂样式可能丢失