@gt-fe/eap-runtime 0.0.8

package/dist/memory/compression/compression-stats.d.ts

@@ -0,0 +1,109 @@
+/**
+ * CompressionStats — 压缩统计服务
+ *
+ * 收集和报告压缩相关的指标：
+ * - 压缩次数
+ * - 压缩率（Token 减少比例）
+ * - 压缩耗时
+ * - 策略使用分布
+ *
+ * @see message-compression.service.ts 压缩接口
+ */
+import type { CompressionStrategy, CompressionRecord } from '../message-compression.service.js';
+/**
+ * 压缩统计指标
+ */
+export interface CompressionMetrics {
+    /** 总压缩次数 */
+    totalCompressions: number;
+    /** 总原始 Token 数 */
+    totalOriginalTokens: number;
+    /** 总压缩后 Token 数 */
+    totalCompressedTokens: number;
+    /** 平均压缩率（0-1，越小越好） */
+    averageCompressionRatio: number;
+    /** 平均压缩耗时（毫秒） */
+    averageDurationMs: number;
+    /** 策略使用分布 */
+    strategyDistribution: Record<CompressionStrategy, number>;
+    /** 最近 N 次压缩的详细记录 */
+    recentCompressions: CompressionRecord[];
+}
+/**
+ * 单次压缩统计
+ */
+export interface CompressionStatEntry {
+    /** 会话 ID */
+    sessionId: string;
+    /** 任务 ID */
+    taskId: string | null;
+    /** 原始消息数 */
+    originalMessageCount: number;
+    /** 压缩后消息数 */
+    compressedMessageCount: number;
+    /** 原始 Token 数 */
+    originalTokens: number;
+    /** 压缩后 Token 数 */
+    compressedTokens: number;
+    /** 压缩率 */
+    compressionRatio: number;
+    /** 使用的策略 */
+    strategy: CompressionStrategy;
+    /** 压缩耗时（毫秒） */
+    durationMs: number;
+    /** 时间戳 */
+    timestamp: string;
+}
+/**
+ * CompressionStatsService — 压缩统计服务
+ */
+export declare class CompressionStatsService {
+    private readonly entries;
+    private readonly maxEntries;
+    constructor(maxEntries?: number);
+    /**
+     * 记录一次压缩
+     *
+     * @param entry - 压缩统计条目
+     */
+    record(entry: CompressionStatEntry): void;
+    /**
+     * 获取压缩指标
+     *
+     * @param sessionId - 可选，按会话过滤
+     * @returns 压缩指标
+     */
+    getMetrics(sessionId?: string): CompressionMetrics;
+    /**
+     * 获取所有条目（调试用）
+     */
+    getEntries(): CompressionStatEntry[];
+    /**
+     * 清空统计
+     */
+    clear(): void;
+    /**
+     * 导出统计报告
+     */
+    exportReport(): string;
+}
+/**
+ * 全局压缩统计服务实例
+ */
+export declare const globalCompressionStats: CompressionStatsService;
+/**
+ * 创建压缩统计条目
+ *
+ * @param params - 参数
+ * @returns 压缩统计条目
+ */
+export declare function createCompressionStatEntry(params: {
+    sessionId: string;
+    taskId?: string;
+    originalMessageCount: number;
+    compressedMessageCount: number;
+    originalTokens: number;
+    compressedTokens: number;
+    strategy: CompressionStrategy;
+    durationMs: number;
+}): CompressionStatEntry;

package/dist/memory/compression/compression-stats.js

@@ -0,0 +1,144 @@
+/**
+ * CompressionStats — 压缩统计服务
+ *
+ * 收集和报告压缩相关的指标：
+ * - 压缩次数
+ * - 压缩率（Token 减少比例）
+ * - 压缩耗时
+ * - 策略使用分布
+ *
+ * @see message-compression.service.ts 压缩接口
+ */
+// ─────────────────────────────────────────────
+// CompressionStatsService
+// ─────────────────────────────────────────────
+/**
+ * CompressionStatsService — 压缩统计服务
+ */
+export class CompressionStatsService {
+    entries = [];
+    maxEntries;
+    constructor(maxEntries = 1000) {
+        this.maxEntries = maxEntries;
+    }
+    /**
+     * 记录一次压缩
+     *
+     * @param entry - 压缩统计条目
+     */
+    record(entry) {
+        this.entries.push(entry);
+        // 限制记录数量
+        if (this.entries.length > this.maxEntries) {
+            this.entries.shift();
+        }
+    }
+    /**
+     * 获取压缩指标
+     *
+     * @param sessionId - 可选，按会话过滤
+     * @returns 压缩指标
+     */
+    getMetrics(sessionId) {
+        const filtered = sessionId
+            ? this.entries.filter((e) => e.sessionId === sessionId)
+            : this.entries;
+        if (filtered.length === 0) {
+            return {
+                totalCompressions: 0,
+                totalOriginalTokens: 0,
+                totalCompressedTokens: 0,
+                averageCompressionRatio: 0,
+                averageDurationMs: 0,
+                strategyDistribution: {},
+                recentCompressions: [],
+            };
+        }
+        // 计算总和
+        const totalOriginalTokens = filtered.reduce((sum, e) => sum + e.originalTokens, 0);
+        const totalCompressedTokens = filtered.reduce((sum, e) => sum + e.compressedTokens, 0);
+        const totalDuration = filtered.reduce((sum, e) => sum + e.durationMs, 0);
+        // 计算策略分布
+        const strategyDistribution = {};
+        for (const entry of filtered) {
+            strategyDistribution[entry.strategy] = (strategyDistribution[entry.strategy] || 0) + 1;
+        }
+        // 获取最近 10 次压缩记录
+        const recentCompressions = filtered
+            .slice(-10)
+            .map((e) => ({
+            sessionId: e.sessionId,
+            taskId: e.taskId,
+            originalMessageCount: e.originalMessageCount,
+            compressedMessageCount: e.compressedMessageCount,
+            originalTokens: e.originalTokens,
+            compressedTokens: e.compressedTokens,
+            strategy: e.strategy,
+            summaryContent: '',
+            createdBy: 'system',
+            createdAt: e.timestamp,
+        }));
+        return {
+            totalCompressions: filtered.length,
+            totalOriginalTokens,
+            totalCompressedTokens,
+            averageCompressionRatio: totalOriginalTokens > 0
+                ? totalCompressedTokens / totalOriginalTokens
+                : 0,
+            averageDurationMs: totalDuration / filtered.length,
+            strategyDistribution: strategyDistribution,
+            recentCompressions,
+        };
+    }
+    /**
+     * 获取所有条目（调试用）
+     */
+    getEntries() {
+        return [...this.entries];
+    }
+    /**
+     * 清空统计
+     */
+    clear() {
+        this.entries.length = 0;
+    }
+    /**
+     * 导出统计报告
+     */
+    exportReport() {
+        const metrics = this.getMetrics();
+        return JSON.stringify(metrics, null, 2);
+    }
+}
+// ─────────────────────────────────────────────
+// 全局实例
+// ─────────────────────────────────────────────
+/**
+ * 全局压缩统计服务实例
+ */
+export const globalCompressionStats = new CompressionStatsService();
+// ─────────────────────────────────────────────
+// 工具函数
+// ─────────────────────────────────────────────
+/**
+ * 创建压缩统计条目
+ *
+ * @param params - 参数
+ * @returns 压缩统计条目
+ */
+export function createCompressionStatEntry(params) {
+    return {
+        sessionId: params.sessionId,
+        taskId: params.taskId ?? null,
+        originalMessageCount: params.originalMessageCount,
+        compressedMessageCount: params.compressedMessageCount,
+        originalTokens: params.originalTokens,
+        compressedTokens: params.compressedTokens,
+        compressionRatio: params.originalTokens > 0
+            ? params.compressedTokens / params.originalTokens
+            : 0,
+        strategy: params.strategy,
+        durationMs: params.durationMs,
+        timestamp: new Date().toISOString(),
+    };
+}

package/dist/memory/compression/compression.repository.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 压缩审计记录 Repository
+ *
+ * 记录消息压缩的审计信息，用于追踪压缩历史。
+ *
+ * @see message-compression.service.ts CompressionRecord 类型定义
+ */
+import type { CompressionRecord } from '../message-compression.service.js';
+/** pg Pool 抽象接口 */
+export interface IPgPool {
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+}
+/**
+ * CREATE TABLE compression_records (
+ *   id                    VARCHAR(36)   PRIMARY KEY,
+ *   session_id            VARCHAR(36)   NOT NULL,
+ *   task_id               VARCHAR(36)   NULL,
+ *   original_message_count INT          NOT NULL,
+ *   compressed_message_count INT        NOT NULL,
+ *   original_tokens       INT           NOT NULL,
+ *   compressed_tokens     INT           NOT NULL,
+ *   strategy              VARCHAR(20)   NOT NULL,
+ *   summary_content       TEXT          NOT NULL,
+ *   created_by            VARCHAR(36)   NOT NULL DEFAULT 'system',
+ *   created_at            TIMESTAMPTZ   NOT NULL DEFAULT NOW(),
+ *   INDEX idx_compression_session (session_id),
+ *   INDEX idx_compression_task (task_id)
+ * );
+ */
+/**
+ * ICompressionRepository — 压缩记录持久化接口
+ */
+export interface ICompressionRepository {
+    /**
+     * 保存压缩记录
+     */
+    save(record: CompressionRecord): Promise<void>;
+    /**
+     * 按 sessionId 查询压缩记录
+     */
+    findBySessionId(sessionId: string): Promise<CompressionRecord[]>;
+}
+/**
+ * PostgresCompressionRepository — PostgreSQL 实现
+ */
+export declare class PostgresCompressionRepository implements ICompressionRepository {
+    private readonly pool;
+    constructor(pool: IPgPool);
+    save(record: CompressionRecord): Promise<void>;
+    findBySessionId(sessionId: string): Promise<CompressionRecord[]>;
+    private rowToRecord;
+}
+/**
+ * InMemoryCompressionRepository — 内存实现（测试用）
+ */
+export declare class InMemoryCompressionRepository implements ICompressionRepository {
+    private readonly store;
+    save(record: CompressionRecord): Promise<void>;
+    findBySessionId(sessionId: string): Promise<CompressionRecord[]>;
+}

package/dist/memory/compression/compression.repository.js

@@ -0,0 +1,71 @@
+/**
+ * 压缩审计记录 Repository
+ *
+ * 记录消息压缩的审计信息，用于追踪压缩历史。
+ *
+ * @see message-compression.service.ts CompressionRecord 类型定义
+ */
+/**
+ * PostgresCompressionRepository — PostgreSQL 实现
+ */
+export class PostgresCompressionRepository {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    async save(record) {
+        const { randomUUID } = await import('node:crypto');
+        const id = randomUUID();
+        const sql = `
+      INSERT INTO compression_records (id, session_id, task_id, original_message_count, compressed_message_count, original_tokens, compressed_tokens, strategy, summary_content, created_by, created_at)
+      VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)
+    `;
+        await this.pool.query(sql, [
+            id,
+            record.sessionId,
+            record.taskId,
+            record.originalMessageCount,
+            record.compressedMessageCount,
+            record.originalTokens,
+            record.compressedTokens,
+            record.strategy,
+            record.summaryContent,
+            record.createdBy || 'system',
+            record.createdAt,
+        ]);
+    }
+    async findBySessionId(sessionId) {
+        const sql = `SELECT * FROM compression_records WHERE session_id = $1 ORDER BY created_at DESC`;
+        const { rows } = await this.pool.query(sql, [sessionId]);
+        return rows.map((row) => this.rowToRecord(row));
+    }
+    rowToRecord(row) {
+        return {
+            sessionId: row.session_id,
+            taskId: row.task_id,
+            originalMessageCount: row.original_message_count,
+            compressedMessageCount: row.compressed_message_count,
+            originalTokens: row.original_tokens,
+            compressedTokens: row.compressed_tokens,
+            strategy: row.strategy,
+            summaryContent: row.summary_content,
+            createdBy: row.created_by,
+            createdAt: row.created_at.toISOString(),
+        };
+    }
+}
+// ─────────────────────────────────────────────
+// In-Memory Implementation (for testing)
+// ─────────────────────────────────────────────
+/**
+ * InMemoryCompressionRepository — 内存实现（测试用）
+ */
+export class InMemoryCompressionRepository {
+    store = [];
+    async save(record) {
+        this.store.push({ ...record });
+    }
+    async findBySessionId(sessionId) {
+        return this.store.filter((r) => r.sessionId === sessionId);
+    }
+}

package/dist/memory/compression/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 消息压缩模块
+ *
+ * 提供多种压缩策略用于处理长对话历史。
+ */
+export { type CompressionConfig, type CompressionResult, type CompressionRecord, type CompressionStrategy, type CompressionReason, type IMessageCompressionService, DEFAULT_COMPRESSION_CONFIG, estimateTokenCount, estimateMessagesTokens, countRounds, } from '../message-compression.service.js';
+export { SlidingWindowCompression, TruncateCompression, type SummarizeFunction, } from './sliding-window.compression.js';
+export { createLLMSummarize, createSimpleSummarize, type LLMCallFunction, } from './llm-summarize.js';
+export { PostgresCompressionRepository, InMemoryCompressionRepository, type ICompressionRepository, } from './compression.repository.js';
+export { CompressionStatsService, globalCompressionStats, createCompressionStatEntry, type CompressionMetrics, type CompressionStatEntry, } from './compression-stats.js';

package/dist/memory/compression/index.js

@@ -0,0 +1,15 @@
+/**
+ * 消息压缩模块
+ *
+ * 提供多种压缩策略用于处理长对话历史。
+ */
+// 压缩接口和工具函数
+export { DEFAULT_COMPRESSION_CONFIG, estimateTokenCount, estimateMessagesTokens, countRounds, } from '../message-compression.service.js';
+// 滑动窗口压缩策略
+export { SlidingWindowCompression, TruncateCompression, } from './sliding-window.compression.js';
+// LLM 摘要函数
+export { createLLMSummarize, createSimpleSummarize, } from './llm-summarize.js';
+// 压缩记录 Repository
+export { PostgresCompressionRepository, InMemoryCompressionRepository, } from './compression.repository.js';
+// 压缩统计
+export { CompressionStatsService, globalCompressionStats, createCompressionStatEntry, } from './compression-stats.js';

package/dist/memory/compression/llm-summarize.d.ts

@@ -0,0 +1,58 @@
+/**
+ * LLM 摘要函数实现
+ *
+ * 使用 LLM 对历史消息进行摘要压缩。
+ * 支持注入不同的 LLM 调用方式。
+ *
+ * @see sliding-window.compression.ts 压缩策略
+ * @see requirements.md Requirement 4.3
+ */
+import type { ILLMProvider, LLMNodeConfig } from '../../graph/nodes/llm-node.js';
+import type { SummarizeFunction } from './sliding-window.compression.js';
+/**
+ * LLM 调用接口（简单版本，向后兼容）
+ */
+export type LLMCallFunction = (prompt: string) => Promise<string>;
+/**
+ * 创建基于 ILLMProvider 的摘要函数
+ *
+ * 这是推荐的方式，使用项目统一的 LLM 调用接口。
+ *
+ * @param provider - ILLMProvider 实例
+ * @param config - LLM 配置（模型、温度等）
+ * @param concise - 是否使用精简 Prompt（默认 false）
+ * @returns 摘要函数
+ */
+export declare function createLLMSummarizeWithProvider(provider: ILLMProvider, config?: Partial<LLMNodeConfig>, concise?: boolean): SummarizeFunction;
+/**
+ * 创建基于简单 LLM 调用函数的摘要函数（向后兼容）
+ *
+ * @param llmCall - 简单的 LLM 调用函数
+ * @returns 摘要函数
+ */
+export declare function createLLMSummarize(llmCall?: LLMCallFunction): SummarizeFunction;
+/**
+ * 简单摘要函数（不依赖 LLM）
+ *
+ * 基于规则的简单摘要，适用于 LLM 不可用的场景。
+ */
+export declare function createSimpleSummarize(): SummarizeFunction;
+/**
+ * 创建摘要函数（自动选择最佳可用方式）
+ *
+ * 优先级：
+ * 1. ILLMProvider（推荐）
+ * 2. LLMCallFunction（向后兼容）
+ * 3. 简单摘要（降级）
+ *
+ * @param options - 配置选项
+ * @returns 摘要函数
+ */
+export declare function createSummarize(options?: {
+    provider?: ILLMProvider;
+    llmCall?: LLMCallFunction;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    concise?: boolean;
+}): SummarizeFunction;

package/dist/memory/compression/llm-summarize.js

@@ -0,0 +1,192 @@
+/**
+ * LLM 摘要函数实现
+ *
+ * 使用 LLM 对历史消息进行摘要压缩。
+ * 支持注入不同的 LLM 调用方式。
+ *
+ * @see sliding-window.compression.ts 压缩策略
+ * @see requirements.md Requirement 4.3
+ */
+// ─────────────────────────────────────────────
+// 摘要 Prompt 模板
+// ─────────────────────────────────────────────
+/**
+ * 摘要 Prompt 模板
+ */
+const SUMMARY_PROMPT_TEMPLATE = `请将以下对话历史压缩为简洁的摘要，保留关键信息：
+
+对话历史：
+{messages}
+
+要求：
+1. 保留用户的核心需求和关键决策
+2. 保留重要的数据和结论
+3. 保留未完成的任务或待解决的问题
+4. 压缩到原来的 30% 左右
+5. 使用中文输出
+
+摘要：`;
+/**
+ * 精简版 Prompt（用于 Token 受限场景）
+ */
+const CONCISE_SUMMARY_PROMPT = `请用 3-5 句话概括以下对话的核心内容：
+
+{messages}
+
+核心摘要：`;
+// ─────────────────────────────────────────────
+// 创建摘要函数
+// ─────────────────────────────────────────────
+/**
+ * 创建基于 ILLMProvider 的摘要函数
+ *
+ * 这是推荐的方式，使用项目统一的 LLM 调用接口。
+ *
+ * @param provider - ILLMProvider 实例
+ * @param config - LLM 配置（模型、温度等）
+ * @param concise - 是否使用精简 Prompt（默认 false）
+ * @returns 摘要函数
+ */
+export function createLLMSummarizeWithProvider(provider, config, concise = false) {
+    const llmConfig = {
+        model: config?.model ?? 'DeepSeek-V4-Pro',
+        temperature: config?.temperature ?? 0.3,
+        maxTokens: config?.maxTokens ?? 1024,
+    };
+    const promptTemplate = concise ? CONCISE_SUMMARY_PROMPT : SUMMARY_PROMPT_TEMPLATE;
+    return async (messages) => {
+        // 格式化消息为文本
+        const formattedMessages = messages
+            .map((m) => {
+            const role = m.role === 'user' ? '用户' : m.role === 'assistant' ? '助手' : m.role;
+            const content = m.content.length > 500
+                ? m.content.substring(0, 500) + '...'
+                : m.content;
+            return `${role}: ${content}`;
+        })
+            .join('\n');
+        // 构造 Prompt
+        const prompt = promptTemplate.replace('{messages}', formattedMessages);
+        // 构造 GraphMessage 格式的请求
+        const requestMessages = [
+            {
+                role: 'system',
+                content: '你是一个专业的对话摘要助手，擅长提取关键信息并生成简洁的摘要。',
+            },
+            {
+                role: 'user',
+                content: prompt,
+            },
+        ];
+        try {
+            // 调用 LLM 生成摘要
+            const response = await provider.invoke(requestMessages, llmConfig);
+            return response.content;
+        }
+        catch (error) {
+            console.error('[LLM Summarize] LLM call failed, falling back to simple summarize:', error);
+            // 降级到简单摘要
+            return simpleSummarize(messages);
+        }
+    };
+}
+/**
+ * 创建基于简单 LLM 调用函数的摘要函数（向后兼容）
+ *
+ * @param llmCall - 简单的 LLM 调用函数
+ * @returns 摘要函数
+ */
+export function createLLMSummarize(llmCall) {
+    if (!llmCall) {
+        return createSimpleSummarize();
+    }
+    return async (messages) => {
+        // 格式化消息为文本
+        const formattedMessages = messages
+            .map((m) => {
+            const role = m.role === 'user' ? '用户' : m.role === 'assistant' ? '助手' : m.role;
+            return `${role}: ${m.content}`;
+        })
+            .join('\n');
+        // 构造 Prompt
+        const prompt = SUMMARY_PROMPT_TEMPLATE.replace('{messages}', formattedMessages);
+        try {
+            // 调用 LLM 生成摘要
+            const summary = await llmCall(prompt);
+            return summary;
+        }
+        catch (error) {
+            console.error('[LLM Summarize] LLM call failed, falling back to simple summarize:', error);
+            return simpleSummarize(messages);
+        }
+    };
+}
+/**
+ * 简单摘要函数（不依赖 LLM）
+ *
+ * 基于规则的简单摘要，适用于 LLM 不可用的场景。
+ */
+export function createSimpleSummarize() {
+    return async (messages) => {
+        return simpleSummarize(messages);
+    };
+}
+// ─────────────────────────────────────────────
+// 内部工具函数
+// ─────────────────────────────────────────────
+/**
+ * 简单摘要实现（纯函数，可复用）
+ */
+function simpleSummarize(messages) {
+    const userMessages = messages.filter((m) => m.role === 'user');
+    const assistantMessages = messages.filter((m) => m.role === 'assistant');
+    // 提取用户问题（取前 200 字符）
+    const userQuestions = userMessages
+        .map((m) => m.content.length > 200 ? m.content.substring(0, 200) + '...' : m.content)
+        .join('；');
+    // 提取助手回答要点（取前 150 字符）
+    const assistantPoints = assistantMessages
+        .map((m) => m.content.length > 150 ? m.content.substring(0, 150) + '...' : m.content)
+        .join('；');
+    // 统计信息
+    const totalMessages = messages.length;
+    const timeRange = messages.length > 0
+        ? `共 ${totalMessages} 条消息`
+        : '';
+    return [
+        `【对话摘要】${timeRange}`,
+        `用户主要问题：${userQuestions}`,
+        `助手回答要点：${assistantPoints}`,
+    ].join('\n');
+}
+// ─────────────────────────────────────────────
+// 工厂函数（推荐使用）
+// ─────────────────────────────────────────────
+/**
+ * 创建摘要函数（自动选择最佳可用方式）
+ *
+ * 优先级：
+ * 1. ILLMProvider（推荐）
+ * 2. LLMCallFunction（向后兼容）
+ * 3. 简单摘要（降级）
+ *
+ * @param options - 配置选项
+ * @returns 摘要函数
+ */
+export function createSummarize(options) {
+    // 优先使用 ILLMProvider
+    if (options?.provider) {
+        return createLLMSummarizeWithProvider(options.provider, {
+            model: options.model,
+            temperature: options.temperature,
+            maxTokens: options.maxTokens,
+        }, options.concise);
+    }
+    // 其次使用简单 LLM 调用函数
+    if (options?.llmCall) {
+        return createLLMSummarize(options.llmCall);
+    }
+    // 降级到简单摘要
+    console.warn('[Summarize] No LLM provider configured, using simple summarize');
+    return createSimpleSummarize();
+}