飞书文档API技能

核心用法

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

核心用法

飞书文档技能是基于飞书开放平台 API 的企业级文档管理解决方案，提供完整的文档 CRUD 操作能力。用户通过配置 FEISHU_APP_ID 和 FEISHU_APP_SECRET 环境变量即可快速接入，支持通过 CLI 命令行或程序化 API 两种方式调用。

关键功能路径：

• 内容创建：支持 Markdown/HTML 自动转换为飞书文档块结构，单次转换上限 10MB，批量插入限制 50 块/次
• 文档更新：提供全量替换 (update) 和增量追加 (append) 两种模式，满足不同场景需求
• 权限管理：内置协作者添加、权限成员查询等企业协作功能
• 块级操作：细粒度控制文档结构，支持块的增删改查及自动分页获取

显著优点

1. 协议转换自动化：内置 convertContent API 将 Markdown/HTML 无缝转为飞书原生块结构，解决格式兼容痛点
2. 企业级可靠性：Token 缓存与并发控制机制、401 自动刷新、429/5xx 指数退避重试（最多 2 次）
3. 双向格式支持：既支持 Markdown→飞书块的服务端转换，也提供本地 markdownToBlocks/blocksToMarkdown 工具函数
4. 完善的错误处理：安全访问响应数据，避免非 JSON 响应导致运行时崩溃

潜在局限

• 生态绑定：深度依赖飞书开放平台，无法迁移至其他文档系统
• 内容大小限制：单次转换 10MB 上限，超大文档需手动分片处理
• 表格处理简化：自动去除 merge_info，复杂表格样式可能丢失
• 批量操作限制：API 硬限制 50 块/次，大批量内容插入需客户端自行分页

适合人群

• 企业自动化运维：需批量生成报告、会议纪要、项目文档的技术团队
• 内容发布管道：构建从 CMS/Markdown 源到飞书文档的自动化发布流程
• 权限管理员：需要程序化管理文档协作者、审计文档访问权限的企业 IT
• 开发者工具链：将飞书文档集成到现有 CI/CD 或文档工作流的工程师

常规风险

1. 凭证管理：FEISHU_APP_SECRET 需妥善保管，避免泄露至版本控制
2. API 限流：高频调用可能触发 429 限流，建议利用内置重试或自行控制速率
3. 数据归属：删除操作通过 Drive API 执行，权限不足时可能失败，需确保应用具备 docs:doc、drive:drive、drive:file 权限
4. 路径遍历（低危）：CLI 的 --content-file 参数建议配合路径白名单使用，防范潜在目录遍历