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。

13.7 KB
Raw Blame
/**
 * chatQuotes — 聊天/文件选中文字引用(chat-text-quote)的纯函数层。
 *
 * 数据契约:引用以 markdown blockquote 形态存在于消息 content。新 composer
 * 把引用作为正文 block atom,因此可按「引用 A → 回复 A → 引用 B → 回复 B」
 * 交错序列化;`parseChatQuoteSegments` 按原顺序还原。`formatQuotesForSend` /
 * `parseLeadingBlockquotes` 继续服务旧的「引用列表前置」调用方与历史消息。
 *
 * 来源文件(file-quote):从文件浏览器选中的引用带 `sourcePath`(workdir
 * 相对路径),编码为条目内最后一行 `> — source: <path>`;能拿到选区行号时
 * 再附 `#Lx-Ly`。模型对引注体例天然理解,可据此 Read 完整上下文 / 精准编辑。
 * 新写入的引用块首行带不可见 Markdown comment marker,用于把产品 quote
 * atom 与正文中用户手写的 blockquote 无歧义地区分;历史前置引用仍兼容。
 *
 * 为什么选 blockquote 而不是结构化字段:引用是模型的母语格式(零 wire /
 * 持久化 schema 改动),手机端 / 远端 / 导出的纯文本视图天然可读;渲染美化
 * 只是本端的展示层解析。解析只对持久化了 `quotesEncoded` 标志的消息启用,
 * 用户普通手打的 markdown 引用保持原样。
 *
 * apps/desktop 的 `renderer/lib/chatQuotes.ts` re-export 本模块,避免 wire format
 * 双实现漂移。
 */

/** 一条选中文字引用。sourcePath 仅文件浏览器来源有(workdir 相对路径)。 */
export interface ChatQuote {
  text: string;
  sourcePath?: string;
  startLine?: number;
  endLine?: number;
}

/** 按消息正文顺序排列的引用 / 用户文字段。 */
export type ChatQuoteSegment =
  | { kind: 'text'; text: string }
  | { kind: 'quote'; quote: ChatQuote };

/** 来源行前缀(条目内最后一行)。 */
const SOURCE_LINE_PREFIX = '— source: ';

/**
 * 新版产品引用块的显式标记。Markdown comment 在普通文本视图中不可见,
 * 同时让解析器能把正文里的用户手写 `> ...` 与 composer quote atom 区分开。
 * 未带标记的历史 quotesEncoded 消息仍只按「消息开头的引用区」兼容解析。
 */
const QUOTE_BLOCK_MARKER = '<!-- cindy-composer-quote -->';
const QUOTE_BLOCK_MARKER_LINE = `> ${QUOTE_BLOCK_MARKER}`;

/**
 * Remove the private product marker from user-facing plain text while keeping
 * the readable Markdown blockquote, source line, and every other line intact.
 * Callers must gate this to messages whose persisted `quotesEncoded` flag is
 * true so an identical line typed by the user is never rewritten.
 */
export function stripChatQuoteMarkerLines(content: string): string {
  return content
    .split('\n')
    .filter((line) => line.trimStart() !== QUOTE_BLOCK_MARKER_LINE)
    .join('\n');
}

function isValidLine(line: number | undefined): line is number {
  return typeof line === 'number' && Number.isInteger(line) && line > 0;
}

function formatSourceLine(q: ChatQuote): string | null {
  if (!q.sourcePath) return null;
  if (!isValidLine(q.startLine)) return q.sourcePath;
  const endLine = isValidLine(q.endLine) && q.endLine >= q.startLine ? q.endLine : q.startLine;
  return endLine === q.startLine
    ? `${q.sourcePath}#L${q.startLine}`
    : `${q.sourcePath}#L${q.startLine}-L${endLine}`;
}

function parseSourceLine(raw: string): Omit<ChatQuote, 'text'> {
  const match = raw.match(/^(.*)#L(\d+)(?:-L(\d+))?$/);
  if (!match) return { sourcePath: raw };
  const sourcePath = match[1];
  const startLine = Number(match[2]);
  const endLine = match[3] ? Number(match[3]) : startLine;
  if (!sourcePath || !isValidLine(startLine) || !isValidLine(endLine)) return { sourcePath: raw };
  return { sourcePath, startLine, endLine: Math.max(startLine, endLine) };
}

/**
 * 引用列表 → 发送文本。编码严格贴合 markdown 标准语义:
 * - 条目内容行 → `> <line>`;条目**内部空行** → 裸 `>`(无尾随空格,免疫
 *   传输层 trailing-space trim);
 * - 条目**首尾空行**在编码前归一化剔除:采集侧选区常吃进段落边界的空行,
 *   它们不携带信息,却会让编码块以裸 `>` 开头——而 parseLeadingBlockquotes
 *   的早退守卫只认 `"> "` 开头(保护用户手打的裸 `>`),开头裸 `>` 的消息
 *   会整段退化为原文渲染,破坏 roundtrip 契约;
 * - 条目之间以**真空行**分隔(markdown 中即两个独立 blockquote);
 * - 带来源的条目末尾追加 `> — source: <path>` 行;正文与引用块空行相接。
 * 注:首尾空行归一化是对 #793 桌面版原实现的修复(桌面同样受益于后续迁移
 * 到本共享模块)。
 */
/** 剥掉字符串首尾的连续换行(线性扫描,不用正则——`/\n+$/` 会被 CodeQL
 *  以多项式回溯告警;引用文本来自用户选区,属不可控输入)。 */
function stripOuterNewlines(text: string): string {
  let start = 0;
  while (start < text.length && text[start] === '\n') start += 1;
  let end = text.length;
  while (end > start && text[end - 1] === '\n') end -= 1;
  return text.slice(start, end);
}

/** 单条引用 → 可独立插入正文任意位置的 Markdown blockquote。 */
export function formatQuoteForSend(quote: ChatQuote): string {
  const lines = stripOuterNewlines(quote.text).split('\n');
  const sourceLine = formatSourceLine(quote);
  if (sourceLine) lines.push(`${SOURCE_LINE_PREFIX}${sourceLine}`);
  return [
    QUOTE_BLOCK_MARKER_LINE,
    ...lines.map((line) => (line ? `> ${line}` : '>')),
  ].join('\n');
}

export function formatQuotesForSend(quotes: readonly ChatQuote[], body: string): string {
  if (quotes.length === 0) return body;
  const block = quotes.map(formatQuoteForSend).join('\n\n');
  return `${block}\n\n${body}`.trimEnd();
}

function quoteFromLines(lines: string[]): ChatQuote {
  const last = lines[lines.length - 1];
  if (last?.startsWith(SOURCE_LINE_PREFIX) && lines.length > 1) {
    return {
      text: lines.slice(0, -1).join('\n'),
      ...parseSourceLine(last.slice(SOURCE_LINE_PREFIX.length)),
    };
  }
  return { text: lines.join('\n') };
}

/**
 * 解析 quotesEncoded 消息里的全部引用块,同时保留它们与用户文字的顺序。
 * 调用方必须先用持久化标志门控,避免把普通手写 markdown 当成产品引用。
 */
export function parseChatQuoteSegments(
  content: string,
): ChatQuoteSegment[] {
  if (!content.includes('> ')) {
    return content ? [{ kind: 'text', text: content }] : [];
  }

  const lines = content.split('\n');
  const segments: ChatQuoteSegment[] = [];
  let textLines: string[] = [];

  const flushText = ({ beforeQuote }: { beforeQuote: boolean }) => {
    const followsQuote = segments[segments.length - 1]?.kind === 'quote';
    const pending = textLines;
    textLines = [];
    if (pending.length === 0) return;

    // 序列化会在 quote / text 块之间固定放一个 Markdown 空行。只消费这个
    // 结构分隔,额外空行都是用户真实输入的回车,必须留给渲染层。两个引用
    // 之间只有空行时要单独计数,因为 `[''].join('\n')` 无法表达一个换行。
    if (pending.every((line) => line === '')) {
      const structuralEmptyLineCount = followsQuote || beforeQuote ? 1 : 0;
      const preservedLineBreakCount = Math.max(0, pending.length - structuralEmptyLineCount);
      if (preservedLineBreakCount > 0) {
        segments.push({ kind: 'text', text: '\n'.repeat(preservedLineBreakCount) });
      }
      return;
    }

    let start = 0;
    let end = pending.length;
    if (followsQuote && pending[start] === '') start += 1;
    if (beforeQuote && end > start && pending[end - 1] === '') end -= 1;
    const text = pending.slice(start, end).join('\n');
    if (text) {
      segments.push({ kind: 'text', text });
    }
  };

  // 历史稳定格式没有显式 marker,只允许在消息开头解析。PR 开发期曾短暂
  // 写出 markerless 交错块,但它与正文里的用户 Markdown blockquote 无法
  // 从 wire text 区分;不能拿 quotesEncoded 当版本号放宽整条消息,否则旧
  // 消息正文里的 `> ...` 会被误还原成产品引用。新版 marker 才允许交错解析。
  const hasExplicitMarkers = content.includes(QUOTE_BLOCK_MARKER_LINE);
  // 只要同条消息出现新版 marker,整条内容就按无歧义的新格式解析。否则正文
  // 开头的用户手写 Markdown blockquote 会被旧版兼容分支误认成产品引用。
  let allowLegacyLeadingQuotes = !hasExplicitMarkers;
  let index = 0;
  while (index < lines.length) {
    const line = lines[index];
    const markerIndent =
      line.trimStart() === QUOTE_BLOCK_MARKER_LINE
        ? line.slice(0, line.length - line.trimStart().length)
        : null;
    const marked = markerIndent !== null;
    const legacyLeading = allowLegacyLeadingQuotes && line.startsWith('> ');
    if (!marked && !legacyLeading) {
      textLines.push(line);
      if (line !== '') allowLegacyLeadingQuotes = false;
      index += 1;
      continue;
    }

    flushText({ beforeQuote: true });
    if (marked) {
      allowLegacyLeadingQuotes = false;
      index += 1;
    }
    const quoteLines: string[] = [];
    while (index < lines.length) {
      const quoteLine = lines[index];
      const quotePrefix = `${markerIndent ?? ''}>`;
      if (quoteLine.startsWith(`${quotePrefix} `)) {
        quoteLines.push(quoteLine.slice(quotePrefix.length + 1));
        index += 1;
        continue;
      }
      if (quoteLine === quotePrefix) {
        quoteLines.push('');
        index += 1;
        continue;
      }
      break;
    }
    segments.push({ kind: 'quote', quote: quoteFromLines(quoteLines) });
  }

  flushText({ beforeQuote: false });
  return segments;
}

/**
 * 将解析后的文字岛拼成「引用胶囊之外」的可见正文。
 *
 * 引用块被收进独立胶囊后,相邻文字岛之间至少保留一个空行,避免首尾文字
 * 粘连;但片段自身已经带回车时只补不足的数量,不能用 join('\n\n') 再叠加
 * 两个换行,否则用户在引用前后保留的回车会被放大。
 */
export function joinChatQuoteTextSegments(segments: readonly ChatQuoteSegment[]): string {
  let body = '';
  let hasTextSegment = false;
  for (const segment of segments) {
    if (segment.kind !== 'text') continue;
    if (!hasTextSegment) {
      body = segment.text;
      hasTextSegment = true;
      continue;
    }

    let trailingNewlines = 0;
    for (let index = body.length - 1; index >= 0 && trailingNewlines < 2; index -= 1) {
      if (body[index] !== '\n') break;
      trailingNewlines += 1;
    }
    let leadingNewlines = 0;
    for (let index = 0; index < segment.text.length && leadingNewlines < 2; index += 1) {
      if (segment.text[index] !== '\n') break;
      leadingNewlines += 1;
    }
    body += '\n'.repeat(Math.max(0, 2 - trailingNewlines - leadingNewlines));
    body += segment.text;
  }
  return body;
}

/**
 * 逆解析(与 formatQuotesForSend 对偶):content 以 "> " 开头时,取出开头的
 * blockquote 区还原成引用列表,其余为正文。规则:
 * - `> x` 行是条目内容,裸 `>` 行是条目内部空行;
 * - 空行后紧跟 `> ` 行 → 条目分隔,继续;空行后不是 → 引用区结束,余下为正文;
 * - 条目最后一行是 `— source: <path>` 时抽为来源(选中文本自身以该前缀结尾的
 *   极端情况会被误判,可接受);
 * - 早退守卫只认 `"> "` 开头:首行是裸 `>` 的用户手打内容原样返回,不吞字符。
 * 正文首行恰以 `> ` 开头会被并入引用块——这是 markdown 引用语义的固有歧义,
 * 视觉化后仍以引用样式呈现,可接受。
 */
export function parseLeadingBlockquotes(content: string): {
  quotes: ChatQuote[];
  body: string;
} {
  if (!content.startsWith('> ')) {
    return { quotes: [], body: content };
  }
  const lines = content.split('\n');
  const quotes: ChatQuote[] = [];
  let current: string[] = [];
  let markerConsumedForCurrent = false;

  const flush = () => {
    if (current.length === 0) return;
    quotes.push(quoteFromLines(current));
    current = [];
    markerConsumedForCurrent = false;
  };

  let i = 0;
  for (; i < lines.length; i++) {
    const line = lines[i];
    if (
      line === QUOTE_BLOCK_MARKER_LINE &&
      current.length === 0 &&
      !markerConsumedForCurrent
    ) {
      markerConsumedForCurrent = true;
      continue;
    }
    if (line.startsWith('> ')) {
      current.push(line.slice(2));
      continue;
    }
    if (line === '>') {
      // 条目内部空行(markdown:同一 blockquote 里的空行)。
      current.push('');
      continue;
    }
    if (line === '' && current.length > 0 && lines[i + 1]?.startsWith('> ')) {
      // 空行 + 下一行仍是引用 → 条目分隔,继续吃下一条。
      flush();
      continue;
    }
    break; // 引用区结束(空行后接正文,或直接非引用行)。
  }
  flush();
  const body = lines.slice(i).join('\n').replace(/^\n+/, '');
  return { quotes, body };
}

/** 来源路径 → UI 展示用文件名(basename)。 */
export function quoteSourceBasename(sourcePath: string): string {
  return sourcePath.split(/[\\/]/).filter(Boolean).pop() ?? sourcePath;
}

export function quoteSourceLineRangeLabel(quote: ChatQuote): string | null {
  if (!isValidLine(quote.startLine)) return null;
  const endLine =
    isValidLine(quote.endLine) && quote.endLine >= quote.startLine
      ? quote.endLine
      : quote.startLine;
  return endLine === quote.startLine ? `L${quote.startLine}` : `L${quote.startLine}-L${endLine}`;
}

/** UI 展示用来源标签:basename + 可选 source 行号。 */
export function quoteSourceDisplayLabel(quote: ChatQuote): string | null {
  if (!quote.sourcePath) return null;
  const lineLabel = quoteSourceLineRangeLabel(quote);
  return `${quoteSourceBasename(quote.sourcePath)}${lineLabel ? `:${lineLabel}` : ''}`;
}