001/*
002 *  Copyright (c) 2023-2026, Agents-Flex (fuhai999@gmail.com).
003 *  <p>
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *  <p>
008 *  http://www.apache.org/licenses/LICENSE-2.0
009 *  <p>
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016package com.agentsflex.core.message;
017
018import com.agentsflex.core.util.Metadata;
019
020/**
021 * 表示一个通用的消息（Message），通常用于与大语言模型（如 OpenAI）进行交互。
022 * 消息内容可以是纯文本，也可以是多模态内容（例如：文本 + 图像等）。
023 *
024 * <p>该类继承自 {@link Metadata}，允许附加任意元数据（如来源、时间戳、追踪ID等）。
025 *
026 * @see #getTextContent()
027 */
028public abstract class Message extends Metadata {
029
030    /**
031     * 提取消息中的纯文本部分。
032     *
033     * <p>无论原始内容是纯文本还是多模态结构（如文本+图像），本方法应返回其中所有文本内容的合理合并结果。
034     * 例如，在 OpenAI 多模态消息中，应遍历所有 {@code content} 元素，提取类型为 {@code text} 的部分并拼接。
035     *
036     * <p>返回的字符串应不包含非文本元素（如图像、音频等），且应保持原始文本的语义顺序（如适用）。
037     * 若消息中无文本内容，则返回空字符串（{@code ""}），而非 {@code null}。
038     *
039     * <p>该方法主要用于日志记录、监控、文本分析等仅需文本语义的场景。
040     *
041     * @return 消息中提取出的纯文本内容。
042     */
043    public abstract String getTextContent();
044}