核心用法
飞书文档(Docx)技能是面向企业协同场景的文档管理工具，基于飞书开放平台官方API构建，提供完整的文档生命周期管理能力。
主要功能模块
文档管理：支持创建、获取、更新、删除文档，通过document_id唯一标识管理。创建时需指定folder-token作为父目录，支持Markdown格式内容自动转换。
内容操作：提供读取原始内容、获取文档块(block)结构、更新指定块、追加内容等细粒度操作。飞书文档采用块级架构，支持page/text/heading/bullet/ordered/code/quote/callout/divider/file/grid/table等12种块类型。
权限控制：可添加/查询文档成员权限，支持view/edit/comment三级权限体系，满足企业级协作安全需求。
版本与搜索：内置版本控制能力，支持按关键词搜索文件夹内文档。
调用方式
- CLI工具：
node bin/cli.js <command> [options] - 程序化调用：通过
src/api.js的FeishuDocsAPI类 - Clawdbot集成：对话式自然语言触发
显著优点
1. 官方API背书：基于飞书开放平台稳定接口，非爬虫方案，合规性高
2. 企业级权限：原生支持飞书组织架构的权限体系，与IM、日历等场景打通
3. 块级灵活性：相比传统文档API，块结构支持更精细的内容操作和样式控制
4. 格式自动转换：内置Markdown→飞书格式转换，降低迁移成本
5. 完整错误处理：网络重试、权限验证、速率限制处理等生产级机制
潜在局限
1. 准入门槛：需注册飞书开发者账号，创建企业应用并配置drive:drive:readonly+drive:drive:write权限，个人用户获取较繁琐
2. 内容大小限制：单次更新内容有上限，大文档需分块处理
3. 速率限制：飞书API存在QPS限制，高频场景需自行实现限流
4. 生态依赖：完全绑定飞书生态，无法跨平台复用
5. 实时性限制：基于轮询/触发机制，非实时协作编辑API
适合人群
- 企业IT管理员：需要批量管理飞书文档、自动化生成报告
- 研发团队：同步GitHub Issues/项目看板到飞书知识库
- 项目经理：自动化项目状态文档更新、权限分发
- Clawdbot用户：希望通过对话快速创建/查询飞书文档
常规风险
- 凭证泄露：
FEISHU_APP_SECRET需严格保密，建议使用FEISHU_APP_SECRET_PATH文件路径方式而非环境变量明文 - 权限越界：应用权限范围需最小化原则，避免授予不必要的数据访问权限
- 数据残留：删除操作不可逆，重要文档建议先备份
- 组织边界：跨租户文档操作需确认应用已获目标文档权限