Goose项目中的"contents.parts must not be empty"错误分析与解决方案

问题背景

在使用Goose项目（一个基于Gemini模型的AI开发工具）时，部分用户反馈在执行复杂任务时遇到工作流意外中断的情况。具体表现为：当用户提供包含多步骤指令的详细提示（如构建Python/FastAPI项目并配置Alembic数据库迁移）时，系统会在初始阶段突然停止响应，随后返回错误信息"GenerateContentRequest.contents[7].parts: contents.parts must not be empty"。

错误本质

这个错误属于API请求验证失败错误，状态码为400（Bad Request）。其核心原因是Gemini模型服务端收到了包含空内容片段的请求。在AI模型交互过程中，每个请求内容(contents)由多个部分(parts)组成，当某个part意外为空时，就会触发这个验证错误。

技术细节

1. 请求结构问题：Gemini API要求每个content块中的parts数组必须包含有效内容，空数组或包含空元素的数组都会导致此错误。

2. 上下文管理：在长对话或多步任务中，Goose需要维护对话上下文。当上下文传递过程中某些内容片段丢失或未能正确填充时，就容易产生空parts。

3. 模型版本差异：该问题在Gemini Flash 2.0和Flash 2.0 Exp版本中表现较为明显，可能与这些版本对输入验证更严格有关。

解决方案

Goose开发团队已通过内部修复（PR #2011）解决了此问题。该修复主要涉及：

1. 请求预处理：在发送请求前增加内容验证步骤，确保所有parts都包含有效数据。

2. 错误恢复机制：当检测到空parts时，系统会自动重新构造请求或提供有意义的回退内容。

3. 上下文完整性检查：优化了长对话场景下的上下文传递机制，防止内容片段丢失。

最佳实践建议

对于Goose用户，为避免类似问题：

1. 分段执行复杂任务：将大型项目分解为多个小任务逐步执行，而非一次性提供所有指令。

2. 检查模型选择：确认使用的是最新稳定版本的模型。

3. 监控交互状态：注意观察系统响应，如发现异常停顿可尝试重新表述需求。

4. 日志分析：遇到问题时检查~/.local/state/goose/logs/cli/下的日志文件，可帮助定位具体原因。

总结

这类API验证错误在AI应用开发中较为常见，反映了客户端与服务端在数据约定上的严格性要求。Goose团队通过增强请求预处理和错误处理机制，有效提升了工具在复杂场景下的稳定性。对于终端用户而言，理解这类错误的本质有助于更高效地使用AI开发工具。