@gt-fe/eap-runtime 0.0.8

package/dist/memory/pg-memory.repository.d.ts

@@ -0,0 +1,44 @@
+/**
+ * PostgresMemoryRepository — Memory 持久化 PostgreSQL 实现
+ *
+ * 基于 pg 连接池实现 IMemoryRepository 接口。
+ * 支持审计字段和软删除。
+ *
+ * @see design.md §1.3 memories 表
+ */
+import type { MemoryRecord, IMemoryRepository } from './long-term-memory.service.js';
+/** pg Pool 抽象接口 */
+export interface IPgPool {
+    query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+}
+export declare class PostgresMemoryRepository implements IMemoryRepository {
+    private readonly pool;
+    constructor(pool: IPgPool);
+    /**
+     * INSERT memory record with audit fields
+     */
+    save(record: MemoryRecord): Promise<void>;
+    /**
+     * SELECT memories by user_id and agent_id
+     * Excludes soft-deleted records
+     */
+    findByUserAndAgent(userId: string, agentCode: string, limit?: number): Promise<MemoryRecord[]>;
+    /**
+     * Soft delete memory (implements IMemoryRepository.delete)
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Soft delete memory with audit
+     */
+    softDelete(id: string, deletedBy: string): Promise<void>;
+    /**
+     * UPDATE memory record
+     */
+    update(record: MemoryRecord): Promise<void>;
+    /**
+     * 将 PostgreSQL 行数据转换为 MemoryRecord
+     */
+    private rowToRecord;
+}

package/dist/memory/pg-memory.repository.js

@@ -0,0 +1,108 @@
+/**
+ * PostgresMemoryRepository — Memory 持久化 PostgreSQL 实现
+ *
+ * 基于 pg 连接池实现 IMemoryRepository 接口。
+ * 支持审计字段和软删除。
+ *
+ * @see design.md §1.3 memories 表
+ */
+// ─────────────────────────────────────────────
+// PostgresMemoryRepository
+// ─────────────────────────────────────────────
+export class PostgresMemoryRepository {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    /**
+     * INSERT memory record with audit fields
+     */
+    async save(record) {
+        const sql = `
+      INSERT INTO memories (id, user_id, agent_id, type, content, relevance_score, created_by, created_at, updated_by, updated_at)
+      VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+    `;
+        await this.pool.query(sql, [
+            record.id,
+            record.userId,
+            record.agentCode,
+            record.type,
+            record.content,
+            record.relevanceScore,
+            record.createdBy || 'system',
+            record.createdAt,
+            record.updatedBy || 'system',
+            record.updatedAt,
+        ]);
+    }
+    /**
+     * SELECT memories by user_id and agent_id
+     * Excludes soft-deleted records
+     */
+    async findByUserAndAgent(userId, agentCode, limit) {
+        const sql = limit !== undefined
+            ? `SELECT * FROM memories WHERE user_id = $1 AND agent_id = $2 AND is_deleted = FALSE ORDER BY relevance_score DESC LIMIT $3`
+            : `SELECT * FROM memories WHERE user_id = $1 AND agent_id = $2 AND is_deleted = FALSE ORDER BY relevance_score DESC`;
+        const params = limit !== undefined ? [userId, agentCode, limit] : [userId, agentCode];
+        const { rows } = await this.pool.query(sql, params);
+        return rows.map((row) => this.rowToRecord(row));
+    }
+    /**
+     * Soft delete memory (implements IMemoryRepository.delete)
+     */
+    async delete(id) {
+        await this.softDelete(id, 'system');
+    }
+    /**
+     * Soft delete memory with audit
+     */
+    async softDelete(id, deletedBy) {
+        const sql = `
+      UPDATE memories
+      SET is_deleted = TRUE, deleted_by = $1, deleted_at = NOW()
+      WHERE id = $2 AND is_deleted = FALSE
+    `;
+        await this.pool.query(sql, [deletedBy, id]);
+    }
+    /**
+     * UPDATE memory record
+     */
+    async update(record) {
+        const sql = `
+      UPDATE memories
+      SET content = $1, relevance_score = $2, type = $3, updated_by = $4, updated_at = $5
+      WHERE id = $6 AND is_deleted = FALSE
+    `;
+        await this.pool.query(sql, [
+            record.content,
+            record.relevanceScore,
+            record.type,
+            record.updatedBy || 'system',
+            record.updatedAt,
+            record.id,
+        ]);
+    }
+    // ─────────────────────────────────────────────
+    // Private Helpers
+    // ─────────────────────────────────────────────
+    /**
+     * 将 PostgreSQL 行数据转换为 MemoryRecord
+     */
+    rowToRecord(row) {
+        return {
+            id: row.id,
+            userId: row.user_id,
+            agentCode: row.agent_id,
+            type: row.type,
+            content: row.content,
+            relevanceScore: row.relevance_score,
+            createdBy: row.created_by,
+            createdAt: row.created_at.toISOString(),
+            updatedBy: row.updated_by,
+            updatedAt: row.updated_at.toISOString(),
+            isDeleted: row.is_deleted,
+            deletedBy: row.deleted_by,
+            deletedAt: row.deleted_at?.toISOString(),
+        };
+    }
+}

package/dist/memory/semantic-retrieval.service.d.ts

@@ -0,0 +1,148 @@
+/**
+ * SemanticRetrievalService — 语义检索服务
+ *
+ * 提供基于语义相似度的记忆检索能力。
+ * 支持多种检索策略：
+ * - 关键词匹配（简单）
+ * - 向量相似度（需外部向量数据库）
+ * - 混合检索（关键词 + 向量）
+ *
+ * @see long-term-memory.service.ts 记忆管理
+ * @see requirements.md Requirement 4.4
+ */
+import type { MemoryRecord } from './long-term-memory.service.js';
+/**
+ * 检索策略类型
+ */
+export type RetrievalStrategy = 'keyword' | 'vector' | 'hybrid';
+/**
+ * 检索配置
+ */
+export interface RetrievalConfig {
+    /** 检索策略（默认 keyword） */
+    strategy: RetrievalStrategy;
+    /** 返回结果数量上限（默认 10） */
+    limit: number;
+    /** 相似度阈值（默认 0.7，仅 vector/hybrid 策略） */
+    similarityThreshold: number;
+    /** 关键词权重（hybrid 策略，默认 0.3） */
+    keywordWeight: number;
+    /** 向量权重（hybrid 策略，默认 0.7） */
+    vectorWeight: number;
+}
+/**
+ * 默认检索配置
+ */
+export declare const DEFAULT_RETRIEVAL_CONFIG: RetrievalConfig;
+/**
+ * 检索结果项
+ */
+export interface RetrievalResult {
+    /** 记忆记录 */
+    record: MemoryRecord;
+    /** 相似度分数（0-1） */
+    score: number;
+    /** 匹配的关键词（keyword 策略） */
+    matchedKeywords?: string[];
+}
+/**
+ * 向量存储接口
+ *
+ * 由外部注入，支持不同的向量数据库实现。
+ */
+export interface IVectorStore {
+    /**
+     * 存储向量
+     *
+     * @param id - 记录 ID
+     * @param vector - 向量
+     * @param metadata - 元数据
+     */
+    upsert(id: string, vector: number[], metadata?: Record<string, unknown>): Promise<void>;
+    /**
+     * 查询相似向量
+     *
+     * @param queryVector - 查询向量
+     * @param limit - 返回数量
+     * @param threshold - 相似度阈值
+     * @returns 相似向量列表
+     */
+    query(queryVector: number[], limit: number, threshold?: number): Promise<VectorResult[]>;
+    /**
+     * 删除向量
+     *
+     * @param id - 记录 ID
+     */
+    delete(id: string): Promise<void>;
+}
+/**
+ * 向量查询结果
+ */
+export interface VectorResult {
+    /** 记录 ID */
+    id: string;
+    /** 相似度分数 */
+    score: number;
+    /** 元数据 */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Embedding 函数接口
+ *
+ * 将文本转换为向量。
+ */
+export type EmbeddingFunction = (text: string) => Promise<number[]>;
+/**
+ * SemanticRetrievalService — 语义检索服务实现
+ */
+export declare class SemanticRetrievalService {
+    private readonly config;
+    private readonly vectorStore?;
+    private readonly embedding;
+    constructor(config?: Partial<RetrievalConfig>, vectorStore?: IVectorStore, embedding?: EmbeddingFunction);
+    /**
+     * 检索相关记忆
+     *
+     * @param query - 查询文本
+     * @param memories - 候选记忆列表
+     * @returns 检索结果
+     */
+    retrieve(query: string, memories: MemoryRecord[]): Promise<RetrievalResult[]>;
+    /**
+     * 关键词检索
+     *
+     * 基于关键词匹配的简单检索。
+     */
+    private keywordRetrieve;
+    /**
+     * 向量检索
+     *
+     * 基于向量相似度的检索。
+     */
+    private vectorRetrieve;
+    /**
+     * 混合检索
+     *
+     * 结合关键词和向量的混合检索。
+     */
+    private hybridRetrieve;
+    /**
+     * 提取关键词
+     *
+     * 简单的关键词提取（基于空格分割 + 停用词过滤）。
+     */
+    private extractKeywords;
+}
+/**
+ * InMemoryVectorStore — 内存向量存储（测试用）
+ */
+export declare class InMemoryVectorStore implements IVectorStore {
+    private readonly store;
+    upsert(id: string, vector: number[], metadata?: Record<string, unknown>): Promise<void>;
+    query(queryVector: number[], limit: number, threshold?: number): Promise<VectorResult[]>;
+    delete(id: string): Promise<void>;
+    /**
+     * 计算余弦相似度
+     */
+    private cosineSimilarity;
+}

package/dist/memory/semantic-retrieval.service.js

@@ -0,0 +1,238 @@
+/**
+ * SemanticRetrievalService — 语义检索服务
+ *
+ * 提供基于语义相似度的记忆检索能力。
+ * 支持多种检索策略：
+ * - 关键词匹配（简单）
+ * - 向量相似度（需外部向量数据库）
+ * - 混合检索（关键词 + 向量）
+ *
+ * @see long-term-memory.service.ts 记忆管理
+ * @see requirements.md Requirement 4.4
+ */
+/**
+ * 默认检索配置
+ */
+export const DEFAULT_RETRIEVAL_CONFIG = {
+    strategy: 'keyword',
+    limit: 10,
+    similarityThreshold: 0.7,
+    keywordWeight: 0.3,
+    vectorWeight: 0.7,
+};
+/**
+ * 默认 Embedding 函数（占位）
+ *
+ * 实际使用时应注入真实的 Embedding 函数（如 OpenAI Embedding）。
+ */
+async function defaultEmbedding(text) {
+    // 简单的哈希向量（占位，实际应使用真实的 Embedding 模型）
+    const vector = new Array(128).fill(0);
+    for (let i = 0; i < text.length; i++) {
+        vector[i % 128] += text.charCodeAt(i) / 1000;
+    }
+    // 归一化
+    const norm = Math.sqrt(vector.reduce((sum, v) => sum + v * v, 0));
+    return vector.map((v) => v / norm);
+}
+// ─────────────────────────────────────────────
+// 语义检索服务
+// ─────────────────────────────────────────────
+/**
+ * SemanticRetrievalService — 语义检索服务实现
+ */
+export class SemanticRetrievalService {
+    config;
+    vectorStore;
+    embedding;
+    constructor(config, vectorStore, embedding) {
+        this.config = { ...DEFAULT_RETRIEVAL_CONFIG, ...config };
+        this.vectorStore = vectorStore;
+        this.embedding = embedding ?? defaultEmbedding;
+    }
+    /**
+     * 检索相关记忆
+     *
+     * @param query - 查询文本
+     * @param memories - 候选记忆列表
+     * @returns 检索结果
+     */
+    async retrieve(query, memories) {
+        switch (this.config.strategy) {
+            case 'keyword':
+                return this.keywordRetrieve(query, memories);
+            case 'vector':
+                return this.vectorRetrieve(query, memories);
+            case 'hybrid':
+                return this.hybridRetrieve(query, memories);
+            default:
+                return this.keywordRetrieve(query, memories);
+        }
+    }
+    /**
+     * 关键词检索
+     *
+     * 基于关键词匹配的简单检索。
+     */
+    async keywordRetrieve(query, memories) {
+        const keywords = this.extractKeywords(query);
+        const results = [];
+        for (const memory of memories) {
+            const content = memory.content.toLowerCase();
+            const matchedKeywords = [];
+            let matchCount = 0;
+            for (const keyword of keywords) {
+                if (content.includes(keyword.toLowerCase())) {
+                    matchedKeywords.push(keyword);
+                    matchCount++;
+                }
+            }
+            if (matchCount > 0) {
+                const score = matchCount / keywords.length;
+                results.push({
+                    record: memory,
+                    score,
+                    matchedKeywords,
+                });
+            }
+        }
+        // 按分数降序排序
+        results.sort((a, b) => b.score - a.score);
+        return results.slice(0, this.config.limit);
+    }
+    /**
+     * 向量检索
+     *
+     * 基于向量相似度的检索。
+     */
+    async vectorRetrieve(query, memories) {
+        if (!this.vectorStore) {
+            // 如果没有向量存储，回退到关键词检索
+            return this.keywordRetrieve(query, memories);
+        }
+        // 生成查询向量
+        const queryVector = await this.embedding(query);
+        // 查询相似向量
+        const vectorResults = await this.vectorStore.query(queryVector, this.config.limit, this.config.similarityThreshold);
+        // 映射到记忆记录
+        const results = [];
+        for (const vectorResult of vectorResults) {
+            const memory = memories.find((m) => m.id === vectorResult.id);
+            if (memory) {
+                results.push({
+                    record: memory,
+                    score: vectorResult.score,
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * 混合检索
+     *
+     * 结合关键词和向量的混合检索。
+     */
+    async hybridRetrieve(query, memories) {
+        // 关键词检索结果
+        const keywordResults = await this.keywordRetrieve(query, memories);
+        // 向量检索结果
+        const vectorResults = await this.vectorRetrieve(query, memories);
+        // 合并结果
+        const mergedResults = new Map();
+        // 添加关键词结果
+        for (const result of keywordResults) {
+            mergedResults.set(result.record.id, {
+                ...result,
+                score: result.score * this.config.keywordWeight,
+            });
+        }
+        // 添加/合并向量结果
+        for (const result of vectorResults) {
+            const existing = mergedResults.get(result.record.id);
+            if (existing) {
+                // 合并分数
+                existing.score += result.score * this.config.vectorWeight;
+            }
+            else {
+                mergedResults.set(result.record.id, {
+                    ...result,
+                    score: result.score * this.config.vectorWeight,
+                });
+            }
+        }
+        // 转换为数组并排序
+        const results = Array.from(mergedResults.values());
+        results.sort((a, b) => b.score - a.score);
+        return results.slice(0, this.config.limit);
+    }
+    /**
+     * 提取关键词
+     *
+     * 简单的关键词提取（基于空格分割 + 停用词过滤）。
+     */
+    extractKeywords(text) {
+        // 停用词列表
+        const stopWords = new Set([
+            '的', '了', '是', '在', '我', '有', '和', '就', '不', '人', '都', '一', '一个',
+            '上', '也', '很', '到', '说', '要', '去', '你', '会', '着', '没有', '看', '好',
+            'the', 'a', 'an', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+            'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'could',
+            'should', 'may', 'might', 'can', 'shall', 'to', 'of', 'in', 'for',
+            'on', 'with', 'at', 'by', 'from', 'as', 'into', 'through', 'during',
+            'before', 'after', 'above', 'below', 'between', 'out', 'off', 'over',
+            'under', 'again', 'further', 'then', 'once',
+        ]);
+        // 分词（简单按空格和标点分割）
+        const words = text
+            .toLowerCase()
+            .replace(/[^\w\u4e00-\u9fff]/g, ' ')
+            .split(/\s+/)
+            .filter((word) => word.length > 1 && !stopWords.has(word));
+        return [...new Set(words)];
+    }
+}
+// ─────────────────────────────────────────────
+// In-Memory 向量存储（测试用）
+// ─────────────────────────────────────────────
+/**
+ * InMemoryVectorStore — 内存向量存储（测试用）
+ */
+export class InMemoryVectorStore {
+    store = new Map();
+    async upsert(id, vector, metadata) {
+        this.store.set(id, { vector, metadata });
+    }
+    async query(queryVector, limit, threshold) {
+        const results = [];
+        for (const [id, { vector }] of this.store) {
+            const score = this.cosineSimilarity(queryVector, vector);
+            if (!threshold || score >= threshold) {
+                results.push({ id, score });
+            }
+        }
+        // 按分数降序排序
+        results.sort((a, b) => b.score - a.score);
+        return results.slice(0, limit);
+    }
+    async delete(id) {
+        this.store.delete(id);
+    }
+    /**
+     * 计算余弦相似度
+     */
+    cosineSimilarity(a, b) {
+        if (a.length !== b.length)
+            return 0;
+        let dotProduct = 0;
+        let normA = 0;
+        let normB = 0;
+        for (let i = 0; i < a.length; i++) {
+            dotProduct += a[i] * b[i];
+            normA += a[i] * a[i];
+            normB += b[i] * b[i];
+        }
+        if (normA === 0 || normB === 0)
+            return 0;
+        return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+    }
+}

package/dist/providers/echo-llm-provider.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Echo LLM Provider — 开发/测试用，将用户最后一条消息回显为 assistant 回复
+ */
+import type { GraphMessage } from '../graph/contracts/executable-graph.js';
+import type { ILLMProvider, LLMNodeConfig, LLMResponse, LLMChunk } from '../graph/nodes/llm-node.js';
+export declare class EchoLLMProvider implements ILLMProvider {
+    invoke(messages: GraphMessage[], config: LLMNodeConfig): Promise<LLMResponse>;
+    stream(messages: GraphMessage[], config: LLMNodeConfig): AsyncIterableIterator<LLMChunk>;
+}
+export declare function createDefaultLLMProvider(): ILLMProvider;

package/dist/providers/echo-llm-provider.js

@@ -0,0 +1,87 @@
+/**
+ * Echo LLM Provider — 开发/测试用，将用户最后一条消息回显为 assistant 回复
+ */
+/**
+ * 解析 `call:<toolName> [args-json | 任意字符串]` 触发语法：
+ * - `call:echo-tool` → `{ name: 'echo-tool', arguments: {} }`
+ * - `call:echo-tool {"text":"hi"}` → arguments 使用解析后的 JSON
+ * - `call:echo-tool hi` → arguments 兜底为 `{ text: 'hi' }`
+ *
+ * 仅用于本地闭环 (`EAP_TOOL_EXECUTION_MODE=mock`) 下驱动 ToolNode，
+ * 让开发者无需接入真实 LLM 即可完成 tool 调用链路验证。
+ */
+function parseSyntheticToolCall(content) {
+    if (!content)
+        return null;
+    const match = content.match(/^\s*call:([^\s]+)\s*(.*)$/);
+    if (!match)
+        return null;
+    const [, name, tail] = match;
+    const trimmed = tail?.trim() ?? '';
+    let args = {};
+    if (trimmed) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            args = typeof parsed === 'object' && parsed !== null ? parsed : { text: trimmed };
+        }
+        catch {
+            args = { text: trimmed };
+        }
+    }
+    return {
+        id: `call-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+        name,
+        arguments: args,
+    };
+}
+export class EchoLLMProvider {
+    async invoke(messages, config) {
+        const lastUser = [...messages].reverse().find((m) => m.role === 'user');
+        const syntheticToolCall = parseSyntheticToolCall(lastUser?.content);
+        const content = syntheticToolCall
+            ? `[echo:${config.model ?? 'default'}] dispatching tool ${syntheticToolCall.name}`
+            : lastUser?.content
+                ? `[echo:${config.model ?? 'default'}] ${lastUser.content}`
+                : '[echo] Hello from EAP runtime';
+        const inputText = messages.map((m) => m.content).join(' ');
+        const inputTokens = Math.ceil(inputText.length / 4);
+        const outputTokens = Math.ceil(content.length / 4);
+        return {
+            content,
+            toolCalls: syntheticToolCall ? [syntheticToolCall] : undefined,
+            inputTokens,
+            outputTokens,
+            model: config.model ?? 'echo',
+        };
+    }
+    async *stream(messages, config) {
+        const response = await this.invoke(messages, config);
+        const words = response.content.split(' ');
+        for (let i = 0; i < words.length; i++) {
+            const isEnd = i === words.length - 1;
+            yield {
+                content: (i === 0 ? '' : ' ') + words[i],
+                isEnd,
+                inputTokens: isEnd ? response.inputTokens : undefined,
+                outputTokens: isEnd ? response.outputTokens : undefined,
+                toolCalls: isEnd ? response.toolCalls : undefined,
+            };
+        }
+    }
+}
+/**
+ * 根据环境变量创建 LLM Provider
+ * - OPENAI_API_KEY 存在 → HttpLLMProvider
+ * - 否则 → EchoLLMProvider
+ */
+import { HttpLLMProvider } from './http-llm-provider.js';
+export function createDefaultLLMProvider() {
+    if (process.env.OPENAI_API_KEY) {
+        return new HttpLLMProvider({
+            apiKey: process.env.OPENAI_API_KEY,
+            baseUrl: process.env.OPENAI_BASE_URL ?? 'https://api.openai.com/v1',
+            defaultModel: process.env.EAP_DEFAULT_MODEL ?? 'DeepSeek-V4-Pro',
+        });
+    }
+    return new EchoLLMProvider();
+}

package/dist/providers/http-llm-provider.d.ts

@@ -0,0 +1,35 @@
+/**
+ * HTTP LLM Provider — OpenAI 兼容 API
+ *
+ * 支持：
+ * - 真流式输出（stream: true + SSE chunk 解析）
+ * - function calling（tools / tool_choice 参数）
+ * - tool_calls 解析（同步 & 流式）
+ */
+import type { GraphMessage } from '../graph/contracts/executable-graph.js';
+import type { ILLMProvider, LLMNodeConfig, LLMResponse, LLMChunk } from '../graph/nodes/llm-node.js';
+export interface HttpLLMProviderConfig {
+    apiKey: string;
+    baseUrl?: string;
+    defaultModel?: string;
+    timeoutMs?: number;
+}
+export declare class HttpLLMProvider implements ILLMProvider {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly defaultModel;
+    private readonly timeoutMs;
+    constructor(config: HttpLLMProviderConfig);
+    invoke(messages: GraphMessage[], config: LLMNodeConfig): Promise<LLMResponse>;
+    stream(messages: GraphMessage[], config: LLMNodeConfig): AsyncIterableIterator<LLMChunk>;
+    private buildRequestBody;
+    /**
+     * 解析同步响应中的 tool_calls
+     */
+    private parseToolCalls;
+    /**
+     * 将流式累积的 tool_calls 转换为最终结果
+     */
+    private finalizeToolCalls;
+    private formatNetworkError;
+}