@zooique/memora 2.0.3 → 3.0.1

package/dist/memory/roundStore.js

@@ -0,0 +1,116 @@
+/**
+ * 问答闭环（Round）存储接口 —— Memora 会话管理的 SSOT
+ *
+ * 设计理念：
+ * - 问答闭环（Round）是独立的、全局唯一的实体
+ * - 会话（Session）只是问答闭环 ID 的有序列表
+ * - 分叉只是复制 ID 列表（指针复制），不复制数据
+ *
+ * 核心优势：
+ * 1. 保持记忆系统的真理源设定（每个 roundId 对应唯一摘要）
+ * 2. 保持会话的独立性（所有会话在存储层平等）
+ * 3. 简洁的分叉实现（只需操作 ID 列表）
+ */
+/**
+ * 轮是否「已收场」（终态）——**判据单一收口点（SSOT）**。
+ *
+ * - `complete`：正常问答闭环完成（appendAssistant 收场）。
+ * - `interrupted`：中断/失败收场（appendInterrupted 收场）。语义定案——中断轮 = 等同用户点「停止」的
+ *   正常 turn：**可删、入会话 roundIds、作后续上下文**，不是半成品草稿/孤儿。
+ *
+ * **为什么必须收口**：v3.0.0 把中断轮从「伪 complete」改为 `interrupted` 后，凡以
+ * `status === 'complete'` 判「该轮是否已闭合」的读取方都会被静默改行为——中断轮的
+ * assistantMessage 会被排除出会话视图与 LLM 历史（`ISessionStore.loadMessages` 是
+ * `restoreHistory` 的唯一上游），违背上述定案。故凡「是否计入会话视图 / LLM 历史」
+ * 「是否已登记会话引用」的判据**一律调用本函数**，禁止各处自写 `status === 'complete'`。
+ *
+ * ⚠️ **勿与渲染分流混用**：`status === 'interrupted'` 只用于「中断轮独立平铺渲染 + 中断标记」，
+ * 回答的是「怎么画」，不是「是否已收场」。两者常在同一函数相邻出现，勿互替。
+ *
+ * @param status - 轮状态
+ * @returns 该轮是否已进入终态（可作后续上下文）
+ */
+export function isRoundSettled(status) {
+    return status === 'complete' || status === 'interrupted';
+}
+// ─── 辅助函数 ───────────────────────────────────────────
+/**
+ * 生成 Round ID（格式：round-{uuid}）
+ *
+ * 使用 crypto.randomUUID() 保证全局唯一性
+ */
+export function generateRoundId() {
+    // 使用 crypto.randomUUID()（Node.js 19+ / 现代浏览器支持）
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+        return `round-${crypto.randomUUID()}`;
+    }
+    // 降级方案：时间戳 + 随机数
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).slice(2, 10);
+    return `round-${timestamp}${random}`;
+}
+/**
+ * 生成消息 ID（格式：msg-{uuid}）
+ */
+export function generateMessageId() {
+    if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+        return `msg-${crypto.randomUUID()}`;
+    }
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).slice(2, 10);
+    return `msg-${timestamp}${random}`;
+}
+/**
+ * 创建 pending 状态的 Round
+ *
+ * 辅助函数：快速创建新问答闭环的骨架
+ *
+ * @param userMessage - 用户消息内容
+ * @returns 新创建的 pending Round
+ */
+export function createPendingRound(userMessage) {
+    const id = generateRoundId();
+    const now = new Date().toISOString();
+    return {
+        id,
+        userMessage: {
+            id: generateMessageId(),
+            role: 'user',
+            content: userMessage,
+            timestamp: now,
+        },
+        status: 'pending',
+        createdAt: now,
+        refCount: 1,
+    };
+}
+/**
+ * 完成 Round（设置 AI 消息）
+ *
+ * 辅助函数：将 pending Round 转换为 complete 状态
+ *
+ * ⚠️ 注意：本函数**不设置任何摘要关联字段**——摘要记忆的 ID 由 roundSummaryGenerator
+ * 按 `round-summary:{sessionName}:{roundId}` 独立构造并按 roundId 溯源，
+ * Round 侧不持有反向指针（GC 清理走 roundId 派生寻址，见 gcService）。
+ *
+ * @param round - 要完成的 Round（必须是 pending 状态）
+ * @param assistantContent - AI 回复内容
+ * @param tokenUsage - Token 用量统计
+ * @returns 更新后的 complete Round
+ */
+export function completeRound(round, assistantContent, tokenUsage) {
+    const now = new Date().toISOString();
+    return {
+        ...round,
+        assistantMessage: {
+            id: generateMessageId(),
+            role: 'assistant',
+            content: assistantContent,
+            timestamp: now,
+            tokenUsage,
+        },
+        status: 'complete',
+        completedAt: now,
+    };
+}
+//# sourceMappingURL=roundStore.js.map

package/dist/memory/roundStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roundStore.js","sourceRoot":"","sources":["../../src/memory/roundStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA6GH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,cAAc,CAAC,MAAmB;IAChD,OAAO,MAAM,KAAK,UAAU,IAAI,MAAM,KAAK,aAAa,CAAC;AAC3D,CAAC;AAicD,uDAAuD;AAEvD;;;;GAIG;AACH,MAAM,UAAU,eAAe;IAC7B,gDAAgD;IAChD,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACvD,OAAO,SAAS,MAAM,CAAC,UAAU,EAAE,EAAE,CAAC;IACxC,CAAC;IACD,iBAAiB;IACjB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACvD,OAAO,SAAS,SAAS,GAAG,MAAM,EAAE,CAAC;AACvC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB;IAC/B,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACvD,OAAO,OAAO,MAAM,CAAC,UAAU,EAAE,EAAE,CAAC;IACtC,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACvD,OAAO,OAAO,SAAS,GAAG,MAAM,EAAE,CAAC;AACrC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAAmB;IACpD,MAAM,EAAE,GAAG,eAAe,EAAE,CAAC;IAC7B,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAErC,OAAO;QACL,EAAE;QACF,WAAW,EAAE;YACX,EAAE,EAAE,iBAAiB,EAAE;YACvB,IAAI,EAAE,MAAM;YACZ,OAAO,EAAE,WAAW;YACpB,SAAS,EAAE,GAAG;SACf;QACD,MAAM,EAAE,SAAS;QACjB,SAAS,EAAE,GAAG;QACd,QAAQ,EAAE,CAAC;KACZ,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAY,EACZ,gBAAwB,EACxB,UAA8C;IAE9C,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAErC,OAAO;QACL,GAAG,KAAK;QACR,gBAAgB,EAAE;YAChB,EAAE,EAAE,iBAAiB,EAAE;YACvB,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,gBAAgB;YACzB,SAAS,EAAE,GAAG;YACd,UAAU;SACX;QACD,MAAM,EAAE,UAAU;QAClB,WAAW,EAAE,GAAG;KACjB,CAAC;AACJ,CAAC"}

package/dist/memory/sessionStore.d.ts

@@ -1,84 +1,93 @@
+import type { MessageRole } from '../memory/types.js';
 /**
- * 会话存储接口（ISessionStore）
+ * 会话存储接口：宿主注入的会话消息持久化能力，内核不直接依赖文件 I/O。
+ * IMemoryStorage 存记忆索引（round-summary），这里存原始对话消息。零依赖内核、接口最小化、不实现则走内存模式。
  *
- * 宿主项目实现此接口，提供会话消息的持久化能力。
- * memora 内核通过此接口读写会话记录，不直接依赖文件 I/O。
- *
- * 与 IMemoryStorage 的关系：
- * - IMemoryStorage：记忆索引（SQLite），存储提取后的 insight
- * - ISessionStore：会话记录，存储原始对话消息
- *
- * 设计原则：
- * - 零依赖内核：memora 不实现文件 I/O，由宿主注入
- * - 接口最小化：只暴露必要的读写操作
- * - 向后兼容：不强制要求实现，不传则使用内存模式
- *
- * @example
- * // 宿主实现（文件存储）
- * class FileSessionStore implements ISessionStore {
- *   appendMessage(date, session, message) { ... }
- *   loadMessages(date, session) { ... }
- *   listSessions() { ... }
- * }
- *
- * // 注入到 Agent
- * const agent = new Agent({
- *   sessionStore: new FileSessionStore('./sessions'),
- *   ...
- * });
+ * 存储模型（round-based 单一模式，SSOT）：
+ * - 会话仅以 Round ID 列表（roundIds）为内容来源
+ * - 消息内容只存于 RoundStore（物理存储唯一真相源）
  */
 export interface ISessionStore {
     /**
-     * 追加消息到指定会话
+     * 加载指定会话的完整消息列表（从 roundIds → RoundStore 展开），不存在返回空数组。
      *
-     * @param date - 会话日期 YYYY-MM-DD
-     * @param session - 会话标识
-     * @param message - 消息对象
-     */
-    appendMessage(date: string, session: string, message: SessionMessage): void;
-    /**
-     * 加载指定会话的消息列表
+     * **只返回 `user` / `assistant` 两种角色**：tool 结果属执行中间态，不落会话消息。这不是实现自由，
+     * 而是接口契约 —— 上下文中 tool 消息的**唯一来源**是 `AgentLoop.appendToolMessage`（入口关
+     * 落盘 + 单条上限），历史回注（`restoreHistory` ← 本方法）不含 tool。两个实现（宿主
+     * `hosts/memora-vscode/.../host/sessionStore.ts`、内核 `inMemorySessionStore.ts`）逐字同构。
      *
-     * @param date - 会话日期 YYYY-MM-DD
-     * @param session - 会话标识
-     * @returns 消息列表，不存在则返回空数组
+     * ⚠️ 改此契约（如让 tool 消息也入历史）须同步评估大文本统一通道 §6.2：
+     * 压缩链的「超大 tool 结果卸载级」正是因本契约而删除（读者先亡 → 写者后死）；若历史重新携带
+     * tool 消息，该级的存在前提会复活。
      */
     loadMessages(date: string, session: string): SessionMessage[];
-    /**
-     * 列出所有会话标识
-     *
-     * @returns 会话标识列表（格式：YYYY-MM-DD-session）
-     */
+    /** 列出所有会话标识（YYYY-MM-DD-session） */
     listSessions(): string[];
+    /** 读取会话标题元数据，不存在返回 undefined */
+    getSessionMeta(sessionId: string): SessionMeta | undefined;
+    /** 设置用户可修改的显示名（displayName）；首轮自动命名走 updateSessionMeta 写 autoName */
+    setSessionTitle?(sessionId: string, title: string): void;
+    /** 更新元数据（autoName/keyTopics/summary/createdAt 等） */
+    updateSessionMeta(sessionId: string, meta: Partial<SessionMeta>): void;
     /**
-     * 复制会话：将源会话的全部消息复制到目标会话
-     *
-     * 实现要求：
-     * - 原子操作：要么全部复制成功，要么不产生副作用
-     * - 保留时间戳：消息的 timestamp 不修改
-     * - 幂等：若目标会话已存在，覆盖（而非追加）
-     * - 若源会话不存在，静默返回（不抛出）
+     * 列出全部会话标题元数据，**必须按 updatedAt 降序**（最近活跃在前）。
      *
-     * @param sourceDate - 源会话日期
-     * @param sourceSession - 源会话标识
-     * @param targetDate - 目标会话日期
-     * @param targetSession - 目标会话标识
+     * 排序方向是本接口契约的一部分，不是各实现自由：`SessionManager.restoreMostRecentSession`
+     * 视 `[0]` 为「最近活跃会话」的唯一真理源；升序实现会让「恢复最近会话」恢复成最旧会话。
      */
-    copySession?(sourceDate: string, sourceSession: string, targetDate: string, targetSession: string): void;
+    listSessionMetas(): SessionMeta[];
+    /** 追加 Round ID 到会话 */
+    appendRoundId(sessionId: string, roundId: string): void;
+    /** 批量追加 Round ID 到会话（分叉操作用） */
+    appendRoundIds(sessionId: string, roundIds: string[]): void;
+    /** 获取会话的 Round ID 列表 */
+    getRoundIds(sessionId: string): string[];
+    /** 设置会话的 Round ID 列表（创建/完整替换，如分叉） */
+    setRoundIds(sessionId: string, roundIds: string[]): void;
+    /** 创建新会话元数据 */
+    createSession(meta: SessionMeta): void;
+    /** 删除会话（同时清理 Round ID 引用） */
+    deleteSession(sessionId: string): void;
 }
 /**
- * 会话消息类型
- *
- * 与 LLM Message 的区别：
- * - SessionMessage 包含时间戳，用于持久化
- * - Message 不含时间戳，用于 LLM 通信
+ * 会话元数据：会话身份（date-session）与展示标题解耦。
+ * 双层命名——autoName（LLM 生成只读）+ displayName（用户可改，覆盖显示）。sessionId 即 `${date}-${session}`。
+ */
+export interface SessionMeta {
+    /** 会话标识（YYYY-MM-DD-sessionName，与 listSessions 一致） */
+    sessionId: string;
+    /** LLM 自动生成名称（只读；归档时 SessionArchiver 可更新为更完整名称） */
+    autoName?: string;
+    /** 用户可修改的显示名称（初始=autoName；清空回退 autoName） */
+    displayName?: string;
+    /** 关键主题标签（SessionArchiver 归档时生成，用于搜索/索引） */
+    keyTopics?: string[];
+    /** 会话摘要（SessionArchiver 归档时生成，用于搜索/预览） */
+    summary?: string;
+    /** 最近活跃时间（ISO 8601，历史列表排序依据） */
+    updatedAt: string;
+    /** 会话消息条数（命名信号与列表展示） */
+    messageCount: number;
+    /** 创建时间（ISO 8601） */
+    createdAt?: string;
+}
+/**
+ * 会话显示名称回退（SSOT 单一语义）：displayName → autoName → 空串。
+ */
+export declare function getSessionDisplayName(meta: SessionMeta | undefined): string;
+/** 仅取 autoName（用于搜索/索引），无则空串 */
+export declare function getSessionAutoName(meta: SessionMeta | undefined): string;
+/**
+ * 会话消息类型：比 LLM Message 多 timestamp（持久化用）；roundId 供 traceSummary 精确回溯到轮次。
  */
 export interface SessionMessage {
-    /** 消息角色 */
-    role: 'user' | 'assistant' | 'system';
+    /** 消息角色（从 memory/types.ts 导入，SSOT 单一真理源） */
+    role: MessageRole;
     /** 消息内容 */
     content: string;
     /** 时间戳（ISO 8601） */
     timestamp: string;
+    /** 所属轮次 ID（可选）：traceSummary 精确回溯用，空则退化为整会话摘要 */
+    roundId?: string;
 }
 //# sourceMappingURL=sessionStore.d.ts.map

package/dist/memory/sessionStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sessionStore.d.ts","sourceRoot":"","sources":["../../src/memory/sessionStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAAC;IAE5E;;;;;;OAMG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAAC;IAE9D;;;;OAIG;IACH,YAAY,IAAI,MAAM,EAAE,CAAC;IAEzB;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,CACV,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACpB,IAAI,CAAC;CACT;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,WAAW;IACX,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;IACtC,WAAW;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB"}
+{"version":3,"file":"sessionStore.d.ts","sourceRoot":"","sources":["../../src/memory/sessionStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAE5B;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,EAAE,CAAC;IAG9D,mCAAmC;IACnC,YAAY,IAAI,MAAM,EAAE,CAAC;IACzB,gCAAgC;IAChC,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;IAC3D,oEAAoE;IACpE,eAAe,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACzD,oDAAoD;IACpD,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC;IACvE;;;;;OAKG;IACH,gBAAgB,IAAI,WAAW,EAAE,CAAC;IAGlC,sBAAsB;IACtB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACxD,+BAA+B;IAC/B,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC5D,wBAAwB;IACxB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzC,qCAAqC;IACrC,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACzD,eAAe;IACf,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC,6BAA6B;IAC7B,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAGlB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;IAGrB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IAGjB,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,wBAAwB;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,MAAM,CAS3E;AAED,gCAAgC;AAChC,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,MAAM,CAIxE;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,IAAI,EAAE,WAAW,CAAC;IAClB,WAAW;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/dist/memory/sessionStore.js

@@ -1,2 +1,24 @@
-export {};
+/**
+ * 会话显示名称回退（SSOT 单一语义）：displayName → autoName → 空串。
+ */
+export function getSessionDisplayName(meta) {
+    if (!meta)
+        return '';
+    // displayName 优先（用户可修改）
+    const displayName = meta.displayName?.trim();
+    if (displayName)
+        return displayName;
+    // autoName 次之（LLM 自动生成）
+    const autoName = meta.autoName?.trim();
+    if (autoName)
+        return autoName;
+    return '';
+}
+/** 仅取 autoName（用于搜索/索引），无则空串 */
+export function getSessionAutoName(meta) {
+    if (!meta)
+        return '';
+    const autoName = meta.autoName?.trim();
+    return autoName ?? '';
+}
 //# sourceMappingURL=sessionStore.js.map

package/dist/memory/sessionStore.js.map

@@ -1 +1 @@
-{"version":3,"file":"sessionStore.js","sourceRoot":"","sources":["../../src/memory/sessionStore.ts"],"names":[],"mappings":""}
+{"version":3,"file":"sessionStore.js","sourceRoot":"","sources":["../../src/memory/sessionStore.ts"],"names":[],"mappings":"AAuFA;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAA6B;IACjE,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,wBAAwB;IACxB,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC;IAC7C,IAAI,WAAW;QAAE,OAAO,WAAW,CAAC;IACpC,wBAAwB;IACxB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC;IACvC,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,gCAAgC;AAChC,MAAM,UAAU,kBAAkB,CAAC,IAA6B;IAC9D,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC;IACvC,OAAO,QAAQ,IAAI,EAAE,CAAC;AACxB,CAAC"}

package/dist/memory/sessionViewLoader.d.ts

@@ -0,0 +1,141 @@
+/**
+ * 会话视图加载器 —— 将 Round ID 列表展开为完整对话
+ *
+ * 设计理念：
+ * - 会话（Session）只存储 Round ID 列表
+ * - RoundStore 存储问答闭环的物理数据
+ * - SessionViewLoader 负责将两者组合成用户可见的逻辑视图
+ *
+ * 核心优势：
+ * 1. 物理存储层与逻辑视图层解耦
+ * 2. 支持分叉：多个会话可以引用同一组 Round
+ * 3. 支持独立存储：Round 数据只存一份
+ */
+import type { Round, RoundMessage } from '../memory/roundStore.js';
+import type { SessionMeta } from '../memory/sessionStore.js';
+/**
+ * 会话视图：展开后的完整对话
+ *
+ * 这是用户可见的对话数据结构，包含：
+ * - 会话元数据
+ * - 问答闭环列表（按顺序）
+ * - 展开后的消息列表（扁平结构）
+ */
+export interface SessionView {
+    /** 会话 ID */
+    sessionId: string;
+    /** 会话元数据 */
+    meta: SessionMeta;
+    /** 问答闭环列表（按 roundIds 顺序） */
+    rounds: Round[];
+    /**
+     * 展开后的消息列表（扁平结构）
+     *
+     * 顺序：round1.userMessage → round1.assistantMessage → round2.userMessage → ...
+     * 仅包含**已收场**状态的 assistantMessage（complete 正常完成 / interrupted 中断收场，
+     * 判据收口在 isRoundSettled，勿自写 'complete'）
+     */
+    messages: RoundMessage[];
+}
+/**
+ * 简化的会话视图（仅用于历史列表等轻量场景）
+ */
+export interface SessionSummary {
+    /** 会话 ID */
+    sessionId: string;
+    /** 会话标题 */
+    title: string;
+    /** 问答闭环数量 */
+    roundCount: number;
+    /** 最后活跃时间 */
+    updatedAt: string;
+    /** 最后一条消息摘要（用于预览） */
+    lastMessagePreview?: string;
+}
+/**
+ * 会话视图加载器接口
+ *
+ * 职责：将 Session（Round ID 列表）+ RoundStore（物理存储）组合成完整视图
+ *
+ * 设计原则：
+ * 1. 透明转换：调用方不需要关心底层存储结构
+ * 2. 批量加载：避免 N+1 查询，一次性加载所有 Round
+ * 3. 容错处理：部分 Round 加载失败时仍可返回可用视图
+ */
+export interface ISessionViewLoader {
+    /**
+     * 加载会话的完整对话视图
+     *
+     * 流程：
+     * 1. 获取 SessionMeta（含 roundIds 列表）
+     * 2. 从 RoundStore 批量加载所有 Round
+     * 3. 展开为扁平消息列表
+     *
+     * @param sessionId - 会话 ID
+     * @returns 完整会话视图
+     * @throws Error 会话不存在时抛出
+     */
+    loadView(sessionId: string): SessionView;
+    /**
+     * 加载会话的简化摘要（用于历史列表等轻量场景）
+     *
+     * 与 loadView 的区别：
+     * - 不加载全量 Round：仅读最后 1 个 Round 生成 lastMessagePreview
+     * - 只返回元数据、统计信息与末条 AI 预览
+     *
+     * @param sessionId - 会话 ID
+     * @returns 会话摘要
+     */
+    loadSummary(sessionId: string): SessionSummary | null;
+    /**
+     * 批量加载多个会话的摘要
+     *
+     * 用于历史列表、批量操作等场景
+     *
+     * @param sessionIds - 会话 ID 数组
+     * @returns 会话摘要数组
+     */
+    loadBatchSummaries(sessionIds: string[]): SessionSummary[];
+    /**
+     * 获取会话的消息数量（性能优化）
+     *
+     * 不加载完整 Round 数据，仅统计消息数
+     *
+     * @param sessionId - 会话 ID
+     * @returns 消息数量（User + AI）
+     */
+    getMessageCount(sessionId: string): number;
+    /**
+     * 从指定 Round 位置截断会话视图
+     *
+     * 用途：分叉操作时获取分叉点之前的对话
+     *
+     * @param sessionId - 会话 ID
+     * @param upToRoundId - 截断到哪个 Round（包含）
+     * @returns 截断后的会话视图
+     */
+    loadViewUpTo(sessionId: string, upToRoundId: string): SessionView;
+}
+/**
+ * 从 Round 列表展开为扁平消息列表
+ *
+ * @param rounds - Round 数组（按顺序）
+ * @returns 展开后的消息数组
+ */
+export declare function flattenRoundsToMessages(rounds: Round[]): RoundMessage[];
+/**
+ * 截断 Round 列表到指定位置
+ *
+ * @param rounds - Round 数组
+ * @param upToRoundId - 截断到此 Round（包含）
+ * @returns 截断后的 Round 数组
+ */
+export declare function truncateRoundsUpTo(rounds: Round[], upToRoundId: string): Round[];
+/**
+ * 计算 Round 列表的消息总数
+ *
+ * @param rounds - Round 数组
+ * @returns 消息数量
+ */
+export declare function countMessagesInRounds(rounds: Round[]): number;
+//# sourceMappingURL=sessionViewLoader.d.ts.map

package/dist/memory/sessionViewLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionViewLoader.d.ts","sourceRoot":"","sources":["../../src/memory/sessionViewLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAI5D;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,YAAY;IACZ,SAAS,EAAE,MAAM,CAAC;IAElB,YAAY;IACZ,IAAI,EAAE,WAAW,CAAC;IAElB,4BAA4B;IAC5B,MAAM,EAAE,KAAK,EAAE,CAAC;IAEhB;;;;;;OAMG;IACH,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,YAAY;IACZ,SAAS,EAAE,MAAM,CAAC;IAElB,WAAW;IACX,KAAK,EAAE,MAAM,CAAC;IAEd,aAAa;IACb,UAAU,EAAE,MAAM,CAAC;IAEnB,aAAa;IACb,SAAS,EAAE,MAAM,CAAC;IAElB,qBAAqB;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAID;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,CAAC;IAEzC;;;;;;;;;OASG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAAC;IAEtD;;;;;;;OAOG;IACH,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,cAAc,EAAE,CAAC;IAE3D;;;;;;;OAOG;IACH,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAE3C;;;;;;;;OAQG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,WAAW,CAAC;CACnE;AAID;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,YAAY,EAAE,CAevE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,WAAW,EAAE,MAAM,GAAG,KAAK,EAAE,CAMhF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,CAS7D"}

package/dist/memory/sessionViewLoader.js

@@ -0,0 +1,65 @@
+/**
+ * 会话视图加载器 —— 将 Round ID 列表展开为完整对话
+ *
+ * 设计理念：
+ * - 会话（Session）只存储 Round ID 列表
+ * - RoundStore 存储问答闭环的物理数据
+ * - SessionViewLoader 负责将两者组合成用户可见的逻辑视图
+ *
+ * 核心优势：
+ * 1. 物理存储层与逻辑视图层解耦
+ * 2. 支持分叉：多个会话可以引用同一组 Round
+ * 3. 支持独立存储：Round 数据只存一份
+ */
+import { isRoundSettled } from '../memory/roundStore.js';
+// ─── 辅助函数 ───────────────────────────────────────────
+/**
+ * 从 Round 列表展开为扁平消息列表
+ *
+ * @param rounds - Round 数组（按顺序）
+ * @returns 展开后的消息数组
+ */
+export function flattenRoundsToMessages(rounds) {
+    const messages = [];
+    for (const round of rounds) {
+        // 始终添加用户消息
+        messages.push(round.userMessage);
+        // 仅添加已收场的 AI 消息（complete 正常完成 / interrupted 中断收场——后者按定案
+        // §一·五「可作后续上下文」同样计入，判据收口在 isRoundSettled，勿自写 'complete'）
+        if (round.assistantMessage && isRoundSettled(round.status)) {
+            messages.push(round.assistantMessage);
+        }
+    }
+    return messages;
+}
+/**
+ * 截断 Round 列表到指定位置
+ *
+ * @param rounds - Round 数组
+ * @param upToRoundId - 截断到此 Round（包含）
+ * @returns 截断后的 Round 数组
+ */
+export function truncateRoundsUpTo(rounds, upToRoundId) {
+    const idx = rounds.findIndex((r) => r.id === upToRoundId);
+    if (idx === -1) {
+        return [...rounds]; // 未找到则返回全部
+    }
+    return rounds.slice(0, idx + 1);
+}
+/**
+ * 计算 Round 列表的消息总数
+ *
+ * @param rounds - Round 数组
+ * @returns 消息数量
+ */
+export function countMessagesInRounds(rounds) {
+    let count = 0;
+    for (const round of rounds) {
+        count += 1; // 用户消息
+        if (isRoundSettled(round.status)) {
+            count += 1; // AI 消息（仅已收场：complete / interrupted）
+        }
+    }
+    return count;
+}
+//# sourceMappingURL=sessionViewLoader.js.map

package/dist/memory/sessionViewLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessionViewLoader.js","sourceRoot":"","sources":["../../src/memory/sessionViewLoader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AA6HxD,uDAAuD;AAEvD;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAe;IACrD,MAAM,QAAQ,GAAmB,EAAE,CAAC;IAEpC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,WAAW;QACX,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QAEjC,wDAAwD;QACxD,yDAAyD;QACzD,IAAI,KAAK,CAAC,gBAAgB,IAAI,cAAc,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3D,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAe,EAAE,WAAmB;IACrE,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,WAAW,CAAC,CAAC;IAC1D,IAAI,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC;QACf,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,WAAW;IACjC,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;AAClC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAe;IACnD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO;QACnB,IAAI,cAAc,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;YACjC,KAAK,IAAI,CAAC,CAAC,CAAC,qCAAqC;QACnD,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/memory/sourceValidation.d.ts

@@ -7,15 +7,12 @@
  */
 export type SourceValidationSeverity = 'block' | 'warn';
 /**
- * 从文件路径自动推断 source（目录映射 + frontmatter 覆盖）
+ * 转义 LIKE 通配符（`%` → `\%`、`_` → `\_`）
  *
- * @param filePath - 文件路径
- * @param frontmatterSource - frontmatter 中显式声明的 source（可选）
- * @returns source 字符串
- */
-export declare function inferSource(filePath: string, frontmatterSource?: string): string;
-/**
- * 转义 LIKE 通配符，防止注入
+ * ⚠️ 必须与 SQL 的 `ESCAPE '\'` 配套使用，即 `LIKE ? ESCAPE '\'`：
+ * 未写 ESCAPE 子句时反斜杠被当作普通字符，转义后的模式匹配不到任何含 `%`/`_` 的字面值，
+ * 查询静默返回空——比不转义更隐蔽（不转义是过度召回，漏转义是零召回）。
+ * 参数本身仍须用 `?` 占位绑定，转义只解决语义、不解决注入。
  *
  * @param str - 原始字符串
  * @returns 转义后的字符串
@@ -24,10 +21,11 @@ export declare function escapeLike(str: string): string;
 /**
  * 截取字符串前 maxLen 字符后转义 LIKE 通配符
  *
- * 用于将用户输入 / insight 文本作为关键词搜索 SQLite LIKE 查询的输入。
- * 截断避免超长输入导致 LIKE 解析性能问题，转义防止通配符注入。
+ * 用于将用户输入 / round-summary 记忆文本作为关键词搜索 SQL LIKE 查询的输入。
+ * 截断避免超长输入导致 LIKE 解析性能问题，转义防止通配符被当作模式符。
+ * 同 `escapeLike`：SQL 侧必须写 `LIKE ? ESCAPE '\'`，否则转义后的模式查不到字面值。
  *
- * @param text - 原始文本（用户输入 / insight 内容）
+ * @param text - 原始文本（用户输入 / round-summary 内容）
  * @param maxLen - 最大截取长度，默认 50
  * @returns 截断 + 转义后的字符串
  */
@@ -54,7 +52,7 @@ export declare function validateSource(source: string): {
 /**
  * 简单 Levenshtein 距离计算（仅用于短字符串，不做优化）
  *
- * 导出供 MemoryInspector 等模块复用（语义去重场景的名称相似度判断）。
+ * 同文件 :121 用于标签 typo 检测；另导出供 DedupManager（语义去重场景的名称相似度）复用。
  */
 export declare function levenshtein(a: string, b: string): number;
 //# sourceMappingURL=sourceValidation.d.ts.map

package/dist/memory/sourceValidation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sourceValidation.d.ts","sourceRoot":"","sources":["../../src/memory/sourceValidation.ts"],"names":[],"mappings":"AAgBA;;;;;;GAMG;AACH,MAAM,MAAM,wBAAwB,GAAG,OAAO,GAAG,MAAM,CAAC;AAUxD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,MAAM,CAWhF;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAAK,GAAG,MAAM,CAEnE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG;IAC9C,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,wBAAwB,CAAC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CA0DA;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CA2BxD"}
+{"version":3,"file":"sourceValidation.d.ts","sourceRoot":"","sources":["../../src/memory/sourceValidation.ts"],"names":[],"mappings":"AAeA;;;;;;GAMG;AACH,MAAM,MAAM,wBAAwB,GAAG,OAAO,GAAG,MAAM,CAAC;AAUxD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAAK,GAAG,MAAM,CAEnE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG;IAC9C,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,wBAAwB,CAAC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CA0DA;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CA2BxD"}