@cicctencent/agent-core 0.1.1 → 0.1.4

package/src/memory/extractor.ts

@@ -1,164 +0,0 @@
-// ============================================================
-// MemoryExtractor — LLM 驱动的原子事实提取器
-// ============================================================
-
-import type { LLMProvider } from '../llm/types.ts';
-import type { Message } from '../types.ts';
-import {
-  EXTRACTION_SYSTEM_PROMPT,
-  buildExtractionUserPrompt,
-} from './prompts.ts';
-
-/** 从对话中提取的原子事实 */
-export interface AtomFact {
-  /** 记忆键（snake_case，用于 upsert） */
-  key: string;
-  /** 事实内容 */
-  content: string;
-  /** 分类 */
-  category: 'user_preference' | 'project_knowledge' | 'learned_fact' | 'custom';
-  /** 重要程度 1-5 */
-  importance: number;
-  /** 来源会话 ID */
-  sourceSessionId: string;
-}
-
-/** 提取配置 */
-export interface ExtractorOptions {
-  /** LLM Provider 实例 */
-  llmProvider: LLMProvider;
-  /** 单次提取最大原子事实数，默认 5 */
-  maxFactsPerSession?: number;
-  /** 触发提取的最小迭代次数，默认 3 */
-  minIterations?: number;
-  /** 提取超时（毫秒），默认 30000 */
-  timeoutMs?: number;
-}
-
-/**
- * LLM 驱动的原子事实提取器
- * 从对话历史中提取持久性、可复用的结构化事实（L1 Atom）
- */
-export class MemoryExtractor {
-  private llmProvider: LLMProvider;
-  private maxFactsPerSession: number;
-  private minIterations: number;
-  private timeoutMs: number;
-
-  constructor(opts: ExtractorOptions) {
-    this.llmProvider = opts.llmProvider;
-    this.maxFactsPerSession = opts.maxFactsPerSession ?? 5;
-    this.minIterations = opts.minIterations ?? 3;
-    this.timeoutMs = opts.timeoutMs ?? 30000;
-  }
-
-  /**
-   * 从对话消息中提取原子事实
-   * @param messages 对话消息列表
-   * @param sessionId 当前会话 ID
-   * @param existingKeys 已有的记忆键（用于去重）
-   * @returns 提取到的原子事实数组
-   */
-  async extract(
-    messages: Message[],
-    sessionId: string,
-    existingKeys: string[],
-  ): Promise<AtomFact[]> {
-    // 构建对话摘要（避免超长对话）
-    const summary = this.buildMessagesSummary(messages);
-
-    const userPrompt = buildExtractionUserPrompt(summary, existingKeys);
-
-    try {
-      const result = await this.callLLM(userPrompt);
-      return this.parseFacts(result, sessionId);
-    } catch (err: any) {
-      console.warn(`[MemoryExtractor] Extraction failed: ${err?.message || err}`);
-      return [];
-    }
-  }
-
-  /**
-   * 调用 LLM 提取事实
-   */
-  private async callLLM(userPrompt: string): Promise<string> {
-    const messages: Message[] = [
-      { role: 'system', content: EXTRACTION_SYSTEM_PROMPT },
-      { role: 'user', content: userPrompt },
-    ];
-
-    const chunks: string[] = [];
-    const stream = this.llmProvider.chatStream({
-      messages,
-      abortSignal: AbortSignal.timeout(this.timeoutMs),
-    });
-
-    for await (const chunk of stream) {
-      if (chunk.delta.content) {
-        chunks.push(chunk.delta.content);
-      }
-    }
-
-    return chunks.join('');
-  }
-
-  /**
-   * 解析 LLM 输出的 JSON 数组
-   */
-  private parseFacts(raw: string, sessionId: string): AtomFact[] {
-    // 尝试提取 JSON 数组（LLM 可能输出额外文本）
-    const jsonMatch = raw.match(/\[[\s\S]*\]/);
-    if (!jsonMatch) return [];
-
-    try {
-      const parsed = JSON.parse(jsonMatch[0]);
-      if (!Array.isArray(parsed)) return [];
-
-      return parsed
-        .filter((item: any) => item.key && item.content)
-        .slice(0, this.maxFactsPerSession)
-        .map((item: any) => ({
-          key: String(item.key).replace(/[^a-z0-9_]/g, '_').toLowerCase(),
-          content: String(item.content),
-          category: this.normalizeCategory(item.category),
-          importance: Math.min(5, Math.max(1, Number(item.importance) || 3)),
-          sourceSessionId: sessionId,
-        }));
-    } catch {
-      console.warn('[MemoryExtractor] Failed to parse LLM output as JSON');
-      return [];
-    }
-  }
-
-  private normalizeCategory(cat: string): AtomFact['category'] {
-    const valid: AtomFact['category'][] = ['user_preference', 'project_knowledge', 'learned_fact', 'custom'];
-    return valid.includes(cat as AtomFact['category']) ? (cat as AtomFact['category']) : 'custom';
-  }
-
-  /**
-   * 构建对话摘要（将消息列表压缩为文本，限制总字符数）
-   */
-  private buildMessagesSummary(messages: Message[]): string {
-    const maxChars = 6000;
-    const lines: string[] = [];
-    let totalLen = 0;
-
-    for (const msg of messages) {
-      if (msg.role === 'system') continue;
-      const role = msg.role === 'user' ? 'USER' : msg.role === 'assistant' ? 'ASSISTANT' : 'TOOL';
-      const content = typeof msg.content === 'string'
-        ? msg.content.slice(0, 500)
-        : JSON.stringify(msg.content).slice(0, 500);
-      const line = `[${role}] ${content}`;
-
-      if (totalLen + line.length > maxChars) {
-        lines.push(`... (${messages.length - lines.length} more messages truncated)`);
-        break;
-      }
-      lines.push(line);
-      totalLen += line.length;
-    }
-
-    return lines.join('\n');
-  }
-}

package/src/memory/persona.ts

@@ -1,106 +0,0 @@
-// ============================================================
-// PersonaGenerator — L3 用户画像生成器
-// ============================================================
-// 基于 L2 场景块生成/增量更新用户画像（L3 Persona），
-// 画像以 markdown 格式存储，注入 prompt 时提供用户全貌
-
-import type { LLMProvider } from '../llm/types.ts';
-import type { Message } from '../types.ts';
-import { PERSONA_GENERATION_SYSTEM_PROMPT } from './prompts.ts';
-import type { SceneBlock } from './scene.ts';
-
-/** 画像维度 */
-export interface PersonaFacet {
-  /** 维度键（如 coding_style, tool_preference） */
-  key: string;
-  /** 维度内容（markdown） */
-  content: string;
-}
-
-/** 画像生成器配置 */
-export interface PersonaGeneratorOptions {
-  llmProvider: LLMProvider;
-  /** 超时（毫秒），默认 30000 */
-  timeoutMs?: number;
-}
-
-/**
- * L3 用户画像生成器
- *
- * 工作流程：
- * 1. 接收 L2 场景块列表
- * 2. 通过 LLM 从场景中提炼稳定用户特征
- * 3. 增量更新画像（保留已有内容，仅修改受影响的部分）
- */
-export class PersonaGenerator {
-  private llmProvider: LLMProvider;
-  private timeoutMs: number;
-
-  constructor(opts: PersonaGeneratorOptions) {
-    this.llmProvider = opts.llmProvider;
-    this.timeoutMs = opts.timeoutMs ?? 30000;
-  }
-
-  /**
-   * 生成或更新用户画像
-   * @param scenes L2 场景块列表
-   * @param existingPersona 已有画像（markdown 文本，用于增量更新）
-   * @returns 更新后的画像 markdown
-   */
-  async generate(
-    scenes: SceneBlock[],
-    existingPersona: string = '',
-  ): Promise<string> {
-    if (scenes.length === 0 && !existingPersona) return '';
-
-    const userPrompt = this.buildUserPrompt(scenes, existingPersona);
-
-    try {
-      return await this.callLLM(userPrompt);
-    } catch (err: any) {
-      console.warn(`[PersonaGenerator] Generation failed: ${err?.message || err}`);
-      return existingPersona;
-    }
-  }
-
-  private buildUserPrompt(scenes: SceneBlock[], existingPersona: string): string {
-    let prompt = '';
-
-    if (scenes.length > 0) {
-      const scenesText = scenes
-        .map(s => `### ${s.title}\n${s.description}\nAtoms: ${s.atomIds.length}`)
-        .join('\n\n');
-      prompt += `**Scenario blocks:**\n${scenesText}\n\n`;
-    }
-
-    if (existingPersona) {
-      prompt += `**Existing persona (update incrementally, preserve unaffected sections):**\n${existingPersona}\n\n`;
-      prompt += `Update the persona based on the new scenario blocks above. Preserve sections not affected by new data.`;
-    } else {
-      prompt += `Generate a user persona based on the scenario blocks above. Use markdown with clear section headers.`;
-    }
-
-    return prompt;
-  }
-
-  private async callLLM(userPrompt: string): Promise<string> {
-    const messages: Message[] = [
-      { role: 'system', content: PERSONA_GENERATION_SYSTEM_PROMPT },
-      { role: 'user', content: userPrompt },
-    ];
-
-    const chunks: string[] = [];
-    const stream = this.llmProvider.chatStream({
-      messages,
-      abortSignal: AbortSignal.timeout(this.timeoutMs),
-    });
-
-    for await (const chunk of stream) {
-      if (chunk.delta.content) {
-        chunks.push(chunk.delta.content);
-      }
-    }
-
-    return chunks.join('').trim();
-  }
-}

package/src/memory/pipeline.ts

@@ -1,192 +0,0 @@
-// ============================================================
-// MemoryPipeline — L1→L2→L3 记忆管道调度器
-// ============================================================
-// 调度记忆层级的渐进式提炼：
-//   L1 (原子事实) → L2 (场景聚合) → L3 (用户画像)
-// 在对话结束后 fire-and-forget 触发
-
-import type { LLMProvider } from '../llm/types.ts';
-import type { MemoryEntry, MemoryLayer, MemoryServiceLike } from './types.ts';
-import { MemoryExtractor } from './extractor.ts';
-import { SceneAggregator, type SceneBlock } from './scene.ts';
-import { PersonaGenerator } from './persona.ts';
-import { getMemoryCheckpoint } from './checkpoint.ts';
-import type { Message } from '../types.ts';
-
-/** 管道配置 */
-export interface PipelineOptions {
-  llmProvider: LLMProvider;
-  /** 触发 L2 聚合的 L1 增量阈值（新 L1 条目数），默认 5 */
-  l2Threshold?: number;
-  /** 触发 L3 画像更新的 L2 增量阈值，默认 3 */
-  l3Threshold?: number;
-}
-
-/** 管道执行结果 */
-export interface PipelineResult {
-  /** 本次提取的 L1 原子事实数 */
-  l1Extracted: number;
-  /** 是否触发了 L2 聚合 */
-  l2Triggered: boolean;
-  /** 是否触发了 L3 画像更新 */
-  l3Triggered: boolean;
-  /** 新的场景块（如果触发了 L2） */
-  newScenes?: SceneBlock[];
-  /** 更新的画像（如果触发了 L3） */
-  newPersona?: string;
-}
-
-/**
- * 记忆管道调度器
- *
- * 调度策略：
- * 1. 每次对话结束：提取 L1 原子事实
- * 2. L1 累积达到阈值：触发 L2 场景聚合
- * 3. L2 累积达到阈值：触发 L3 画像生成
- *
- * 所有操作均为 fire-and-forget，不阻塞对话响应
- */
-export class MemoryPipeline {
-  private llmProvider: LLMProvider;
-  private l2Threshold: number;
-  private l3Threshold: number;
-
-  constructor(opts: PipelineOptions) {
-    this.llmProvider = opts.llmProvider;
-    this.l2Threshold = opts.l2Threshold ?? 5;
-    this.l3Threshold = opts.l3Threshold ?? 3;
-  }
-
-  /**
-   * 执行完整管道（L1 提取 → 条件触发 L2 → 条件触发 L3）
-   *
-   * @param messages 对话消息
-   * @param sessionId 会话 ID
-   * @param memoryService MemoryService 实例（延迟导入避免循环依赖）
-   */
-  async run(
-    messages: Message[],
-    sessionId: string,
-    memoryService: MemoryServiceLike,
-  ): Promise<PipelineResult> {
-    const result: PipelineResult = {
-      l1Extracted: 0,
-      l2Triggered: false,
-      l3Triggered: false,
-    };
-
-    // === Phase 1: L1 提取 ===
-    const existingKeys = memoryService.getKeys();
-    const extractor = new MemoryExtractor({ llmProvider: this.llmProvider });
-    const facts = await extractor.extract(messages, sessionId, existingKeys);
-
-    // 写入 L1 条目
-    for (const fact of facts) {
-      memoryService.save(fact.key, fact.content, fact.category, fact.importance, {
-        memoryLayer: 'L1',
-        sourceSessionId: sessionId,
-        sourceTimestamp: new Date().toISOString(),
-      });
-    }
-    result.l1Extracted = facts.length;
-
-    if (facts.length === 0) return result;
-
-    console.log(`[Pipeline] L1: extracted ${facts.length} facts from session ${sessionId}`);
-
-    // === Phase 2: 条件触发 L2 聚合 ===
-    const l1Entries = memoryService.getAllEntries('L1');
-    const l1Count = l1Entries.length;
-    const checkpoint = getMemoryCheckpoint();
-
-    if (checkpoint.shouldTriggerL2(l1Count, this.l2Threshold)) {
-      try {
-        const existingL2 = memoryService.getAllEntries('L2');
-        const existingScenes: SceneBlock[] = existingL2.map(e => ({
-          sceneId: e.sceneId || e.key,
-          title: e.key,
-          description: e.content,
-          atomIds: e.sourceIds || [],
-        }));
-
-        const aggregator = new SceneAggregator({ llmProvider: this.llmProvider });
-        const atoms = l1Entries.map(e => ({
-          id: e.id,
-          key: e.key,
-          content: e.content,
-          category: e.category,
-        }));
-
-        const scenes = await aggregator.aggregate(atoms, existingScenes);
-        result.l2Triggered = true;
-        result.newScenes = scenes;
-
-        // 写入 L2 条目（upsert by sceneId）
-        for (const scene of scenes) {
-          memoryService.save(scene.sceneId, `${scene.title}\n${scene.description}`, 'scene', 4, {
-            memoryLayer: 'L2',
-            sceneId: scene.sceneId,
-            sourceLayer: 'L1',
-            sourceIds: scene.atomIds,
-          });
-        }
-
-        // 回填 L1 条目的 sceneId
-        for (const scene of scenes) {
-          for (const atomId of scene.atomIds) {
-            const entry = l1Entries.find(e => e.id === atomId);
-            if (entry && entry.sceneId !== scene.sceneId) {
-              memoryService.save(entry.key, entry.content, entry.category, entry.importance, {
-                memoryLayer: 'L1',
-                sceneId: scene.sceneId,
-              });
-            }
-          }
-        }
-
-        console.log(`[Pipeline] L2: aggregated ${scenes.length} scenes from ${l1Count} atoms`);
-
-        // 更新检查点
-        checkpoint.updateL2(l1Count);
-      } catch (err: any) {
-        console.warn(`[Pipeline] L2 aggregation failed:`, err?.message);
-      }
-    }
-
-    // === Phase 3: 条件触发 L3 画像 ===
-    const l2Entries = memoryService.getAllEntries('L2');
-    if (checkpoint.shouldTriggerL3(l2Entries.length, this.l3Threshold)) {
-      try {
-        const existingL3 = memoryService.getAllEntries('L3');
-        const existingPersona = existingL3.length > 0 ? existingL3[0].content : '';
-
-        const generator = new PersonaGenerator({ llmProvider: this.llmProvider });
-        const scenes: SceneBlock[] = l2Entries.map(e => ({
-          sceneId: e.sceneId || e.key,
-          title: e.key,
-          description: e.content,
-          atomIds: e.sourceIds || [],
-        }));
-
-        const persona = await generator.generate(scenes, existingPersona);
-        result.l3Triggered = true;
-        result.newPersona = persona;
-
-        if (persona) {
-          memoryService.save('user_persona', persona, 'persona', 5, {
-            memoryLayer: 'L3',
-            sourceLayer: 'L2',
-            sourceIds: l2Entries.map(e => e.id),
-          });
-          console.log(`[Pipeline] L3: persona updated (${persona.length} chars)`);
-          checkpoint.updateL3(l2Entries.length);
-        }
-      } catch (err: any) {
-        console.warn(`[Pipeline] L3 generation failed:`, err?.message);
-      }
-    }
-
-    return result;
-  }
-}
-

package/src/memory/recall.ts

@@ -1,217 +0,0 @@
-// ============================================================
-// MemoryRecallEngine — 智能记忆召回引擎（带超时保护）
-// ============================================================
-
-import type { MemoryEntry, MemoryLayer } from './types.ts';
-
-/** 召回结果 */
-export interface RecallResult {
-  /** 召回的记忆条目（按相关度排序） */
-  entries: ScoredMemoryEntry[];
-  /** 是否超时 */
-  timedOut: boolean;
-  /** 召回策略描述 */
-  strategy: string;
-}
-
-/** 带分数的记忆条目 */
-export interface ScoredMemoryEntry extends MemoryEntry {
-  /** 相关度分数 0-1 */
-  relevanceScore: number;
-}
-
-/** 召回配置 */
-export interface RecallOptions {
-  /** 最大返回条数，默认 5 */
-  maxResults?: number;
-  /** 召回超时（毫秒），默认 3000 */
-  timeoutMs?: number;
-  /** 仅召回指定层级 */
-  layers?: MemoryLayer[];
-}
-
-/**
- * 智能记忆召回引擎
- *
- * 召回策略（优先级排序）：
- * 1. 关键词匹配：userText 分词后与 key/content 做模糊匹配
- * 2. 重要性加权：importance 高的记忆权重更大
- * 3. 时效性衰减：近期更新的记忆优先（updatedAt 越新分数越高）
- *
- * 超时保护：超过 timeoutMs 立即返回空结果，不阻塞对话
- */
-export class MemoryRecallEngine {
-
-  /**
-   * 召回相关记忆（带超时保护）
-   */
-  async recall(
-    userText: string,
-    allMemories: MemoryEntry[],
-    options: RecallOptions = {},
-  ): Promise<RecallResult> {
-    const timeoutMs = options.timeoutMs ?? 3000;
-
-    return Promise.race([
-      this.recallInner(userText, allMemories, options),
-      new Promise<RecallResult>((resolve) =>
-        setTimeout(() => resolve({ entries: [], timedOut: true, strategy: 'timeout' }), timeoutMs),
-      ),
-    ]);
-  }
-
-  private async recallInner(
-    userText: string,
-    allMemories: MemoryEntry[],
-    options: RecallOptions,
-  ): Promise<RecallResult> {
-    const maxResults = options.maxResults ?? 5;
-    const layers = options.layers;
-
-    // 层级过滤
-    let candidates = layers
-      ? allMemories.filter(e => layers.includes(e.memoryLayer))
-      : allMemories;
-
-    if (candidates.length === 0) {
-      return { entries: [], timedOut: false, strategy: 'empty' };
-    }
-
-    // 提取查询关键词（简单分词：空格 + 标点切分，过滤短词）
-    const queryTerms = this.extractTerms(userText);
-
-    // 构建 IDF 映射表（TF-IDF 加权）
-    const idfMap = this.buildIDFMap(queryTerms, candidates);
-
-    // 对每条记忆计算分数
-    const scored: ScoredMemoryEntry[] = candidates.map(entry => {
-      const keywordScore = this.computeKeywordScore(entry, queryTerms, idfMap);
-      const importanceScore = (entry.importance || 3) / 5; // 0.2 ~ 1.0
-      const recencyScore = this.computeRecencyScore(entry.updatedAt); // 0.0 ~ 1.0
-
-      // 加权合成
-      const relevanceScore = keywordScore * 0.6 + importanceScore * 0.2 + recencyScore * 0.2;
-
-      return { ...entry, relevanceScore };
-    });
-
-    // 过滤低分（阈值 0.05）并排序
-    const filtered = scored
-      .filter(e => e.relevanceScore > 0.05)
-      .sort((a, b) => b.relevanceScore - a.relevanceScore)
-      .slice(0, maxResults);
-
-    return {
-      entries: filtered,
-      timedOut: false,
-      strategy: filtered.length > 0 ? 'keyword+importance+recency' : 'no_match',
-    };
-  }
-
-  /**
-   * 提取查询词项（简单分词）
-   * 支持中英文混合：英文按空格，中文按字
-   */
-  private extractTerms(text: string): string[] {
-    if (!text) return [];
-
-    // 英文：小写 + 按空格/标点切分
-    const englishTerms = text
-      .toLowerCase()
-      .split(/[\s,.!?;:，。！？；：]+/)
-      .filter(t => t.length >= 2);
-
-    // 中文：提取连续中文片段，再按 2-gram 切分
-    const chineseSegments = text.match(/[\u4e00-\u9fff]{2,}/g) || [];
-    const chineseTerms: string[] = [];
-    for (const seg of chineseSegments) {
-      for (let i = 0; i < seg.length - 1; i++) {
-        chineseTerms.push(seg.slice(i, i + 2));
-      }
-      if (seg.length >= 3) {
-        for (let i = 0; i < seg.length - 2; i++) {
-          chineseTerms.push(seg.slice(i, i + 3));
-        }
-      }
-    }
-
-    return [...new Set([...englishTerms, ...chineseTerms])];
-  }
-
-  /**
-   * 计算关键词匹配分数（TF-IDF 加权）
-   * 稀有词（出现在少量记忆中）获得更高权重，常见词权重降低
-   */
-  private computeKeywordScore(entry: MemoryEntry, terms: string[], idfMap?: Map<string, number>): number {
-    if (terms.length === 0) return 0;
-
-    const text = `${entry.key} ${entry.content} ${entry.category}`.toLowerCase();
-    let weightedScore = 0;
-    let totalWeight = 0;
-
-    for (const term of terms) {
-      if (text.includes(term.toLowerCase())) {
-        const idf = idfMap?.get(term) ?? 1.0;
-        weightedScore += idf;
-      }
-      totalWeight += idfMap?.get(term) ?? 1.0;
-    }
-
-    return totalWeight > 0 ? weightedScore / totalWeight : 0;
-  }
-
-  /**
-   * 构建 IDF 映射表：term → IDF 分数
-   * IDF = log(N / df)，N=总文档数，df=包含该 term 的文档数
-   */
-  private buildIDFMap(terms: string[], candidates: MemoryEntry[]): Map<string, number> {
-    const N = candidates.length;
-    if (N === 0) return new Map();
-
-    const df = new Map<string, number>();
-    for (const term of terms) {
-      let count = 0;
-      const lowerTerm = term.toLowerCase();
-      for (const entry of candidates) {
-        const text = `${entry.key} ${entry.content} ${entry.category}`.toLowerCase();
-        if (text.includes(lowerTerm)) count++;
-      }
-      df.set(term, count);
-    }
-
-    const idf = new Map<string, number>();
-    for (const [term, count] of df) {
-      // 加 1 平滑避免除零
-      idf.set(term, Math.log((N + 1) / (count + 1)) + 1);
-    }
-    return idf;
-  }
-
-  /**
-   * 计算时效性分数（0-1）
-   * 24 小时内的记忆得 1.0，30 天前的记忆得 ~0.1
-   */
-  private computeRecencyScore(updatedAt: string): number {
-    const age = Date.now() - new Date(updatedAt).getTime();
-    const dayMs = 24 * 60 * 60 * 1000;
-
-    if (age < dayMs) return 1.0;          // 24 小时内
-    if (age < 7 * dayMs) return 0.8;      // 7 天内
-    if (age < 30 * dayMs) return 0.5;     // 30 天内
-    return 0.2;                            // 超过 30 天
-  }
-}
-
-/**
- * 将召回结果格式化为可注入 system prompt 的文本
- */
-export function formatRecallForPrompt(result: RecallResult): string {
-  if (result.entries.length === 0) return '';
-
-  const lines = result.entries.map(e => {
-    const score = e.relevanceScore.toFixed(2);
-    return `- [${e.category}] ${e.key}: ${e.content}（相关度: ${score}）`;
-  });
-
-  return `## Long-term Memory (auto-recalled, ${result.entries.length} entries)\n${lines.join('\n')}`;
-}