/** * 正文真实增量流式输出(F073)的纯逻辑层:`answer_start / answer_delta / * answer_end / answer_abort` 事件的解析、状态机与 markdown 增量规整器。 * * 不 import vue、不发网络请求,可被 harness 的 esbuild 直接打包断言。 */ /* markdown 规整 */ export const LIST_ITEM_RE = /^\s*(?:[-*+]|\d+[.)])\s+\S/; /** * 规整 markdown 换行:渲染层是 `white-space: normal`,单个 \n 会被折叠, * 于是把非列表项之间的单换行提升为空行;连续列表项之间保留单换行,不打断编号。 */ /** * 两行之间是否需要插入空行。 * * 规则(2026-10-29 用户要求「\n\n 换两行」): * - 普通行之间**保留原始换行**:单个 \n = 段内换行(一行),双个 \n = 空一行(分段); * - 连续列表项保持紧排(不插空行); * - 列表项与普通行之间必须插空行,否则 markdown 会把普通行并进列表项(懒续行)。 */ const needsBlankBetweenLines = (prev: string, line: string): boolean => { const prevBlank = prev.trim() === ''; const lineBlank = line.trim() === ''; if (prevBlank || lineBlank) { return false; } const prevList = LIST_ITEM_RE.test(prev); const lineList = LIST_ITEM_RE.test(line); if (prevList && lineList) { return false; } return prevList || lineList; }; export function normalizeChatMarkdown(text: string): string { const value = String(text || ''); if (!value.includes('\n')) { return value; } const lines = value.split('\n'); const result: string[] = [lines[0]]; for (let i = 1; i < lines.length; i++) { const prev = lines[i - 1]; const line = lines[i]; if (needsBlankBetweenLines(prev, line)) { result.push(''); } result.push(line); } return result.join('\n'); } /** * 增量规整器:把逐片段到达的原始正文变成「与 `normalizeChatMarkdown(全文)` 逐步同前缀」 * 的增量文本 —— 否则 `answer_end` 的整块替换会与已流文本分歧,导致整段重建与卡片闪现。 * * 不变式:**任一时刻 `已发出的全部文本 === normalizeChatMarkdown(已输入的全部文本)`**。 */ export interface IncrementalMarkdownNormalizer { /** 输入一段原始增量,返回应立即展示的规整增量(可能为空串——还在扣前缀) */ push(text: string): string; /** 收尾:释放仍在扣住的部分(end 会用最终全文覆盖,故非必须) */ finish(): string; } /** `line` 是否已能确定是列表项(正则无 `$` 锚,命中即不会被后续字符推翻) */ const isListItemSoFar = (line: string): boolean => LIST_ITEM_RE.test(line); /** `line` 是否还可能变成列表项(是则不能提前释放) */ const couldBecomeListItem = (line: string): boolean => /^\s*$/.test(line) || // 只有空白,后面可能跟 - 或数字 /^\s*[-*+]\s*$/.test(line) || /^\s*\d+$/.test(line) || /^\s*\d+[.)]\s*$/.test(line); export const createIncrementalMarkdownNormalizer = (): IncrementalMarkdownNormalizer => { /** 已发出的全部文本 */ let out = ''; /** 上一整行(用于判断「本行前是否要插空行」) */ let prevLine: string | null = null; /** 当前输入行(可能还没结束) */ let pendingLine = ''; /** 当前行的内容是否已发出 */ let lineOpen = false; /** 是否收到过输入(空输入不该在 finish 里凭空产出空行) */ let received = false; /** 两行之间是否需要插入空行(与 normalizeChatMarkdown 同一判据) */ const needsBlankBetween = needsBlankBetweenLines; /** * 开出一行:先补空行(需要的话),再写内容。 * 换行是**行与行之间的分隔符**,行末的 `\n` 由「下一行出现」或「输入里的 `\n`」补, * 不能在本行结束时直接加一个(否则末行多出换行,与 normalizeChatMarkdown 不一致)。 */ const openLine = (line: string): void => { if (prevLine !== null && needsBlankBetween(prevLine, line)) { out += '\n'; } out += line; lineOpen = true; }; return { push(text: string): string { const value = String(text ?? ''); if (!value) return ''; received = true; const before = out.length; let rest = value; while (rest) { const nl = rest.indexOf('\n'); if (nl < 0) { // 没有换行:本行还没结束 if (lineOpen) { out += rest; // 已开出,直接续写 } else { pendingLine += rest; // 能判定就提前释放(扣住的只是「可能变成列表项」的短前缀) if (pendingLine && (isListItemSoFar(pendingLine) || !couldBecomeListItem(pendingLine))) { openLine(pendingLine); } } rest = ''; break; } // 遇到换行:本行到此结束 const piece = rest.slice(0, nl); if (lineOpen) { out += piece; } else { pendingLine += piece; openLine(pendingLine); } out += '\n'; // 这一行与下一行之间的分隔符 prevLine = pendingLine; pendingLine = ''; lineOpen = false; rest = rest.slice(nl + 1); } return out.slice(before); }, finish(): string { if (!received) return ''; const before = out.length; // 输入末尾没有换行的那一行(或「输入以 \n 结尾」时那个尾部空行) if (!lineOpen) { openLine(pendingLine); pendingLine = ''; } return out.slice(before); }, }; }; /* 应用层的内容对齐(纯函数,供 useBusinessAssistantChat 调用) */ /** * `answer_end`:把已上屏的内容对齐到最终全文 —— 正常是纯尾缀追加(零抖动); * 与增量拼接不一致时整块重建,重建前先剥掉基线里的 ``(否则卡片会闪现重播)。 */ export const applyAnswerStreamEnd = ( content: string, streamedBody: string, finalText: string ): string => { const text = String(content || ''); const body = String(streamedBody || ''); // 兜底:末尾不是这段流式正文(被别的路径改过)→ 什么都不切,直接接上最终正文(绝不丢字) if (!body || !text.endsWith(body)) { return body ? text + finalText : text + finalText; } if (finalText.startsWith(body)) { return text + finalText.slice(body.length); // 正常路径:纯尾缀追加 } // 罕见分歧(后端最终校验改过草稿):整块重建,基线里的 先剥掉 const base = text.slice(0, text.length - body.length).replace(/]*>[\s\S]*?<\/scope>\s*/gi, ''); return base + finalText; }; /** * 流式轮里 `answer` 事件那段开场概述要不要展示:去掉空白后是流式正文的前缀 → 同一段的 * 压缩版,跳过;不是 → 另一段内容,必须保留(宁可多一段,不能丢字)。 */ export const shouldKeepAnswerOverview = (overview: string, streamBody: string): boolean => { const collapsed = String(overview || '').replace(/\s+/g, ''); if (!collapsed) return false; const body = String(streamBody || '').replace(/\s+/g, ''); if (!body) return true; // 正文为空:绝不能丢 // 判据:与正文的公共前缀占概述的比重(压缩版常截断在词中间,严格前缀比不出来) const max = Math.min(collapsed.length, body.length); let common = 0; while (common < max && collapsed[common] === body[common]) common++; return common < collapsed.length * 0.9; }; /** * 流式轮的最终组装:把「正文之上」「正文」「正文之下」三块拼成完整内容 —— * 正文是整篇长文,卡片需排在正文之上,参考资料/二维码仍在正文之下。 * 拼接前剥掉基线里的 `` 进度标记(整块重写会让卡片被重新解析、闪现重播)。 */ export const composeStreamedContent = ( baseText: string, leading: string, body: string, trailing: string ): string => { const base = String(baseText || '').replace(/]*>[\s\S]*?<\/scope>\s*/gi, ''); return [base, leading, body, trailing] .map((part) => String(part || '').trimEnd()) .filter((part) => part.trim().length > 0) .join('\n\n'); }; /** * 这段开场概述是不是已经会在别处展示(是就不必再摆一遍,否则会走整块重排): * 与某条 notice 归一化后相同,或正文里已经含这句。 */ export const isOverviewAlreadyShown = ( overview: string, body: string, notices: readonly string[] = [] ): boolean => { const text = String(overview || '').replace(/\s+/g, ''); if (!text) return true; const bodyText = String(body || '').replace(/\s+/g, ''); if (bodyText && bodyText.includes(text)) return true; return notices.some((notice) => String(notice || '').replace(/\s+/g, '') === text); }; /** * `answer_end` 之后把应用侧记录的「流式正文」同步成**上屏正文**:最终文本可能比增量拼接更长, * 不同步会让重排时后缀匹配失败(卡片插到正文后面、正文上屏两份)。 * 取 `finalText`;它为空时保持原值(宁可保留旧值,也不能清空而丢正文)。 */ export const resolveStreamedBodyAfterEnd = (streamedBody: string, finalText: string): string => { const next = String(finalText ?? ''); return next ? next : String(streamedBody ?? ''); }; export interface StreamComposeResult { /** 重排后的完整内容 */ next: string; /** 上屏内容末尾是否就是这段流式正文(false = 落了兜底分支) */ matched: boolean; } /** * 流式轮重排:把「正文之上(卡片)」与「正文之下(参考资料等)」摆到正文两侧, * 得到版式 卡片 → 正文 → 参考资料。 * * 上屏内容以这段正文结尾时切掉正文重拼;否则**绝不把正文再插一份**,而是以它的 * 最后一次出现为锚点切开(正文确实找不到才补插,宁可多一段也不丢字)。 */ export const composeAroundStreamBody = ( content: string, streamedBody: string, leading: string, trailing: string, /** 需要先从内容里抹掉的、之前已上屏的「正文之上」内容(卡片集合变了时用) */ replacedLeading = '', /** 同上,但抹的是「正文之下」:尾部已提前上屏、现在需要重排时用(见 flushTailEarly) */ replacedTrailing = '' ): StreamComposeResult => { let before = String(content ?? ''); const body = String(streamedBody ?? ''); const stale = String(replacedLeading ?? ''); // 卡片集合变了(开流后才又来了 item):旧卡片块已被 `leading` 取代,先抹掉,否则两份并存 if (stale && stale !== leading && before.includes(stale)) { before = before.replace(stale, '').replace(/\n{3,}/g, '\n\n'); } // 尾部提前上屏过、现在要按新顺序重排(典型:二维码要排在参考资料之前)→ 先抹掉旧尾部 const staleTail = String(replacedTrailing ?? ''); if (staleTail && before.includes(staleTail)) { before = before.replace(staleTail, '').replace(/\n{3,}/g, '\n\n'); } if (!body) { return { next: composeStreamedContent(before, leading, '', trailing), matched: true }; } if (before.endsWith(body)) { return { next: composeStreamedContent(before.slice(0, before.length - body.length), leading, body, trailing), matched: true, }; } const at = before.lastIndexOf(body); if (at < 0) { // 正文不在上屏内容里:补插(不丢字优先)—— 不该出现的路径,调用方会告警 return { next: composeStreamedContent(before, leading, body, trailing), matched: false }; } const base = before.slice(0, at); const afterBody = before.slice(at + body.length); return { next: composeStreamedContent( base, leading, body, [afterBody, trailing].filter((part) => String(part || '').trim()).join('\n\n') ), matched: false, }; }; /** * `answer_abort` / 断流:撤掉未定稿的草稿 —— 用**后缀匹配**从当前内容里去掉这段流式正文, * 不按「开流时的基线长度」切(基线可能已被别的路径改过,切了会错位)。 */ export const applyAnswerStreamAbort = (content: string, streamedBody: string): string => { const text = String(content || ''); const body = String(streamedBody || ''); if (!body || !text.endsWith(body)) return text; // 对不上就不动(宁可多留,也不切坏) return text.slice(0, text.length - body.length); }; /* 事件解析 */ export type AnswerStreamTarget = 'summary' | 'answer'; export type AnswerAbortReason = | 'generation_failed' | 'regenerating' | 'not_used' | 'not_finalized'; export type AnswerEndStatus = 'completed' | 'fallback'; export type ParsedAnswerStreamEvent = | { kind: 'start'; streamId: string; target: AnswerStreamTarget; sequence: number } | { kind: 'delta'; streamId: string; target: AnswerStreamTarget; sequence: number; text: string } | { kind: 'end'; streamId: string; target: AnswerStreamTarget; sequence: number; text: string; status: AnswerEndStatus; } | { kind: 'abort'; streamId: string; target: AnswerStreamTarget; sequence: number; reason: AnswerAbortReason; }; const asRecord = (value: unknown): Record | null => value && typeof value === 'object' && !Array.isArray(value) ? (value as Record) : null; const pickString = (value: unknown): string | null => { if (typeof value !== 'string') return null; const trimmed = value.trim(); return trimmed ? trimmed : null; }; const pickSequence = (value: unknown): number | null => { if (typeof value === 'number' && Number.isFinite(value)) return value; if (typeof value === 'string' && value.trim() && Number.isFinite(Number(value))) { return Number(value); } return null; }; const TARGETS: AnswerStreamTarget[] = ['summary', 'answer']; const ABORT_REASONS: AnswerAbortReason[] = [ 'generation_failed', 'regenerating', 'not_used', 'not_finalized', ]; /** * 解析流式事件。形状不符(`stream_id` 缺失/空、`target` 非法)→ 返回 null,协调器不处理 * 该事件(正文退回 answer/summary 完整事件路径,不丢内容)。 * 其余字段宽松:`sequence` 缺失按 0,`text` 非字符串按空串,`status`/`reason` 非法取兜底。 */ export function parseAnswerStreamEvent( data: unknown, eventName: string ): ParsedAnswerStreamEvent | null { const node = asRecord(data); if (!node) return null; const streamId = pickString(node.stream_id); if (!streamId) return null; const target = pickString(node.target) as AnswerStreamTarget | null; if (!target || !TARGETS.includes(target)) return null; const sequence = pickSequence(node.sequence) ?? 0; const text = typeof node.text === 'string' ? node.text : ''; switch (eventName) { case 'answer_start': return { kind: 'start', streamId, target, sequence }; case 'answer_delta': return { kind: 'delta', streamId, target, sequence, text }; case 'answer_end': { const status = pickString(node.status) === 'completed' ? 'completed' : 'fallback'; return { kind: 'end', streamId, target, sequence, text, status }; } case 'answer_abort': { const raw = pickString(node.reason) as AnswerAbortReason | null; const reason = raw && ABORT_REASONS.includes(raw) ? raw : 'generation_failed'; return { kind: 'abort', streamId, target, sequence, reason }; } default: return null; } } /* 状态机 */ export interface AnswerStreamState { /** 当前活动流的 id;null = 本轮没有活动流(走旧路径) */ streamId: string | null; target: AnswerStreamTarget | null; /** 已消费的最大序号 */ lastSequence: number; /** 是否出现过序号缺口(拼接不完整,等最终替换兜底) */ hasGap: boolean; /** 是否已收到 answer_end(正文已定稿) */ completed: boolean; /** 拼接草稿;completed 后即最终正文 */ text: string; } export const createAnswerStreamState = (): AnswerStreamState => ({ streamId: null, target: null, lastSequence: 0, hasGap: false, completed: false, text: '', }); export type AnswerStreamEffect = | { kind: 'none' } | { kind: 'start'; streamId: string; target: AnswerStreamTarget } | { kind: 'append'; text: string; hasGap: boolean } | { kind: 'replace'; streamId: string; target: AnswerStreamTarget; text: string; status: AnswerEndStatus } | { kind: 'discard'; streamId: string; reason: AnswerAbortReason }; /** * 把事件折算成「新状态 + 要执行的效果」: * - start:重置为新流 * - delta:过期流 / 已完成流 / 已消费序号(`sequence <= lastSequence`)一律忽略; * 序号缺口(`sequence > lastSequence + 1`)置 `hasGap` 但仍按序拼接(等最终替换兜底) * - end:同 id 才处理;无论 `completed` 还是 `fallback` 都**整块替换** * - abort:同 id 才处理;复位状态(丢弃临时正文) */ export function applyAnswerStreamEvent( state: AnswerStreamState, ev: ParsedAnswerStreamEvent | null ): { state: AnswerStreamState; effect: AnswerStreamEffect } { if (!ev) return { state, effect: { kind: 'none' } }; if (ev.kind === 'start') { return { state: { streamId: ev.streamId, target: ev.target, lastSequence: ev.sequence, hasGap: false, completed: false, text: '', }, effect: { kind: 'start', streamId: ev.streamId, target: ev.target }, }; } // 后面的三类都必须同 id(过期流的 end/delta/abort 一律忽略) if (ev.streamId !== state.streamId) { return { state, effect: { kind: 'none' } }; } if (ev.kind === 'delta') { if (state.completed) return { state, effect: { kind: 'none' } }; // end 之后的 delta 不认 if (ev.sequence <= state.lastSequence) return { state, effect: { kind: 'none' } }; // 已消费序号 const hasGap = state.hasGap || ev.sequence > state.lastSequence + 1; return { state: { ...state, lastSequence: ev.sequence, hasGap, text: state.text + ev.text, }, effect: { kind: 'append', text: ev.text, hasGap }, }; } if (ev.kind === 'end') { return { state: { ...state, completed: true, lastSequence: ev.sequence, text: ev.text, }, effect: { kind: 'replace', streamId: ev.streamId, target: ev.target, text: ev.text, status: ev.status, }, }; } // abort return { state: createAnswerStreamState(), effect: { kind: 'discard', streamId: ev.streamId, reason: ev.reason }, }; }