Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

19.5 KB
Raw Blame
/**
 * messageNavRailModel
 * ---------------------------------------------------------------------------
 * MessageNavRail(左缘"提问导航条")的纯逻辑层:条目派生 / 当前提问判定 /
 * 空间与截断规划。全部为无 DOM 依赖的纯函数,按 scrollAnchoringDetect /
 * viewportFillDetect 的既有惯例拆出,在 node 环境直接单测。
 *
 * 组件侧(MessageNavRail.tsx)只负责测量与渲染:把 DOM 几何量喂进来,拿结果画。
 */

import type { ChatMessage } from '@/hooks/useCCAgentChat';
import { isRealAutomationOrigin } from '@/lib/messageAutomationOrigin';
import { stripChatQuoteMarkerLines } from '@/lib/chatQuotes';
import { resolveUserDisplayText } from './userMessageDisplayText';

export interface NavRailEntry {
  /** user 消息的 clientId,同时是 data-message-client-id 锚点值。 */
  id: string;
  /** scheduler 注入的自动化提问;导航条用更短的刻度与手动提问区分。 */
  isAutomation?: boolean;
  /**
   * 提问的单行预览。不是原文首行:user 消息可能带 composer 引用标记行
   * (`> <!-- cindy-composer-quote -->`),直接截原文会把内部标记裸奔进
   * 预览卡(2026-07-28 验收实锤)。派生时先经 resolveUserDisplayText 取
   * 显示文本(hook / Orca 消息与气泡正文同源),再剥引用标记行,并优先取
   * 用户自己的话(引用块之外的首个非空行)。content 已由 store 归一成可见
   * 正文,不做二次 parseUserContent(提问本身是 JSON 字面量会被解空丢刻度,
   * PR #830 review)。
   */
  preview: string;
  /**
   * 纯附件且取不到任何文件名时(粘贴截图无 originalName),preview 为空、
   * 这里记附件数,组件用 i18n 文案("附件 N 件")兜底渲染预览与 aria ——
   * 纯附件提问是真实提问,必须有刻度(PR #830 review 回归修复)。
   */
  attachmentsOnly?: number;
  /**
   * 该轮最终回答的摘要(已压平空白、截断)。agent 对话里大量提问是
   * "继续 / 不对,重来"这类不含识别信息的短指令,回答摘要才是用户认出
   * "这根刻度是哪一轮"的主载体 — 它是识别的必需品,不是装饰。
   * 取本轮最后一条非空 assistant 正文:前面的开工叙述会随最终回答覆盖。
   * 回答尚未产生(流式中 / 被打断)时为 undefined,预览卡只显示提问行。
   */
  answerExcerpt?: string;
}

/**
 * 少于这个数量不出导航条。设计依据:少于 4 轮的对话通常一两屏内看完,
 * "地图"没有价值;且用提问数(而非内容高度)做门槛,流式输出把回答撑长时
 * 门槛判定不抖动,导航条不会闪现/消失。
 */
export const NAV_RAIL_MIN_ENTRIES = 4;

/**
 * 点击刻度后,目标提问顶边停在滚动容器顶下方这么多像素。
 * 轮次跳转的目的是"重读这一轮":视口应恰好框住 提问 → 回答,上一轮的
 * 尾巴一行都不该露。所以不走消息通用锚点的 scroll-mt-20(那 80px 是给
 * 搜索跳转留上文语境用的,是另一个任务),改由跳转侧手动计算滚动位置。
 */
export const NAV_RAIL_JUMP_TOP_OFFSET_PX = 12;

/**
 * "当前提问"阈值线距容器顶的偏移。必须大于 NAV_RAIL_JUMP_TOP_OFFSET_PX:
 * 跳转落定后目标自身恰好压线成为当前项,刻度加深不漂移到上一条。
 */
export const NAV_RAIL_ACTIVE_FUDGE_PX = 40;

/** 回答摘要的最大长度(预览卡 CSS 再做 3 行 clamp,这里只防超长字符串)。 */
export const NAV_RAIL_EXCERPT_MAX_CHARS = 200;

/**
 * 空闲补页的目标提问数。导航条是"整段对话的地图",而老会话打开时只加载
 * 尾部切片 —— 尾部提问太少时地图没法用。8 = 出场门槛(4)的两倍:不止
 * "勉强出现",而是一张有导航价值的近期地图,通常一页历史就能凑齐。
 */
export const NAV_RAIL_BACKFILL_TARGET_ENTRIES = 8;

/**
 * 空闲补页的轮数预算(每轮 = 一次 onLoadMore 翻页)。超大会话的内存兜底:
 * 预算用完仍不足 8 条就到此为止,更早的地图随用户上滚自然补齐。
 * "打开会话即拥有全量地图"需要独立的提问索引查询(与消息加载解耦),
 * 涉及主进程与远程隧道路由,留作后续方向,不在本改动内。
 */
export const NAV_RAIL_BACKFILL_MAX_ROUNDS = 3;

/**
 * 是否还需要为导航条补一页历史。纯判定,由 MessageStream 在空闲期调用;
 * 翻页动作本身沿现有 onLoadMore 通道(F-SYNC-2 滚动补偿协议照走)。
 */
export function shouldBackfillForNavRail(input: {
  entryCount: number;
  hasMoreMessages: boolean;
  isLoadingMore: boolean;
  rounds: number;
}): boolean {
  if (!input.hasMoreMessages || input.isLoadingMore) return false;
  if (input.rounds >= NAV_RAIL_BACKFILL_MAX_ROUNDS) return false;
  return input.entryCount < NAV_RAIL_BACKFILL_TARGET_ENTRIES;
}

/**
 * 内容列左侧留白至少这么宽才有导航条的位置。
 * 组成:左缘留白 8px + 刻度触达区 24px + 与内容列的安全间距 12px。
 * 不够宽(窄窗口 / 嵌入式小面板)时整条隐藏,绝不压在气泡上。
 */
export const NAV_RAIL_MIN_GUTTER_PX = 44;

/** 每根刻度占用的纵向空间(2px 线 + 7px 间距)。实测验收结论:9px 紧凑但
 *  单根可辨认;14px 被否(松散难看)。调整前先实机看效果再动。 */
export const NAV_RAIL_TICK_PITCH_PX = 9;
/** 空间不足时允许压缩到的最小纵距;再小刻度就粘连不可点了。 */
export const NAV_RAIL_TICK_MIN_PITCH_PX = 5;

/**
 * 刻度带可用高度低于这个值时导航条不出场(与横向留白门槛同级的纵向门槛)。
 * 极矮视口 / 输入 overlay 占满高度时,连出场门槛条数的刻度都摆不下,
 * 硬渲染会溢出压到输入区(PR #830 review)。取值 = 门槛条数 × 标准纵距。
 */
export const NAV_RAIL_MIN_AVAIL_HEIGHT_PX = NAV_RAIL_MIN_ENTRIES * NAV_RAIL_TICK_PITCH_PX;

/**
 * 从已加载的 messages 派生导航条目(每条真实提问一根刻度)。
 *
 * 过滤规则与 PrevMessageJumpChip 的 userMessageIds 同源,再加一条:
 * - isSyntheticTrigger:合成指令行渲染 null,没有可滚动的锚点;
 * - systemCardType:user 位次上的系统卡(compact / learn …),不是用户提问。
 *
 * 回答摘要只属于最近一根可见刻度。一根刻度下可以有多个 SDK turn:
 * 封轮(turnCompleted / 费用 / 用量,含空 wrap-up)提交当前候选;封轮后的
 * 未收尾进度只暂存,要等下一次封轮才提交。合成续跑 / 系统卡 user 行结束
 * 整根刻度归属;steer 插话不是边界。
 *
 * 注意输入是全量已加载 messages 而非 visibleRenderItems —— 导航条要覆盖
 * 整段已加载历史,渲染窗口外的目标由跳转侧扩窗解决(见 MessageStream 的
 * rail-jump layout effect)。更早的未加载 DB 分页(hasMoreMessages)不在
 * 条目里,随用户上滚加载后自然补齐。
 */
export function deriveNavRailEntries(messages: readonly ChatMessage[]): NavRailEntry[] {
  const entries: NavRailEntry[] = [];
  let lastOwnsAnswers = false;
  let lastExcerptSealed = false;
  let pendingAnswers: ChatMessage[] = [];
  let committedExcerpt: string | null = null;

  const excerptFromPending = (): string | null => {
    for (let i = pendingAnswers.length - 1; i >= 0; i--) {
      const excerpt = normalizeExcerpt(pendingAnswers[i].content);
      if (excerpt) return excerpt;
    }
    return null;
  };

  const commitPendingIfAny = () => {
    const excerpt = excerptFromPending();
    if (excerpt) committedExcerpt = excerpt;
    pendingAnswers = [];
  };

  const applyToLastEntry = () => {
    const last = entries[entries.length - 1];
    if (last) {
      const live = lastExcerptSealed ? null : excerptFromPending();
      const excerpt = live ?? committedExcerpt;
      if (excerpt) last.answerExcerpt = excerpt;
    }
    pendingAnswers = [];
    committedExcerpt = null;
  };

  const closeAnswerTurn = () => {
    applyToLastEntry();
    lastOwnsAnswers = false;
    lastExcerptSealed = false;
  };

  for (const m of messages) {
    if (m.role === 'user') {
      // 运行中插话(steer)不是新一轮问答:MessageStream 的轮次语义也不把
      // 它当边界,算成刻度会把进行中的回答错挂到插话名下(PR #830 review)。
      if (m.delivery === 'steer') continue;
      if (m.isSyntheticTrigger || m.systemCardType) {
        closeAnswerTurn();
        continue;
      }
      // 预览来源按序:显示文本(hook 消息取 userText / 剥 <thread_context>,
      // Orca 通信行解包 JSON,与 UserMessage 气泡正文同源,见
      // userMessageDisplayText.ts;PR #830 review)→ ChatMessage 顶层
      // images/files 字段的附件名(store 入库时已把封装解到顶层,content 即
      // 可见正文,PR #830 review)。
      let preview = promptPreviewLine(resolveUserDisplayText(m));
      const attachmentNames = [
        ...(m.images ?? []).map((image) =>
          'originalName' in image ? image.originalName : undefined,
        ),
        ...(m.files ?? []).map((file) => file.name),
      ].filter((name): name is string => Boolean(name));
      if (!preview) preview = attachmentNames.join(' · ');
      const attachmentCount = (m.images?.length ?? 0) + (m.files?.length ?? 0);
      if (preview) {
        closeAnswerTurn();
        entries.push({
          id: m.clientId,
          preview,
          isAutomation: isRealAutomationOrigin(m.automationOrigin),
        });
        lastOwnsAnswers = true;
      } else if (attachmentCount > 0) {
        // 有附件但一个名字都取不到(粘贴截图):仍是真实提问,保留刻度,
        // 预览文案由组件按 attachmentsOnly 用 i18n 兜底。
        closeAnswerTurn();
        entries.push({
          id: m.clientId,
          preview: '',
          attachmentsOnly: attachmentCount,
          isAutomation: isRealAutomationOrigin(m.automationOrigin),
        });
        lastOwnsAnswers = true;
      } else {
        // 无文本、无附件 → 无法识别的空刻度,不当成提问(PR #830 review)。
        closeAnswerTurn();
      }
      continue;
    }
    if (!lastOwnsAnswers) continue;
    if (m.role !== 'assistant' || m.systemCardType) continue;
    const sealed = isSealedAssistantAnswer(m);
    if (m.content.trim().length > 0) pendingAnswers.push(m);
    if (sealed) {
      commitPendingIfAny();
      lastExcerptSealed = true;
    }
  }
  applyToLastEntry();
  return entries;
}

/**
 * 与 latestMessageText.logic.isTitleTurnCompleted 同口径:
 * 显式 turnCompleted=false 是失败,不能被费用/用量兜底当成封轮。
 */
function isSealedAssistantAnswer(message: ChatMessage): boolean {
  if (message.turnCompleted === false) return false;
  if (message.turnCompleted === true) return true;
  return (
    (message.turnMoney?.amount ?? 0) > 0 ||
    (typeof message.turnCostUsd === 'number' && message.turnCostUsd > 0) ||
    message.turnUsageDetails !== undefined
  );
}

/**
 * 提问(可见正文)→ 单行预览。无条件剥引用标记行(不赌 quotesEncoded 旗标),
 * 优先取引用块之外用户自己的话;全引用消息退回引用文字本身。
 *
 * 输入按**已归一化的可见正文**处理,不再 parseUserContent:store 侧两条入库
 * 路径(发送存 text / 历史映射存 parsed.text)都已解掉附件封装,附件名在
 * ChatMessage 顶层 images/files。这里再解析一次,提问本身恰好是 JSON 字面量
 * 时(如只输入 `[1,2,3]`)会被误当成附件封装 / SDK content blocks,预览解空、
 * 真实提问丢刻度,出场门槛也被算小(PR #830 review)。
 */
export function promptPreviewLine(visibleText: string): string {
  const lines = stripChatQuoteMarkerLines(visibleText).split('\n');
  const own = lines.find((line) => line.trim() && !line.trimStart().startsWith('>'));
  const anyLine = lines.find((line) => line.trim()) ?? '';
  return (own ?? anyLine).replace(/^\s*>\s?/, '').trim();
}

/**
 * 摘要净化:剥常见 Markdown 标记 → 压平空白成单行 → 截断到上限。
 * AI 回答几乎都是 Markdown,不剥标记的话预览卡里全是 `**` / 反引号 / 标题井号
 * 这类源码噪音。只做轻量文本级剥离(粗体星号 / 行内代码 / 标题与引用前缀 /
 * 无序列表符 / 链接留文字),不追求完整 Markdown 解析 —— 预览要的是可扫读,
 * 不是保真渲染。下划线不动(文件名 / 标识符里是正文)。
 * 全空白返回空串(调用方按 falsy 丢弃)。
 */
export function normalizeExcerpt(raw: string): string {
  return raw
    .replace(/<!--[\s\S]*?-->/g, '') // HTML 注释(含 composer 引用标记)
    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1') // 链接/图片留文字
    .replace(/^#{1,6}\s+/gm, '') // 标题前缀
    .replace(/^>\s?/gm, '') // 引用前缀
    .replace(/^[-+]\s+/gm, '') // 无序列表符(星号由下一条统一剥)
    .replace(/[*`]/g, '') // 粗体/斜体星号、行内代码反引号
    .replace(/\s+/g, ' ')
    .trim()
    .slice(0, NAV_RAIL_EXCERPT_MAX_CHARS);
}

/**
 * 判定"当前提问":视口顶端正在阅读的内容归属于哪条提问。
 *
 * 语义 = 最后一条"顶边已越过视口顶部阈值线"的提问(它的回答正被阅读)。
 * 全部都还在阈值线之下(视口停在对话最顶端)时,当前提问 = 第一条。
 *
 * @param topAt 取第 i 条的顶边位置(getBoundingClientRect().top)。
 *   `null` = 该消息在渲染窗口外未挂载。渲染窗口是"锚点 → 末尾"的后缀切片,
 *   未挂载必然在窗口起点之前、也就在视口上方 —— 视作"已越过阈值"。
 * @param thresholdTop 视口顶部阈值线(容器 top + fudge)。fudge 要盖过
 *   scroll-mt-20 的 80px 锚点偏移,跳转落定后目标自身恰好压线变为当前项。
 */
export function pickActiveNavId(
  ids: ReadonlyArray<string>,
  thresholdTop: number,
  topAt: (index: number) => number | null,
): string | null {
  if (ids.length === 0) return null;
  const idx = lastIndexAtOrBelow(ids.length, thresholdTop, topAt, true);
  return idx >= 0 ? ids[idx] : ids[0];
}

/**
 * 二分查找"最后一个顶边不超过 limit 的条目下标"(找不到返回 -1)。
 *
 * 前提:tops 随文档序单调不减,未挂载(null)视作 -∞ 且只出现在前缀
 * (渲染窗口是"锚点 → 末尾"的后缀切片)。每次 topAt 是一次
 * querySelector + getBoundingClientRect 强制布局读,且判定在 rAF 里逐帧
 * 跑 —— 线性反向扫描在"滚动到长会话历史顶部"场景下每帧要测几百个锚点,
 * 二分降到 O(log n)(PR #830 review)。
 */
function lastIndexAtOrBelow(
  count: number,
  limit: number,
  topAt: (index: number) => number | null,
  inclusive: boolean,
): number {
  let lo = 0;
  let hi = count - 1;
  let found = -1;
  while (lo <= hi) {
    const mid = (lo + hi) >> 1;
    const top = topAt(mid) ?? Number.NEGATIVE_INFINITY;
    if (inclusive ? top <= limit : top < limit) {
      found = mid;
      lo = mid + 1;
    } else {
      hi = mid - 1;
    }
  }
  return found;
}

/** 范围判定的底部容差:轮次顶边至少要探进视口底这么多像素才算可见。 */
export const NAV_RAIL_RANGE_BOTTOM_EDGE_PX = 8;

export interface NavRailVisibleRange {
  /** 视口内首个可见轮次的条目下标(含)。 */
  startIndex: number;
  /** 视口内最后一个可见轮次的条目下标(含)。 */
  endIndex: number;
}

/**
 * 判定"当前视口正显示着哪些轮次"(整段高亮用,与单一"当前项"互补:
 * 当前项 = 阅读锚点,加长;可见范围 = 屏上内容的归属轮次,提亮)。
 *
 * 轮次 i 的内容区间 = [top_i, top_{i+1});最后一轮延伸到无穷。与
 * [viewTop, viewBottom) 相交即可见。tops 随文档序单调递增;`null`(渲染
 * 窗口外未挂载)视作 -∞ —— 其轮次内容必在视口上方。
 *
 * 边界语义:调用方传入的应是**有效视口**,即已经扣除容差的边界 ——
 * 顶部与"当前项"共用 NAV_RAIL_ACTIVE_FUDGE_PX(视口顶部的几十像素往往
 * 是上一轮的收尾空白:消息间距 + 跳转落点偏移,一行内容都没露,严格几何
 * 相交会把上一轮误点亮,2026-07-28 实拍验收抓到的缺陷);底部扣
 * NAV_RAIL_RANGE_BOTTOM_EDGE_PX 防 1 像素露头就点亮。顶部与当前项共线的
 * 推论:当前项恒等于亮带首项,加长与提亮两个信号永不打架。
 *
 * 视口整体在第一条提问之前(还没有任何轮次开始)时返回 null。
 */
export function pickVisibleNavRange(
  ids: ReadonlyArray<string>,
  viewTop: number,
  viewBottom: number,
  topAt: (index: number) => number | null,
): NavRailVisibleRange | null {
  const n = ids.length;
  if (n === 0) return null;
  // 末端:最后一个"轮次起点已进入视口底之上"的条目。
  const endIndex = lastIndexAtOrBelow(n, viewBottom, topAt, false);
  if (endIndex < 0) return null;
  // 起端:最后一个"顶边仍在视口顶之上(含压线)"的条目 —— 它以及它之后
  // 到 endIndex 的轮次都有内容落在视口里;不存在时视口从第一条开始。
  const startIndex = Math.min(endIndex, Math.max(0, lastIndexAtOrBelow(n, viewTop, topAt, true)));
  return { startIndex, endIndex };
}

export interface NavRailPlan {
  /** 从这个下标开始渲染(之前的条目被截断,只保留最近的一段)。 */
  startIndex: number;
  /** 实际采用的纵距(px/根)。 */
  pitchPx: number;
  /** 被截掉的更早条目数;>0 时组件渲染"更早还有 N 条"占位刻度。 */
  hiddenCount: number;
}

/**
 * 纵向空间规划:先压缩间距,还放不下就截断只保留最近的一段。
 * 截断时预留一根刻度的位置给"更早还有 N 条"占位。
 */
export function planNavRailTicks(entryCount: number, availableHeightPx: number): NavRailPlan {
  if (entryCount <= 0 || availableHeightPx <= 0) {
    return { startIndex: 0, pitchPx: NAV_RAIL_TICK_PITCH_PX, hiddenCount: 0 };
  }
  if (entryCount * NAV_RAIL_TICK_PITCH_PX <= availableHeightPx) {
    return { startIndex: 0, pitchPx: NAV_RAIL_TICK_PITCH_PX, hiddenCount: 0 };
  }
  const compressed = Math.floor(availableHeightPx / entryCount);
  if (compressed >= NAV_RAIL_TICK_MIN_PITCH_PX) {
    return { startIndex: 0, pitchPx: compressed, hiddenCount: 0 };
  }
  // 最小纵距也放不下:截断。留一格给"更早还有 N 条"占位刻度。
  const slots = Math.max(2, Math.floor(availableHeightPx / NAV_RAIL_TICK_MIN_PITCH_PX));
  const shown = Math.min(entryCount, slots - 1);
  return {
    startIndex: entryCount - shown,
    pitchPx: NAV_RAIL_TICK_MIN_PITCH_PX,
    hiddenCount: entryCount - shown,
  };
}

/**
 * 计算刻度线宽度。悬浮或 scrub 时,以目标为中心向两侧逐级收缩 1~3 根;
 * 当前阅读位置仍保留自己的加长反馈,避免交互态覆盖阅读态。
 */
export function planNavRailTickWidth(input: {
  distance: number | null;
  isActive: boolean;
  inView: boolean;
  isAutomation?: boolean;
}): string {
  // 所有状态共享同一条 26px 轨道;hover/scrub 的渐进伸缩由渲染层
  // 的 scaleX 负责,避免普通态出现不一致的横条长度。
  void input;
  return 'w-[26px]';
}

export function planNavRailTickProgress(distance: number | null): number {
  if (distance === null) return 0;
  if (distance === 0) return 1;
  if (distance === 1) return 0.7;
  if (distance === 2) return 0.4;
  if (distance === 3) return 0.2;
  return 0;
}

/**
 * 导航条是否有横向空间:内容列(maxWidth 截断后)左侧的实际留白够不够。
 * 内容列由 mx-auto 居中,留白 = (容器宽 - 内容实际宽) / 2。
 */
export function hasNavRailRoom(containerWidthPx: number, contentMaxWidthPx: number): boolean {
  if (containerWidthPx <= 0) return false;
  const contentWidth = Math.min(containerWidthPx, contentMaxWidthPx);
  return (containerWidthPx - contentWidth) / 2 >= NAV_RAIL_MIN_GUTTER_PX;
}