@zooique/memora 2.0.0 → 3.0.0

package/dist/agent/messageHistory.d.ts

@@ -1,135 +1,185 @@
 /**
- * 消息历史：Agent 对话过程中的消息持久化
+ * 消息历史：封装用户输入/Agent 回复的会话持久化，维护当前会话（date+session），经 ISessionStore 落库。
  *
- * 职责：
- *   - 封装"用户输入 → 会话存储"的追加操作
- *   - 封装"Agent 回复 → 会话存储"的追加操作
- *   - 维护当前会话上下文（date + session）
- *   - 通过 ISessionStore 接口实现会话持久化
+ * 存储模型（round-based 单一模式，SSOT）：
+ * 所有消息经 appendUser/appendAssistant 写入 RoundStore（物理真相源），并登记 roundId 到会话的 roundIds 列表；
+ * 会话仅持有 roundIds，不再另存扁平消息列表。
  */
 import type { ISessionStore, SessionMessage } from '../memory/sessionStore.js';
-/**
- * 分叉结果
- */
+import type { InteractiveInputKind, IRoundStore, RoundEvidenceEvent } from '../memory/roundStore.js';
+/** 分叉结果（round-based 模式） */
 export interface ForkResult {
-    /** 新会话标识（不含日期前缀，如 "main-b1"） */
+    /** 新会话标识（不含日期前缀，平等普通会话） */
     newSession: string;
     /** 会话日期 */
     date: string;
-    /** 从源会话复制的消息列表 */
-    messages: SessionMessage[];
+    /** 新会话的 Round ID 列表（已复制的指针） */
+    roundIds: string[];
 }
-/**
- * 消息历史类
- */
+/** 消息历史类 */
 export declare class MessageHistory {
-    /**
-     * 会话存储（可选）
-     * 注入后，消息会持久化到宿主提供的存储实现。
-     * 不注入则仅在内存中保存（AgentLoop.messages[]）。
-     */
+    /** 会话存储（可选）；注入则持久化，否则仅在内存保存（AgentLoop.messages[]） */
     private readonly sessionStore?;
+    /** 问答闭环存储（可选）；注入则启用 round-based 模式（消息内容唯一真相源） */
+    private readonly roundStore?;
     /** 当前日期 YYYY-MM-DD */
     private currentDate;
     /** 当前会话标识（不含日期前缀） */
     private currentSession;
-    /**
-     * 挂起的归档企划集合，Agent.close() 等待它们完成
-     * 容纳 Promise<void>（fire-and-forget 内部）
-     */
+    /** 挂起的 fire-and-forget 归档集合，Agent.close() 等待其完成 */
     private pendingArchives;
+    /** Round-based 模式下当前轮次的 pending Round 缓存（roundId → Round） */
+    private pendingRounds;
     constructor(
-    /**
-     * 会话存储（可选）
-     * 注入后，消息会持久化到宿主提供的存储实现。
-     * 不注入则仅在内存中保存（AgentLoop.messages[]）。
-     */
-    sessionStore?: ISessionStore | undefined, initialDate?: string, initialSession?: string);
-    /**
-     * 获取当前会话名（日期-会话组合名）
-     */
+    /** 会话存储（可选）；注入则持久化，否则仅在内存保存（AgentLoop.messages[]） */
+    sessionStore?: ISessionStore | undefined, initialDate?: string, initialSession?: string, 
+    /** 问答闭环存储（可选）；注入则启用 round-based 模式（消息内容唯一真相源） */
+    roundStore?: IRoundStore | undefined);
+    /** 当前会话名（date-session 组合名） */
     get currentSessionName(): string;
-    /** 获取当前日期 YYYY-MM-DD（只读，供 agent 层使用） */
+    /** 当前日期 YYYY-MM-DD */
     get currentDateValue(): string;
-    /** 获取当前会话标识（只读，供 agent 层使用） */
+    /** 当前会话标识 */
     get currentSessionValue(): string;
     /**
-     * 获取当前会话标识
+     * 当前会话第一条轮次的 roundId（会话起点背景，互斥排除用）。
+     * 装配时若第一条不在最近轮内（长会话），完整对话层显式补入第一条，其 roundId 须计入 exclude
+     * 避免其摘要被二次召回。
      */
+    getFirstRoundId(): string | null;
+    /** 当前会话标识 */
     get session(): string;
+    /** 切换会话，返回新会话全名 */
+    switchSession(newSession: string): string;
     /**
-     * 切换会话
-     * @param newSession - 新会话标识
-     * @returns 新会话的全名
+     * 自动生成会话名（平等普通会话命名，无分叉标记）。
+     * 使用时间戳生成唯一名称，实际应委托给 SessionNamer 生成有意义的标题。
      */
-    switchSession(newSession: string): string;
+    private generateSessionName;
     /**
-     * 自动生成分支名
-     *
-     * 算法：扫描已存在会话，找到以 sourceSession-b 为前缀的最大序号，+1
-     *
-     * @param sourceSession - 源会话标识
-     * @returns 自动生成的分支名（如 "main-b1"）
+     * 获取当前会话的 Round ID 列表（单一 round-based 路径）
      */
-    private autoBranchName;
+    private getCurrentRoundIds;
     /**
-     * 分叉当前会话
+     * 获取当前会话的元数据
+     */
+    private getCurrentSessionMeta;
+    /**
+     * 从指定 Round 位置分叉会话（唯一分叉方式，round-based）
      *
-     * 流程：
-     * 1. 从 sessionStore 加载当前会话全部消息
-     * 2. 生成唯一新会话名
-     * 3. 通过 sessionStore.copySession() 复制到新会话
-     * 4. switchSession() 切换当前会话标识到新会话
+     * 核心操作：复制 Round ID 列表（指针复制，不复制数据）
+     * 新会话是完全平等的普通会话，无特殊标记。
      *
-     * @param targetSession - 自定义目标会话名（可选，不传则自动生成）
-     * @returns 分叉结果
-     * @throws 若 sessionStore 未注入、copySession 未实现或当前会话无消息
+     * @param roundId - 分叉点的 Round ID（必须存在于当前会话）
+     * @param targetSession - 可选，自定义新会话名；不传则自动生成
+     * @returns 分叉结果（含新会话 ID 和 roundIds）
+     * @throws 会话不存在 / Round 不存在 / 对话繁忙时抛错
      */
-    forkSession(targetSession?: string): ForkResult;
+    forkSession(roundId?: string, targetSession?: string): ForkResult;
     /**
-     * 追加 user 消息到当前会话
-     * 失败不抛出（消息持久化失败不应阻塞对话）
+     * 追加 user 消息到当前会话（持久化失败不抛出，不阻塞对话）。
+     *
+     * Round-based 路径：roundStore 注入且 roundId 存在时，创建 pending Round
+     * 写入 RoundStore（refCount=0，未完成不登记会话）。**仅 complete 才 appendRoundId**——
+     * 崩溃残留的 pending 轮是孤儿（refCount=0），可由 GC 清理，不污染会话视图。
+     *
+     * 交互输入：opts.interactive 为真且 roundId 对应轮已存在（prepare 建 pending 或
+     * 暂停已完成轮）时，不再创建/覆盖新轮——按序追加到该轮 interactiveInputs，保问答闭环不分裂。
      *
-     * 日期使用 todayDate() 动态获取，而非缓存的 this.currentDate，
-     * 确保跨日后消息写入当天目录。
+     * @param content 用户输入内容
+     * @param roundId 闭环节点轮次 ID（可选，交互输入必须携带 = appendUser 的 head roundId）
+     * @param opts 交互输入选项（interactive=是否交互归属；kind=折叠块类型文案；
+     *        question/options=该回答所对的 ask_user 提问原文与候选选项，随回答一并持久化）
      */
-    appendUser(content: string): Promise<void>;
+    appendUser(content: string, roundId?: string, opts?: {
+        interactive?: boolean;
+        kind?: InteractiveInputKind;
+        question?: string;
+        options?: string[];
+    }): Promise<void>;
     /**
-     * 追加 assistant 消息到当前会话
-     * 失败不抛出
+     * 追加裁决证据到在途 Round（悬案取证轨；持久化失败不抛出，不阻塞对话）。
      *
-     * 日期使用 todayDate() 动态获取，确保跨日后消息写入当天目录。
+     * 挂载模式与 interactiveInputs 逐字同构：不新建/不覆盖轮，按序追加到该轮 `evidence`。
+     * **必须同步 pendingRounds**——否则收场 appendAssistant/appendInterrupted 以旧缓存对象
+     * 覆盖落盘，证据被静默丢弃（突变点：漏 set 即丢证据）。
+     * 轮缺失（异常兜底）：warn 后丢弃——证据缺失不伪造第二轨道补写。
+     *
+     * @param roundId 闭环节点轮次 ID
+     * @param ev 裁决证据事件（空响应 / 台账替身回显个案证据）
      */
-    appendAssistant(content: string): Promise<void>;
+    appendEvidence(roundId: string, ev: RoundEvidenceEvent): Promise<void>;
     /**
-     * 列出所有会话标识
+     * 追加 assistant 消息到当前会话（持久化失败不抛出）。
+     *
+     * Round-based 路径：完成 pending Round 时**才登记会话引用**——
+     * incrementRef（refCount 0→1）+ appendRoundId。pending 缓存丢失（跨重启）时从
+     * RoundStore 取回补全；Round 不存在（异常兜底）时创建独立 complete Round 并登记，
+     * 保证用户消息不丢失。
      *
-     * @returns 会话标识列表（格式：YYYY-MM-DD-session），未注入 ISessionStore 则返回空
+     * 闭环节点续写：同一 roundId 已存在 assistantMessage（跨暂停-续跑：
+     * 暂停轮已把 ask_user 提问/中断半截落为 assistantMessage）时，旧段入 assistantLog，
+     * assistantMessage 恒为末段（最终回答）——问答闭环不因续跑分裂新轮，且前序 LLM
+     * 文本（如主动提问）不丢失。
      */
-    listAllSessions(): Promise<string[]>;
+    appendAssistant(content: string, roundId?: string): Promise<void>;
     /**
-     * 从会话存储恢复历史消息
-     * 用于重启后恢复之前的对话
+     * 中断轮收场：把「未正常完成」的轮升级为正常 stop turn 并入会话。
+     *
+     * 语义定案（step-atomic-persistence.md §一·五）：崩溃残留轮（pending/error + refCount=0 + 有已
+     * 落盘 processEvents）= 等同于用户点「停止」的正常 turn——可删、入会话 roundIds、作后续上下文，
+     * **不是**半成品草稿/孤儿。宿主经 `IRoundStore.listInterruptedRecent` 打捞后再调本方法完成
+     * 「升级登记」，恢复为普通 turn 渲染无需特殊草稿卡。
      *
-     * @param date - 会话日期 YYYY-MM-DD
-     * @param session - 会话标识
-     * @returns 会话中的消息列表，未注入 ISessionStore 则返回空数组
+     * **两个调用时机**：
+     * 1. 崩溃/断电后重启——宿主 `chatPanel.upgradeInterruptedRounds` 打捞后调用；
+     * 2. **运行期非正常收场**——`seed/orchestrator.act()` 在中断（用户取消/超时）与失败
+     *    （LLM/网络错误）两条路径上就地调用（SSOT 收口，见该处注释）。运行期即收尾可避免
+     *    留下 pending 孤儿轮、须等下次重启才打捞（LLM 4xx 中断的长任务轮即此类）。
+     *    依据 = `memory/roundStore.ts` RoundStatus 文档「运行时失败不翻状态机，一律按中断处理」。
+     *
+     * 收场约定与 appendAssistant 同一真理源（refCount 0→1 + appendRoundId + status interrupted +
+     * completedAt + isReappend 防重复登记，两处终态判据同为 `isRoundSettled`），Round schema /
+     * 存储格式不变；
+     * **有意不直接复用 appendAssistant**，两处差异：
+     * - appendAssistant 顶层跳过空内容 → 无文本中断轮无法收场；本方法允许多段「即使无
+     *   assistantMessage 总结也按 stop 语义收场」（§一·五验收口径）。
+     * - 中断标记统一追加默认文案（LOOP_CONSTANTS.DEFAULT_INTERRUPTED_MARK），与运行期两条
+     *   中断收场路径（loop 流式中断 / orchestrator 历史写入）的默认降级同源（SSOT）。
+     *
+     * 幂等：已收场（complete / interrupted 终态）的轮再调直接返回（宿主打捞与运行期收尾可能对同一轮各触发一次）。
+     *
+     * @param roundId 待收场轮 ID（须已存在于 RoundStore 或本实例 pendingRounds；缺失仅记日志不抛错，防御性降级）
+     * @param opts.content 已产出的助手文本（运行期由 consumeExecutionStream 累积；宿主打捞时
+     *        从 processEvents 的 narrate 内容拼接派生）。缺省/空则**不写** assistantMessage，
+     *        仍按 stop 语义收场
+     * @param opts.interruptedMark 中断标记（缺省用 LOOP_CONSTANTS.DEFAULT_INTERRUPTED_MARK）
      */
+    appendInterrupted(roundId: string, opts?: {
+        content?: string;
+        interruptedMark?: string;
+    }): Promise<void>;
+    /** 列出所有会话标识（YYYY-MM-DD-session）；未注入 ISessionStore 返回空 */
+    listAllSessions(): Promise<string[]>;
+    /** 恢复会话历史并同步当前会话到指定 date/session（保持状态一致）；未注入 ISessionStore 返回空 */
     loadSessionMessages(date: string, session: string): Promise<SessionMessage[]>;
     /**
-     * 把外部 fire-and-forget 归档注册到 pendingArchives
-     * 供 Agent.chat() 触发 signal 归档时使用
+     * 从 Round ID 列表加载会话消息（round-based 模式）
+     *
+     * 将 Round ID 列表展开为扁平的 SessionMessage[]，
+     * 供 AgentLoop 加载上下文使用。
+     *
+     * @param roundIds - Round ID 列表
+     * @returns 展开后的消息列表（user + assistant 成对）
      */
+    loadRoundBasedMessages(roundIds: string[]): SessionMessage[];
+    /** 注册外部 fire-and-forget 归档到 pendingArchives，供 Agent.chat() 触发 signal 归档时使用 */
     registerPendingArchive(p: Promise<unknown>): void;
     /**
-     * 等待所有挂起的归档完成（Agent.close() 时调用）
-     * 防止 fire-and-forget 还在写 SQLite 时 db 已被 close
-     *
-     * 重要：会捕获**等待期间新加入**的归档（解决 init() → archiveMissingSessions() 的 race）
-     * 实现：用 50ms 间隔轮询检查新加入的 promise，直到所有归档完成或超时
-     *
-     * @param timeoutMs 单次等待超时（默认 5000ms）
-     * @returns 是否所有归档都完成（false 表示有超时）
+     * 等待所有挂起归档完成（Agent.close() 时调用），防止归档写入时存储已被关闭。
+     * 会捕获等待期间新加入的归档（解决 init() → archiveMissingSessions() 的 race）；
+     * 50ms 轮询直到全部完成或超时。
+     * @returns 是否全部完成（false = 超时）
      */
     awaitPendingArchives(timeoutMs?: number): Promise<boolean>;
 }

package/dist/agent/messageHistory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"messageHistory.d.ts","sourceRoot":"","sources":["../../src/agent/messageHistory.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAM9E;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW;IACX,IAAI,EAAE,MAAM,CAAC;IACb,kBAAkB;IAClB,QAAQ,EAAE,cAAc,EAAE,CAAC;CAC5B;AAED;;GAEG;AACH,qBAAa,cAAc;IAavB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;IAjBhC,sBAAsB;IACtB,OAAO,CAAC,WAAW,CAAS;IAC5B,qBAAqB;IACrB,OAAO,CAAC,cAAc,CAAS;IAE/B;;;OAGG;IACH,OAAO,CAAC,eAAe,CAAoC;;IAGzD;;;;OAIG;IACc,YAAY,CAAC,EAAE,aAAa,YAAA,EAC7C,WAAW,CAAC,EAAE,MAAM,EACpB,cAAc,SAAS;IAMzB;;OAEG;IACH,IAAI,kBAAkB,IAAI,MAAM,CAE/B;IAED,wCAAwC;IACxC,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAED,+BAA+B;IAC/B,IAAI,mBAAmB,IAAI,MAAM,CAEhC;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED;;;;OAIG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;IAKzC;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IA0BtB;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,UAAU;IAuD/C;;;;;;OAMG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBhD;;;;;OAKG;IACG,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBrD;;;;OAIG;IACG,eAAe,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAQ1C;;;;;;;OAOG;IACG,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAenF;;;OAGG;IACH,sBAAsB,CAAC,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI;IAOjD;;;;;;;;;OASG;IACG,oBAAoB,CAAC,SAAS,SAAO,GAAG,OAAO,CAAC,OAAO,CAAC;CA4B/D"}
+{"version":3,"file":"messageHistory.d.ts","sourceRoot":"","sources":["../../src/agent/messageHistory.ts"],"names":[],"mappings":"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"}