package com.gzzm.lobster.context;

import com.gzzm.lobster.llm.LobsterMessage;
import com.gzzm.lobster.llm.ModelRouteResult;
import com.gzzm.lobster.thread.ThreadRoom;

import java.util.List;

/**
 * SummarizerService —— 历史摘要服务 / History summarization service.
 *
 * <p>把一段被折叠的历史消息（user / assistant / tool）压成一段中性叙述文本。
 * 调用方在折叠路径内部使用：返回 null/空字符串视为"无摘要"，由调用方走兜底（bullet 折叠）。
 *
 * <p>设计目标对齐 Claude Code auto-compact：
 * <ul>
 *   <li>包含用户高层目标、关键事实（路径/行号/报错）、工具调用链路、未完成事项</li>
 *   <li>不编造、不省略具体值</li>
 *   <li>失败/超时一律返回 null，让调用方走 bullet 兜底</li>
 * </ul>
 *
 * <p>Implementations:
 * <ul>
 *   <li>{@link BulletSummarizer} —— 纯字符串拼接，零成本，零外部依赖</li>
 *   <li>{@link LlmSummarizer} —— 调便宜小模型做真摘要；启用受 LobsterConfig.summarizerEnabled 控制</li>
 * </ul>
 */
public interface SummarizerService {

    /**
     * 把一段被折叠的消息压成摘要文本.
     *
     * @param oldMessages 待压缩的消息片段（按时序）.
     * @param thread      当前 thread；非 null —— 用于路由与审计.
     * @param route       LLM 路由结果；LlmSummarizer 用主链直接调用，BulletSummarizer 不使用.
     * @return 摘要文本；返回 null 或空表示交给调用方兜底.
     */
    String summarize(List<LobsterMessage> oldMessages, ThreadRoom thread, ModelRouteResult route);
}