人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习【免费下载链接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent开发、运行、调优与演进相关的全套SDK能力。项目地址https://gitcode.com/openJiuwen/agent-core-java点击查看免费下载BaseMessageChunk 是 openJiuwen agent-core-javacom.openjiuwen.core.foundation.llm.schema包中面向大模型流式输出场景设计的消息片段基类它继承BaseMessage定义消息片段的公共字段并通过merge方法把连续到达的多个片段合并为一条完整消息。本文围绕 BaseMessageChunk.md 的类签名展开结合仓库源码、合并工具类、模型客户端与 Agent 层的真实调用链及单元测试讲解消息片段的数据模型、分片合并策略与在流式 Agent 推理中的落地方式读完即可掌握 openJiuwen 中流式分片 → 增量合并 → 完整消息这条核心链路。一、为什么需要消息片段Message Chunk大模型推理普遍采用 SSEServer-Sent Events等协议逐 token 流式返回结果。一条完整的 assistant 回复会被拆分成几十上百个增量片段每个片段只携带一小段文本、半个工具调用参数或一个finish_reason。如果调用方不处理片段就无法拿到完整内容也无法在流尚未结束时做增量处理例如实时渲染文本、边生成边解析工具参数。openJiuwen 的设计思路与 Python 版openjiuwen/core/foundation/llm/schema/message_chunk.py保持一致每个流式增量对应一个 Chunk 对象Chunk 之间通过merge运算按顺序累加最终还原为一条完整消息。BaseMessageChunk就是这套体系的地基——它定义了所有消息片段共有的字段与合并基础。二、类定义与继承关系BaseMessageChunk位于包com.openjiuwen.core.foundation.llm.schema其类签名如下public class BaseMessageChunk extends BaseMessage源码位于 BaseMessageChunk.java类声明同时使用了四个 Lombok 注解Data SuperBuilder NoArgsConstructor EqualsAndHashCode(callSuper true) public class BaseMessageChunk extends BaseMessage { // ... }SuperBuilder允许子类如AssistantMessageChunk、ToolMessageChunk通过 Builder 链式构造同时继承父类字段EqualsAndHashCode(callSuper true)相等性判断包含父类BaseMessage的字段NoArgsConstructor为无参构造提供支持供序列化框架与合并工具使用。继承的父类 BaseMessage.java 定义了四个公共字段字段类型默认值说明roleString—消息角色如system/user/assistant/toolcontentObject空字符串消息内容可为字符串、结构化列表或 MapnameStringnull可选的消息发送方名称metadataMapString, Object空LinkedHashMap附加元数据其中content在写入时会经过normalizeContent校验内容必须可序列化调用SerializationUtils.requireSerializable检查以保证消息可以安全地跨进程传输、落盘或进入记忆/轨迹存储metadata写入时同样会做一次拷贝copyMetadata避免外部 Map 被意外修改。此外BaseMessage提供两个实用的内容访问方法getContentAsString()当content是String时直接返回否则返回toString()getContentAsList()当content是List时返回列表否则返回null。这两个方法在 Chunk 合并与下游消息构造中被广泛使用。三、构造方法从零创建一条消息片段关联文档给出的构造签名如下public BaseMessageChunk(String role, Object content, String name)对应源码实现BaseMessageChunk.javapublic BaseMessageChunk(String role, Object content, String name) { super(role, content, name, null); }它直接委托父类的(role, content, name, metadata)构造器metadata传null父类会将其拷贝为null而非默认空 Map符合流式增量不附加元数据的语义。注意BaseMessage的(role, content, name, metadata)构造器会对content执行normalizeContent(content, true)即允许content为null而在实际流式链路中OpenAIModelClient等实现会将缺失的content归一化为空字符串避免下游空指针。四、merge 方法消息片段的合并基础BaseMessageChunk的核心能力是merge其公开签名与源码如下public BaseMessageChunk merge(BaseMessageChunk other) { ... }实际实现为merge(Object other)BaseMessageChunk.javapublic BaseMessageChunk merge(Object other) { if (!(other instanceof BaseMessageChunk otherChunk)) { throw new IllegalArgumentException(Cannot merge BaseMessageChunk with other); } Object mergedContent MessageChunkMerge.mergeParserContent(getContent(), otherChunk.getContent()); return new BaseMessageChunk( getRole(), mergedContent, getName() ! null ? getName() : otherChunk.getName() ); }合并规则可以拆解为三点类型安全入参必须是BaseMessageChunk类型否则抛出IllegalArgumentException。这与 Python 版__add__的类型校验行为一致内容合并content交由MessageChunkMerge.mergeParserContent按类型智能合并见下一节名称保留name采用左优先策略——若当前片段已有名称则保留否则取新片段的名称。这与第一个片段携带 name后续片段可能为空的真实流式行为吻合。合并后的结果是一个全新的BaseMessageChunk对象原片段不被修改符合不可变合并语义可安全用于累加器。五、合并策略的底层实现MessageChunkMerge 与 MergeUtilsmerge调用的核心工具是 MessageChunkMerge.java其mergeParserContent(left, right)采用按运行时类型分派的合并策略left 与 right 的类型合并结果任一为null返回非空一侧两边都空则返回null两侧均为String直接字符串拼接如left right leftright两侧均为List先拷贝左列表再追加右列表所有元素concat两侧均为Map递归执行mergeDicts做键级合并两侧同类型且非基本标量反射执行mergePydanticModels按字段合并其他情况返回右侧值新值覆盖旧值mergeDicts的键级规则同样是字符串拼接、列表拼接、Map 递归合并其余右值覆盖。对同类型 POJOmergePydanticModels借助 JavaBeans 内省Introspector.getBeanInfo遍历可读写属性对每个字段递归调用mergeParserContent——这正是工具调用参数分片拼接的实现基础。该工具类还额外提供两个流式字段合并能力concatTokenIds(left, right)把两段 token id 列表顺序拼接mergeLogprobs(left, right)对 logprobs 的 Map 结构按 key 合并key 下的列表执行拼接。仓库中还提供了一份功能几乎等同、并额外抽象出MergeableT接口对应 Python 的__add__的 MergeUtils.java两者均明确标注镜像 Python 版message_chunk.py供上层按需选用。5.1 合并工具的正确性由测试保障MessageChunkTest.java 与 MessageChunkPythonParityTest.java 覆盖了上述全部策略其中后者以动态测试工厂TestFactory逐条对齐 Python 侧 30 个用例如test_merge_parser_content_strings、test_merge_dicts_nested、test_merge_pydantic_models_tool_call。测试断言包括字符串拼接、列表拼接、嵌套 Map 递归合并、同 key 冲突时右侧覆盖等为Java 与 Python 行为一致提供了可验证依据。六、子类体系AssistantMessageChunk 与 ToolMessageChunkBaseMessageChunk是基类实际流式链路中登场的是它的两个子类见 schema.README.md 的类型清单6.1 AssistantMessageChunkassistant 流式片段AssistantMessageChunk.java 继承AssistantMessage而AssistantMessage又继承BaseMessage额外承载流式场景的字段toolCalls工具调用增量含id、type、name、arguments、indexfinishReason结束原因默认字符串null表示尚未结束reasoningContent思维链/推理内容增量usageMetadata、promptTokenIds、completionTokenIds、logprobs、parserContent。其merge方法对每个字段执行专门的合并策略content、parserContent走mergeParserContentreasoningContent两侧字符串直接拼接orEmpty处理 nulltoolCalls是最复杂的部分——按稳定键index id name anon归桶keyOf同一调用 id 的增量片段合入同一条ToolCall并拼接argumentsappendFragment同时处理三类流式容错场景纯参数片段无 id/name/index 仅有 arguments合并进最近一次调用无 id 的流式增量与最近一条 function 调用合并带不同index的并行调用必须保持独立绝不误并入前一条有专门测试assistantChunkMergeKeepsParallelCallsWithDistinctIndexesSeparate守护。 此外还会过滤完全空的虚片段isVacuousFragmentcompletionTokenIds用concatTokenIds拼接、promptTokenIds采用左优先preferLeft、logprobs用mergeLogprobs合并finishReason只有当新片段的值为真实原因非null时才覆盖旧值usageMetadata右非空取右否则取左。6.2 ToolMessageChunktool 流式片段ToolMessageChunk.java 继承ToolMessage其merge相对简单content直接以字符串形式拼接getContentAsString()toolCallId采用右非空取右、否则保留左的策略。这与工具执行结果可能分段返回、而调用 id 只在首段出现的真实场景一致。七、合并机制在模型客户端与 Agent 中的真实调用链BaseMessageChunk的合并能力并非孤立存在而是贯穿整个流式推理链路。7.1 模型客户端SSE 流解析为 Chunk在 OpenAIModelClient.java 中parseStreamChunk把每个 SSE 增量choices[0].delta解析为一个AssistantMessageChunk缺失的content会被规范化为空字符串finish_reason缺失时置为null随后mergeChunks用累加器把所有分片顺序合并为一条完整消息OpenAIModelClient.java#L1602-L1608private AssistantMessageChunk mergeChunks(ListAssistantMessageChunk chunks) { AssistantMessageChunk merged null; for (AssistantMessageChunk chunk : chunks) { merged merged null ? chunk : (AssistantMessageChunk) merged.merge(chunk); } return merged; }7.2 Agent 层边流边合并还原完整消息在 ReActAgent.java 中流式推理循环同样维护一个accumulatedChunk累加器每收到一个AssistantMessageChunk就调用accumulatedChunk.merge(chunk)待流结束后将合并结果转换为完整的AssistantMessage携带合并后的content、toolCalls、reasoningContent、usageMetadata、token ids 与 logprobs供后续工具调用、记忆写入或轨迹存储使用。这也说明merge不仅是数据拼接更是 Agent 流式行为正确性的关键一环——工具参数分片、推理内容增量、finish_reason 传递都依赖它。八、小结BaseMessageChunk是 openJiuwen 消息片段体系的基类继承BaseMessage通过merge(BaseMessageChunk other)提供片段合并基础合并策略由MessageChunkMerge/MergeUtils承载字符串拼接、列表拼接、Map 递归合并、同类型 POJO 字段级合并其余情况新值覆盖子类AssistantMessageChunk实现了包括工具调用归并、并行调用区分、推理内容拼接在内的复杂合并ToolMessageChunk提供工具结果与toolCallId的保留式合并合并机制在OpenAIModelClient的 SSE 解析与ReActAgent的流式推理累加器中实际落地并有MessageChunkTest与MessageChunkPythonParityTest两个测试类持续验证其与 Python 版行为的一致性。如果需要进一步了解merge的调用前提与边界可查阅 MessageChunkTest.java 中的合并失败用例如非 Chunk 类型入参抛出IllegalArgumentException以及 MessageChunkPythonParityTest.java 中与 Python 侧逐条对齐的动态测试清单。赞分享人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习【免费下载链接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent开发、运行、调优与演进相关的全套SDK能力。项目地址https://gitcode.com/openJiuwen/agent-core-java点击查看免费下载相关推荐openJiuwen Agent Core JavaAssistantMessageChunk 流式消息片段与合并机制深度解析openJiuwen Agent Core JavaAssistantMessageChunk 流式消息片段与合并机制深度解析 AssistantMessag人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习openJiuwen Agent Core 消息基类 BaseMessage 完全指南字段、构造、序列化与流式合并机制openJiuwen Agent Core 消息基类 BaseMessage 完全指南字段、构造、序列化与流式合并机制 com.openjiuwen.core人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习openJiuwen Agent Core Java 消息模型详解AssistantMessage 的字段、工具调用与序列化机制openJiuwen Agent Core Java 消息模型详解AssistantMessage 的字段、工具调用与序列化机制 本文围绕 openJiuwe人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习上一篇Jetson-FFmpeg 项目常见问题解决方案下一篇Crocoddyl 项目常见问题解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考