metona-ai-desktop/electron/services/session-recorder.service.ts

/**
 * Session Recorder — 会话录制器（TRACE 层）
 *
 * 负责将完整的会话执行轨迹写入 session_*.jsonl 文件。
 * 每行一条 JSON 事件，支持事后回放和分析。
 *
 * P1-6 重构：
 * 1. 多会话支持——每个会话独立的状态（文件路径/seq），并发会话互不串扰
 *    （原实现单会话状态，第二个会话 startRecording 会覆盖第一个的录制目标）
 * 2. 事件签名统一携带 sessionId 参数，与 README 宣称的 9 种事件对齐：
 *    session_start, context_built, iteration_start, llm_request,
 *    llm_response, tool_call, tool_result, iteration_end, session_end
 *
 * 日志格式：SSE-like JSON Lines
 *
 * @see docs/MetonaAI-Desktop 架构与交互设计.html — 全链路透明可追踪
 * @see docs/生产级通用 AI Agent 智能体桌面应用：完整设计与构建指南.html — 第十一章
 */

import { join } from 'path';
import {
  appendFileSync,
  existsSync,
  mkdirSync,
  promises,
  readdirSync,
  statSync,
  unlinkSync,
} from 'fs';
import log from 'electron-log';

// ===== 事件类型 =====

export type TraceEventType =
  | 'session_start'
  | 'context_built'
  | 'iteration_start'
  | 'llm_request'
  | 'llm_response'
  | 'tool_call'
  | 'tool_result'
  | 'iteration_end'
  | 'session_end';

export interface TraceEvent {
  seq: number;
  ts: string;
  event: TraceEventType;
  sessionId: string;
  [key: string]: unknown;
}

/** 单个会话的录制状态 */
interface SessionRecordState {
  filePath: string;
  seq: number;
  buffer: string[];
  flushTimer: NodeJS.Timeout | null;
  flushing: boolean;
  /**
   * v0.7.4 P3-4: 当前 in-flight 异步 flush 的 Promise（供 flushSync 等待）。
   * 根治"异步 flush 失败把数据 unshift 回 buffer 后，stopRecording 删除状态
   * 导致重试数据丢失"的竞态。
   */
  flushPromise: Promise<void> | null;
}

// ===== 服务类 =====

export class SessionRecorder {
  /** P1-6: 每会话独立状态（支持并发会话录制） */
  private sessions = new Map<string, SessionRecordState>();

  /**
   * F-8 接通: 录制总开关（logging.traceEnabled，默认 true）
   * 关闭时 writeEvent 丢弃所有事件（状态 Map 仍维护以保持接口兼容）
   */
  private enabled = true;

  constructor(private workspacePath: string) {}

  /** F-8: 设置录制开关（main.ts 启动时按 logging.traceEnabled 注入） */
  setEnabled(enabled: boolean): void {
    this.enabled = enabled;
    if (!enabled) {
      log.info('[SessionRecorder] Trace recording disabled by config (logging.traceEnabled=false)');
    }
  }

  /** 获取指定会话的录制状态（不存在返回 null） */
  private state(sessionId: string): SessionRecordState | null {
    return this.sessions.get(sessionId) ?? null;
  }

  /**
   * 开始录制会话
   */
  startRecording(sessionId: string): void {
    const logsDir = join(this.workspacePath, 'logs');
    if (!existsSync(logsDir)) {
      mkdirSync(logsDir, { recursive: true });
    }

    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
    const filePath = join(logsDir, `session_${sessionId}_${timestamp}.jsonl`);

    this.sessions.set(sessionId, {
      filePath,
      seq: 0,
      buffer: [],
      flushTimer: null,
      flushing: false,
      flushPromise: null,
    });

    // 写入 session_start 事件
    this.writeEvent(sessionId, {
      event: 'session_start',
      sessionId,
      workspace: this.workspacePath,
    });

    log.info(`Session recording started: ${filePath}`);
  }

  /**
   * 停止录制（P1-6: 按会话停止，不影响其他并发录制）
   * v0.7.4 P3-4: 改为 async —— 先等待 in-flight 异步 flush 完成（防止其失败回滚的
   * 数据在状态删除后丢失），再同步 flush 剩余 buffer，最后删除状态。
   */
  async stopRecording(
    sessionId: string,
    params: {
      totalIterations: number;
      totalTokens: number;
      durationMs: number;
      terminationReason: string;
    },
  ): Promise<void> {
    const state = this.state(sessionId);
    if (!state) return;

    this.writeEvent(sessionId, {
      event: 'session_end',
      sessionId,
      totalIterations: params.totalIterations,
      totalTokens: params.totalTokens,
      durationMs: params.durationMs,
      terminationReason: params.terminationReason,
    });

    // #35 修复: 同步 flush 确保最后的 session_end 事件写入文件
    // v0.7.4 P3-4: flushSync 先等待 in-flight flush（避免交叉写入/丢数据）再同步落盘
    await this.flushSync(sessionId);

    log.info(`Session recording stopped: ${state.filePath}`);
    this.sessions.delete(sessionId);
  }

  /**
   * 记录上下文构建
   */
  recordContextBuilt(sessionId: string, params: { tokenCount: number; usageRatio: number }): void {
    this.writeEvent(sessionId, {
      event: 'context_built',
      sessionId,
      tokens: params.tokenCount,
      ratio: params.usageRatio,
    });
  }

  /**
   * 记录迭代开始
   */
  recordIterationStart(sessionId: string, iteration: number): void {
    this.writeEvent(sessionId, {
      event: 'iteration_start',
      sessionId,
      iteration,
    });
  }

  /**
   * 记录 LLM 请求
   */
  recordLLMRequest(params: {
    sessionId: string;
    iteration: number;
    provider: string;
    model: string;
    messageCount: number;
  }): void {
    this.writeEvent(params.sessionId, {
      event: 'llm_request',
      sessionId: params.sessionId,
      iteration: params.iteration,
      provider: params.provider,
      model: params.model,
      messageCount: params.messageCount,
    });
  }

  /**
   * 记录 LLM 响应
   */
  recordLLMResponse(params: {
    sessionId: string;
    iteration: number;
    content: string;
    finishReason: string;
    tokenUsage: { input: number; output: number; total: number };
  }): void {
    this.writeEvent(params.sessionId, {
      event: 'llm_response',
      sessionId: params.sessionId,
      iteration: params.iteration,
      contentPreview: params.content.slice(0, 200),
      finishReason: params.finishReason,
      tokenUsage: params.tokenUsage,
    });
  }

  /**
   * 记录工具调用
   */
  recordToolCall(params: {
    sessionId: string;
    iteration: number;
    toolName: string;
    args: Record<string, unknown>;
  }): void {
    this.writeEvent(params.sessionId, {
      event: 'tool_call',
      sessionId: params.sessionId,
      iteration: params.iteration,
      tool: params.toolName,
      args: params.args,
    });
  }

  /**
   * 记录工具结果
   */
  recordToolResult(params: {
    sessionId: string;
    iteration: number;
    toolName: string;
    success: boolean;
    durationMs: number;
    resultPreview?: string;
    error?: string;
  }): void {
    this.writeEvent(params.sessionId, {
      event: 'tool_result',
      sessionId: params.sessionId,
      iteration: params.iteration,
      tool: params.toolName,
      success: params.success,
      durationMs: params.durationMs,
      resultPreview: params.resultPreview?.slice(0, 500),
      error: params.error,
    });
  }

  /**
   * 记录迭代结束
   */
  recordIterationEnd(sessionId: string, params: { iteration: number; durationMs: number }): void {
    this.writeEvent(sessionId, {
      event: 'iteration_end',
      sessionId,
      iteration: params.iteration,
      durationMs: params.durationMs,
    });
  }

  /**
   * 获取录制文件路径
   */
  getFilePath(sessionId?: string): string | null {
    if (sessionId) return this.state(sessionId)?.filePath ?? null;
    const first = this.sessions.values().next().value;
    return first?.filePath ?? null;
  }

  // ===== v0.7.3 P3-3: JSONL 录制文件生命周期治理 =====

  /** JSONL 录制文件名模式（仅治理本服务产出的文件） */
  private static readonly RECORDING_NAME = /^session_.+\.jsonl$/;

  /**
   * 统计录制目录中的 JSONL 文件（设置页展示 + 清理前置确认用）。
   * 目录不存在 / 统计失败返回零值（不抛错）。
   */
  getRecordingStats(): { count: number; totalBytes: number } {
    try {
      const logsDir = join(this.workspacePath, 'logs');
      if (!existsSync(logsDir)) return { count: 0, totalBytes: 0 };
      const names = readdirSync(logsDir).filter((n) => SessionRecorder.RECORDING_NAME.test(n));
      let totalBytes = 0;
      for (const name of names) {
        try {
          totalBytes += statSync(join(logsDir, name)).size;
        } catch {
          /* 单文件统计失败跳过 */
        }
      }
      return { count: names.length, totalBytes };
    } catch {
      return { count: 0, totalBytes: 0 };
    }
  }

  /**
   * 清理旧录制文件（按修改时间保留最近 maxFiles 个，默认 200）。
   *
   * 背景：workspace/logs/session_*.jsonl 随使用无限累积无任何清理路径。
   * 清理策略：mtime 降序保留前 maxFiles 个，其余删除；仅匹配本服务的
   * session_*.jsonl 命名（用户自放文件不受影响）。启动时（main.ts）与
   * 设置页手动清理共用本方法。
   *
   * @returns 实际删除的文件数
   */
  pruneOldRecordings(maxFiles = 200): number {
    try {
      const logsDir = join(this.workspacePath, 'logs');
      if (!existsSync(logsDir)) return 0;
      const entries = readdirSync(logsDir)
        .filter((n) => SessionRecorder.RECORDING_NAME.test(n))
        .map((name) => {
          try {
            return { name, mtime: statSync(join(logsDir, name)).mtimeMs };
          } catch {
            return { name, mtime: 0 };
          }
        })
        .sort((a, b) => b.mtime - a.mtime);

      if (entries.length <= maxFiles) return 0;
      const toDelete = entries.slice(maxFiles);
      let deleted = 0;
      for (const entry of toDelete) {
        try {
          unlinkSync(join(logsDir, entry.name));
          deleted++;
        } catch {
          /* 单文件删除失败（占用中）跳过 */
        }
      }
      if (deleted > 0) {
        log.info(
          `[SessionRecorder] Pruned ${deleted} old recording file(s) (kept ${Math.min(maxFiles, entries.length)})`,
        );
      }
      return deleted;
    } catch (err) {
      log.warn('[SessionRecorder] pruneOldRecordings failed:', err);
      return 0;
    }
  }

  // ===== 私有方法 =====

  /**
   * 写入事件到缓冲区
   *
   * #35 修复: 缓冲写入，定时异步 flush，避免每次 appendFileSync 阻塞主进程
   * 高频事件（30-50 次/秒）先 push 到内存 buffer，每 100ms 批量异步写入文件
   */
  private writeEvent(sessionId: string, data: Record<string, unknown>): void {
    const state = this.state(sessionId);
    if (!state) return;
    // F-8 接通: logging.traceEnabled=false 时丢弃事件（不写文件）
    if (!this.enabled) return;

    const event: TraceEvent = {
      seq: state.seq++,
      ts: new Date().toISOString(),
      sessionId,
      ...data,
    } as TraceEvent;

    const line = JSON.stringify(event);

    // 审查修复: buffer 上限防止 OOM — 高频事件持续 flush 失败时避免内存无限增长
    const MAX_BUFFER_SIZE = 1000;
    if (state.buffer.length >= MAX_BUFFER_SIZE) {
      // v0.7.4 P3-4 修正: 超限路径原调用 async flushSync 但未 await（同步方法内无法 await），
      // flushSync 改为 async 后产生 in-flight 窗口（await 期间新事件与另一 flush 交叉）。
      // 现改为内联同步落盘：直接 appendFileSync 当前 buffer（不含本行），保证确定性。
      const flushData = state.buffer.join('\n') + '\n';
      state.buffer = [];
      try {
        appendFileSync(state.filePath, flushData, 'utf-8');
      } catch (error) {
        log.error('Trace event buffer overflow flush failed:', error);
        state.buffer.unshift(flushData.trimEnd());
      }
    }
    state.buffer.push(line);
    if (!state.flushTimer) {
      state.flushTimer = setTimeout(() => {
        const st = this.state(sessionId);
        if (st) {
          st.flushTimer = null;
          void this.flush(sessionId);
        }
      }, 100);
    }
  }

  /**
   * #35 修复: 异步 flush 缓冲区到文件
   * 审查修复: 用局部变量保存 filePath，防止 stopRecording 将状态删除后 appendFile 抛错；
   * 失败时将数据 unshift 回 buffer 避免丢整批数据
   * v0.7.4 P3-4: flush 的 Promise 存入 state.flushPromise，供 flushSync 等待 ——
   * 根治"异步 flush 失败回滚数据后 stopRecording 删除状态导致数据丢失"的竞态。
   */
  private async flush(sessionId: string): Promise<void> {
    const state = this.state(sessionId);
    if (!state || state.flushing || state.buffer.length === 0) return;
    state.flushing = true;
    const filePath = state.filePath; // 局部变量，防止中途状态被删除
    const data = state.buffer.join('\n') + '\n';
    state.buffer = [];

    const run = (async (): Promise<void> => {
      try {
        await promises.appendFile(filePath, data, 'utf-8');
      } catch (error) {
        log.error('Trace event flush failed:', error);
        // 审查修复: 失败时将数据放回 buffer 头部，下次 flush/flushSync 重试
        const st = this.state(sessionId);
        if (st) st.buffer.unshift(data.trimEnd());
      } finally {
        const st = this.state(sessionId);
        if (st) st.flushing = false;
      }
    })();
    state.flushPromise = run;
    await run;
    // 清空引用（若期间又发起了新 flush，由新调用覆盖）
    const st = this.state(sessionId);
    if (st && st.flushPromise === run) st.flushPromise = null;
  }

  /**
   * #35 修复: 同步 flush 缓冲区到文件
   * 用于 stopRecording 确保最后的数据（如 session_end 事件）写入文件
   * 审查修复: 如果异步 flush 正在进行（flushing=true），等待其完成后再写入，避免数据交叉/丢失
   * v0.7.4 P3-4: 改为 async 且真正等待 in-flight flush —— 旧实现只检查 flushing 标志后
   * buffer 为空即返回，若异步 flush 失败把数据 unshift 回 buffer，stopRecording 随即将
   * 状态删除，重试数据整体丢失。现在先 await flushPromise（失败回滚的数据会回到 buffer），
   * 再同步 appendFileSync 剩余数据，确保零丢失。
   */
  private async flushSync(sessionId: string): Promise<void> {
    const state = this.state(sessionId);
    if (!state) return;
    if (state.flushTimer) {
      clearTimeout(state.flushTimer);
      state.flushTimer = null;
    }
    // 等待 in-flight 异步 flush 完成（其失败回滚的数据会回到 buffer）
    if (state.flushPromise) {
      try {
        await state.flushPromise;
      } catch {
        /* flush 内部已吞错，此处防御 */
      }
    }
    if (state.buffer.length === 0) return;
    const data = state.buffer.join('\n') + '\n';
    state.buffer = [];
    try {
      appendFileSync(state.filePath, data, 'utf-8');
    } catch (error) {
      log.error('Trace event flushSync failed:', error);
      // 审查修复: 失败时将数据放回 buffer，避免数据丢失
      state.buffer.unshift(data.trimEnd());
    }
  }
}