@zhin.js/agent 0.0.0

package/lib/conversation-memory.d.ts

@@ -0,0 +1,181 @@
+/**
+ * ConversationMemory — 基于数据库的会话记忆（话题感知 + 链式摘要）
+ *
+ * 两张表分离存储：
+ *
+ *   ai_messages 表（逐条记录）：
+ *   ┌──────────────────────────────────────────────────────────┐
+ *   │ session_id | role      | content        | round | time   │
+ *   │ s1         | user      | 你好           | 1     | ...    │
+ *   │ s1         | assistant | 你好呀！       | 1     | ...    │
+ *   │ ...        | ...       | ...            | ...   | ...    │
+ *   └──────────────────────────────────────────────────────────┘
+ *
+ *   ai_summaries 表（链式摘要）：
+ *   ┌────────────────────────────────────────────────────────────────────┐
+ *   │ id | session_id | parent_id | from_round | to_round | summary     │
+ *   │ 1  | s1         | null      | 1          | 7        | 用户讨论了… │
+ *   │ 2  | s1         | 1         | 8          | 15       | 之前...又…  │
+ *   └────────────────────────────────────────────────────────────────────┘
+ *
+ * 摘要触发规则：
+ *   1. 检测到话题切换（当前消息与最近消息的关键词重合度低）
+ *   2. 且上一个话题持续 ≥ minTopicRounds 轮
+ *   → 异步生成摘要，覆盖上一话题的全部消息
+ *
+ * 上下文构建规则：
+ *   1. 取最新 summary + 最近 slidingWindowSize 轮消息（滑动窗口）
+ *   2. 检查连续性：summary.to_round === window第一条round - 1
+ *      → 连续：[summary] + [window]
+ *      → 不连续：丢弃 summary，仅用 [window]
+ */
+import type { AIProvider, ChatMessage } from '@zhin.js/core';
+/** ai_messages 表结构 */
+export declare const AI_MESSAGE_MODEL: {
+    session_id: {
+        type: "text";
+        nullable: boolean;
+    };
+    role: {
+        type: "text";
+        nullable: boolean;
+    };
+    content: {
+        type: "text";
+        nullable: boolean;
+    };
+    round: {
+        type: "integer";
+        nullable: boolean;
+    };
+    created_at: {
+        type: "integer";
+        default: number;
+    };
+};
+/** ai_summaries 表结构（链式） */
+export declare const AI_SUMMARY_MODEL: {
+    session_id: {
+        type: "text";
+        nullable: boolean;
+    };
+    parent_id: {
+        type: "integer";
+        nullable: boolean;
+    };
+    from_round: {
+        type: "integer";
+        nullable: boolean;
+    };
+    to_round: {
+        type: "integer";
+        nullable: boolean;
+    };
+    summary: {
+        type: "text";
+        nullable: boolean;
+    };
+    created_at: {
+        type: "integer";
+        default: number;
+    };
+};
+/**
+ * 数据库模型接口（与 RelatedModel 的链式查询 API 对齐）
+ *
+ * select(...fields) → Selection (thenable, 支持 .where().orderBy().limit())
+ * create(data) → Promise<any>
+ */
+interface DbModel {
+    select(...fields: string[]): any;
+    create(data: Record<string, any>): Promise<any>;
+}
+export interface ConversationMemoryConfig {
+    /** 一个话题至少持续多少轮才触发摘要（默认 5） */
+    minTopicRounds?: number;
+    /** 滑动窗口大小：最近 N 轮消息（默认 5） */
+    slidingWindowSize?: number;
+    /** 话题切换检测阈值（0-1，值越低越敏感，默认 0.15） */
+    topicChangeThreshold?: number;
+}
+export declare class ConversationMemory {
+    private store;
+    private provider;
+    private config;
+    private summarizing;
+    /** per-session 话题跟踪 */
+    private topicStates;
+    /** per-session 轮次缓存（避免每次查数据库） */
+    private roundCache;
+    constructor(config?: ConversationMemoryConfig);
+    setProvider(provider: AIProvider): void;
+    upgradeToDatabase(msgModel: DbModel, sumModel: DbModel): void;
+    /**
+     * 保存一轮对话，并检测话题切换来触发摘要
+     */
+    saveRound(sessionId: string, userContent: string, assistantContent: string): Promise<void>;
+    /**
+     * 话题检测流程（全程异步，不阻塞对话）：
+     *
+     *   1. 短消息（token ≤ 3）→ 跳过检测，视为延续话题
+     *   2. Jaccard 快检 → 高相似(≥ 0.5) → 肯定同话题，跳过 LLM
+     *   3. Jaccard 不确定(< 0.5) → 调 LLM 裁决
+     *   4. LLM 判定切换 + 旧话题 ≥ minTopicRounds → 触发摘要
+     */
+    private handleTopicAndSummary;
+    /** 更新话题状态（同话题情况） */
+    private updateTopicState;
+    /**
+     * 调用 LLM 判断话题是否切换
+     *
+     * 输入: 最近几条用户消息 + 当前用户消息
+     * 输出: true = 话题切换, false = 同话题
+     */
+    private detectTopicChangeByLLM;
+    /**
+     * 异步生成链式摘要（不阻塞对话）
+     */
+    private generateSummaryAsync;
+    /**
+     * 构建 LLM 上下文消息列表
+     *
+     * 规则：
+     *   1. 取滑动窗口（最近 slidingWindowSize 轮）
+     *   2. 取最新 summary
+     *   3. 检查连续性：summary.to_round === window第一轮 - 1
+     *      → 连续：[summary] + [window 消息]
+     *      → 不连续：仅 [window 消息]
+     */
+    buildContext(sessionId: string): Promise<ChatMessage[]>;
+    private callLLMSummarize;
+    searchMessages(sessionId: string, keyword: string, limit?: number): Promise<{
+        round: number;
+        role: string;
+        content: string;
+        time: number;
+    }[]>;
+    getMessagesByRound(sessionId: string, fromRound: number, toRound: number): Promise<{
+        round: number;
+        role: string;
+        content: string;
+        time: number;
+    }[]>;
+    getCurrentRound(sessionId: string): Promise<number>;
+    traceByKeyword(sessionId: string, keyword: string, limit?: number): Promise<{
+        summary: {
+            id: number;
+            fromRound: number;
+            toRound: number;
+            summary: string;
+        } | null;
+        messages: {
+            round: number;
+            role: string;
+            content: string;
+            time: number;
+        }[];
+    }>;
+    dispose(): void;
+}
+export {};
+//# sourceMappingURL=conversation-memory.d.ts.map

package/lib/conversation-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-memory.d.ts","sourceRoot":"","sources":["../src/conversation-memory.ts"],"names":[],"mappings":"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"}