@gt-fe/eap-runtime 0.0.8

package/dist/memory/compression/sliding-window.compression.d.ts

@@ -0,0 +1,60 @@
+/**
+ * SlidingWindowCompression — 滑动窗口 + LLM 摘要压缩策略
+ *
+ * 压缩策略：
+ * 1. 保留最近 N 轮对话（preserveRecentRounds）
+ * 2. 将历史部分用 LLM 生成摘要
+ * 3. 用摘要 + 最近 N 轮 替换原始消息
+ *
+ * @see message-compression.service.ts 压缩接口定义
+ * @see requirements.md Requirement 4.3
+ */
+import type { GraphMessage } from '../../graph/contracts/executable-graph.js';
+import type { CompressionConfig, CompressionResult, IMessageCompressionService } from '../message-compression.service.js';
+/**
+ * LLM 摘要函数接口
+ *
+ * 由外部注入，支持不同的 LLM 实现。
+ */
+export type SummarizeFunction = (messages: GraphMessage[]) => Promise<string>;
+export declare class SlidingWindowCompression implements IMessageCompressionService {
+    private readonly config;
+    private readonly summarize;
+    constructor(config?: Partial<CompressionConfig>, summarize?: SummarizeFunction);
+    /**
+     * 检查是否需要压缩
+     */
+    checkCompression(messages: GraphMessage[], config?: Partial<CompressionConfig>): CompressionResult;
+    /**
+     * 执行消息压缩
+     *
+     * 滑动窗口策略：
+     * 1. 找到最近 N 轮的起始位置
+     * 2. 将历史部分用 LLM 生成摘要
+     * 3. 用摘要 + 最近 N 轮替换原始消息
+     */
+    compress(messages: GraphMessage[], config?: Partial<CompressionConfig>): Promise<GraphMessage[]>;
+    /**
+     * 估算消息的 Token 数
+     */
+    estimateTokens(messages: GraphMessage[]): number;
+    /**
+     * 找到最近 N 轮的起始位置
+     *
+     * 从后往前数 N 个 user 消息，返回分割点索引。
+     */
+    private findSplitIndex;
+}
+/**
+ * 截断压缩策略
+ *
+ * 直接丢弃旧消息，只保留最近 N 条。
+ * 简单但会丢失上下文，不推荐用于生产环境。
+ */
+export declare class TruncateCompression implements IMessageCompressionService {
+    private readonly config;
+    constructor(config?: Partial<CompressionConfig>);
+    checkCompression(messages: GraphMessage[], config?: Partial<CompressionConfig>): CompressionResult;
+    compress(messages: GraphMessage[], config?: Partial<CompressionConfig>): Promise<GraphMessage[]>;
+    estimateTokens(messages: GraphMessage[]): number;
+}

package/dist/memory/compression/sliding-window.compression.js

@@ -0,0 +1,175 @@
+/**
+ * SlidingWindowCompression — 滑动窗口 + LLM 摘要压缩策略
+ *
+ * 压缩策略：
+ * 1. 保留最近 N 轮对话（preserveRecentRounds）
+ * 2. 将历史部分用 LLM 生成摘要
+ * 3. 用摘要 + 最近 N 轮 替换原始消息
+ *
+ * @see message-compression.service.ts 压缩接口定义
+ * @see requirements.md Requirement 4.3
+ */
+import { DEFAULT_COMPRESSION_CONFIG, estimateMessagesTokens, countRounds, } from '../message-compression.service.js';
+/**
+ * 默认摘要函数（占位）
+ *
+ * 实际使用时应注入真实的 LLM 摘要函数。
+ */
+async function defaultSummarize(messages) {
+    // 提取消息内容作为简单摘要
+    const contents = messages
+        .filter((m) => m.role === 'user' || m.role === 'assistant')
+        .map((m) => `${m.role}: ${m.content.substring(0, 100)}`)
+        .join('\n');
+    return `[对话摘要]\n${contents}`;
+}
+// ─────────────────────────────────────────────
+// SlidingWindowCompression
+// ─────────────────────────────────────────────
+export class SlidingWindowCompression {
+    config;
+    summarize;
+    constructor(config, summarize) {
+        this.config = { ...DEFAULT_COMPRESSION_CONFIG, ...config };
+        this.summarize = summarize ?? defaultSummarize;
+    }
+    /**
+     * 检查是否需要压缩
+     */
+    checkCompression(messages, config) {
+        const mergedConfig = { ...this.config, ...config };
+        const currentTokens = this.estimateTokens(messages);
+        const currentRounds = countRounds(messages);
+        // 检查 Token 数是否超限
+        if (currentTokens > mergedConfig.maxTokens) {
+            return {
+                needsCompression: true,
+                reason: 'token-exceeded',
+                currentTokens,
+                currentRounds,
+            };
+        }
+        // 检查轮次是否超限
+        if (currentRounds > mergedConfig.maxRounds) {
+            return {
+                needsCompression: true,
+                reason: 'rounds-exceeded',
+                currentTokens,
+                currentRounds,
+            };
+        }
+        return {
+            needsCompression: false,
+            currentTokens,
+            currentRounds,
+        };
+    }
+    /**
+     * 执行消息压缩
+     *
+     * 滑动窗口策略：
+     * 1. 找到最近 N 轮的起始位置
+     * 2. 将历史部分用 LLM 生成摘要
+     * 3. 用摘要 + 最近 N 轮替换原始消息
+     */
+    async compress(messages, config) {
+        const mergedConfig = { ...this.config, ...config };
+        // 1. 找到最近 N 轮的起始位置
+        const splitIndex = this.findSplitIndex(messages, mergedConfig.preserveRecentRounds);
+        // 如果消息太少，不需要压缩
+        if (splitIndex <= 0) {
+            return messages;
+        }
+        // 2. 分割消息：历史部分 + 最近部分
+        const historyMessages = messages.slice(0, splitIndex);
+        const recentMessages = messages.slice(splitIndex);
+        // 3. 用 LLM 生成摘要
+        const summary = await this.summarize(historyMessages);
+        // 4. 构造压缩后的消息列表
+        const compressedMessages = [
+            // 摘要作为 system 消息
+            {
+                role: 'system',
+                content: `[对话历史摘要]\n${summary}`,
+            },
+            // 保留最近 N 轮
+            ...recentMessages,
+        ];
+        return compressedMessages;
+    }
+    /**
+     * 估算消息的 Token 数
+     */
+    estimateTokens(messages) {
+        return estimateMessagesTokens(messages);
+    }
+    /**
+     * 找到最近 N 轮的起始位置
+     *
+     * 从后往前数 N 个 user 消息，返回分割点索引。
+     */
+    findSplitIndex(messages, preserveRounds) {
+        let userCount = 0;
+        for (let i = messages.length - 1; i >= 0; i--) {
+            if (messages[i].role === 'user') {
+                userCount++;
+                if (userCount >= preserveRounds) {
+                    return i;
+                }
+            }
+        }
+        // 如果消息轮次不足，返回 0（不压缩）
+        return 0;
+    }
+}
+// ─────────────────────────────────────────────
+// TruncateCompression — 截断策略（简单但不推荐）
+// ─────────────────────────────────────────────
+/**
+ * 截断压缩策略
+ *
+ * 直接丢弃旧消息，只保留最近 N 条。
+ * 简单但会丢失上下文，不推荐用于生产环境。
+ */
+export class TruncateCompression {
+    config;
+    constructor(config) {
+        this.config = { ...DEFAULT_COMPRESSION_CONFIG, ...config };
+    }
+    checkCompression(messages, config) {
+        const mergedConfig = { ...this.config, ...config };
+        const currentTokens = this.estimateTokens(messages);
+        const currentRounds = countRounds(messages);
+        if (currentTokens > mergedConfig.maxTokens || currentRounds > mergedConfig.maxRounds) {
+            return {
+                needsCompression: true,
+                reason: currentTokens > mergedConfig.maxTokens ? 'token-exceeded' : 'rounds-exceeded',
+                currentTokens,
+                currentRounds,
+            };
+        }
+        return {
+            needsCompression: false,
+            currentTokens,
+            currentRounds,
+        };
+    }
+    async compress(messages, config) {
+        const mergedConfig = { ...this.config, ...config };
+        const preserveCount = mergedConfig.preserveRecentRounds * 2; // 每轮 2 条消息
+        if (messages.length <= preserveCount) {
+            return messages;
+        }
+        // 截断：只保留最近 N 条消息
+        const truncated = messages.slice(-preserveCount);
+        // 添加截断标记
+        const marker = {
+            role: 'system',
+            content: `[注意：以下对话之前的历史已被截断，共丢失 ${messages.length - truncated.length} 条消息]`,
+        };
+        return [marker, ...truncated];
+    }
+    estimateTokens(messages) {
+        return estimateMessagesTokens(messages);
+    }
+}

package/dist/memory/index.d.ts

@@ -0,0 +1,4 @@
+export { LongTermMemoryService, InMemoryMemoryRepository, type IMemoryRepository, type MemoryRecord, type MemoryType, type CompressionResult, } from './long-term-memory.service.js';
+export { PostgresMemoryRepository } from './pg-memory.repository.js';
+export { SlidingWindowCompression, TruncateCompression, type IMessageCompressionService, type CompressionConfig, type SummarizeFunction, DEFAULT_COMPRESSION_CONFIG, estimateMessagesTokens, countRounds, } from './compression/index.js';
+export { SemanticRetrievalService, InMemoryVectorStore, type RetrievalConfig, type RetrievalStrategy, type RetrievalResult, type IVectorStore, type VectorResult, type EmbeddingFunction, DEFAULT_RETRIEVAL_CONFIG, } from './semantic-retrieval.service.js';

package/dist/memory/index.js

@@ -0,0 +1,7 @@
+// Memory Management — 长期记忆服务
+export { LongTermMemoryService, InMemoryMemoryRepository, } from './long-term-memory.service.js';
+export { PostgresMemoryRepository } from './pg-memory.repository.js';
+// 消息压缩模块
+export { SlidingWindowCompression, TruncateCompression, DEFAULT_COMPRESSION_CONFIG, estimateMessagesTokens, countRounds, } from './compression/index.js';
+// 语义检索模块
+export { SemanticRetrievalService, InMemoryVectorStore, DEFAULT_RETRIEVAL_CONFIG, } from './semantic-retrieval.service.js';

package/dist/memory/long-term-memory.service.d.ts

@@ -0,0 +1,94 @@
+/**
+ * LongTermMemoryService — 跨 Session 长期记忆管理
+ *
+ * 功能：
+ * - store: 存储用户偏好/摘要/事实
+ * - retrieve: 按相关性检索记忆
+ * - forget: 删除指定记忆
+ * - compress: 判断消息是否超阈值需要压缩（实际 LLM 摘要为外部关注）
+ * - injectMemories: 将相关记忆注入 GraphState
+ *
+ * @see design.md §1.1 记忆管理
+ * @see design.md §1.3 memories 表
+ */
+import type { GraphState, GraphMessage } from '../graph/contracts/executable-graph.js';
+/** 记忆类型 */
+export type MemoryType = 'preference' | 'summary' | 'fact';
+/**
+ * MemoryRecord — 对应 memories 表
+ */
+export interface MemoryRecord {
+    id: string;
+    userId: string;
+    agentCode: string;
+    type: MemoryType;
+    content: string;
+    relevanceScore: number;
+    createdBy: string;
+    createdAt: string;
+    updatedBy: string;
+    updatedAt: string;
+    isDeleted: boolean;
+    deletedBy?: string | null;
+    deletedAt?: string | null;
+}
+/**
+ * compress 方法的返回值
+ */
+export interface CompressionResult {
+    /** 是否需要压缩 */
+    needsCompression: boolean;
+    /** 当前消息数 */
+    messageCount: number;
+    /** 阈值 */
+    threshold: number;
+}
+/**
+ * IMemoryRepository — 记忆持久化接口
+ */
+export interface IMemoryRepository {
+    save(record: MemoryRecord): Promise<void>;
+    findByUserAndAgent(userId: string, agentCode: string, limit?: number): Promise<MemoryRecord[]>;
+    delete(id: string): Promise<void>;
+    update(record: MemoryRecord): Promise<void>;
+}
+/**
+ * InMemoryMemoryRepository — Map-based 内存实现
+ *
+ * 开发/测试用，生产由 PostgresMemoryRepository 替换
+ */
+export declare class InMemoryMemoryRepository implements IMemoryRepository {
+    private readonly store;
+    save(record: MemoryRecord): Promise<void>;
+    findByUserAndAgent(userId: string, agentCode: string, limit?: number): Promise<MemoryRecord[]>;
+    delete(id: string): Promise<void>;
+    update(record: MemoryRecord): Promise<void>;
+}
+export declare class LongTermMemoryService {
+    private readonly repository;
+    constructor(repository?: IMemoryRepository);
+    /**
+     * 存储一条记忆
+     */
+    store(userId: string, agentCode: string, type: MemoryType, content: string, relevanceScore?: number): Promise<MemoryRecord>;
+    /**
+     * 检索记忆，按 relevanceScore 降序排列
+     */
+    retrieve(userId: string, agentCode: string, limit?: number): Promise<MemoryRecord[]>;
+    /**
+     * 删除（遗忘）一条记忆
+     */
+    forget(memoryId: string): Promise<void>;
+    /**
+     * 判断消息是否超阈值需要压缩
+     *
+     * ponytail: 实际 LLM summarize 是外部关注，这里只返回"是否需要"标志
+     */
+    compress(messages: GraphMessage[], threshold: number): CompressionResult;
+    /**
+     * 将相关记忆注入 GraphState
+     *
+     * 从长期记忆中加载相关上下文，以 system 消息的形式注入到 state.messages 开头。
+     */
+    injectMemories(state: GraphState, userId: string, agentCode: string): Promise<GraphState>;
+}

package/dist/memory/long-term-memory.service.js

@@ -0,0 +1,120 @@
+/**
+ * LongTermMemoryService — 跨 Session 长期记忆管理
+ *
+ * 功能：
+ * - store: 存储用户偏好/摘要/事实
+ * - retrieve: 按相关性检索记忆
+ * - forget: 删除指定记忆
+ * - compress: 判断消息是否超阈值需要压缩（实际 LLM 摘要为外部关注）
+ * - injectMemories: 将相关记忆注入 GraphState
+ *
+ * @see design.md §1.1 记忆管理
+ * @see design.md §1.3 memories 表
+ */
+import { randomUUID } from 'node:crypto';
+// ─────────────────────────────────────────────
+// In-Memory Repository (Default)
+// ─────────────────────────────────────────────
+/**
+ * InMemoryMemoryRepository — Map-based 内存实现
+ *
+ * 开发/测试用，生产由 PostgresMemoryRepository 替换
+ */
+export class InMemoryMemoryRepository {
+    store = new Map();
+    async save(record) {
+        this.store.set(record.id, { ...record });
+    }
+    async findByUserAndAgent(userId, agentCode, limit) {
+        const results = [];
+        for (const record of this.store.values()) {
+            if (record.userId === userId && record.agentCode === agentCode) {
+                results.push({ ...record });
+            }
+        }
+        // 按 relevanceScore 降序
+        results.sort((a, b) => b.relevanceScore - a.relevanceScore);
+        return limit !== undefined ? results.slice(0, limit) : results;
+    }
+    async delete(id) {
+        this.store.delete(id);
+    }
+    async update(record) {
+        this.store.set(record.id, { ...record });
+    }
+}
+// ─────────────────────────────────────────────
+// LongTermMemoryService
+// ─────────────────────────────────────────────
+export class LongTermMemoryService {
+    repository;
+    constructor(repository) {
+        this.repository = repository ?? new InMemoryMemoryRepository();
+    }
+    /**
+     * 存储一条记忆
+     */
+    async store(userId, agentCode, type, content, relevanceScore = 1.0) {
+        const now = new Date().toISOString();
+        const record = {
+            id: randomUUID(),
+            userId,
+            agentCode,
+            type,
+            content,
+            relevanceScore,
+            createdBy: userId,
+            createdAt: now,
+            updatedBy: userId,
+            updatedAt: now,
+            isDeleted: false,
+        };
+        await this.repository.save(record);
+        return record;
+    }
+    /**
+     * 检索记忆，按 relevanceScore 降序排列
+     */
+    async retrieve(userId, agentCode, limit) {
+        return this.repository.findByUserAndAgent(userId, agentCode, limit);
+    }
+    /**
+     * 删除（遗忘）一条记忆
+     */
+    async forget(memoryId) {
+        await this.repository.delete(memoryId);
+    }
+    /**
+     * 判断消息是否超阈值需要压缩
+     *
+     * ponytail: 实际 LLM summarize 是外部关注，这里只返回"是否需要"标志
+     */
+    compress(messages, threshold) {
+        return {
+            needsCompression: messages.length > threshold,
+            messageCount: messages.length,
+            threshold,
+        };
+    }
+    /**
+     * 将相关记忆注入 GraphState
+     *
+     * 从长期记忆中加载相关上下文，以 system 消息的形式注入到 state.messages 开头。
+     */
+    async injectMemories(state, userId, agentCode) {
+        const memories = await this.retrieve(userId, agentCode);
+        if (memories.length === 0)
+            return state;
+        const memoryContent = memories
+            .map((m) => `[${m.type}] ${m.content}`)
+            .join('\n');
+        const memoryMessage = {
+            role: 'system',
+            content: `[Long-term Memory]\n${memoryContent}`,
+        };
+        return {
+            ...state,
+            messages: [memoryMessage, ...state.messages],
+        };
+    }
+}

package/dist/memory/message-compression.service.d.ts

@@ -0,0 +1,128 @@
+/**
+ * MessageCompressionService — 消息压缩服务
+ *
+ * 当对话消息过长时自动触发压缩，保留关键信息同时减少 Token 数。
+ * 支持多种压缩策略：滑动窗口 + LLM 摘要、截断、headroom 等。
+ *
+ * @see design.md §1.1 记忆管理
+ * @see requirements.md Requirement 4.3
+ */
+import type { GraphMessage } from '../graph/contracts/executable-graph.js';
+/**
+ * 压缩策略类型
+ */
+export type CompressionStrategy = 'sliding-window' | 'truncate' | 'headroom';
+/**
+ * 压缩配置
+ */
+export interface CompressionConfig {
+    /** 压缩策略（默认 sliding-window） */
+    strategy: CompressionStrategy;
+    /** 触发压缩的 Token 上限（默认模型 context window 的 70%） */
+    maxTokens: number;
+    /** 备用：按轮次触发（默认 20 轮） */
+    maxRounds: number;
+    /** 压缩后保留的最近轮次（默认 5 轮） */
+    preserveRecentRounds: number;
+    /** 目标压缩比（压缩后/压缩前，默认 0.3） */
+    compressionRatio: number;
+    /** 用于摘要的模型（可选，默认使用当前 Agent 的模型） */
+    summaryModel?: string;
+}
+/**
+ * 默认压缩配置
+ */
+export declare const DEFAULT_COMPRESSION_CONFIG: CompressionConfig;
+/**
+ * 压缩触发原因
+ */
+export type CompressionReason = 'token-exceeded' | 'rounds-exceeded' | 'manual';
+/**
+ * 压缩结果
+ */
+export interface CompressionResult {
+    /** 是否需要压缩 */
+    needsCompression: boolean;
+    /** 触发原因 */
+    reason?: CompressionReason;
+    /** 当前 Token 数 */
+    currentTokens: number;
+    /** 当前轮次数 */
+    currentRounds: number;
+    /** 压缩后的消息（仅在执行压缩后返回） */
+    compressedMessages?: GraphMessage[];
+    /** 实际压缩比 */
+    compressionRatio?: number;
+    /** 生成的摘要内容 */
+    summary?: string;
+}
+/**
+ * 压缩记录（审计用）
+ */
+export interface CompressionRecord {
+    /** 会话 ID */
+    sessionId: string;
+    /** 任务 ID（可选） */
+    taskId: string | null;
+    /** 原始消息数 */
+    originalMessageCount: number;
+    /** 压缩后消息数 */
+    compressedMessageCount: number;
+    /** 原始 Token 数 */
+    originalTokens: number;
+    /** 压缩后 Token 数 */
+    compressedTokens: number;
+    /** 使用的策略 */
+    strategy: CompressionStrategy;
+    /** 摘要内容 */
+    summaryContent: string;
+    /** 创建人 */
+    createdBy: string;
+    /** 创建时间 */
+    createdAt: string;
+}
+/**
+ * IMessageCompressionService — 消息压缩服务接口
+ */
+export interface IMessageCompressionService {
+    /**
+     * 检查是否需要压缩
+     *
+     * @param messages - 当前消息列表
+     * @param config - 压缩配置
+     * @returns 压缩检查结果
+     */
+    checkCompression(messages: GraphMessage[], config?: Partial<CompressionConfig>): CompressionResult;
+    /**
+     * 执行消息压缩
+     *
+     * @param messages - 原始消息列表
+     * @param config - 压缩配置
+     * @returns 压缩后的消息列表
+     */
+    compress(messages: GraphMessage[], config?: Partial<CompressionConfig>): Promise<GraphMessage[]>;
+    /**
+     * 估算消息的 Token 数
+     *
+     * @param messages - 消息列表
+     * @returns 估算的 Token 数
+     */
+    estimateTokens(messages: GraphMessage[]): number;
+}
+/**
+ * 简单的 Token 估算器
+ *
+ * 基于字符数估算 Token 数，粗略但快速。
+ * 中文约 1.5 字符 = 1 Token，英文约 4 字符 = 1 Token。
+ */
+export declare function estimateTokenCount(text: string): number;
+/**
+ * 估算消息列表的 Token 数
+ */
+export declare function estimateMessagesTokens(messages: GraphMessage[]): number;
+/**
+ * 计算消息轮次数
+ *
+ * 一个 user + assistant 消息对算一轮。
+ */
+export declare function countRounds(messages: GraphMessage[]): number;

package/dist/memory/message-compression.service.js

@@ -0,0 +1,69 @@
+/**
+ * MessageCompressionService — 消息压缩服务
+ *
+ * 当对话消息过长时自动触发压缩，保留关键信息同时减少 Token 数。
+ * 支持多种压缩策略：滑动窗口 + LLM 摘要、截断、headroom 等。
+ *
+ * @see design.md §1.1 记忆管理
+ * @see requirements.md Requirement 4.3
+ */
+/**
+ * 默认压缩配置
+ */
+export const DEFAULT_COMPRESSION_CONFIG = {
+    strategy: 'sliding-window',
+    maxTokens: 100000, // 约 70% of 128k context
+    maxRounds: 20,
+    preserveRecentRounds: 5,
+    compressionRatio: 0.3,
+};
+// ─────────────────────────────────────────────
+// Token 估算器
+// ─────────────────────────────────────────────
+/**
+ * 简单的 Token 估算器
+ *
+ * 基于字符数估算 Token 数，粗略但快速。
+ * 中文约 1.5 字符 = 1 Token，英文约 4 字符 = 1 Token。
+ */
+export function estimateTokenCount(text) {
+    // 统计中文字符数
+    const chineseChars = (text.match(/[\u4e00-\u9fff]/g) || []).length;
+    // 统计非中文字符数
+    const otherChars = text.length - chineseChars;
+    // 中文 1.5 字符 ≈ 1 Token，英文 4 字符 ≈ 1 Token
+    return Math.ceil(chineseChars / 1.5 + otherChars / 4);
+}
+/**
+ * 估算消息列表的 Token 数
+ */
+export function estimateMessagesTokens(messages) {
+    let totalTokens = 0;
+    for (const msg of messages) {
+        // 基础开销（role、格式等）
+        totalTokens += 4;
+        // 内容 Token
+        if (msg.content) {
+            totalTokens += estimateTokenCount(msg.content);
+        }
+        // toolCalls 额外开销
+        if (msg.toolCalls) {
+            totalTokens += estimateTokenCount(JSON.stringify(msg.toolCalls));
+        }
+    }
+    return totalTokens;
+}
+/**
+ * 计算消息轮次数
+ *
+ * 一个 user + assistant 消息对算一轮。
+ */
+export function countRounds(messages) {
+    let rounds = 0;
+    for (const msg of messages) {
+        if (msg.role === 'user') {
+            rounds++;
+        }
+    }
+    return rounds;
+}