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; /** * 本回合里**早于 `userMessage`** 的提问(2026-11-11)。 * * 用户连发多条时并入同一回合:`userMessage` 是最新那条, * 前面几条按时间顺序放这里。渲染层要先展示它们,用户才看得到自己说过什么。 */ priorAsks?: 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-16)。 * * ## 为什么需要 * * 容器发文件的机制(2026-11-16 向 `agent-node-lj-test` 核实,容器原话): * 「我在正文里写 `MEDIA:/绝对路径`,由 Matrix 适配器解析后以 m.file 附件事件发出, * 同时正文保留文本。」 * * 正常情况下「几个 MEDIA 标记 = 几个 m.file 事件」。但容器也承认会出现: * 「标记存在但适配器没有为它们生成对应的事件……实际只到了部分文件」。 * * 这时用户在正文里看得见 3 个链接,卡片区却只有 2 张,**没有任何提示**—— * 看起来像 App 吞了一个文件。 * * 容器的建议原话: * 「最可靠的是数附件事件,而不是数正文链接……两者不一致就按『缺卡片』处理。」 * * 所以这里只做**对账提示**,不伪造卡片:正文里数到 N 个,附件事件只有 M 个, * 差多少就告诉用户多少。真正的补齐在容器侧(适配器要为每个标记生成事件)。 * * 只统计**明确的 MEDIA 标记**与**可识别的附件链接**,不做模糊猜测 —— * 正文里随便一句 URL 不该被当成「文件丢失」。 */ missingFileCount: 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(); 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 解析出一个**空 `
`**,
   * 叠加 `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,
  /**
   * 容器**明确**上报的本会话空闲态(2026-11-11)。
   *
   * 三态:`true` 明确空闲 → 直接收尾(与 ✅ reaction 同级的事实信号);
   * `false` 明确在跑;`undefined` 不知道 → 不参与判定。
   *
   * 用户实测:右上角已显示「在线」(容器报 idle),卡片却还挂着「50s 输出中」。
   * 根因就是这里只把 `quietMs` 置 0,而「有步骤 + 无信号」的保持逻辑不看它。
   */
  agentIdle: boolean | undefined = undefined,
) : TurnBlockView {
  const { steps, body } = splitIntoParts(src.messages);
  /*
   * 🔴 同一文件只出一张卡(2026-11-14 用户截图实证)。
   *
   * 现象:容器回复一张 HTML 表格,界面上出现**两个同名卡片**。
   * 根因:同一个文件在时间线里有两条消息各带一次 `m.file`
   * (一条是插件转发的原始附件,一条是 Agent 回复里附带的那份),
   * 而这里直接 map 出去、不做任何去重。
   *
   * 判据用附件 URL(同一个 s3 对象地址必然相同),退化时用文件名+大小。
   * 保留**先出现**的那条 —— key 更稳定,也与用户阅读顺序一致。
   */
  const seenFiles = new Set();
  const files = body
    .filter((b): b is Extract => b.kind === 'file')
    .filter((b) => {
      const f = b.file;
      /* 优先用云盘地址(同一对象必然相同);退化用 url;再退化用 名字+大小 */
      const id = f.cloudUrl || f.url || `${f.name}|${f.size}`;
      if (seenFiles.has(id)) return false;
      seenFiles.add(id);
      return true;
    })
    .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 秒):
   *   · 它由页面层弹「容器无响应」提示,是**明确的异常态**,不是"正常完成"
   *   · 没有它,容器真挂了界面会永远转圈
   *
   * ⚠️ 只在**有过程步骤**时启用:没有步骤的纯文本回合(容器只回一句话),
   *    仍按静默窗口收尾 —— 那种回合发完就是发完了,不该无限挂着。
   */
  /*
   * 🔴 「有步骤 + 没收到结束信号」→ 保持输出中,但**必须有上限**(2026-11-11)。
   *
   * ## 初版没有上限,导致历史会话永远转圈
   *
   * 初版写成 `hasSteps && !turnEnded && waitingSince > 0` —— 只要回合有工具步骤、
   * 又没收到过 ✅,就永远算 live。
   *
   * 但 **✅ reaction 是实时事件**:打开几天前的历史会话时,
   * 那些回合的 ✅ 早就发生过了、App 根本收不到(不是当前房间的实时流)。
   * 于是每一条历史回合都被判成「还在输出」——
   * 用户实测:「点开历史会话,显示 26208s 输出中,而且文字还在一个个蹦出来」。
   *
   * ## 现在的判据:**只有在「用户刚发出、且还在合理等待窗口内」才保持**
   *
   * 以用户提问时刻为锚点,超过 `LONG_TASK_HOLD_MS`(10 分钟)就不再保持 ——
   *   · 真实长任务:实测容器跑过 3 分钟以上,10 分钟足够覆盖
   *   · 历史会话:`waitingSince` 是几天前,立刻超出 → 正确判成已结束
   *   · 容器真挂了:10 分钟后着陆,由 `isTurnStalled` 弹「无响应」提示,不会永远转
   *
   * 这个上限**小于** `TURN_TIMEOUT_MS`(5 分钟用户级超时)的语义边界:
   * 两者都只是「什么时候停止说在忙」,不改写已经发生的事实。
   */
  const LONG_TASK_HOLD_MS = 10 * 60_000;
  /*
   * 🔴 容器明确说「本会话空闲」→ **立即收尾,优先级高于保持逻辑**(2026-11-11)。
   *
   * 用户实测:右上角已经显示「在线」(容器报了 idle),卡片却还挂着「50s 输出中」。
   * 根因是 `agentIdle` 只把 `quietMs` 置 0,而 `heldOpenByNoSignal` 不看它 ——
   * 「有步骤 + 没 ✅」照样让块保持 live。
   *
   * 这不合理:**容器说空闲** 和 **✅ reaction** 是同一级别的事实信号
   * (都是容器自己宣布「这轮完了」),只是通道不同、到达时刻可能差几秒。
   * 任何一个到了都该收尾。
   */
  const settledBySession = agentIdle === true;
  const heldOpenByNoSignal =
    hasSteps &&
    !turnEnded &&
    !settledBySession &&
    waitingSince > 0 &&
    now - waitingSince < LONG_TASK_HOLD_MS;
  /*
   * 🔴 超时**不再强行改写状态**(2026-11-11 用户裁决「应该保持到会话结束」)。
   *
   * 上一版把 `hardTimedOut` 直接塞进 `live`,到点就把回合从「输出中」改成
   * 「已结束」—— 这跟「60 秒猜完成」是同一个错误,只是把猜的时间点挪后。
   * 用户要的是:**干活期间始终如实显示在干活**。
   *
   * 现在超时的作用只剩一个:**让页面层弹「容器无响应」提示**
   * (`isTurnTimedOut` 消费 `waitMs`),状态本身继续如实显示。
   * 用户看到「跑了 8 分钟 + 顺便弹个提示」比「跑到 3 分钟突然说完成」合理得多。
   */
  const live =
    !closedBlocks &&
    !(waitingTooLong && !hasSteps) &&
    !turnEnded &&
    !settledBySession &&
    (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 地跳。
   */
  /*
   * 🔴 `startAt` 必须在容器思考期间也有效(2026-11-18 修复「已处理 0s」)。
   *
   * ## 原来的问题
   *
   * 原写法 `waitingSince > 0 ? waitingSince : src.startedAt`:
   * `src.startedAt` 由 `turn-aggregator` 在**收到第一条 agent 消息时**才赋值
   * (新建回合时初始化为 0)。容器思考期间还没有任何 agent 消息,
   * 于是 `startedAt === 0` → `elapsedSeconds()` 直接 `return 0`
   * → 界面显示「已处理 **0s**」并一直不动(用户实测)。
   *
   * ## 现在的兜底顺序
   *
   *   ① `waitingSince`  —— 用户发问时刻(最准,含容器思考的空档)
   *   ② `src.startedAt` —— 首条 agent 消息时刻
   *   ③ 0             —— 交给调用方:`elapsedSeconds()` 见 0 返回 0,
   *                        而模板已用 `turnSeconds() > 0` 控制是否显示,
   *                        所以这里绝不会显示成「已处理 0s」。
   *
   * ⚠️ 不能用 `now` 兜底 —— `now` 每秒变,`startAt` 跟着变会导致读数
   *    永远停在 0(每秒都被重算成新起点)。
   */
  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)} ` : '';
  /*
   * 🔴 已有输出 → **不再显示任何等待文案**(2026-11-13 用户裁决)。
   *
   * 原来这里返回「正在输出…(Ns)」,但它和卡片头的「已处理 Ns」
   * 表达的是同一件事,而且**两个计时器起点不同**(本函数从用户发消息算,
   * `card-running` 从首条 agent 消息算),同一屏出现两个对不上的秒数。
   *
   * 现在:有输出就把时间显示完全交给卡片头。
   * 开局阶段(还没有任何输出)仍保留「正在思考…」「已送达,等待回复…」——
   * 那是用户唯一的反馈,不能省。
   */
  if (hasOutput) return '';
  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);
    const merged = mergeBodies(blocks);
    const collected = collectFiles(blocks);

    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),
      missingFileCount: countMissingFiles(merged?.text ?? '', collected.length),
      merged,
      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,
  /**
   * 容器**明确**上报的本会话空闲态(2026-11-11 统一方案)。
   *
   * 🔴 三态:`true` 明确空闲(直接收尾)/ `false` 明确在跑 / `undefined` 不知道。
   * 初版是布尔且默认 `false`,但调用方传的 `agentIdle()` 曾把「没上报」
   * 当成「空闲」,会误杀所有仍在跑的回合。现在三态分开,`undefined` 不参与判定。
   */
  agentIdle: boolean | undefined = undefined,
  turnEndedAfter: string | null = null,
): AssistantTurn[] {
  return turns.map((t, turnIndex) => {
    /*
     * 🔴 这是不是**最后一个**回合?(2026-11-14 用户实测修复)
     *
     * 场景:任务执行中用户打断并发了新消息 → 旧回合永远等不到容器回复
     * (容器去处理新消息了),于是旧卡片的「等待回复…」转圈**一直挂着**。
     *
     * 判据:后面还有别的用户提问,说明这条已经**过时**了,
     * 不该再显示「等待回复」——用户已经在等更新的一轮。
     */
    const isLastTurn = turnIndex === turns.length - 1;
    /*
     * 🔴 拆成两个概念(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;
    /*
     * 「还在等第一口气」:必须同时是**最后一个**回合。
     * 后面已经有更新的用户提问 → 这条已过时,转圈要停(见 `isLastTurn` 注释)。
     */
    const pendingReply = hasUserAsk && noAgentReply && isLastTurn;
    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 userAskTimes = (t.userAskTimes ?? []).filter((a) => a > 0);
    const askCount = userAskTimes.length;
    /*
     * 🔴 拆轮的真正前提:**每个提问之间都隔着新一轮对话**(2026-11-11 修正)。
     *
     * 用户实测(截图):发第一条后马上补发第二条「以 html 的形式发给我」,
     * 界面出现「已送达等待回复 → 用户第二条 → 容器回复」的错乱顺序。
     *
     * 根因:原判据只看 `askCount > 1`,把「用户连发两条补充说明」也当成两轮,
     * 于是第二条用户消息被挪到两个 agent 块之间渲染。
     *
     * 现在追加一条:**相邻两个提问之间必须有 agent 消息**
     * (即提问 1 → 回复 → 提问 2),才认为真的是两轮。
     * 连发两条(中间容器一句话都没说)视为同一轮,不拆。
     */
    const asks = [...userAskTimes].sort((a, b) => a - b);
    const hasReplyBetweenAsks =
      asks.length > 1 &&
      asks.slice(1).every((at, i) => {
        const prev = asks[i];
        return (t.blocks ?? []).some((m) => {
          const mt = Date.parse(m.ts) || 0;
          return mt > prev && mt < at;
        });
      });
    const canSplit =
      askCount > 1 && hasReplyBetweenAsks && (t.rounds?.length ?? 0) > 1;
    const rounds: Message[][] = canSplit
      ? t.rounds!
      : t.blocks.length > 0
        ? [t.blocks]
        : [];
    /*
     * 没有 agent 消息时也要有**一个**占位块,否则「已发出、等回复」的标志
     * (`awaitingFirstReply`)无处挂载,卡片会整张消失。
     */
    const usedKeys = new Set();
    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 秒),
               * 也天然挡住了「上一轮的信号误伤这一轮」。
               *
               * 🔴 2026-11-14 补充:**不是最后一轮的回合,一律视为已结束**。
               *
               * 用户实测:容器早就回完了,卡片还在「已处理 Ns」继续计时,
               * 而且此时发新消息也没有任何拦截(说明容器侧确实闲了)。
               *
               * 根因:`turnEndedAfter` 只保存**一个**值 —— 最近一次 ✅ 标注的
               * 消息 id。多轮对话里它必然被后续轮次覆盖;更常见的是 ✅ 到达后
               * 又有新消息涌入,`最后一条消息 id` 已经不等于记录时的那条,
               * 严格相等判定永远失败 → 旧卡片永远转。
               *
               * 判据补一条:**后面还有更新的用户提问**(`!isLastTurn`)说明
               * 这一轮早已过去,无论 ✅ 有没有对上,都不该再显示在跑。
               */
              turnEnded:
                !isLastTurn ||
                (turnEndedAfter != null &&
                  msgs.length > 0 &&
                  msgs[msgs.length - 1]?.id === turnEndedAfter),
            },
            now,
            agentIdle === true ? 0 : quietMs,
            startAt,
            false,
            agentIdle,
          );
        })
      : [
          toBlockView(
            {
              agentId: null,
              key: 'agent:wait',
              messages: [],
              startedAt: 0,
              updatedAt: 0,
              typing,
              closed: t.closed,
            },
            now,
            agentIdle === true ? 0 : quietMs,
            userAsk,
            pendingReply,
          ),
        ];
    const live = blocks.some((b) => b.live);

    return {
      id: t.id,
      userMessage: t.userMessage,
      priorAsks: t.priorAsks ?? [],
      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),
      missingFileCount: countMissingFiles(
        mergeBodies(blocks)?.text ?? '',
        collectFiles(blocks).length,
      ),
      /*
       * 单聊的正文仍**合并成一份**(2026-11-07 用户要求「一整轮一张卡」)。
       * 拆轮只为了分别计时与分别判定状态,不改变阅读形态。
       */
      merged: mergeBodies(blocks),
      files: collectFiles(blocks),
    };
  });
}

/** 整轮的全部文件(跨容器聚合,宫格统一渲染) */
function collectFiles(blocks: TurnBlockView[]): { key: string; file: FileCard }[] {
  const seen = new Set();
  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;
}

/**
 * 正文里声明了、但没拿到附件事件的文件数(2026-11-16 真机修复)。
 *
 * ## 背景
 *
 * 向容器 `agent-node-lj-test` 核实(2026-11-16),容器原话:
 *   「我用 `MEDIA:` 标记。在正文里写 `MEDIA:/绝对路径`,由 Matrix 适配器解析后
 *     以 m.file 附件事件发出,同时正文保留文本。」
 *   「(多文件时)标记存在但适配器没有为它们生成对应的事件……实际只到了部分文件。」
 *
 * 于是出现「正文 3 条链接、卡片 2 张」且**毫无提示**。
 *
 * ## 只认明确的标记
 *
 * 只统计两种**确定是容器声明的文件**:
 *   ① `MEDIA:/path` 标记(容器的正式约定)
 *   ② 指向本项目云盘的链接(`s3.fmode.cn` / `file-cloud.fmode.cn`)
 *
 * 不做模糊匹配 —— 正文里随便一句 URL 不该被当成「文件丢失」。
 * 正文里的裸路径(如 `/opt/data/work/x.html`)也不计入:容器发文件时
 * 一定会写 MEDIA 标记或给出可下载链接,裸路径只是解释文字。
 *
 * ## 为什么要去重
 *
 * 同一个文件在正文里可能被提到多次(链接 + MEDIA 标记),
 * 按「文件名」去重后再和卡片数比较,才能得到真实的差。
 *
 * @param text        整轮合并后的正文
 * @param cardCount   实际渲染出的卡片数(已去重)
 * @returns 缺失的文件数;0 表示正文声明数与卡片数吻合
 */
function countMissingFiles(text: string, cardCount: number): number {
  if (!text && cardCount === 0) return 0;
  const declared = new Set();

  // ① MEDIA 标记:`MEDIA:xxx`(容器写的是 MEDIA:/绝对路径)
  for (const match of text.matchAll(/MEDIA:\s*(\S+)/gi)) {
    declared.add(basename(match[1]));
  }

  // ② 云盘链接:只认本项目域名,且取路径最后一段做文件名
  for (const match of text.matchAll(
    /https?:\/\/(?:s3|file-cloud)\.fmode\.cn\/[^\s)\]>'"]+/gi,
  )) {
    declared.add(basename(match[0]));
  }

  /*
   * 🔴 剔除中间产物(2026-11-18)。
   *
   * 容器有时会把 `data.json` / `probe.txt` / `same.txt` 这类辅助文件也列进正文。
   * 它们本来就不是交付物、也不会挂附件卡片,算进「缺失」会让提示一直误报
   * (实测:「还有 4 个文件未收到」,其中 2 个是容器自测的探针文件)。
   *
   * 判据与 `artifact-sync.service.ts::isIntermediateName()` 保持同一套口径。
   */
  for (const name of declared) {
    if (isPaidDeliverableGuess(name) === false) declared.delete(name);
  }

  // 正文里一个明确的文件都没声明 → 谈不上缺失(避免把纯文字回复误判)
  if (declared.size === 0) return 0;
  return Math.max(0, declared.size - cardCount);
}

/**
 * 粗判「这个文件名像不像用户要的交付物」(2026-11-18)。
 *
 * ⚠️ 与 `artifact-sync.service.ts::isIntermediateName()` 是**镜像实现** ——
 *    两个模块分属不同层(core/assistant-turn 与 core/artifact-sync),
 *    为避免循环依赖没有直接 import。改判据时**两处都要改**。
 */
function isPaidDeliverableGuess(fileName: string): boolean {
  const n = (fileName || '').trim().toLowerCase();
  if (!n) return false;
  /* 去掉云盘前缀(`3-mwln7vrfjy-data.json` → `data.json`) */
  /*
   * 剥掉云盘存储名的序号前缀,兼容两种形态:
   *   `3-mwln7vrfjy-data.json`  → `data.json`(数字-随机串-)
   *   `0-probe.txt`             → `probe.txt`(数字-)
   */
  const clean = n.replace(/^\d+-([a-z0-9]{6,}-)?/, '');

  /* 与 artifact-sync.service.ts::isIntermediateName 保持同一口径 */
  const DATA_ONLY = /\.(json|yaml|yml|toml|ini|log|lock)$/;
  if (DATA_ONLY.test(clean) && /^(data|tmp|temp|cache|intermediate|scratch|state)/.test(clean))
    return false;
  if (/^(build|gen|generate|make|run|test|probe)[-_a-z0-9]*\.(py|sh|js|ts|mjs|bat|ps1)$/.test(clean))
    return false;
  if (/^(draft|backup|bak|old|tmp)[-_.]/.test(clean)) return false;
  if (/\.(bak|tmp|swp|orig)$/.test(clean)) return false;
  if (/^(probe|same|wtest)([-_.]|\d)/.test(clean)) return false;
  return true;
}

/** 取路径/URL 最后一段(去掉 query 与 hash),用于按文件名去重比对 */
function basename(pathOrUrl: string): string {
  const noQuery = pathOrUrl.split(/[?#]/)[0];
  const seg = noQuery.split('/').filter(Boolean).pop() ?? noQuery;
  try {
    return decodeURIComponent(seg).toLowerCase();
  } catch {
    return seg.toLowerCase();
  }
}

/**
 * 把整轮所有块的正文拼成一份。
 *
 * 块之间用空行分隔(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;
}