OA2023/OASystem/OASystem.Api/OAMethodLib/TokenHubAI/Models/StreamChunk.cs

namespace OASystem.API.OAMethodLib.TokenHubAI.Models;

/// <summary>
/// 流式响应片段
/// </summary>
public class StreamChunk
{
    // ============ 内容 ============

    /// <summary>
    /// 内容片段
    /// </summary>
    public string? Content { get; set; }

    /// <summary>
    /// 增量消息对象
    /// </summary>
    public ChatMessage? Delta { get; set; }

    // ============ 状态 ============

    /// <summary>
    /// 是否结束
    /// </summary>
    public bool IsDone { get; set; }

    /// <summary>
    /// 完成原因
    /// </summary>
    /// <remarks>
    /// - stop：正常结束
    /// - length：达到最大长度
    /// - content_filter：内容被过滤
    /// - tool_calls：工具调用
    /// </remarks>
    public string? FinishReason { get; set; }

    /// <summary>
    /// 使用的模型
    /// </summary>
    public string? Model { get; set; }

    /// <summary>
    /// 响应 ID
    /// </summary>
    public string? Id { get; set; }

    /// <summary>
    /// 索引
    /// </summary>
    public int Index { get; set; }

    // ============ 工具调用 ============

    /// <summary>
    /// 工具调用列表（流式）
    /// </summary>
    public List<ToolCall>? ToolCalls { get; set; }

    // ============ 统计 ============

    /// <summary>
    /// Token 使用统计（仅在结束时返回）
    /// </summary>
    public TokenUsage? Usage { get; set; }

    // ============ 工厂方法 ============

    /// <summary>
    /// 创建内容片段
    /// </summary>
    public static StreamChunk ContentChunk(string content)
    {
        return new StreamChunk
        {
            Content = content,
            IsDone = false
        };
    }

    /// <summary>
    /// 创建结束标记
    /// </summary>
    public static StreamChunk Done(string? finishReason = "stop")
    {
        return new StreamChunk
        {
            IsDone = true,
            FinishReason = finishReason
        };
    }

    /// <summary>
    /// 创建错误片段
    /// </summary>
    public static StreamChunk Error(string errorMessage)
    {
        return new StreamChunk
        {
            IsDone = true,
            Content = $"[错误: {errorMessage}]"
        };
    }

    /// <summary>
    /// 判断是否包含内容
    /// </summary>
    public bool HasContent => !string.IsNullOrEmpty(Content) || Delta?.Content != null;

    /// <summary>
    /// 获取完整内容（累积）
    /// </summary>
    public string GetFullContent()
    {
        if (!string.IsNullOrEmpty(Content))
            return Content;

        return Delta?.Content ?? string.Empty;
    }

    /// <summary>
    /// 判断是否正常结束
    /// </summary>
    public bool IsNormalEnd => IsDone && FinishReason is "stop" or null;
}