open-codesign 会话历史持久化恢复:从 v0.2 TODO stub 到 JSONL 聊天存储的 IPC 链路重建

原创2026-09-27 20:41:161,823 阅读
文章标签:人工智能AI 应用桌面应用

open-codesign 会话历史持久化恢复:从 v0.2 TODO stub 到 JSONL 聊天存储的 IPC 链路重建

导读

本文基于仓库内的 session_history_restore_plan.md 计划文档,完整还原 open-codesign 桌面端(Electron)一次会话历史持久化链路修复的根因分析与四步实施方案。该计划针对 window.codesign.chat.* 在 v0.2 阶段遗留的 TODO stub——聊天记录既不落盘也无法重载的问题,通过主进程 IPC 通道恢复、preload 桥接、快照种子与工具状态更新回归覆盖四个步骤完成重建。读完本文,你将掌握 open-codesign 主进程 / preload / 渲染进程三层之间聊天数据的完整调用链、JSONL 会话文件的存储与回放机制,以及如何验证这套恢复方案的正确性。

一、问题根因:v0.2 遗留的 TODO stub

计划文档开门见山地给出了问题的根因:

window.codesign.chat.* 在 apps/desktop/src/preload/index.ts 中是 v0.2 的 TODO stub。它返回空列表、在内存中完成 append,因此渲染器(renderer)的聊天记录从未被持久化,也无法在重启后重新加载。

这段话描述了三个具体症状,可以对照源码逐一理解:

  1. chat.list 返回空列表:界面每次启动读取聊天历史时得到的都是 [],历史对话"凭空消失";
  2. chat.append 只在内存中追加:消息仅在当前进程存活期间可见,进程退出即丢失;
  3. 聊天记录既不持久化也不重载:没有落盘通道,自然也没有恢复路径,用户无法接续上一次会话。

修复前,preload 层 chat 对象是一段"占位实现";修复后,它变成了一组真正指向主进程 IPC 通道的桥接方法(详见下文第四节)。

二、恢复方案总览:四步重建链路

计划文档给出了完整的实施清单(当前状态均为已完成):

步骤 内容 状态
1 在主进程中使用现有的聊天消息辅助函数(chat message helpers)恢复持久化的聊天 IPC 通道 ✅ 已完成
2 将 preload 中的聊天方法指向这些 IPC 通道 ✅ 已完成
3 为 append/list、快照种子(snapshot seeding)与工具状态更新(tool status updates)补充 IPC 回归测试覆盖 ✅ 已完成
4 运行聚焦的桌面端主进程测试 ✅ 已完成

这套方案的核心思想是不新造轮子:主进程侧本就存在一套围绕 SessionManager 的会话聊天辅助函数(位于 apps/desktop/src/main/session-chat.ts),只是缺少暴露给渲染层的 IPC 通道。恢复工作因此变成"接线"而非"重写"——把已有能力通过 IPC 暴露出去,再让 preload 指向它。

三、第一步:主进程恢复持久化聊天 IPC 通道

恢复后的 IPC 通道注册在 apps/desktop/src/main/snapshots-ipc.ts(第 1601–1625 行),共四条:

ipcMain.handle('chat:v1:list', (_e, raw): ChatMessageRow[] => {
  const designId = parseDesignIdPayload(raw, 'chat:v1:list');
  return runDb('chat:list', () => listSessionChatMessages(chatStoreOptions(db), designId));
});

ipcMain.handle('chat:v1:append', (_e, raw): ChatMessageRow => {
  const input = parseChatAppendInput(raw);
  return runDb('chat:append', () => appendSessionChatMessage(chatStoreOptions(db), input));
});

ipcMain.handle('chat:v1:seed-from-snapshots', (_e, raw): { inserted: number } => {
  const designId = parseDesignIdPayload(raw, 'chat:v1:seed-from-snapshots');
  return runDb('chat:seed-from-snapshots', () => ({
    inserted: seedSessionChatFromSnapshots(chatStoreOptions(db), designId),
  }));
});

ipcMain.handle('chat:v1:update-tool-status', (_e, raw): { ok: true } => {
  const input = parseToolStatusInput(raw);
  runDb('chat:update-tool-status', () => appendSessionToolStatus(chatStoreOptions(db), input));
  return { ok: true };
});

四条通道的职责划分非常清晰:

  • chat:v1:list:读取某个 design 的全部聊天记录,返回 ChatMessageRow[];
  • chat:v1:append:追加一条聊天消息,返回持久化后的完整行(含 id、seq、createdAt);
  • chat:v1:seed-from-snapshots:首次打开既有 design 时,用快照中的 prompt 反向填充聊天历史,返回插入条数;
  • chat:v1:update-tool-status:更新某条工具调用(tool_call)消息的执行状态,返回 { ok: true }。

底层真正干活的是 session-chat.ts 中导出的辅助函数——listSessionChatMessages、appendSessionChatMessage、seedSessionChatFromSnapshots、appendSessionToolStatus。每个 handler 都经过 runDb 包裹,配合 CodesignError 与 IPC_BAD_INPUT / IPC_NOT_FOUND 等错误码(见 packages/shared/src/error-codes.ts),保证异常路径可控。

3.1 存储层:JSONL 会话文件

session-chat.ts 的存储模型是每个 design 一个 JSONL 文件:

function sessionFileForDesign(sessionDir: string, designId: string): string {
  const safeId = designId.replace(/[^A-Za-z0-9_-]/g, '_');
  return path.join(sessionDir, `${safeId}.jsonl`);
}
  • designId 会被清洗为只含 A-Za-z0-9_- 的安全文件名,避免路径注入;
  • 会话文件放在 db.sessionDir 下,主进程通过 SessionChatStoreOptions({ db, sessionDir })统一传入;
  • 写入前 mkdirSync(..., { recursive: true }) 确保目录存在,文件为 JSON.stringify 的逐行追加(writeFileSync 全量重写)。

3.2 消息条目类型与 schema 版本

每条写入会话文件的自定义条目(custom entry)都带 type: 'custom' 与 customType,由常量标识:

常量 customType 值 用途
CHAT_MESSAGE_CUSTOM_TYPE open-codesign.chat.message 聊天消息本体
CHAT_TOOL_STATUS_CUSTOM_TYPE open-codesign.chat.tool_status 工具调用状态更新
COMMENT_CUSTOM_TYPE open-codesign.comment.v1 评论事件(add/update/remove/mark-applied)
CONTEXT_BRIEF_CUSTOM_TYPE open-codesign.context.brief.v1 设计简报
RUN_PREFERENCES_CUSTOM_TYPE open-codesign.context.run_preferences.v1 运行偏好
ACTIVE_MESSAGE_CUSTOM_TYPE open-codesign.active-message.v1 运行中的活跃消息

所有持久化结构均携带 schemaVersion: 1,例如存储的聊天消息:

interface StoredChatMessage {
  schemaVersion: 1;
  id: number;
  seq: number;
  kind: ChatMessageKind;
  payload: unknown;
  snapshotId: string | null;
}

回放时通过 parseStoredMessage、parseStatusUpdate、parseCommentEvent 等解析函数做严格校验(schemaVersion 必须为 1、字段类型逐一检查),遇到畸形条目会抛出 IPC_DB_ERROR,而不是静默吞掉数据。

3.3 追加消息:seq 与活动时间戳

appendSessionChatMessage 的实现要点:

const seq = listSessionChatMessages(opts, input.designId).length;
const stored: StoredChatMessage = {
  schemaVersion: 1,
  id: seq,
  seq,
  kind: input.kind,
  payload: input.payload ?? {},
  snapshotId: input.snapshotId ?? null,
};
  • seq 取自当前消息总数,保证同一会话内消息序号单调递增且稳定,这是后面工具状态按 seq 回写的前提;
  • 默认会调用 touchDesignActivity(db, designId, createdAt) 更新设计活跃时间(快照种子等批量回填场景通过 { touchActivity: false } 关闭,避免污染排序)。

四、第二步:preload 聊天方法指向 IPC 通道

恢复后的 preload 桥接位于 apps/desktop/src/preload/index.ts(第 865–898 行),window.codesign.chat 从 TODO stub 变成了四个真实调用 ipcRenderer.invoke 的方法:

chat: {
  list: (designId: string) =>
    ipcRenderer.invoke('chat:v1:list', { schemaVersion: 1, designId }) as Promise<ChatMessageRow[]>,
  append: (input: ChatAppendInput) =>
    ipcRenderer.invoke('chat:v1:append', { schemaVersion: 1, ...input }) as Promise<ChatMessageRow>,
  seedFromSnapshots: (designId: string) =>
    ipcRenderer.invoke('chat:v1:seed-from-snapshots', { schemaVersion: 1, designId }) as Promise<{ inserted: number }>,
  updateToolStatus: (input: { designId; seq; status: 'done' | 'error'; result?; durationMs?; errorMessage? }) =>
    ipcRenderer.invoke('chat:v1:update-tool-status', { schemaVersion: 1, ...input }) as Promise<{ ok: true }>,
  onAgentEvent: (cb: (event: AgentStreamEvent) => void) => { ... },
}

注意所有 IPC 载荷都携带 schemaVersion: 1,与主进程 handler 中的 parseDesignIdPayload / requireSchemaV1 校验对应;同时 onAgentEvent 订阅了 agent:event:v1 通道,用于接收主进程推送的实时 Agent 事件(见第五节)。

渲染进程侧的消费端同样印证了这条链路:在 apps/desktop/src/renderer/src/store/slices/chat.ts 中,打开设计时会先 window.codesign.chat.seedFromSnapshots(designId) 再 window.codesign.chat.list(designId) 加载历史,追加消息则走 window.codesign.chat.append(input)——这正是计划中"渲染器聊天行从未被持久化或重载"问题被修复后的实际调用形态。

五、快照种子:让既有设计的历史"复活"

对于 v0.2 之前创建、从未写入过会话文件的既有设计,直接 chat:list 只能得到空数组。seedSessionChatFromSnapshots(session-chat.ts 第 690–724 行)解决这个问题:

export function seedSessionChatFromSnapshots(opts, designId): number {
  if (listSessionChatMessages(opts, designId).length > 0) return 0; // 已有历史则跳过

  const snapshots = listSnapshots(opts.db, designId).slice().reverse();
  for (const snapshot of snapshots) {
    if (snapshot.prompt 非空) {
      appendSessionChatMessage(opts, { designId, kind: 'user', payload: { text: snapshot.prompt } }, { touchActivity: false });
    }
    appendSessionChatMessage(opts, {
      designId,
      kind: 'artifact_delivered',
      payload: { createdAt: snapshot.createdAt },
      snapshotId: snapshot.id,
    }, { touchActivity: false });
  }
  return inserted;
}

关键行为:

  • 幂等:会话文件已存在聊天记录时直接返回 0,绝不重复播种;
  • 从快照反推历史:每个快照的 prompt 回填为一条 user 消息,并追加一条带 snapshotId 的 artifact_delivered 消息(标记交付了哪个快照产物);
  • 时间顺序:快照按时间倒序取、再 reverse() 成正序写入,保证聊天记录的自然顺序;
  • 不触碰活动时间:批量回填使用 touchActivity: false,避免把所有设计"顶"到活跃列表最前。

六、实时事件投影:run 事件到聊天行的持续写入

持久化不只发生在用户手动 append 时。Agent 运行过程中的流式事件同样需要落到会话文件中,这一职责由 apps/desktop/src/main/run-event-chat.ts 的 projectRunEventToChat 承担,其注释点明设计原则:"日志(journal)是权威来源;回放用于修复日志与聊天写入之间的崩溃间隙。"

事件 → 聊天行的映射规则:

Agent 事件 生成的聊天行 说明
turn_end assistant_text 写入 finalText,携带 runId 与 runEventKey(generationId:seq)
tool_call_start tool_call 记录 toolName、args、toolCallId、command、status
tool_call_result tool_call 状态更新 按 runId + toolCallId 定位原行,appendSessionToolStatus 回写 done/error、result、durationMs
error error 消息 记录 message 与 code
run_settled 结算所有 running 工具 + 补写 assistant_text / artifact_delivered completed → done,否则 → error

去重与幂等是这套投影机制的关键:每条追加都带唯一 runEventKey,append 前先检查 rows.some((row) => payload(row)['runEventKey'] === eventKey),重复事件不会产生重复行;工具结果按 seq 应用,且通过 runResultEventKey 保证"已提交的结果不会被运行结算推断的错误覆盖"(见 applyStatusUpdate 中删除 error/errorMessage 的逻辑)。

主进程在 apps/desktop/src/main/ipc/generate.ts(第 333–381 行)的 publishEvent 中完成"日志先写、投影随后、事件再推送给渲染器"的编排:事件先 journal.append 持久化,再 projectRunEventToChat 投影到聊天存储,最后 target.send('agent:event:v1', durable) 推送给窗口。此外 codesign:v1:recover-runs handler(同文件第 463–511 行)会读取 journal 中全部历史事件并重放投影,实现启动时的崩溃恢复。

七、工具状态更新的落地细节

chat:v1:update-tool-status 对应的 appendSessionToolStatus(session-chat.ts 第 599–629 行)有几个值得注意的实现细节:

  1. 先定位再更新:按 seq 找到原始消息,若其 kind !== 'tool_call' 直接返回,绝不写入孤儿状态;
  2. 结果压缩:工具结果先经 compactToolResultForHistory(toolName, result) 压缩(见 apps/desktop/src/main/ipc/tool-log.ts),避免把超大结果原样塞进 JSONL;
  3. 回放时合并:replayEntries 在重建聊天行时按 seq 找到对应 tool_call 行并 applyStatusUpdate 合并状态字段,因此读取出来的行始终是"已应用最新状态"的最终形态;
  4. 错误字段规范化:errorMessage 会被展开为 { error: { message } } 与平铺 errorMessage 两种形态,供渲染层不同组件消费。

八、回归测试覆盖与验证

计划第三步要求为 append/list、快照种子、工具状态更新补充 IPC 回归测试,仓库中的测试文件可以逐一对应:

验证方式(第四步)即运行桌面端主进程的聚焦测试。仓库使用 pnpm + vitest(配置见 apps/desktop/vitest.config.ts),典型命令为:

# 仓库根目录(pnpm workspace)
pnpm --filter @open-codesign/desktop test -- session-chat run-event-chat

或单独跑某个文件:

pnpm --filter @open-codesign/desktop vitest run apps/desktop/src/main/session-chat.test.ts

若要在本地复现整个链路,可先 pnpm install,再运行 pnpm --filter @open-codesign/desktop dev(dev 入口见 apps/desktop/scripts/dev.cjs)启动 Electron 应用,创建/打开一个 design 后重启应用,即可验证聊天历史被从 <sessionDir>/<safeId>.jsonl 中恢复。

九、小结

从这份计划文档可以提炼出 open-codesign 桌面端会话历史持久化的完整链路:

渲染进程 store/slices/chat.ts
        │  window.codesign.chat.{list,append,seedFromSnapshots,updateToolStatus}
        ▼
preload 层 index.ts(IPC 桥接,携带 schemaVersion: 1)
        │  ipcRenderer.invoke('chat:v1:*')
        ▼
主进程 snapshots-ipc.ts(IPC handler + 输入校验 + runDb)
        │
        ▼
session-chat.ts(SessionManager + JSONL 文件 + 回放/校验)
        ▲
        │  projectRunEventToChat(run-event-chat.ts)
        │  RunJournal 事件流(ipc/generate.ts publishEvent / recover-runs)

这条链路的修复价值在于:聊天记录从"进程内存中的易失数据"升级为"以 JSONL 落盘、可由快照种子恢复、可被运行日志回放修复的持久数据",同时通过 schemaVersion 版本化、seq 序号、runEventKey 去重等手段保证读取结果的确定性与幂等性。对于需要在 Electron 桌面应用中实现"会话级聊天持久化 + 崩溃恢复 + 历史回填"的开发者,这份计划与实现提供了一个结构清晰、可逐层验证的参考范式。

登录后查看全文
open-codesign