create-feishu-doc

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