Bolt.diy项目中的"Invalid prompt"错误分析与解决方案

问题背景

在Bolt.diy项目的本地开发环境中，用户在使用聊天功能时遇到了一个关键错误："Invalid prompt: messages must be an array of CoreMessage or UIMessage"。这个错误导致所有LLM(大语言模型)的提示请求都无法正常执行，严重影响了开发体验。

错误现象

当用户尝试发送任何提示时，系统会返回以下错误信息：

{
  "name": "Error",
  "message": "Custom error: Invalid prompt: messages must be an array of CoreMessage or UIMessage",
  "stack": "...",
  "component": "Chat",
  "action": "request"
}

该问题在Windows系统上使用npm运行开发环境时出现，且在不同浏览器(Chrome、Chrome Canary和Firefox)中表现一致。

根本原因分析

经过技术团队深入调查，发现问题的根源在于聊天历史数据的结构验证失败。具体来说：

1. 数据结构不匹配：后端期望接收的消息数组应该是由CoreMessage或UIMessage类型组成的，但实际接收到的数据不符合这一要求。

2. 历史数据污染：问题特别出现在从浏览器IndexedDB持久化存储中加载的聊天历史数据上。某些用户消息包含了无效的结构：

   • content字段被错误地存储为数组格式[{ type: 'text', ... }]
   • 不正确地包含了parts字段

3. 验证失败：当useChatHistory钩子从数据库加载这些"脏数据"并传递给useChat钩子时，后端验证机制会拒绝这些不符合规范的消息。

解决方案

技术团队在app/lib/persistence/useChatHistory.ts文件中实施了修复方案，主要包含以下关键逻辑：

// 清理加载的消息数据
const cleanedMessages = storedMessages.messages.map(msg => {
  if (msg.role === 'user') {
    let finalContent = '';
    // 处理不同类型的content字段
    if (typeof msg.content === 'string') {
      finalContent = msg.content;
    } else if (Array.isArray(msg.content)) {
      // 在数组内容中查找文本部分
      const textPart = (msg.content as any[]).find((item: any) => item.type === 'text');
      finalContent = textPart?.text || ''; // 如果找不到则使用空字符串
    }
    // 返回新对象，确保content为字符串且无parts字段
    return {
      ...msg,
      content: finalContent,
      parts: undefined, // 显式移除parts字段
    };
  }
  // 对其他角色消息保持原样
  return msg;
});

这个修复方案实现了以下功能：

1. 数据清洗：遍历从数据库加载的所有消息
2. 用户消息处理：特别处理role为'user'的消息
3. 内容标准化：确保content字段最终为字符串格式
4. 字段清理：显式移除不应存在的parts字段
5. 兼容性保持：不影响其他角色消息的原始结构

技术启示

这个问题的解决过程为我们提供了几个重要的技术启示：

1. 数据验证的重要性：在前后端交互中，严格的数据结构验证可以防止潜在的错误传播。

2. 数据迁移的挑战：当数据结构发生变化时，需要考虑历史数据的兼容性问题。

3. 防御性编程：在数据处理层添加适当的清洗逻辑，可以提高系统的健壮性。

4. 持久化数据的风险：浏览器存储的数据可能包含过时或不一致的结构，需要特别处理。

最佳实践建议

基于此问题的经验，我们建议开发者在类似场景中：

1. 实现数据版本控制机制，便于识别和处理不同版本的数据结构
2. 在数据持久化层添加数据清洗和转换逻辑
3. 建立全面的数据结构文档，明确各字段的预期类型和用途
4. 考虑添加数据迁移工具，处理历史数据的不兼容问题
5. 实施端到端测试，验证从数据存储到API调用的完整流程

总结

Bolt.diy项目中的这个"Invalid prompt"错误展示了数据结构不一致可能导致的系统问题。通过分析根本原因并实施针对性的数据清洗方案，技术团队不仅解决了当前问题，还为系统未来的稳定性奠定了基础。这个案例也提醒我们，在快速迭代的开发过程中，需要特别关注数据结构的兼容性和持久化数据的处理。