fmode-app/src/app/core/assistant-turn.ts

import { FileCard, Message } from './api/models';
import { GroupTurn } from './group-turns';
import { mergeConsecutiveBodies, MergedMessage } from './message-merge';
import {
  isCommandLine,
  isProseLine,
  isToolActivityMessage,
  ProcessStep,
  splitMessage,
} from './message-segments';
import { fmtTime } from './time';
import { Turn } from './turn-aggregator';

/**
 * AI 输出的回合视图模型（2026-11-06 用户需求）
 *
 * ## 为什么要有这一层
 *
 * 用户要求「所有输出在一个固定区域内持续追加，顶部过程区可折叠，
 * 下半部分是正文与文档宫格」，并且**双端、单聊与群聊效果一致**。
 *
 * 但四个页面原本各写一套：桌面单聊是扁平流、桌面群聊是 turn → 容器块、
 * 移动两页又是一套。规则一旦分叉就会漂移（右栏预览就是前车之鉴）。
 *
 * 所以把「回合长什么样」收敛到这里：**纯函数，不依赖 Angular**，
 * 两端共用同一份数据，只在渲染层保留与端相关的样式差异。
 *
 * ## 单聊与群聊的统一
 *
 * - 群聊：一个回合有 N 个块（每个被 @ 的容器一块）
 * - 单聊：同样用块表达，但**固定只有 1 块**（`agentId: null`）
 *
 * 这样上层模板只认 `blocks[]`，不必区分单聊群聊。
 *
 * ## 顶部过程区从哪来
 *
 * 容器的回复把「过程行」和「正文」混在**同一条消息文本**里：
 *
 * ```
 * 我先看一下环境。
 * · bash
 * 找到了，正在改。
 * ```
 *
 * 两步取过程：
 *   ① 纯终端消息（整条都是 `· bash` 这类）→ 整条进过程区
 *   ② 混在正文里的过程行 → 由 `splitMessage` 拆出来
 *
 * 判定全部复用 `message-segments.ts` 的既有口径，**不在本文件新造正则**。
 */

/** 下半区的内容块（顶部过程区已单独抽出，不在此列） */
export type TurnBodyBlock =
  | { kind: 'text'; key: string; message: MergedMessage }
  | { kind: 'file'; key: string; file: FileCard; message: Message }
  | { kind: 'task'; key: string; taskId: string; message: Message };

/** 一个「说话方」在回合内的呈现数据 */
export interface TurnBlockView {
  key: string;
  /** 单聊为 null；群聊为容器 id */
  agentId: string | null;
  /** 群聊成员显示名（由宿主传入 `nameOf` 时才有） */
  agentName?: string;
  /**
   * 容器真实处理耗时（秒）：首条 → 末条 agent 消息。
   *
   * 🔴 UI **不再直接读取**它（读数走 `elapsedSeconds()`），仅保留作数据/诊断用，
   * 以及 `updatedAt <= startAt` 这种退化情形下的兜底。
   */
  seconds: number;
  /**
   * 本块开始时刻（epoch ms；0 = 无锚点）。
   *
   * 2026-11-10 新增：秒数改为**逐秒现算**，锚点必须是时刻而不是秒数，
   * 否则只能靠容器发新事件来「跳一下」。见 `elapsedSeconds()`。
   */
  startAt: number;
  /** 本块最后活动时刻（epoch ms，0 = 无消息）—— 结束态定格用 */
  updatedAt: number;
  /** 顶部过程区 */
  steps: ProcessStep[];
  /** 下半区正文 / 文件 / 任务 */
  body: TurnBodyBlock[];
  /** 文件宫格的数据（从 body 的 file 项抽出，便于模板直接栅格渲染） */
  files: { key: string; file: FileCard }[];
  /** 本块是否仍在输出 */
  live: boolean;
  /**
   * 容器是否**明确宣告本轮结束**（2026-11-11）。
   *
   * 为 true 时 `live` 必定为 false —— 结束信号优先于所有静默窗口。
   * 渲染层可据此把「已完成」写得更肯定（可选，不影响原有判据）。
   */
  turnEnded?: boolean;
  /**
   * 是否仍在**等第一口气**（2026-11-11）。
   *
   * 与 `live` 解耦：`live` 受 25 秒静默窗口约束会提前转 false，
   * 而用户要一直等到 180 秒超时才该失去等待指示。
   * 渲染层应把 `live || waiting` 当作「还在进行中」。
   */
  waiting: boolean;
  /** 本块是否无内容且未在输出（群聊未响应） */
  empty: boolean;
  /**
   * 本块自身合并后的正文（2026-11-07）。
   *
   * 群聊多容器时，**每个容器单独渲染自己的正文**，不能跨容器拼接 ——
   * 用户要求「@ 了三个人就要看出谁说了什么」，拼在一起等于丢失归属。
   * 单聊只有一块，用回合级的 `merged` 即可。
   */
  merged: TurnMergedBody | null;
  /** 用户发出这条消息的时刻（毫秒）。0 = 无锚点（容器主动发言） */
  waitingSince: number;
  /**
   * 构建这一帧时，距用户发消息已经等了多久（毫秒）。
   *
   * 🔴 组件渲染用 `waitingSince` + 实时时钟现算，`waitMs` 只是构建快照，
   *    供纯函数与测试使用（2026-11-09）。
   */
  waitMs: number;
}

export type TurnPhase = 'thinking' | 'replying' | 'done' | 'failed' | 'idle' | 'progressOnly';

/**
 * 整轮合并后的正文（2026-11-07 用户需求）。
 *
 * 用户要求「这一轮对话的所有输出融合到**一张卡片**里，不再是每段单独复制，
 * 顶部折叠思考和操作」。所以正文本不该按容器/消息分段，而应拼成一份。
 */
export interface TurnMergedBody {
  /** 稳定 key（首条正文消息 id），用于模板 track */
  key: string;
  /** 合并后的正文（Markdown） */
  text: string;
  /** 参与合并的消息（末尾那条用于取时间戳、任务引用等元信息） */
  message: Message;
}

/** 一个完整回合：一条用户消息 + 它的全部回复 */
export interface AssistantTurn {
  id: string;
  userMessage?: Message;
  /** 用户在同回合内额外发的文件（群聊「文字 + 多个文件」时） */
  userFiles: Message[];
  blocks: TurnBlockView[];
  phase: TurnPhase;
  /** 容器真实处理耗时（秒，诊断用；UI 读数走 `elapsedSeconds(blocks[i], now)`） */
  seconds: number;
  live: boolean;
  closed: boolean;
  /** 过程步骤总数，用于折叠头「运行了 N 步」 */
  stepCount: number;
  /** 文件总数，用于宫格标题 */
  fileCount: number;
  /**
   * 整轮合并后的正文与文件（2026-11-07）。
   *
   * 「一整轮 = 一张卡」：不管中间隔了多少次工具调用，正文全部拼成一份
   * 给卡片渲染，过程进顶部折叠区，文件进底部宫格。
   *
   * 🔴 **单聊用这个**。群聊多容器时各自独立，见 `blocks[].merged`。
   */
  merged: TurnMergedBody | null;
  /** 整轮的全部文件（跨容器聚合，宫格统一渲染） */
  files: { key: string; file: FileCard }[];
}

/** 构建一块所需的原料（由单聊/群聊两种输入各转一份） */
interface BlockSource {
  agentId: string | null;
  /**
   * 显式块 key（2026-11-11）。
   *
   * 单聊按轮次拆块后，每块 `agentId` 都是 null，若仍用 `agentId ?? 'agent'`
   * 生成 key，多块就会**全部叫 'agent'** → 模板 `@for track` 报 NG0955，
   * 且 `segTime`/`waitLabels`/`targetsOf` 以 key 为字典键，后一轮覆盖前一轮，
   * 读数在 39s / 9s / 43s 之间乱跳（用户实测）。
   *
   * 拆轮时由调用方传 `agent:<首条消息 id>`；不传则回落到旧逻辑。
   */
  key?: string;
  messages: Message[];
  startedAt: number;
  updatedAt: number;
  typing: boolean;
  closed: boolean;
  /**
   * 容器**明确宣告本轮结束**（2026-11-11）。
   *
   * 来源：容器在 `post_llm_call` 发 `m.typing=false`，App 侧
   * `chat.service` 记录该事件的时刻，再按「是否晚于本块末条消息」判定。
   *
   * 语义与 `!typing` 不同：`typing=false` 只是「此刻没在打字」，
   * 两条消息之间的空档也会出现；本字段要求信号**确实在本轮末条消息之后**，
   * 才算「这一轮干完了」。
   */
  turnEnded?: boolean;
}

/* ------------------------------------------------------------------ */
/* 从原始消息派生「过程」与「正文」                                     */
/* ------------------------------------------------------------------ */

/**
 * 把一组消息拆成「顶部过程步骤」与「下半区内容块」。
 *
 * 处理顺序很关键：
 *   1. 先按纯终端消息把整条消息**提走**进过程区（它不该出现在正文里）
 *   2. 剩下的正文消息交给 `mergeConsecutiveBodies` 合并连续片段
 *   3. 合并后再用 `splitMessage` 把夹在正文里的过程行拆出来
 *
 * 🔴 这里不能只认 `block.kind === 'process'`。
 *    `toBlocks()` 有个既有设计：**孤立单步（前后无空行）会被内联成 text**
 *    （`message-segments.ts:281-285`），为的是「只有一个步骤时不必多点一次」。
 *    但在本视图模型里，顶部过程区与下半区必须**严格互斥**，否则
 *    「过程区折叠了、正文里却还留着那一行」。
 *    所以这里按**行**再判一次：`· 工具名` 形态的行一律归过程区。
 */
function splitIntoParts(messages: Message[]): {
  steps: ProcessStep[];
  body: TurnBodyBlock[];
} {
  const steps: ProcessStep[] = [];
  const bodies: Message[] = [];
  /**
   * 容器声明为 `final` 的消息 id（2026-11-11）。
   *
   * 这些消息在 ② 步**不能再被 `divideText` 拆一次** —— 容器已经明确说
   * 「整条是正文」，正文里出现 `cd /opt/...` 这类行也不该被当成命令挪进过程区。
   */
  const forcedFinal = new Set<string>();

  for (const m of messages) {
    const text = m.text ?? '';
    if (!text.trim()) continue;

    /*
     * 🔴 一律按行拆分，不再「整条判成工具活动就丢弃」（2026-11-11 修复）。
     *
     * 原实现：
     *   if (isToolActivityMessage(text) && !proseOf(text)) {
     *     steps.push(...stepsOf(text));   // stepsOf 只取 process 块
     *     continue;                        // ← 同条消息里的正文永远消失
     *   }
     *
     * 后果（用户实测）：容器回一段混排消息，比如
     *   「有的，共 69 行…」 + `**已上云（可直接下载）**` + 两行 `🐍 Running code…`
     * 工具行严格过半 → 整条进过程区 → 那句结论和文件名**再也看不到**。
     *
     * 现在交给 `divideText` 逐行判：工具行 / 命令行进过程区，
     * 其余（含结论、markdown 加粗、列表）留在正文。
     */

    /*
     * 🔴 容器声明了类别就**完全听它的**（2026-11-11）。
     *
     * 这是根治「日志吞正文」的路径：文本启发式永远有误判（正文里出现代码块、
     * 命令行、英文列表都可能被当成过程）。容器自己知道哪条是过程、哪条是结论。
     *
     * 容器改造完成前该字段缺失 → 自动落回下面的启发式，行为不变。
     */
    if (m.fmodeKind === 'process') {
      /* 整条进过程区：不再逐行猜，避免把里面的中文切成「正文」 */
      for (const line of text.split('\n')) {
        const t = line.trim();
        if (t) steps.push({ kind: 'tool', label: t });
      }
      continue;
    }
    if (m.fmodeKind === 'final') {
      /* 整条是正文：即使里面看起来像命令行，也不拆（②' 步会跳过它） */
      bodies.push(m);
      forcedFinal.add(m.id);
      continue;
    }

    const { steps: s, text: kept } = divideText(text);
    steps.push(...s);
    if (kept.trim()) bodies.push(kept.trim() === text.trim() ? m : { ...m, text: kept.trim() });
  }

  /*
   * ② 合并连续正文。
   *    带附件的消息由 `mergeConsecutiveBodies` 内部规则挡住（见 message-merge.ts 注释），
   *    它们不进 `bodies`，单独成块。
   */
  const merged = mergeConsecutiveBodies(bodies);
  const body: TurnBodyBlock[] = [];

  for (const mm of merged) {
    /*
     * 容器声明为 final 的正文**不做二次拆分**（2026-11-11）。
     * 合并后仍按 `mergedIds` 判断：只要**所有**参与合并的消息都是 final，
     * 整段就当正文；否则走启发式（混合情况下以启发式为准更安全）。
     */
    const allFinal = mm.mergedIds.length > 0 && mm.mergedIds.every((id) => forcedFinal.has(id));
    if (allFinal) {
      if ((mm.text ?? '').trim()) {
        body.push({ kind: 'text', key: mm.mergedIds[0], message: { ...mm, text: (mm.text ?? '').trim() } });
      }
      if (mm.file) body.push({ kind: 'file', key: `${mm.mergedIds[0]}-f`, file: mm.file, message: mm });
      if (mm.taskId) body.push({ kind: 'task', key: `${mm.mergedIds[0]}-t`, taskId: mm.taskId, message: mm });
      continue;
    }
    const { steps: s, text } = divideText(mm.text ?? '');
    steps.push(...s);

    if (text.trim()) {
      body.push({ kind: 'text', key: mm.mergedIds[0], message: { ...mm, text: text.trim() } });
    }
    if (mm.file) {
      body.push({ kind: 'file', key: `${mm.mergedIds[0]}-f`, file: mm.file, message: mm });
    }
    if (mm.taskId) {
      body.push({ kind: 'task', key: `${mm.mergedIds[0]}-t`, taskId: mm.taskId, message: mm });
    }
  }

  /*
   * ③ 只有附件、没有正文的消息不会被 `mergeConsecutiveBodies` 输出（它只处理 text），
   *    这里补回来，否则「容器只回了一个文件」会整个消失。
   */
  for (const m of messages) {
    if (!m.file && !m.taskId) continue;
    const covered = body.some((b) => b.message.id === m.id);
    if (covered) continue;
    if (m.file) body.push({ kind: 'file', key: `${m.id}-f`, file: m.file, message: m });
    if (m.taskId) body.push({ kind: 'task', key: `${m.id}-t`, taskId: m.taskId, message: m });
  }

  return { steps, body };
}

/**
 * 从一段文本里取过程行（返回 steps）。
 * 纯终端文本直接用 `splitMessage` 的 process 块。
 */
function stepsOf(text: string): ProcessStep[] {
  const out: ProcessStep[] = [];
  for (const b of splitMessage(text)) {
    if (b.kind === 'process') out.push(...b.steps);
  }
  return out;
}

/**
 * 把一段**混合**文本拆成「过程步骤」与「纯正文」。
 *
 * 两步：
 *   ① `splitMessage` 能识别的 process 块 → 步骤
 *   ② 剩下的 text 块里，仍可能有被 `toBlocks` 内联的单步行（`· bash`），按行再剥一次
 *
 * 返回的 text 已不含过程行，顶部折叠后正文不会再出现一遍。
 */function divideText(text: string): { steps: ProcessStep[]; text: string } {
  const steps: ProcessStep[] = [];
  const keep: string[] = [];

  /*
   * 🔴 先按代码围栏切段，再在段内逐行拆（2026-11-11 修复空代码块）。
   *
   * 原来直接对整条文本逐行判：闭合围栏 ``` 被 `isCommandLine` 当成命令
   * 挪进过程区，正文里只剩开围栏 → markdown 解析出一个**空 `<pre>`**，
   * 叠加 `md-render` 的「复制」按钮，界面上就是一个黑色空块。
   *
   * 现在围栏内的所有行**原样进正文**，不参与任何命令行/步骤判定。
   */
  for (const piece of splitByFences(text)) {
    if (piece.fence) {
      keep.push(...piece.lines);
      continue;
    }
    for (const b of splitMessage(piece.lines.join('\n'))) {
      if (b.kind === 'process') {
        /*
         * 🔴 `splitMessage` 也会把「行首 emoji + 成句中文」解析成 process 块
         *    （`💾 自我升级小结：…了。` 实测如此）。这类是**结论**不是过程，
         *    交还正文，否则折叠区里会出现半句话。
         */
        const prose = b.steps.filter((s) => isProseLine(s.label));
        const tools = b.steps.filter((s) => !isProseLine(s.label));
        steps.push(...tools);
        for (const p of prose) keep.push(p.label);
        continue;
      }
      if (b.kind !== 'text') continue;

      for (const line of b.text.split('\n')) {
        const inline = inlineStepOf(line);
        if (inline && !isProseLine(line)) {
          steps.push(inline);
          continue;
        }
        /*
         * 裸命令行（无 emoji、无 `·` 前缀）也要进过程区（2026-11-11）。
         * 容器会把 `cd /opt/data && node x.js` 直接贴出来 ——
         * 它既不是正文也不带工具标记，光靠 `inlineStepOf` 识别不到。
         */
        if (isCommandLine(line)) {
          steps.push({ kind: 'tool', label: line.trim() });
          continue;
        }
        keep.push(line);
      }
    }
  }

  return { steps, text: keep.join('\n').replace(/\n{3,}/g, '\n\n') };
}

/**
 * 按**成对**代码围栏切成若干段（2026-11-11）。
 *
 * - 围栏行本身与其内部内容 → `fence: true` 段，调用方应整段当正文
 * - 围栏外 → `fence: false` 段，调用方可继续逐行拆
 * - **未闭合**的围栏延续到文末，整段当正文（宁可多显示代码，不要吞内容）
 */
function splitByFences(text: string): { fence: boolean; lines: string[] }[] {
  const FENCE = /^\s*(`{3,}|~{3,})/;
  const out: { fence: boolean; lines: string[] }[] = [];
  let cur: { fence: boolean; lines: string[] } = { fence: false, lines: [] };
  let open: string | null = null;

  const flush = (): void => {
    if (cur.lines.length > 0) out.push(cur);
  };

  for (const line of text.split('\n')) {
    const fm = FENCE.exec(line);
    if (fm) {
      const mark = fm[1][0];
      if (open === null) {
        /* 开围栏：把围栏行放进一个新的 fence 段 */
        flush();
        cur = { fence: true, lines: [line] };
        open = mark;
      } else if (mark === open) {
        /* 闭围栏：收尾当前 fence 段 */
        cur.lines.push(line);
        flush();
        cur = { fence: false, lines: [] };
        open = null;
      } else {
        /* 围栏内出现另一种记号 → 当内容 */
        cur.lines.push(line);
      }
      continue;
    }
    cur.lines.push(line);
  }
  flush();
  return out;
}

/** 行首 `· 工具名` 形态 → 一步；否则 null */
const INLINE_STEP = /^\s*[·•]\s*([a-zA-Z][\w.\-]{0,40})(?:\s*[:：]?\s*(.+))?$/;

function inlineStepOf(line: string): ProcessStep | null {
  const m = INLINE_STEP.exec(line);
  if (!m) return null;
  return { kind: 'tool', label: m[1], detail: m[2]?.trim() || undefined };
}

/**
 * 这条「看起来像终端活动」的文本，其实是一句**结论性叙述**吗？
 *
 * ## 为什么需要（2026-11-07 实测）
 *
 * 容器会这样汇报一次自我升级：
 *
 * ```
 * 💾 自我升级小结：🔧 「multi-artifact-delivery」磨得更锋利了。
 * ```
 *
 * 行首 `💾` 命中了 `TOOL_EMOJI_LEAD`，于是整条被当成工具活动，
 * 折叠头上显示成「运行了 1 步 · 自我升级小结：…」——
 * 用户要读的**结论**被折进了过程区。
 *
 * ## 判定口径（宁可放过、不可误折）
 *
 * 同时满足才算叙述：
 *   ① 以中文句末标点收尾（。！？）
 *   ② 去掉行首 emoji 后，剩下的是一段**中文句子**（至少 6 个汉字）
 *
 * 真正的工具行（`💻 bash`、`✍️ Writing /path`）主体是英文工具名与路径，
 * 不含成句中文，不会被误判。
 */

function proseOf(text: string): boolean {
  const lines = text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
  if (lines.length === 0) return false;
  // 只要有一条是「成句中文」，整条就当正文 —— 终端活动不会夹杂叙述
  return lines.some((line) => {
    if (!/[。！？]$/.test(line)) return false;
    // 剥掉行首的项目符号与 emoji（含变体选择符 / 零宽连接符）
    const body = line
      .replace(/^[\s*·•-]+/, '')
      .replace(/^[\p{Extended_Pictographic}️‍\u{1F3FB}-\u{1F3FF}]+\s*/u, '');
    return (body.match(/[一-龥]/g)?.length ?? 0) >= 6;
  });
}

/* ------------------------------------------------------------------ */
/* 块 → 视图                                                           */
/* ------------------------------------------------------------------ */

/**
 * 默认「还在输出」的静默窗口 —— 与 `turn-aggregator.QUIET_MS` 同源。
 *
 * 🔴 为什么不能用一个短窗口（2026-11-08 用户反馈「只闪一下『正在回复』就消失」）：
 *    容器跑工具时，两段正文之间常有 5–20 秒空档。窗口短于一拍，
 *    回合就被判成「已结束」，界面的「正在思考…」随之消失 ——
 *    而容器其实还在干活，用户无从得知。
 *
 * 调用方应优先传 `QUIET_MS`；这里的字面量只是兜底，两处必须同步修改。
 */
/**
 * 判定「超时」的时长门槛。
 *
 * ## 演进
 *
 * | 时间 | 值 | 原因 |
 * |---|---|---|
 * | 2026-11-10 | 5 分钟 | 初值 |
 * | 2026-11-10 | 3 分钟 | 5 分钟太长（干等），1 分钟太短（误报）→ 折中 |
 * | **2026-11-11** | **5 分钟** | 见下（**语义变了，不能直接沿用旧结论**） |
 *
 * ## 为什么又回到 5 分钟
 *
 * 旧结论「5 分钟太长」成立的前提是：**超时会强行把界面改成「已结束」**，
 * 用户干等 5 分钟看到的是错误的完成状态，所以越短越好。
 *
 * 2026-11-11 用户裁决「应该保持到会话结束」之后，这个前提没了：
 *   · 超时**不再改写状态** —— 长任务跑多久就如实显示多久「输出中」
 *   · 超时只决定**什么时候弹一条提示**，告诉用户「好像有点久」
 *
 * 在这种情况下，短反而有害：
 *   · 容器自己实测跑过 3 分钟以上（它还说过「3 分钟了，值得等」）
 *   · 180 秒会在正常长任务上频繁误报，把提示变成狼来了
 *
 * 5 分钟能覆盖实测到的长任务，同时容器真挂了也不会让用户无限茫然。
 *
 * @see isTurnStalled —— 另一条提示路径：**有输出但长时间无新增**，
 *      门槛是 `STALL_MS`（60 秒），与这里互补，不会重复打扰。
 */
export const TURN_TIMEOUT_MS = 300_000;

const DEFAULT_QUIET_MS = 25_000;

/**
 * 「卡住」门槛：**最后一条输出之后**静止多久算异常。
 *
 * 取 60 秒：容器跑一轮工具调用常有 10~30 秒空档，
 * 1 分钟毫无动静基本可以认定停下了，同时不至于误报。
 *
 * 🔴 位置必须在 `toBlockView` **之前**：它用这个常量做「长任务宽限」，
 *    而模块级 `const` 是从上往下求值的，放到后面会触发 TDZ 报错。
 */
export const STALL_MS = 60_000;

function toBlockView(
  src: BlockSource,
  now: number,
  quietMs: number,
  waitingSince = 0,
  /**
   * 用户已发出消息、但容器还一条都没回（2026-11-09）。
   *
   * 🔴 为什么需要独立标志：
   *    这类回合 `blocks` 为空 → `updatedAt = 0` → `idleFor` 极大 → `live` 恒 false，
   *    于是回合卡根本不会生成，界面在发送后**什么状态都不显示**，
   *    只能干等容器约 10 秒后第一次回话（用户实测「10 秒后才显示正在思考」）。
   *
   *    但「已发出」本身就是一个确定的状态，应该立刻可见。
   */
  awaitingFirstReply = false,
): TurnBlockView {
  const { steps, body } = splitIntoParts(src.messages);
  const files = body
    .filter((b): b is Extract<TurnBodyBlock, { kind: 'file' }> => b.kind === 'file')
    .map((b) => ({ key: b.key, file: b.file }));

  /*
   * live 判定与 `isTurnOpen` 同口径：容器正在 typing，或末条消息至今未超过静默窗口。
   * 群聊里某个成员可能先回完，所以按**块**判断而不是按回合。
   *
   * 🔴 typing 不能无限期作数（2026-11-09）。
   *
   * 实测：容器一轮结束后**不会**发 `m.typing:false`，`peerTyping` 一直停在 true。
   * 这时 `live` 恒为真 → 回合永远「输出中」、永远不会自动折叠
   * （用户实测：内容早已输出完，界面挂着「运行了 2 步 · 163s 输出中」）。
   *
   * 所以 typing 也受静默窗口约束：已经很久没有新内容，就不再信它。
   */
  const idleFor = now - src.updatedAt;
  /*
   * 🔴 typing 窗口收紧为 `quietMs`（2026-11-11 用户实测）。
   *
   * 原来是 `quietMs * 2`（50 秒）：容器明明已经把正文输出完、也不再发新消息，
   * 界面却要继续挂 50 秒「输出中」，用户以为卡住了（截图：20s 那次读数，
   * 实际等了 56 秒才变「已完成」）。
   *
   * 容器结束后**不会发 `m.typing:false`**，所以 typing 迟早要过期；
   * 既然过期后由「静默窗口」接管（同样的 quietMs），就没必要给 typing 双倍宽限 ——
   * 两个窗口对齐后，正文一停、读数也就跟着停，不会多挂 25 秒。
   */
  const typingAlive = src.typing && idleFor < quietMs;
  /*
   * 等待超时收尾（2026-11-10，用户裁决保留）：
   *
   * `awaitingFirstReply` 若恒为真 → `live` 永远 true → 界面永远挂着
   * 「已送达，等待回复…（253s）」，`isTurnTimedOut` 要求 `!live` 永远不成立，
   * 全局提示也就永远不弹。所以等待超过 `TURN_TIMEOUT_MS` 后不再算「还在等」，
   * 交给超时逻辑收尾 → 占位消失、全局提示出现。
   */
  const waitingTooLong =
    awaitingFirstReply && waitingSince > 0 && now - waitingSince >= TURN_TIMEOUT_MS;
  /*
   * 🔴 用户级超时（2026-11-11 口径定稿后必须对**所有**未结束回合生效）。
   *
   * 结束判据改成「只看容器信号」之后，`live` 会在容器不吭声时一直为真。
   * 如果只有「还没回第一条」的回合能超时，那么「回了一半、容器挂了」的回合
   * 会永远转圈 —— 必须有出口，否则是把「提前完成」换成了「永远转圈」。
   *
   * 这是**异常态**出口：页面层据此弹「容器无响应」提示，
   * 与「正常完成」在语义上分得清清楚楚。
   */
  const hardTimedOut =
    waitingSince > 0 && now - waitingSince >= TURN_TIMEOUT_MS;
  /*
   * 🔴 长任务宽限（2026-11-11 用户实测修复）。
   *
   * 用户看到「运行了 2 步 · Writing ... 9s · 已结束 · 无交付」，
   * 而容器其实还在跑。
   *
   * 根因：`idleFor` 用的是**最后一条 agent 消息**的时间，而容器跑长工具时
   * 恰恰不产生消息 —— 20~25 秒空档就足以让 `live` 转 false，
   * 于是「有过程步骤、但没正文」的块被判成 `progressOnly`（已结束）。
   *
   * 现在：**已有过程步骤**说明容器真的在干活，宽限到 `STALL_MS`（60 秒）。
   * 超过 60 秒仍无动静，就交给 `isTurnStalled` 的全局提示（「容器已停止响应」），
   * 两个信号同一常量、互补而不冲突。
   */
  const hasSteps = steps.length > 0;
  const graceMs = hasSteps ? Math.max(quietMs, STALL_MS) : quietMs;
  /*
   * 🔴 「先显示已完成、过很久正文才出来」（2026-11-11 用户实测第二大问题）。
   *
   * ## 现象
   *
   * 用户问天气 → 容器先回一句「我先查一下这三地的实时天气。」→ 然后跑工具、
   * 几十秒后才发真正的结果。第一条消息到达时静默窗口开始倒计时，宽限一过
   * 就被判成 `done`（「已完成」），用户看到「已完成」却没有答案。
   *
   * ## 为什么不能只靠时间窗口
   *
   * 容器是**分条发送**的：它可能在任何时刻停顿 60 秒以上（跑长工具、查网络）。
   * 从「有没有消息」推断「有没有干完」，本质上信息不足。
   *
   * ## 现在的判据（三档，优先级从高到低）
   *
   *   ① 容器**明确宣告结束**（`turnEnded`：✅ reaction / typing=false）
   *      → 立即收尾，这是唯一「确定干完了」的信号
   *   ② 没有任何结束信号，但**本轮已经从用户提问算起跑完了整个超时窗口**
   *      → 才允许判结束（兜底老容器，行为与改造前一致）
   *   ③ 其余情况 → 保持「输出中」，不提前说完成
   *
   * 这样长任务不会再出现「先完成后输出」：只要容器没说结束，
   * 界面就一直如实显示在干活。
   */
  const silentLongEnough =
    waitingSince > 0 && now - waitingSince >= TURN_TIMEOUT_MS;
  /*
   * 🔴 `src.closed` 在有步骤时也要让路。
   *
   * `closed` 是聚合层在静默 `QUIET_MS` 后打的「这轮不再有新消息」标记 ——
   * 它恰恰会在容器跑长工具时打上（跑工具不产生消息）。
   * 若这里仍然 `!src.closed`，宽限就永远用不上，用户照样看到「已结束」。
   *
   * 所以：**没有步骤时**照旧尊重 closed（正常收尾）；
   *        **有步骤时**以时间为准（宽限到 STALL_MS）。
   */
  const closedBlocks = !hasSteps && src.closed;
  /*
   * 🔴 容器明确宣告结束（2026-11-11，`turnEnded`）—— **优先级高于一切时间窗口**。
   *
   * 实测（`scripts/.probe-typing.mjs`，lj-test）：容器 16.8 秒就把正文发完并打了 ✅，
   * 但整轮 105 秒发不出一条结束信号，App 只能等 25 秒（有步骤时 60 秒）静默窗口，
   * 于是「20 秒的活」显示到 50 多秒还在「输出中」（用户实测截图）。
   *
   * 现在容器侧插件在 `post_llm_call` 发 `m.typing=false`，App 侧收到即停：
   *   · 有结束信号 → `live` 立刻为 false，读数定格在末条消息时刻
   *   · 无结束信号（未改造容器）→ 照旧走下面的静默窗口兜底，行为不变
   *
   * ⚠️ 只认「**确认结束**」，不认「没在打字」。容器在两条消息之间的空档也可能发
   *    `typing=false`（本轮结束刷新），若把它当成结束，长工具跑一半就会被切断。
   *    所以信号必须带**轮次标识**，由 `turnEndedFor()` 按「是否晚于本块末条消息」判定。
   */
  const turnEnded = src.turnEnded === true;
  /*
   * 🔴 「还没收到结束信号」→ 不许判完成（2026-11-11）。
   *
   * 这是「先完成后输出」的根治点：容器分条发送时，第一条消息到达后
   * 静默窗口就开始了，宽限一过就显示「已完成」，而真正的答案还在后面。
   *
   * 判据：**有消息、没结束信号、整个超时窗口还没跑完** → 继续算「输出中」。
   *   · 老容器（无信号）：最多多挂到 180 秒超时，之后照常收尾 → 不会永远转
   *   · 新容器：收到 ✅/typing=false 立刻收尾 → 不残留
   *
   * 注意这里**不覆盖** `turnEnded` 和 `waitingTooLong`：
   * 有结束信号就正常结束；超过 180 秒必须有出口，否则卡片永远停不下来。
   */
  /*
   * 🔴 结束以**容器信号**为准，不以时间猜（2026-11-11 用户裁决）。
   *
   * 用户原话：「为什么保持到 90s，应该保持到会话结束」。
   *
   * 他说得对。90 秒是我拍的兜底值，本质还是「用时间猜」——
   * 容器跑 2 分钟的长任务，到 90 秒照样会被标成「已结束」，
   * 这正是用户一直在抱怨的那个毛病。把 60 秒换成 90 秒，只是把问题推迟了 30 秒。
   *
   * 正确判据只有一条：**容器说结束（✅/❌ reaction）才算结束**。
   * 在那之前，只要这一轮**确实在干活**（有过程步骤），就一直算「输出中」。
   *
   * 唯一的出口是用户级超时 `TURN_TIMEOUT_MS`（180 秒）：
   *   · 它由页面层弹「容器无响应」提示，是**明确的异常态**，不是"正常完成"
   *   · 没有它，容器真挂了界面会永远转圈
   *
   * ⚠️ 只在**有过程步骤**时启用：没有步骤的纯文本回合（容器只回一句话），
   *    仍按静默窗口收尾 —— 那种回合发完就是发完了，不该无限挂着。
   */
  const heldOpenByNoSignal =
    hasSteps && !turnEnded && waitingSince > 0;
  /*
   * 🔴 超时**不再强行改写状态**（2026-11-11 用户裁决「应该保持到会话结束」）。
   *
   * 上一版把 `hardTimedOut` 直接塞进 `live`，到点就把回合从「输出中」改成
   * 「已结束」—— 这跟「60 秒猜完成」是同一个错误，只是把猜的时间点挪后。
   * 用户要的是：**干活期间始终如实显示在干活**。
   *
   * 现在超时的作用只剩一个：**让页面层弹「容器无响应」提示**
   * （`isTurnTimedOut` 消费 `waitMs`），状态本身继续如实显示。
   * 用户看到「跑了 8 分钟 + 顺便弹个提示」比「跑到 3 分钟突然说完成」合理得多。
   */
  const live =
    !closedBlocks &&
    !(waitingTooLong && !hasSteps) &&
    !turnEnded &&
    (awaitingFirstReply || typingAlive || idleFor < graceMs || heldOpenByNoSignal);
  /*
   * 「还在等回复」——与 `live` **解耦**（2026-11-11 用户实测修复）。
   *
   * ## 为什么要独立于 live
   *
   * `live` 回答的是「是不是在流式输出」，它受 25 秒静默窗口约束
   * （`QUIET_MS`）—— 容器不回 typing 事件，不这样收尾回合就永远不结束。
   *
   * 但用户看到的是：发完消息，等 25 秒，界面**变成一片空白**
   * （段落被跳过、等待文案返回空串），然后一直空白到第 180 秒才弹超时提示。
   * 中间这 155 秒里没有任何「我在等」的指示（用户实测反馈）。
   *
   * `waiting` 回答的是「用户还在等第一口气」：只要还没超时，就该一直有提示。
   */
  /*
   * 「还在等第一口气」（2026-11-11）—— 与 `live` / `closed` 都解耦。
   *
   * 判据只看三件事：
   *   ① 用户确实发过消息（`waitingSince > 0`）
   *   ② 容器**一条 agent 消息都没回**（`src.messages` 为空）
   *   ③ 还没到 180 秒超时
   *
   * 🔴 为什么不能复用 `awaitingFirstReply`：它在 `turnsFromDm` 里带了
   *    `!t.closed`，而 `closed` 是聚合层在 25 秒静默后打的标记，远早于用户的
   *    超时判定。复用它会让「回合收尾 → live=false → waiting=false」同时成立，
   *    界面正好掉进那段纯空白（用户实测反馈的正是这个）。
   *
   * 🔴 为什么不能写成 `!src.closed`：`toBlockView` 拿不到 `t.closed`，
   *    而且上一条的理由说明这个标记本来就不该参与用户等待的语义。
   */
  const waiting =
    awaitingFirstReply && src.messages.length === 0 && waitingSince > 0 && !waitingTooLong;

  /*
   * 用时读数（2026-11-10 合并口径）：
   *
   * | 字段 | 锚点 | 用途 |
   * |---|---|---|
   * | `startAt`   | **用户发出问话的时刻** | 头部与段头的实时读数（1→2→3… 每秒加） |
   * | `seconds`   | 首条 → 末条 agent 消息 | 容器**真实处理耗时**，结束时定格，不跳变 |
   *
   * 进行中的读数由渲染层用每秒时钟现算（`elapsedSeconds()`），
   * 不再用「消息事件时间戳相减」——那样只会 5s → 18s → 30s 地跳。
   */
  const startAt = waitingSince > 0 ? waitingSince : src.startedAt;

  return {
    key: src.key ?? src.agentId ?? 'agent',
    agentId: src.agentId,
    /** 容器真实处理耗时（首条 → 末条 agent 消息），结束才有意义 */
    seconds:
      src.startedAt > 0 && src.updatedAt >= src.startedAt
        ? Math.max(0, Math.round((src.updatedAt - src.startedAt) / 1000))
        : 0,
    /** 本块开始时刻（epoch ms，0 = 无锚点）—— 逐秒读数的锚点 */
    startAt,
    updatedAt: src.updatedAt,
    steps,
    body,
    files,
    live,
    turnEnded,
    waiting,
    empty: !live && !waiting && body.length === 0 && steps.length === 0,
    merged: mergeBodies([{ body }]),
    waitingSince,
    waitMs: waitingSince > 0 ? Math.max(0, now - waitingSince) : 0,
  };
}

/**
 * 由各块合成回合阶段。
 *
 * 🔴 2026-11-10：「已完成」必须真的代表**有东西交付给用户**。
 *
 * 原判据是「只要不是全空就算 done」，于是容器只回了一串内部进度
 * （`🐍 Running code…` + 一句日志）时，卡片照样标「已完成」，
 * 用户打开一看什么也没有（实测截图）。
 *
 * 现在区分三档：
 *   · 有正文 或 有文件 → `done`（真的交付了）
 *   · 只有过程步骤、没有正文也没有文件 → `progressOnly`（干了活，但没交付）
 *   · 什么都没有 → `idle`
 */
function phaseOf(blocks: TurnBlockView[], closed: boolean): TurnPhase {
  if (blocks.some((b) => b.live && (b.body.length > 0 || b.steps.length > 0))) return 'replying';
  if (blocks.some((b) => b.live)) return 'thinking';
  if (blocks.length === 0) return closed ? 'idle' : 'thinking';

  const delivered = blocks.some((b) => b.body.length > 0 || b.files.length > 0);
  if (delivered) return 'done';
  // 只剩过程步骤：做过事，但没有可交付的内容
  return blocks.some((b) => b.steps.length > 0) ? 'progressOnly' : 'idle';
}

/**
 * 一块的**当前**用时秒数（2026-11-10 用户要求：一秒一秒叠加）。
 *
 * | 状态 | 返回值 |
 * |---|---|
 * | 无锚点（`startAt <= 0`） | 0，不显示 |
 * | 已结束（`!live`） | 从用户发问到结束的总用时（定格） |
 * | 进行中 | `floor((now - startAt) / 1000)`，**逐秒递增** |
 *
 * 🔴 进行中必须用实时时钟现算。原来直接用结束时刻相减，
 *    只在容器发新事件那一跳才变，用户看到的是 5s → 18s → 30s 的跳变。
 *
 * 取整一律 `floor`：进行中与结束态用同一种口径，结束瞬间才不会倒退 1 秒。
 *
 * @param block 块视图
 * @param now   当前时间（组件每秒刷新一次的那个时钟）
 */
export function elapsedSeconds(block: TurnBlockView, now: number): number {
  if (block.startAt <= 0) return 0;
  /*
   * 🔴 结束态与进行中必须**同口径**，否则读数会倒退（2026-11-11 用户实测）。
   *
   * 进行中显示 `now - startAt` —— 这是用户体感的等待时长，包含容器思考的空档。
   * 原来结束后切成 `updatedAt - startAt`（末条 agent 消息时刻），
   * 但 `updatedAt` 只到「最后一条 agent 消息」，比用户实际等的短：
   * 用户等了 56 秒，一结束读数瞬间掉回 20 秒，看起来像计时坏了。
   *
   * 🔴 2026-11-11 二次修正：有**结束信号**时定格在末条消息时刻。
   *
   * 容器侧插件现在会发 `m.typing=false`，所以「正文发完」到「界面收尾」之间
   * 不再有 25/60 秒的空转。此时若仍读到 `now`，末条消息之后到信号到达的那一两秒
   * 会被算进读数，与 `seconds`（容器真实处理耗时）对不上。
   * 有信号时用 `updatedAt`（末条消息），读数即为容器真实耗时，精确且不再倒退。
   *
   * 只有在**没有结束信号**（未改造的老容器）时，才保留「用户体感时长」口径 ——
   * 因为那种情况下收尾是猜的，读数取 `now` 才不会在判定结束前突然跳跃。
   */
  if (!block.live) {
    if (block.updatedAt <= block.startAt) return block.seconds;
    /*
     * 定格到「末条活动时刻」。`now` 只用来兜住时钟尚未推进的边界，
     * 不额外加宽限 —— 宽限值是拍脑袋的，会让读数与测试/实际都对不上。
     */
    const endAt = Math.min(now, block.updatedAt);
    return Math.max(0, Math.floor((endAt - block.startAt) / 1000));
  }
  return Math.max(0, Math.floor((now - block.startAt) / 1000));
}

/**
 * 等待中的占位文案（2026-11-09 用户裁决）。
 *
 * | 阶段 | 判据 | 文案 |
 * |---|---|---|
 * | 已发出，还没有任何输出 | `live` 且无内容 | 8 秒内「正在思考…」；之后「已送达，等待回复…（Ns）」 |
 * | 开始输出 | `live` 且有内容 | 「正在输出…（Ns）」 |
 * | 结束且全空 | 非 live 且 empty | **空**（不再显示「未响应」气泡） |
 *
 * 🔴 文案要**一直兜底到回复真的回来**，中途不能消失：
 *    容器回一轮要十几秒，界面空白会被理解成「发了没反应」。
 *
 * 🔴 2026-11-10 用户裁决：**超时不再在会话里留「未响应」气泡**。
 *
 * 原实现回合结束后恒显示一个「⊙ 未响应」的小气泡，永远留在消息流里，
 * 看起来像「每条都失败了」。改为：
 *   · 会话内**完全移除**该占位（返回空串，段级判据同步不再渲染）
 *   · 由页面层弹**全局提示**（可手动关闭、不自动消失），见 `useTurnTimeout()`
 *
 * @param waitMs 距用户发出消息已经过了多久
 * @param hasOutput 是否已经开始输出内容
 * @param live 是否仍在进行中
 * @param empty 是否已结束且什么也没有
 */
export function waitText(
  waitMs: number,
  hasOutput: boolean,
  live: boolean,
  empty: boolean,
  /**
   * 锚点时刻（epoch ms）：用户发出这条问话的时刻（2026-11-11）。
   *
   * 传了就带上起始时刻，让用户知道「从几点开始等的」——
   * 只显示「正在思考…」时，用户分不清是刚发出还是已经卡了五分钟，
   * 也不知道该不该刷新。0 / 缺省 = 不显示时刻（保持旧行为，老调用点不受影响）。
   */
  startAt = 0,
): string {
  // 已结束：无论有没有内容，都不再留等待占位（超时提示交给全局 toast）
  if (!live) return '';
  const sec = Math.max(0, Math.round(waitMs / 1000));
  const at = startAt > 0 ? `${fmtTime(startAt)} ` : '';
  if (hasOutput) return sec > 0 ? `正在输出…（${sec}s）` : '正在输出…';
  if (waitMs < WAIT_HINT_MS) {
    return at ? `已送达 ${at}· 正在思考…（${sec}s）` : '正在思考…';
  }
  return sec > 0
    ? `${at ? `${at}已送达` : '已送达'}，等待回复…（${sec}s）`
    : '已送达，等待回复…';
}

/** 超过这个时长就明确告诉用户「发出了、在等」，不再只是「正在思考」 */
export const WAIT_HINT_MS = 8_000;

/**
 * 判定「这一轮是否已经超时未响应」（2026-11-10）。
 *
 * 超时 = 用户已发出消息、但经过 `timeoutMs` 仍**没有任何 agent 输出**，且回合已结束。
 * 页面据此弹全局提示（手动关闭）。
 *
 * @param waitMs  距用户发出消息的毫秒数
 * @param hasOutput agent 是否已经有正文或步骤
 * @param live    回合是否仍在进行
 */
export function isTurnTimedOut(
  waitMs: number,
  hasOutput: boolean,
  live: boolean,
  timeoutMs = TURN_TIMEOUT_MS,
): boolean {
  return !live && !hasOutput && waitMs >= timeoutMs;
}

/**
 * 判定「容器卡住了」（2026-11-11）。
 *
 * ## 与 `isTurnTimedOut` 的分工
 *
 * | 情况 | 判据 | 函数 |
 * |---|---|---|
 * | 发了之后**一个字都没回**，超过 3 分钟 | `!live && !hasOutput && wait >= 180s` | `isTurnTimedOut` |
 * | 回了**一部分**就停住，不再有任何新增 | `hasOutput && 静止 >= 60s` | `isTurnStalled` |
 *
 * 🔴 为什么必须有第二个：容器常常先回一句「我先看一下这个文件」、
 *    跑了两步工具，然后就再没有下文了（用户实测截图 09:51 之后一片空白）。
 *    这时 `hasOutput === true`，`isTurnTimedOut` **永远返回 false** ——
 *    界面停在「已结束」但没有任何提示，用户只能干等。
 *
 * 这里的「静止」用**最后一条消息到现在的时长**，不是用户发问时长：
 * 容器跑长任务时应该一直在产生工具活动，持续 1 分钟毫无动静即为异常。
 *
 * @param idleMs   距本回合**最后一次** agent 活动的毫秒数
 * @param hasOutput agent 是否已经有正文或步骤
 * @param live     回合是否仍在进行（还在 live 说明 Quartz 静默窗口还没过）
 */
export function isTurnStalled(
  idleMs: number,
  hasOutput: boolean,
  live: boolean,
  stallMs = STALL_MS,
): boolean {
  /*
   * 🔴 2026-11-11 口径定稿后修正：**不再要求 `!live`**。
   *
   * 旧判据假设「live 说明还在动」，但现在 `live` 的语义变成了
   * 「这一轮还没收到结束信号」—— 长任务卡死时它会一直为真，
   * 于是「容器无响应」提示永远不会弹，用户只能干等。
   *
   * 正确的判据是**有没有新东西进来**：已经有输出、但连续 `stallMs` 毫无新增，
   * 无论 live 与否都该提醒用户「可能卡住了」。
   * 它只是**提示**，不改状态 —— 容器真有动静了，下一次渲染提示自然消失。
   */
  /* 一个字都没回的由 `isTurnTimedOut` 负责，两处不重叠 */
  if (!hasOutput) return false;
  return idleMs >= stallMs;
}

/* ------------------------------------------------------------------ */
/* 两种输入 → 统一的回合视图                                           */
/* ------------------------------------------------------------------ */

/**
 * 群聊：`buildGroupTurns` 的结果 → 回合视图。
 *
 * 每个 `GroupBlock` 对应一个块；块顺序保持 `targets` 的声明顺序。
 */
export function turnsFromGroup(
  turns: GroupTurn[],
  now: number,
  quietMs = DEFAULT_QUIET_MS,
  nameOf?: (agentId: string) => string,
): AssistantTurn[] {
  return turns.map((t) => {
    const blocks = t.blocks.map((b) => {
      const view = toBlockView(
        {
          agentId: b.agentId,
          messages: b.messages,
          startedAt: b.startedAt,
          updatedAt: b.updatedAt,
          typing: b.typing,
          closed: b.closed,
        },
        now,
        quietMs,
        t.userMessage ? Date.parse(t.userMessage.ts) || 0 : 0,
        /*
         * 群聊里「这一块还没收到任何回复」= 等待中（2026-11-09，与单聊同口径）。
         *
         * 原来空块的 `updatedAt = 0` 会让 `idleFor` 极大，`live` 恒 false，
         * 于是卡片是个空壳、没有文字 —— 用户看不到「谁在思考」（实测）。
         */
        b.messages.length === 0 && !b.closed,
      );
      const name = nameOf?.(b.agentId);
      return name ? { ...view, agentName: name } : view;
    });

    const live = blocks.some((b) => b.live);

    return {
      id: t.id,
      userMessage: t.userMessage,
      userFiles: t.userFiles ?? [],
      blocks,
      phase: phaseOf(blocks, t.closed),
      // 与块级同口径：从用户发消息起算，live 时走当前时钟（时间戳取自原始块）
      seconds: roundSeconds(t.blocks, now, live, t.userMessage ? Date.parse(t.userMessage.ts) || 0 : 0),
      live,
      closed: t.closed,
      stepCount: blocks.reduce((n, b) => n + b.steps.length, 0),
      fileCount: blocks.reduce((n, b) => n + b.files.length, 0),
      merged: mergeBodies(blocks),
      files: collectFiles(blocks),
    };
  });
}

/**
 * 单聊：`buildTurns` 的结果 → 回合视图（固定 1 块）。
 *
 * @param typing   容器是否在 typing（容器大多不发，通常为 false）
 * @param quietMs  「还在输出」的静默窗口，调用方传 `QUIET_MS`
 * @param agentIdle 容器**明确上报**的空闲态。为 true 时忽略静默窗口直接收尾 ——
 *                  只有容器能宣布「我干完了」，比任何时间窗都准。
 * @param turnEndedAfter 收到容器 `m.typing=false` 时，本会话最后一条 agent 消息的 id
 *                       （null = 无信号）。只有「本块末条消息就是这个 id」才认它结束。
 */
export function turnsFromDm(
  turns: Turn[],
  now: number,
  typing: boolean,
  quietMs = DEFAULT_QUIET_MS,
  agentIdle = false,
  turnEndedAfter: string | null = null,
): AssistantTurn[] {
  return turns.map((t) => {
    /*
     * 🔴 拆成两个概念（2026-11-11）：
     *
     * `awaitingFirstReply`（live 用）：要求 `!t.closed` —— 回合静默收尾后
     *    `live` 该转 false，否则卡片永远不收尾（2026-11-10 的裁决，保留）。
     *
     * `pendingReply`（waiting 用）：**不看 closed** —— `closed` 是聚合层在
     *    25 秒静默后打的标记，远早于用户的 180 秒超时。若它也否认「还在等」，
     *    界面从第 25 秒起就是一片空白，直到第 180 秒才弹提示（用户实测反馈）。
     *
     * 所以「有用户提问 + 容器一条都没回 + 没超时」就是还在等，与 closed 无关。
     */
    const hasUserAsk = !!t.userMessage;
    const noAgentReply = t.blocks.length === 0;
    const awaitingFirstReply = hasUserAsk && noAgentReply && !t.closed;
    const pendingReply = hasUserAsk && noAgentReply;
    const userAsk = t.userMessage ? Date.parse(t.userMessage.ts) || 0 : 0;
    /*
     * 🔴 按「轮次」拆块（2026-11-10）—— **收窄触发条件**（2026-11-11）。
     *
     * 拆轮原本是为了「图 + 文字各跑一轮时分别计时」。
     * 但它按「相邻消息间隔 > 20 秒」（`ROUND_GAP_MS`）切分，而容器跑一个
     * 长工具时**本来就不产生消息** —— 于是普通长任务被误切成 2~4 轮，
     * 每轮各自判断 live，出现「有的块已完成、有的块还在跑」的混乱观感，
     * 且所有块 key 都叫 `agent` 导致 NG0955。
     *
     * 现在只在**确实有多个用户提问**（图文各发一条）时才拆轮；
     * 单次提问不论间隔多久都只出 1 块。
     */
    const askCount = (t.userAskTimes ?? []).filter((a) => a > 0).length;
    const canSplit = askCount > 1 && (t.rounds?.length ?? 0) > 1;
    const rounds: Message[][] = canSplit
      ? t.rounds!
      : t.blocks.length > 0
        ? [t.blocks]
        : [];
    /*
     * 没有 agent 消息时也要有**一个**占位块，否则「已发出、等回复」的标志
     * （`awaitingFirstReply`）无处挂载，卡片会整张消失。
     */
    const usedKeys = new Set<string>();
    const blocks = rounds.length
      ? rounds.map((msgs, idx) => {
          const times = msgs.map((m) => Date.parse(m.ts) || 0).filter((n) => n > 0);
          const first = times.length ? Math.min(...times) : 0;
          const last = times.length ? Math.max(...times) : 0;
          /*
           * 本轮读秒锚点 = **不晚于本轮首条消息的最后一个用户提问时刻**。
           * 图文被拆成两条时：图片那轮用图片的发出时刻，文字那轮用文字的发出时刻，
           * 两轮读数各算各的，不会互相拉高，也不会在结束瞬间倒退。
           */
          const asks = (t.userAskTimes ?? []).filter((a) => a > 0 && (first === 0 || a <= first));
          const startAt = asks.length ? Math.max(...asks) : first || userAsk;
          /* key 必须唯一：多块共用 'agent' 会触发 NG0955 且让读数互相覆盖 */
          const base = `agent:${msgs[0]?.id ?? `r${idx}`}`;
          const key = usedKeys.has(base) ? `${base}:${idx}` : base;
          usedKeys.add(key);
          return toBlockView(
            {
              agentId: null,
              key,
              messages: msgs,
              startedAt: first,
              updatedAt: last,
              typing,
              closed: t.closed,
              /*
               * 结束信号按**消息 id** 认领（2026-11-11）：
               * 收到 `typing=false` 时记下的末条 agent 消息 id，必须正好是本块的末条。
               * 不跨时钟比较（服务端 ts vs 本地时钟会差 1~2 秒），
               * 也天然挡住了「上一轮的信号误伤这一轮」。
               */
              turnEnded:
                turnEndedAfter != null &&
                msgs.length > 0 &&
                msgs[msgs.length - 1]?.id === turnEndedAfter,
            },
            now,
            agentIdle ? 0 : quietMs,
            startAt,
            false,
          );
        })
      : [
          toBlockView(
            {
              agentId: null,
              key: 'agent:wait',
              messages: [],
              startedAt: 0,
              updatedAt: 0,
              typing,
              closed: t.closed,
            },
            now,
            agentIdle ? 0 : quietMs,
            userAsk,
            pendingReply,
          ),
        ];
    const live = blocks.some((b) => b.live);

    return {
      id: t.id,
      userMessage: t.userMessage,
      userFiles: t.userFiles ?? [],
      blocks,
      phase: phaseOf(blocks, t.closed),
      /* 回合用时取最长的块（各轮并行跑，按最长那轮算体感） */
      seconds: blocks.reduce((max, b) => Math.max(max, b.seconds), 0),
      live,
      closed: t.closed,
      stepCount: blocks.reduce((n, b) => n + b.steps.length, 0),
      fileCount: blocks.reduce((n, b) => n + b.files.length, 0),
      /*
       * 单聊的正文仍**合并成一份**（2026-11-07 用户要求「一整轮一张卡」）。
       * 拆轮只为了分别计时与分别判定状态，不改变阅读形态。
       */
      merged: mergeBodies(blocks),
      files: collectFiles(blocks),
    };
  });
}

/** 整轮的全部文件（跨容器聚合，宫格统一渲染） */
function collectFiles(blocks: TurnBlockView[]): { key: string; file: FileCard }[] {
  const seen = new Set<string>();
  const out: { key: string; file: FileCard }[] = [];
  for (const b of blocks) {
    for (const f of b.files) {
      // 同名同大小的重复文件只出一张卡（多容器转发同一份时）
      const sig = `${f.file.name}|${f.file.size ?? 0}|${f.file.url}`;
      if (seen.has(sig)) continue;
      seen.add(sig);
      out.push(f);
    }
  }
  return out;
}

/**
 * 把整轮所有块的正文拼成一份。
 *
 * 块之间用空行分隔（Markdown 段落边界），保持可读；
 * key 取首条正文消息 id，**不随内容增长而变** —— 否则流式时模板会重建 DOM。
 */
function mergeBodies(blocks: { body: TurnBodyBlock[] }[]): TurnMergedBody | null {
  const parts: string[] = [];
  let first: Message | null = null;
  let last: Message | null = null;

  for (const b of blocks) {
    for (const part of b.body) {
      if (part.kind !== 'text') continue;
      const t = (part.message.text ?? '').trim();
      if (!t) continue;
      parts.push(t);
      if (!first) first = part.message;
      last = part.message;
    }
  }
  if (!first || !last) return null;

  return { key: first.id, text: parts.join('\n\n'), message: last };
}

/** 回合耗时：首条 agent 消息到末条（各块取并集，避免多块重复计算） */
/**
 * 回合级耗时（群聊汇总用）。
 *
 * 🔴 必须与块级 `toBlockView` 同一口径（2026-11-10），否则同一张卡片上
 *    段头写一个数、汇总写另一个数，用户会以为界面在乱跳。
 *
 * 口径：从**用户发出消息**起算。live 时取当前时钟（稳定递增），
 *       结束后冻结在最晚的一条消息时间。多块之间取「最大结束 - 用户消息」，
 *       也就是「这一轮最忙的那个成员干完为止」。
 */
function roundSeconds(
  blocks: { startedAt: number; updatedAt: number }[],
  now: number,
  live: boolean,
  waitingSince: number,
): number {
  const starts = blocks.map((b) => b.startedAt).filter((n) => n > 0);
  const ends = blocks.map((b) => b.updatedAt).filter((n) => n > 0);
  // 锚点优先取用户消息，没有才回落到最早的一条 agent 消息
  const anchor = waitingSince > 0 ? waitingSince : starts.length ? Math.min(...starts) : 0;
  if (anchor <= 0) return 0;
  const endAt = live ? now : ends.length ? Math.max(...ends) : 0;
  if (endAt < anchor) return 0;
  return Math.max(0, Math.round((endAt - anchor) / 1000));
}

/** 便捷入口：判断回合里是否有该文件（避免模板里重复过滤） */
export function hasFiles(t: AssistantTurn): boolean {
  return t.fileCount > 0;
}