通用飞书文档创建技能
概述
本技能提供通用的飞书文档创建功能，根据用户提供的任意内容创建文档。支持各种文档类型：小说、技术文档、项目计划、报告、笔记、文章等。由于飞书文档API对单次写入内容长度有限制，本技能通过智能分段、分批写入和重试机制确保各种长文档的完整创建。
核心工作流程
第一步：创建空白文档
- 调用飞书API的
feishu_doc工具的create操作 - 传入文档标题和初始内容（通常只包含标题）
- 记录返回的
document_id和文档URL
第二步：等待文档初始化
- 等待2秒钟，确保文档在飞书服务端完全初始化
- 这是关键步骤，避免在文档未就绪时进行写入操作
第三步：分批次追加内容
- 将完整内容按逻辑分段（每段约300-500字）
- 对每个内容段：
- 调用
feishu_doc工具的append操作 - 使用上一步获取的
document_id - 等待1秒后再处理下一段
- 内容分段建议：
- 按自然段落或章节分段（如：小说章节、文档章节、主题段落等）
- 避免单段内容过长导致API失败（建议300-500字/段）
- 保持逻辑完整性，不在句子中间切断
- 根据内容类型智能分段：小说按章节、技术文档按主题、报告按部分
第四步：错误处理和重试
- 如果
append操作失败（返回400错误）： - 等待2秒后重试
- 最多重试3次
- 如果仍然失败，记录错误并继续下一段
- 重试时可以考虑：
- 减少内容长度
- 简化格式（移除复杂Markdown）
- 检查网络连接
最佳实践
内容分段策略
- 小段落优先：每段300-500字，避免API限制
- 逻辑完整：按章节或主题分段，不在句子中间切断
- 格式简化：使用飞书支持的简单格式（纯文本、简单列表）
- 进度跟踪：记录已写入的段落数和总段落数
错误处理策略
- 立即重试：首次失败后等待2秒重试
- 降级处理：重试失败时简化内容格式
- 跳过继续：单个段落失败不影响整体进度
- 最终验证：所有段落写入后读取文档验证完整性
性能优化
- 并行写入：可以同时处理多个文档
- 批量操作：相似内容可以合并写入
- 缓存利用：重复内容可以缓存避免重复生成
- 进度保存：支持断点续传，记录已完成的段落
使用示例
示例1：创建小说章节文档
# 伪代码示例
1. create_doc("剑来小说第一章")
2. wait(2)
3. append_content("第一节：小镇少年...")
4. wait(1)
5. append_content("第二节：集市奇遇...")
6. wait(1)
7. append_content("第三节：神秘预言...")
8. 验证文档完整性
示例2：创建技术文档
# 伪代码示例
1. create_doc("Python编程指南")
2. wait(2)
3. append_content("第一章：Python基础...")
4. wait(1)
5. append_content("第二章：函数和模块...")
6. wait(1)
7. append_content("第三章：面向对象编程...")
8. 验证文档完整性
示例3：通用文档创建流程
# 伪代码示例
1. 获取用户输入的文档标题和内容
2. 创建空白文档
3. 等待文档初始化
4. 将内容智能分段
5. 分批次写入所有段落
6. 处理错误和重试
7. 验证文档完整性
8. 返回文档链接和创建结果
常见问题解决
问题1：API返回400错误
原因：内容过长或格式不支持
解决：
- 减少单次写入内容长度
- 移除复杂Markdown格式
- 使用纯文本格式重试
问题2：文档内容丢失
原因：写入操作未成功但未检测到
解决：
- 每次写入后验证返回状态
- 记录每个段落的写入状态
- 最终读取文档验证完整性
问题3：写入速度慢
原因：等待时间过长或网络延迟
解决：
- 优化等待时间（1-2秒通常足够）
- 考虑并行写入多个段落
- 使用本地缓存减少重复生成
资源文件
scripts/create_feishu_doc.py
提供Python脚本实现完整的文档创建流程，包括错误处理和重试机制。
references/feishu_api_guide.md
飞书API使用指南，包含常见错误代码和解决方案。
技能特点：
- 通用性强：支持各种类型的文档内容创建
- 智能分段：根据内容类型自动智能分段
- 错误处理：智能重试和格式简化机制
- 进度跟踪：实时显示写入进度和成功率
- 完整性验证：创建后验证文档完整性
- 用户友好：简单的接口和详细的状态报告