cardbuddy 0.13.3 → 0.14.1

package/dist/vendored/server/core/turnJournal.js

@@ -0,0 +1,386 @@
+/**
+ * 回合日志（turn journal）：把一轮 AI 对话的完整 SSE 事件流按 seq 追加落盘。
+ *
+ * 为什么要有它（P2 的地基）：
+ *  ① 断线续跑 —— 客户端断开后回合在服务端继续跑（detached），事件全在日志里，
+ *    重连 / 刷新 / 换标签页都能按 seq 回放 + 续订，几十分钟的建卡不再「连不上就等于没了」。
+ *  ② 服务端权威历史 —— 回合结束时把日志 reduce 成一条 assistant 消息写进 chatHistory，
+ *    浏览器侧的 POST 退化为合并校对：客户端死掉（崩溃 / 关标签页）也不再丢轨迹。
+ *  ③ 事后可查 —— .cache/ai-turns/<cardId>.jsonl 就是这轮发生过什么的完整证据链，
+ *    排查「模型为什么说改好了其实没改」时比对话记录更细（含每次重试与折叠）。
+ *
+ * 形态：一张卡一个 jsonl（跨回合追加，行内带 turnId），行 = SSE 事件 + {seq, ts}。
+ * 写入走 250ms 合批 appendFile：text-delta 一秒能来几十条，逐条同步写盘会把事件循环打碎。
+ * 截图 base64 不入日志（与对话记录同取向：只留 mime 标记），否则一轮几张图就几 MB。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { safeCardId } from './chatHistory.js'
+
+/** 单个日志文件的上限：超了轮转成 .1.jsonl（只留一代旧档），避免 .cache 无限涨 */
+const JOURNAL_MAX_BYTES = 4 * 1024 * 1024
+/** 合批写盘间隔：再短 IO 次数翻倍，再长断电解剖时丢的窗口变大 */
+const FLUSH_INTERVAL_MS = 250
+
+/** 回合日志目录（.cache/ 不入库）：与 ai-chats 同级，删卡时一并清理 */
+export function turnsDir(root) {
+  return path.join(root, '.cache', 'ai-turns')
+}
+
+function journalFile(root, cardId) {
+  const id = safeCardId(cardId)
+  return id ? path.join(turnsDir(root), `${id}.jsonl`) : ''
+}
+
+/** 内存里的活跃回合：cardId -> TurnJournal。reattach / stop / 收尾写历史都从这里找 */
+const liveJournals = new Map()
+
+export function getLiveJournal(cardId) {
+  return liveJournals.get(String(cardId || '')) || null
+}
+
+/**
+ * 读一份日志的行（服务重启后的回放 / 事后排查用）。
+ * 坏行（写到一半断电）直接跳过：日志是证据不是状态，容错比报错有用。
+ */
+export function readJournalLines(root, cardId) {
+  const file = journalFile(root, cardId)
+  if (!file || !fs.existsSync(file)) return []
+  const out = []
+  for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+    const t = line.trim()
+    if (!t) continue
+    try {
+      out.push(JSON.parse(t))
+    } catch {
+      /* 半截行跳过 */
+    }
+  }
+  return out
+}
+
+/**
+ * 最近回合清单（面板「上一轮跑到哪了」与测试断言用）：扫日志里的 turn-start / turn-end 配对。
+ * @returns {Array<{turnId:string, startedAt:number, endedAt:number, status:string, steps:number}>}
+ */
+export function listTurns(root, cardId, limit = 10) {
+  const lines = readJournalLines(root, cardId)
+  const byId = new Map()
+  for (const l of lines) {
+    if (l.type === 'turn-start') {
+      byId.set(l.turnId, { turnId: l.turnId, startedAt: l.ts || 0, endedAt: 0, status: 'running', steps: 0 })
+    } else if (l.type === 'turn-end' && byId.has(l.turnId)) {
+      const t = byId.get(l.turnId)
+      t.endedAt = l.ts || 0
+      t.status = l.status || 'done'
+    } else if (l.type === 'tool-result' && byId.has(l.turnId)) {
+      byId.get(l.turnId).steps++
+    }
+  }
+  return [...byId.values()].slice(-limit)
+}
+
+export class TurnJournal {
+  /**
+   * @param {{ root:string, cardId:string, turnId:string, startedAt:number, meta?:object }} opts
+   */
+  constructor({ root, cardId, turnId, startedAt, meta = {} }) {
+    this.root = root
+    this.cardId = String(cardId || '')
+    this.turnId = turnId
+    this.startedAt = startedAt
+    this.meta = meta
+    this.seq = 0
+    /** 本回合全部行（回放 / reduce 的数据源；detached 期间也继续长） */
+    this.lines = []
+    /** 活着的续订连接（reattach 的 SSE res） */
+    this.subscribers = new Set()
+    this.status = 'running'
+    this.detached = false
+    this.closed = false
+    this.file = journalFile(root, cardId)
+    this._pending = ''
+    this._flushTimer = 0
+    this._writing = null
+    if (this.file) {
+      try {
+        fs.mkdirSync(path.dirname(this.file), { recursive: true })
+        if (fs.existsSync(this.file) && fs.statSync(this.file).size > JOURNAL_MAX_BYTES) {
+          const old = `${this.file}.1`
+          try {
+            if (fs.existsSync(old)) fs.unlinkSync(old)
+            fs.renameSync(this.file, old)
+          } catch {
+            /* 轮转失败不致命：继续往原文件追加 */
+          }
+        }
+      } catch {
+        this.file = ''
+      }
+    }
+    liveJournals.set(this.cardId, this)
+    this.append({ type: 'turn-start', turnId: this.turnId, cardId: this.cardId, startedAt: this.startedAt, ...this.meta })
+  }
+
+  /**
+   * 记一条事件并返回带上 seq 的行（sseWrite 会把 seq 一并发给客户端，重连时按它对账）。
+   * 截图 base64 在这里被摘掉：日志要能长期留着，base64 一张图几百 KB 留不起。
+   */
+  append(evt) {
+    if (this.closed) return null
+    this.seq += 1
+    let payload = evt
+    if (evt && evt.image && typeof evt.image === 'object') {
+      payload = { ...evt, image: { mime: evt.image.mime || 'image/png', omitted: true } }
+    }
+    const line = { seq: this.seq, ts: Date.now(), turnId: this.turnId, ...payload }
+    this.lines.push(line)
+    this._pending += `${JSON.stringify(line)}\n`
+    if (!this._flushTimer) this._flushTimer = setTimeout(() => this.flush(), FLUSH_INTERVAL_MS)
+    for (const res of this.subscribers) {
+      try {
+        if (!res.writableEnded && !res.destroyed) res.write(`data: ${JSON.stringify(line)}\n\n`)
+      } catch {
+        this.subscribers.delete(res)
+      }
+    }
+    return line
+  }
+
+  /** 合批落盘；并发调用串成链，避免两个 appendFile 交错写坏行 */
+  flush() {
+    if (this._flushTimer) {
+      clearTimeout(this._flushTimer)
+      this._flushTimer = 0
+    }
+    if (!this.file || !this._pending) return Promise.resolve()
+    const chunk = this._pending
+    this._pending = ''
+    const job = (this._writing || Promise.resolve())
+      .then(() => {
+        try {
+          fs.appendFileSync(this.file, chunk, 'utf8')
+        } catch {
+          /* 写盘失败（磁盘满 / 目录被删）：内存里仍在，续跑不受影响 */
+        }
+      })
+    this._writing = job
+    return job
+  }
+
+  /** seq 之后的行（回放用；afterSeq=0 即全量） */
+  replay(afterSeq = 0) {
+    const n = Number(afterSeq) || 0
+    return n > 0 ? this.lines.filter((l) => l.seq > n) : this.lines.slice()
+  }
+
+  subscribe(res) {
+    this.subscribers.add(res)
+  }
+
+  unsubscribe(res) {
+    this.subscribers.delete(res)
+  }
+
+  /** 客户端断开：回合继续跑，只打个标记（日志与收尾写历史都不受影响） */
+  markDetached() {
+    if (this.detached || this.closed) return
+    this.detached = true
+    this.append({ type: 'client-detached', turnId: this.turnId })
+  }
+
+  /** 回合收尾：落 turn-end、flush、通知续订者结束、退出活跃表 */
+  async close(status = 'done', extra = {}) {
+    if (this.closed) return
+    this.status = status
+    this.append({ type: 'turn-end', turnId: this.turnId, status, ...extra })
+    // 置 closed 必须晚于 turn-end：append 对已关闭日志直接丢弃，顺序反了这行永远写不进去
+    this.closed = true
+    await this.flush()
+    for (const res of this.subscribers) {
+      try {
+        if (!res.writableEnded && !res.destroyed) res.end()
+      } catch {
+        /* 连接早已不在 */
+      }
+    }
+    this.subscribers.clear()
+    if (liveJournals.get(this.cardId) === this) liveJournals.delete(this.cardId)
+  }
+
+  /**
+   * 把事件流 reduce 成一条 assistant 消息（服务端权威历史的唯一来源）。
+   * 口径与前端 ChatPanel.onEvent 对齐：同一份事件，两边还原出同一条消息，
+   * 合并时才能按 turnId 认亲而不是出现「同一轮两条回答」。
+   */
+  reduce() {
+    const msg = {
+      id: `srv-${this.turnId}`,
+      role: 'assistant',
+      content: '',
+      reasoning: '',
+      reasoningMs: 0,
+      toolCalls: [],
+      events: [],
+      error: '',
+      errorCode: '',
+      status: 'done',
+      turnId: this.turnId,
+      serverAuthored: true,
+      ts: this.startedAt,
+      elapsedMs: 0,
+    }
+    let thinkStartedAt = 0
+    let lastTs = this.startedAt
+    const rowOf = (id, name) => {
+      let row = msg.toolCalls.find((t) => t.toolCallId === id)
+      if (!row) {
+        row = { toolCallId: id, toolName: name || '', args: {}, result: undefined, error: '', ms: 0, startedAt: 0 }
+        msg.toolCalls.push(row)
+      }
+      return row
+    }
+    for (const l of this.lines) {
+      lastTs = l.ts || lastTs
+      switch (l.type) {
+        case 'reasoning-delta':
+          if (!thinkStartedAt) thinkStartedAt = l.ts
+          msg.reasoning += l.text || ''
+          break
+        case 'text-delta':
+          if (thinkStartedAt && !msg.reasoningMs) msg.reasoningMs = Math.max(0, l.ts - thinkStartedAt)
+          msg.content += l.text || ''
+          break
+        case 'tool-call-start': {
+          const row = rowOf(l.toolCallId, l.toolName)
+          row.toolName = l.toolName || row.toolName
+          row.startedAt = row.startedAt || l.ts
+          row.pending = true
+          break
+        }
+        case 'tool-call': {
+          const row = rowOf(l.toolCallId, l.toolName)
+          row.toolName = l.toolName || row.toolName
+          row.args = l.args || {}
+          row.pending = false
+          row.startedAt = row.startedAt || l.ts
+          break
+        }
+        case 'tool-result': {
+          const row = rowOf(l.toolCallId, l.toolName)
+          row.result = l.result ?? ''
+          row.truncated = Boolean(l.truncated)
+          if (l.error) row.error = String(l.error)
+          if (l.image) row.image = l.image
+          row.startedAt = row.startedAt || l.ts
+          row.ms = Math.max(0, l.ts - row.startedAt)
+          row.pending = false
+          break
+        }
+        case 'approval-request': {
+          const row = msg.toolCalls.find((t) => t.approvalId === l.approvalId) || msg.toolCalls[msg.toolCalls.length - 1]
+          if (row && row.result === undefined) {
+            row.approvalId = l.approvalId
+            if (l.command) row.command = l.command
+            row.needsApproval = true
+          }
+          break
+        }
+        case 'approval-decided': {
+          const row = msg.toolCalls.find((t) => t.approvalId === l.approvalId)
+          if (row) {
+            row.needsApproval = false
+            row.approvalNote = l.ok
+              ? l.scope === 'turn' ? '本回合已授权，不再询问' : '已确认执行'
+              : l.reason ? `已拒绝执行（${l.reason}）` : '已拒绝执行'
+            row.autoApproved = false
+          }
+          break
+        }
+        case 'approval-auto': {
+          const row = msg.toolCalls[msg.toolCalls.length - 1]
+          if (row) {
+            row.autoApproved = true
+            row.approvalNote = '免确认策略命中，已自动执行'
+            if (l.command) row.command = l.command
+          }
+          break
+        }
+        case 'notice':
+          msg.events.push({ ts: l.ts, level: l.level || 'warn', code: l.code || '', message: l.message || '' })
+          break
+        case 'round-retry':
+          msg.events.push({ ts: l.ts, level: 'warn', code: l.code || 'round-retry', message: l.message || `本步自动重试（第 ${l.attempt}/${l.attempts} 次）` })
+          break
+        case 'turn-end':
+          // 日志收尾行（close 写的）：状态以它为准。中止可能走「上游抛错 → 外层 catch」这条路，
+          // 那条路上不会再发 aborted 事件，只看事件流会把「用户停了」误记成「跑完了」。
+          // 注意与下面的 'turn-ended'（后端预算/熔断的收尾事件）不是同一个东西。
+          if (l.status === 'aborted' || l.status === 'error') msg.status = l.status
+          if (l.error && !msg.error) msg.error = String(l.error)
+          if (l.detached) msg.detached = true
+          // 本回合累计用量 / 前缀缓存命中：随权威历史落盘，刷新后摘要条上的命中率不丢
+          if (l.usage) msg.usage = l.usage
+          break
+        case 'turn-ended':
+          msg.budget = { reason: l.reason || '', message: l.message || '' }
+          break
+        case 'error':
+          msg.error = l.message || ''
+          msg.errorCode = l.code || ''
+          msg.status = 'error'
+          break
+        case 'aborted':
+          msg.status = 'aborted'
+          break
+        default:
+          break
+      }
+    }
+    if (msg.reasoning && !msg.reasoningMs && thinkStartedAt) msg.reasoningMs = Math.max(0, lastTs - thinkStartedAt)
+    // 悬空调用（轮次被中断 / 报错时没等到结果）钉成终止态：与前端 revive 的口径一致
+    if (msg.status !== 'done') {
+      for (const tc of msg.toolCalls) {
+        if (!tc.error && tc.result === undefined) tc.error = '已终止：该调用未拿到结果（轮次被中断）'
+      }
+    }
+    msg.elapsedMs = Math.max(0, lastTs - this.startedAt)
+    return msg
+  }
+}
+
+/**
+ * 开一份回合日志并登记进活跃表（同卡单飞锁保证同一时刻只有一份）。
+ * @returns {TurnJournal|null} 无 cardId 时返回 null（无卡回合不落日志，也无从续跑）
+ */
+export function openJournal({ root, cardId, turnId, startedAt, meta }) {
+  if (!cardId) return null
+  return new TurnJournal({ root, cardId, turnId, startedAt, meta })
+}
+
+/**
+ * 删卡联动：把这张卡的回合日志（含轮转旧档）一并清掉，.cache 里不留孤儿文件。
+ * 若此刻仍有活跃回合（删卡与建卡并发），先摘出活跃表并停止写盘 —— 卡片都没了，
+ * 续跑与权威历史都失去落点，留着反而会在下轮误判「上一轮还在跑」。
+ */
+export function deleteJournal(root, cardId) {
+  const file = journalFile(root, cardId)
+  if (!file) return { ok: false, error: 'missing-card-id' }
+  const live = getLiveJournal(cardId)
+  if (live && live.file === file) {
+    live.closed = true
+    live.file = ''
+    if (live._flushTimer) {
+      clearTimeout(live._flushTimer)
+      live._flushTimer = 0
+    }
+    live._pending = ''
+    if (liveJournals.get(live.cardId) === live) liveJournals.delete(live.cardId)
+  }
+  try {
+    for (const f of [file, file + '.1']) if (fs.existsSync(f)) fs.unlinkSync(f)
+  } catch (e) {
+    return { ok: false, error: String((e && e.message) || e) }
+  }
+  return { ok: true }
+}