feat: 支持配置 OpenAI 消息内容块格式

- 新增标准字符串与文本内容块数组两种序列化模式

- 统一处理各角色消息并保留多模态及工具调用结构

- 补充默认模式与内容块模式测试

easy-agents-core/src/main/java/com/easyagents/core/model/chat/ChatConfig.java

@@ -27,6 +27,9 @@ public class ChatConfig extends BaseModelConfig {
     protected Boolean supportToolMessage;
     protected Boolean supportThinking;
 
+    /** OpenAI-compatible 消息 content 的序列化格式。 */
+    protected ChatMessageContentFormat messageContentFormat = ChatMessageContentFormat.STANDARD;
+
     // 在调用工具的时候，是否需要推理结果作为 reasoning_content 传给大模型， 比如 Deepseek
     // 参考文档： https://api-docs.deepseek.com/zh-cn/guides/thinking_mode#%E5%B7%A5%E5%85%B7%E8%B0%83%E7%94%A8
     protected Boolean needReasoningContentForToolMessage;
@@ -135,6 +138,35 @@ public class ChatConfig extends BaseModelConfig {
         return supportThinking == null || supportThinking;
     }
 
+    /**
+     * 获取消息 content 的序列化格式。
+     *
+     * @return 消息 content 格式
+     */
+    public ChatMessageContentFormat getMessageContentFormat() {
+        return messageContentFormat;
+    }
+
+    /**
+     * 设置消息 content 的序列化格式。
+     *
+     * @param messageContentFormat 消息 content 格式；null 时回退为标准格式
+     */
+    public void setMessageContentFormat(ChatMessageContentFormat messageContentFormat) {
+        this.messageContentFormat = messageContentFormat == null
+            ? ChatMessageContentFormat.STANDARD
+            : messageContentFormat;
+    }
+
+    /**
+     * 判断是否需要将纯文本 content 序列化为内容块数组。
+     *
+     * @return 配置为内容块数组时返回 true
+     */
+    public boolean isTextPartsMessageContent() {
+        return messageContentFormat == ChatMessageContentFormat.TEXT_PARTS;
+    }
+
     public Boolean getNeedReasoningContentForToolMessage() {
         return needReasoningContentForToolMessage;
     }

easy-agents-core/src/main/java/com/easyagents/core/model/chat/ChatMessageContentFormat.java

@@ -0,0 +1,28 @@
+/*
+ *  Copyright (c) 2023-2026, Easy-Agents (fuhai999@gmail.com).
+ *  <p>
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *  <p>
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *  <p>
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ */
+package com.easyagents.core.model.chat;
+
+/**
+ * OpenAI-compatible 消息 content 的序列化格式。
+ */
+public enum ChatMessageContentFormat {
+
+    /** 保持供应商默认格式，纯文本 content 使用字符串。 */
+    STANDARD,
+
+    /** 将各角色的纯文本 content 统一序列化为文本内容块数组。 */
+    TEXT_PARTS
+}

easy-agents-core/src/main/java/com/easyagents/core/model/client/OpenAIChatMessageSerializer.java

@@ -58,11 +58,39 @@ public class OpenAIChatMessageSerializer implements ChatMessageSerializer {
             } else if (message instanceof ToolMessage) {
                 buildToolMessageObject(objectMap, (ToolMessage) message, config);
             }
+            normalizeMessageContent(objectMap, config);
             messageList.add(objectMap);
         });
         return messageList;
     }
 
+    /**
+     * 根据模型配置将纯文本 content 规范为 OpenAI 文本内容块数组。
+     * 已经是多模态内容块数组的 content 保持不变。
+     *
+     * @param objectMap 已完成角色字段构建的消息
+     * @param config 模型配置
+     */
+    protected void normalizeMessageContent(Map<String, Object> objectMap, ChatConfig config) {
+        if (config == null
+            || !config.isTextPartsMessageContent()
+            || !objectMap.containsKey("content")) {
+            return;
+        }
+
+        Object content = objectMap.get("content");
+        if (content instanceof List<?>) {
+            return;
+        }
+        if (content == null || content instanceof String) {
+            String text = content == null ? "" : (String) content;
+            objectMap.put("content", List.of(Maps.of("type", "text").set("text", text)));
+            return;
+        }
+        throw new IllegalStateException(
+            "Unsupported OpenAI message content type: " + content.getClass().getName());
+    }
+
     protected void buildToolMessageObject(Map<String, Object> objectMap, ToolMessage message, ChatConfig config) {
         if (config.isSupportToolMessage()) {
             objectMap.put("role", "tool");
@@ -289,4 +317,3 @@ public class OpenAIChatMessageSerializer implements ChatMessageSerializer {
         }
     }
 }
-

easy-agents-core/src/test/java/com/easyagents/core/test/model/client/OpenAIChatMessageSerializerTest.java

@@ -1,7 +1,12 @@
 package com.easyagents.core.test.model.client;
 
+import com.easyagents.core.message.AiMessage;
+import com.easyagents.core.message.SystemMessage;
+import com.easyagents.core.message.ToolCall;
+import com.easyagents.core.message.ToolMessage;
 import com.easyagents.core.message.UserMessage;
 import com.easyagents.core.model.chat.ChatConfig;
+import com.easyagents.core.model.chat.ChatMessageContentFormat;
 import com.easyagents.core.model.client.OpenAIChatMessageSerializer;
 import org.junit.Assert;
 import org.junit.Test;
@@ -14,6 +19,50 @@ import java.util.Map;
  */
 public class OpenAIChatMessageSerializerTest {
 
+    /**
+     * 验证标准模式继续使用原有纯文本字符串格式。
+     */
+    @Test
+    public void shouldKeepStringContentInStandardMode() {
+        ToolMessage toolMessage = toolMessage("call-1", "工具结果");
+
+        List<Map<String, Object>> messages = new OpenAIChatMessageSerializer()
+                .serializeMessages(List.of(
+                        SystemMessage.of("系统提示"),
+                        new UserMessage("用户问题"),
+                        new AiMessage("助手回答"),
+                        toolMessage
+                ), new ChatConfig());
+
+        Assert.assertEquals("系统提示", messages.get(0).get("content"));
+        Assert.assertEquals("用户问题", messages.get(1).get("content"));
+        Assert.assertEquals("助手回答", messages.get(2).get("content"));
+        Assert.assertEquals("工具结果", messages.get(3).get("content"));
+    }
+
+    /**
+     * 验证内容块模式会转换全部纯文本消息角色。
+     */
+    @Test
+    public void shouldSerializeAllTextRolesAsContentParts() {
+        ChatConfig config = textPartsConfig();
+        ToolMessage toolMessage = toolMessage("call-1", "工具结果");
+
+        List<Map<String, Object>> messages = new OpenAIChatMessageSerializer()
+                .serializeMessages(List.of(
+                        SystemMessage.of("系统提示"),
+                        new UserMessage("用户问题"),
+                        new AiMessage("助手回答"),
+                        toolMessage
+                ), config);
+
+        assertTextPart(messages.get(0), "系统提示");
+        assertTextPart(messages.get(1), "用户问题");
+        assertTextPart(messages.get(2), "助手回答");
+        assertTextPart(messages.get(3), "工具结果");
+        Assert.assertEquals("call-1", messages.get(3).get("tool_call_id"));
+    }
+
     /**
      * 验证 Data URI 会写入标准的 image_url.url 字段。
      */
@@ -33,4 +82,71 @@ public class OpenAIChatMessageSerializerTest {
         Assert.assertEquals("image_url", imageContent.get("type"));
         Assert.assertEquals(dataUri, imageUrl.get("url"));
     }
+
+    /**
+     * 验证内容块模式保留多模态数组和工具调用结构字段。
+     */
+    @Test
+    public void shouldPreserveStructuredFieldsInTextPartsMode() {
+        String dataUri = "data:image/png;base64,AQID";
+        UserMessage userMessage = new UserMessage("识别图片");
+        userMessage.addImageUrl(dataUri);
+        AiMessage assistantMessage = new AiMessage(null);
+        assistantMessage.setReasoningContent("先分析");
+        assistantMessage.setToolCalls(List.of(
+                new ToolCall("call-1", "image_search", "{\"query\":\"license\"}")));
+        ToolMessage toolMessage = toolMessage("call-1", "工具结果");
+
+        List<Map<String, Object>> messages = new OpenAIChatMessageSerializer()
+                .serializeMessages(List.of(userMessage, assistantMessage, toolMessage), textPartsConfig());
+
+        List<?> userContent = (List<?>) messages.get(0).get("content");
+        Assert.assertEquals(2, userContent.size());
+        Assert.assertEquals("image_url", ((Map<?, ?>) userContent.get(1)).get("type"));
+        assertTextPart(messages.get(1), "");
+        Assert.assertEquals("先分析", messages.get(1).get("reasoning_content"));
+        Assert.assertTrue(messages.get(1).containsKey("tool_calls"));
+        assertTextPart(messages.get(2), "工具结果");
+        Assert.assertEquals("call-1", messages.get(2).get("tool_call_id"));
+    }
+
+    /**
+     * 创建内容块数组模式配置。
+     *
+     * @return 内容块数组模式配置
+     */
+    private ChatConfig textPartsConfig() {
+        ChatConfig config = new ChatConfig();
+        config.setMessageContentFormat(ChatMessageContentFormat.TEXT_PARTS);
+        config.setNeedReasoningContentForToolMessage(Boolean.TRUE);
+        return config;
+    }
+
+    /**
+     * 创建工具结果消息。
+     *
+     * @param toolCallId 工具调用标识
+     * @param content 工具结果文本
+     * @return 工具结果消息
+     */
+    private ToolMessage toolMessage(String toolCallId, String content) {
+        ToolMessage message = new ToolMessage();
+        message.setToolCallId(toolCallId);
+        message.setContent(content);
+        return message;
+    }
+
+    /**
+     * 断言消息 content 只包含指定文本内容块。
+     *
+     * @param message 已序列化消息
+     * @param expectedText 预期文本
+     */
+    private void assertTextPart(Map<String, Object> message, String expectedText) {
+        List<?> content = (List<?>) message.get("content");
+        Assert.assertEquals(1, content.size());
+        Map<?, ?> textPart = (Map<?, ?>) content.get(0);
+        Assert.assertEquals("text", textPart.get("type"));
+        Assert.assertEquals(expectedText, textPart.get("text"));
+    }
 }