answer-stream.ts 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529
  1. /**
  2. * 正文真实增量流式输出(F073)的纯逻辑层:`answer_start / answer_delta /
  3. * answer_end / answer_abort` 事件的解析、状态机与 markdown 增量规整器。
  4. *
  5. * 不 import vue、不发网络请求,可被 harness 的 esbuild 直接打包断言。
  6. */
  7. /* markdown 规整 */
  8. export const LIST_ITEM_RE = /^\s*(?:[-*+]|\d+[.)])\s+\S/;
  9. /**
  10. * 规整 markdown 换行:渲染层是 `white-space: normal`,单个 \n 会被折叠,
  11. * 于是把非列表项之间的单换行提升为空行;连续列表项之间保留单换行,不打断编号。
  12. */
  13. /**
  14. * 两行之间是否需要插入空行。
  15. *
  16. * 规则(2026-10-29 用户要求「\n\n 换两行」):
  17. * - 普通行之间**保留原始换行**:单个 \n = 段内换行(一行),双个 \n = 空一行(分段);
  18. * - 连续列表项保持紧排(不插空行);
  19. * - 列表项与普通行之间必须插空行,否则 markdown 会把普通行并进列表项(懒续行)。
  20. */
  21. const needsBlankBetweenLines = (prev: string, line: string): boolean => {
  22. const prevBlank = prev.trim() === '';
  23. const lineBlank = line.trim() === '';
  24. if (prevBlank || lineBlank) {
  25. return false;
  26. }
  27. const prevList = LIST_ITEM_RE.test(prev);
  28. const lineList = LIST_ITEM_RE.test(line);
  29. if (prevList && lineList) {
  30. return false;
  31. }
  32. return prevList || lineList;
  33. };
  34. export function normalizeChatMarkdown(text: string): string {
  35. const value = String(text || '');
  36. if (!value.includes('\n')) {
  37. return value;
  38. }
  39. const lines = value.split('\n');
  40. const result: string[] = [lines[0]];
  41. for (let i = 1; i < lines.length; i++) {
  42. const prev = lines[i - 1];
  43. const line = lines[i];
  44. if (needsBlankBetweenLines(prev, line)) {
  45. result.push('');
  46. }
  47. result.push(line);
  48. }
  49. return result.join('\n');
  50. }
  51. /**
  52. * 增量规整器:把逐片段到达的原始正文变成「与 `normalizeChatMarkdown(全文)` 逐步同前缀」
  53. * 的增量文本 —— 否则 `answer_end` 的整块替换会与已流文本分歧,导致整段重建与卡片闪现。
  54. *
  55. * 不变式:**任一时刻 `已发出的全部文本 === normalizeChatMarkdown(已输入的全部文本)`**。
  56. */
  57. export interface IncrementalMarkdownNormalizer {
  58. /** 输入一段原始增量,返回应立即展示的规整增量(可能为空串——还在扣前缀) */
  59. push(text: string): string;
  60. /** 收尾:释放仍在扣住的部分(end 会用最终全文覆盖,故非必须) */
  61. finish(): string;
  62. }
  63. /** `line` 是否已能确定是列表项(正则无 `$` 锚,命中即不会被后续字符推翻) */
  64. const isListItemSoFar = (line: string): boolean => LIST_ITEM_RE.test(line);
  65. /** `line` 是否还可能变成列表项(是则不能提前释放) */
  66. const couldBecomeListItem = (line: string): boolean =>
  67. /^\s*$/.test(line) || // 只有空白,后面可能跟 - 或数字
  68. /^\s*[-*+]\s*$/.test(line) ||
  69. /^\s*\d+$/.test(line) ||
  70. /^\s*\d+[.)]\s*$/.test(line);
  71. export const createIncrementalMarkdownNormalizer = (): IncrementalMarkdownNormalizer => {
  72. /** 已发出的全部文本 */
  73. let out = '';
  74. /** 上一整行(用于判断「本行前是否要插空行」) */
  75. let prevLine: string | null = null;
  76. /** 当前输入行(可能还没结束) */
  77. let pendingLine = '';
  78. /** 当前行的内容是否已发出 */
  79. let lineOpen = false;
  80. /** 是否收到过输入(空输入不该在 finish 里凭空产出空行) */
  81. let received = false;
  82. /** 两行之间是否需要插入空行(与 normalizeChatMarkdown 同一判据) */
  83. const needsBlankBetween = needsBlankBetweenLines;
  84. /**
  85. * 开出一行:先补空行(需要的话),再写内容。
  86. * 换行是**行与行之间的分隔符**,行末的 `\n` 由「下一行出现」或「输入里的 `\n`」补,
  87. * 不能在本行结束时直接加一个(否则末行多出换行,与 normalizeChatMarkdown 不一致)。
  88. */
  89. const openLine = (line: string): void => {
  90. if (prevLine !== null && needsBlankBetween(prevLine, line)) {
  91. out += '\n';
  92. }
  93. out += line;
  94. lineOpen = true;
  95. };
  96. return {
  97. push(text: string): string {
  98. const value = String(text ?? '');
  99. if (!value) return '';
  100. received = true;
  101. const before = out.length;
  102. let rest = value;
  103. while (rest) {
  104. const nl = rest.indexOf('\n');
  105. if (nl < 0) {
  106. // 没有换行:本行还没结束
  107. if (lineOpen) {
  108. out += rest; // 已开出,直接续写
  109. } else {
  110. pendingLine += rest;
  111. // 能判定就提前释放(扣住的只是「可能变成列表项」的短前缀)
  112. if (pendingLine && (isListItemSoFar(pendingLine) || !couldBecomeListItem(pendingLine))) {
  113. openLine(pendingLine);
  114. }
  115. }
  116. rest = '';
  117. break;
  118. }
  119. // 遇到换行:本行到此结束
  120. const piece = rest.slice(0, nl);
  121. if (lineOpen) {
  122. out += piece;
  123. } else {
  124. pendingLine += piece;
  125. openLine(pendingLine);
  126. }
  127. out += '\n'; // 这一行与下一行之间的分隔符
  128. prevLine = pendingLine;
  129. pendingLine = '';
  130. lineOpen = false;
  131. rest = rest.slice(nl + 1);
  132. }
  133. return out.slice(before);
  134. },
  135. finish(): string {
  136. if (!received) return '';
  137. const before = out.length;
  138. // 输入末尾没有换行的那一行(或「输入以 \n 结尾」时那个尾部空行)
  139. if (!lineOpen) {
  140. openLine(pendingLine);
  141. pendingLine = '';
  142. }
  143. return out.slice(before);
  144. },
  145. };
  146. };
  147. /* 应用层的内容对齐(纯函数,供 useBusinessAssistantChat 调用) */
  148. /**
  149. * `answer_end`:把已上屏的内容对齐到最终全文 —— 正常是纯尾缀追加(零抖动);
  150. * 与增量拼接不一致时整块重建,重建前先剥掉基线里的 `<scope>`(否则卡片会闪现重播)。
  151. */
  152. export const applyAnswerStreamEnd = (
  153. content: string,
  154. streamedBody: string,
  155. finalText: string
  156. ): string => {
  157. const text = String(content || '');
  158. const body = String(streamedBody || '');
  159. // 兜底:末尾不是这段流式正文(被别的路径改过)→ 什么都不切,直接接上最终正文(绝不丢字)
  160. if (!body || !text.endsWith(body)) {
  161. return body ? text + finalText : text + finalText;
  162. }
  163. if (finalText.startsWith(body)) {
  164. return text + finalText.slice(body.length); // 正常路径:纯尾缀追加
  165. }
  166. // 罕见分歧(后端最终校验改过草稿):整块重建,基线里的 <scope> 先剥掉
  167. const base = text.slice(0, text.length - body.length).replace(/<scope\b[^>]*>[\s\S]*?<\/scope>\s*/gi, '');
  168. return base + finalText;
  169. };
  170. /**
  171. * 流式轮里 `answer` 事件那段开场概述要不要展示:去掉空白后是流式正文的前缀 → 同一段的
  172. * 压缩版,跳过;不是 → 另一段内容,必须保留(宁可多一段,不能丢字)。
  173. */
  174. export const shouldKeepAnswerOverview = (overview: string, streamBody: string): boolean => {
  175. const collapsed = String(overview || '').replace(/\s+/g, '');
  176. if (!collapsed) return false;
  177. const body = String(streamBody || '').replace(/\s+/g, '');
  178. if (!body) return true; // 正文为空:绝不能丢
  179. // 判据:与正文的公共前缀占概述的比重(压缩版常截断在词中间,严格前缀比不出来)
  180. const max = Math.min(collapsed.length, body.length);
  181. let common = 0;
  182. while (common < max && collapsed[common] === body[common]) common++;
  183. return common < collapsed.length * 0.9;
  184. };
  185. /**
  186. * 流式轮的最终组装:把「正文之上」「正文」「正文之下」三块拼成完整内容 ——
  187. * 正文是整篇长文,卡片需排在正文之上,参考资料/二维码仍在正文之下。
  188. * 拼接前剥掉基线里的 `<scope>` 进度标记(整块重写会让卡片被重新解析、闪现重播)。
  189. */
  190. export const composeStreamedContent = (
  191. baseText: string,
  192. leading: string,
  193. body: string,
  194. trailing: string
  195. ): string => {
  196. const base = String(baseText || '').replace(/<scope\b[^>]*>[\s\S]*?<\/scope>\s*/gi, '');
  197. return [base, leading, body, trailing]
  198. .map((part) => String(part || '').trimEnd())
  199. .filter((part) => part.trim().length > 0)
  200. .join('\n\n');
  201. };
  202. /**
  203. * 这段开场概述是不是已经会在别处展示(是就不必再摆一遍,否则会走整块重排):
  204. * 与某条 notice 归一化后相同,或正文里已经含这句。
  205. */
  206. export const isOverviewAlreadyShown = (
  207. overview: string,
  208. body: string,
  209. notices: readonly string[] = []
  210. ): boolean => {
  211. const text = String(overview || '').replace(/\s+/g, '');
  212. if (!text) return true;
  213. const bodyText = String(body || '').replace(/\s+/g, '');
  214. if (bodyText && bodyText.includes(text)) return true;
  215. return notices.some((notice) => String(notice || '').replace(/\s+/g, '') === text);
  216. };
  217. /**
  218. * `answer_end` 之后把应用侧记录的「流式正文」同步成**上屏正文**:最终文本可能比增量拼接更长,
  219. * 不同步会让重排时后缀匹配失败(卡片插到正文后面、正文上屏两份)。
  220. * 取 `finalText`;它为空时保持原值(宁可保留旧值,也不能清空而丢正文)。
  221. */
  222. export const resolveStreamedBodyAfterEnd = (streamedBody: string, finalText: string): string => {
  223. const next = String(finalText ?? '');
  224. return next ? next : String(streamedBody ?? '');
  225. };
  226. export interface StreamComposeResult {
  227. /** 重排后的完整内容 */
  228. next: string;
  229. /** 上屏内容末尾是否就是这段流式正文(false = 落了兜底分支) */
  230. matched: boolean;
  231. }
  232. /**
  233. * 流式轮重排:把「正文之上(卡片)」与「正文之下(参考资料等)」摆到正文两侧,
  234. * 得到版式 卡片 → 正文 → 参考资料。
  235. *
  236. * 上屏内容以这段正文结尾时切掉正文重拼;否则**绝不把正文再插一份**,而是以它的
  237. * 最后一次出现为锚点切开(正文确实找不到才补插,宁可多一段也不丢字)。
  238. */
  239. export const composeAroundStreamBody = (
  240. content: string,
  241. streamedBody: string,
  242. leading: string,
  243. trailing: string,
  244. /** 需要先从内容里抹掉的、之前已上屏的「正文之上」内容(卡片集合变了时用) */
  245. replacedLeading = '',
  246. /** 同上,但抹的是「正文之下」:尾部已提前上屏、现在需要重排时用(见 flushTailEarly) */
  247. replacedTrailing = ''
  248. ): StreamComposeResult => {
  249. let before = String(content ?? '');
  250. const body = String(streamedBody ?? '');
  251. const stale = String(replacedLeading ?? '');
  252. // 卡片集合变了(开流后才又来了 item):旧卡片块已被 `leading` 取代,先抹掉,否则两份并存
  253. if (stale && stale !== leading && before.includes(stale)) {
  254. before = before.replace(stale, '').replace(/\n{3,}/g, '\n\n');
  255. }
  256. // 尾部提前上屏过、现在要按新顺序重排(典型:二维码要排在参考资料之前)→ 先抹掉旧尾部
  257. const staleTail = String(replacedTrailing ?? '');
  258. if (staleTail && before.includes(staleTail)) {
  259. before = before.replace(staleTail, '').replace(/\n{3,}/g, '\n\n');
  260. }
  261. if (!body) {
  262. return { next: composeStreamedContent(before, leading, '', trailing), matched: true };
  263. }
  264. if (before.endsWith(body)) {
  265. return {
  266. next: composeStreamedContent(before.slice(0, before.length - body.length), leading, body, trailing),
  267. matched: true,
  268. };
  269. }
  270. const at = before.lastIndexOf(body);
  271. if (at < 0) {
  272. // 正文不在上屏内容里:补插(不丢字优先)—— 不该出现的路径,调用方会告警
  273. return { next: composeStreamedContent(before, leading, body, trailing), matched: false };
  274. }
  275. const base = before.slice(0, at);
  276. const afterBody = before.slice(at + body.length);
  277. return {
  278. next: composeStreamedContent(
  279. base,
  280. leading,
  281. body,
  282. [afterBody, trailing].filter((part) => String(part || '').trim()).join('\n\n')
  283. ),
  284. matched: false,
  285. };
  286. };
  287. /**
  288. * `answer_abort` / 断流:撤掉未定稿的草稿 —— 用**后缀匹配**从当前内容里去掉这段流式正文,
  289. * 不按「开流时的基线长度」切(基线可能已被别的路径改过,切了会错位)。
  290. */
  291. export const applyAnswerStreamAbort = (content: string, streamedBody: string): string => {
  292. const text = String(content || '');
  293. const body = String(streamedBody || '');
  294. if (!body || !text.endsWith(body)) return text; // 对不上就不动(宁可多留,也不切坏)
  295. return text.slice(0, text.length - body.length);
  296. };
  297. /* 事件解析 */
  298. export type AnswerStreamTarget = 'summary' | 'answer';
  299. export type AnswerAbortReason =
  300. | 'generation_failed'
  301. | 'regenerating'
  302. | 'not_used'
  303. | 'not_finalized';
  304. export type AnswerEndStatus = 'completed' | 'fallback';
  305. export type ParsedAnswerStreamEvent =
  306. | { kind: 'start'; streamId: string; target: AnswerStreamTarget; sequence: number }
  307. | { kind: 'delta'; streamId: string; target: AnswerStreamTarget; sequence: number; text: string }
  308. | {
  309. kind: 'end';
  310. streamId: string;
  311. target: AnswerStreamTarget;
  312. sequence: number;
  313. text: string;
  314. status: AnswerEndStatus;
  315. }
  316. | {
  317. kind: 'abort';
  318. streamId: string;
  319. target: AnswerStreamTarget;
  320. sequence: number;
  321. reason: AnswerAbortReason;
  322. };
  323. const asRecord = (value: unknown): Record<string, unknown> | null =>
  324. value && typeof value === 'object' && !Array.isArray(value)
  325. ? (value as Record<string, unknown>)
  326. : null;
  327. const pickString = (value: unknown): string | null => {
  328. if (typeof value !== 'string') return null;
  329. const trimmed = value.trim();
  330. return trimmed ? trimmed : null;
  331. };
  332. const pickSequence = (value: unknown): number | null => {
  333. if (typeof value === 'number' && Number.isFinite(value)) return value;
  334. if (typeof value === 'string' && value.trim() && Number.isFinite(Number(value))) {
  335. return Number(value);
  336. }
  337. return null;
  338. };
  339. const TARGETS: AnswerStreamTarget[] = ['summary', 'answer'];
  340. const ABORT_REASONS: AnswerAbortReason[] = [
  341. 'generation_failed',
  342. 'regenerating',
  343. 'not_used',
  344. 'not_finalized',
  345. ];
  346. /**
  347. * 解析流式事件。形状不符(`stream_id` 缺失/空、`target` 非法)→ 返回 null,协调器不处理
  348. * 该事件(正文退回 answer/summary 完整事件路径,不丢内容)。
  349. * 其余字段宽松:`sequence` 缺失按 0,`text` 非字符串按空串,`status`/`reason` 非法取兜底。
  350. */
  351. export function parseAnswerStreamEvent(
  352. data: unknown,
  353. eventName: string
  354. ): ParsedAnswerStreamEvent | null {
  355. const node = asRecord(data);
  356. if (!node) return null;
  357. const streamId = pickString(node.stream_id);
  358. if (!streamId) return null;
  359. const target = pickString(node.target) as AnswerStreamTarget | null;
  360. if (!target || !TARGETS.includes(target)) return null;
  361. const sequence = pickSequence(node.sequence) ?? 0;
  362. const text = typeof node.text === 'string' ? node.text : '';
  363. switch (eventName) {
  364. case 'answer_start':
  365. return { kind: 'start', streamId, target, sequence };
  366. case 'answer_delta':
  367. return { kind: 'delta', streamId, target, sequence, text };
  368. case 'answer_end': {
  369. const status = pickString(node.status) === 'completed' ? 'completed' : 'fallback';
  370. return { kind: 'end', streamId, target, sequence, text, status };
  371. }
  372. case 'answer_abort': {
  373. const raw = pickString(node.reason) as AnswerAbortReason | null;
  374. const reason = raw && ABORT_REASONS.includes(raw) ? raw : 'generation_failed';
  375. return { kind: 'abort', streamId, target, sequence, reason };
  376. }
  377. default:
  378. return null;
  379. }
  380. }
  381. /* 状态机 */
  382. export interface AnswerStreamState {
  383. /** 当前活动流的 id;null = 本轮没有活动流(走旧路径) */
  384. streamId: string | null;
  385. target: AnswerStreamTarget | null;
  386. /** 已消费的最大序号 */
  387. lastSequence: number;
  388. /** 是否出现过序号缺口(拼接不完整,等最终替换兜底) */
  389. hasGap: boolean;
  390. /** 是否已收到 answer_end(正文已定稿) */
  391. completed: boolean;
  392. /** 拼接草稿;completed 后即最终正文 */
  393. text: string;
  394. }
  395. export const createAnswerStreamState = (): AnswerStreamState => ({
  396. streamId: null,
  397. target: null,
  398. lastSequence: 0,
  399. hasGap: false,
  400. completed: false,
  401. text: '',
  402. });
  403. export type AnswerStreamEffect =
  404. | { kind: 'none' }
  405. | { kind: 'start'; streamId: string; target: AnswerStreamTarget }
  406. | { kind: 'append'; text: string; hasGap: boolean }
  407. | { kind: 'replace'; streamId: string; target: AnswerStreamTarget; text: string; status: AnswerEndStatus }
  408. | { kind: 'discard'; streamId: string; reason: AnswerAbortReason };
  409. /**
  410. * 把事件折算成「新状态 + 要执行的效果」:
  411. * - start:重置为新流
  412. * - delta:过期流 / 已完成流 / 已消费序号(`sequence <= lastSequence`)一律忽略;
  413. * 序号缺口(`sequence > lastSequence + 1`)置 `hasGap` 但仍按序拼接(等最终替换兜底)
  414. * - end:同 id 才处理;无论 `completed` 还是 `fallback` 都**整块替换**
  415. * - abort:同 id 才处理;复位状态(丢弃临时正文)
  416. */
  417. export function applyAnswerStreamEvent(
  418. state: AnswerStreamState,
  419. ev: ParsedAnswerStreamEvent | null
  420. ): { state: AnswerStreamState; effect: AnswerStreamEffect } {
  421. if (!ev) return { state, effect: { kind: 'none' } };
  422. if (ev.kind === 'start') {
  423. return {
  424. state: {
  425. streamId: ev.streamId,
  426. target: ev.target,
  427. lastSequence: ev.sequence,
  428. hasGap: false,
  429. completed: false,
  430. text: '',
  431. },
  432. effect: { kind: 'start', streamId: ev.streamId, target: ev.target },
  433. };
  434. }
  435. // 后面的三类都必须同 id(过期流的 end/delta/abort 一律忽略)
  436. if (ev.streamId !== state.streamId) {
  437. return { state, effect: { kind: 'none' } };
  438. }
  439. if (ev.kind === 'delta') {
  440. if (state.completed) return { state, effect: { kind: 'none' } }; // end 之后的 delta 不认
  441. if (ev.sequence <= state.lastSequence) return { state, effect: { kind: 'none' } }; // 已消费序号
  442. const hasGap = state.hasGap || ev.sequence > state.lastSequence + 1;
  443. return {
  444. state: {
  445. ...state,
  446. lastSequence: ev.sequence,
  447. hasGap,
  448. text: state.text + ev.text,
  449. },
  450. effect: { kind: 'append', text: ev.text, hasGap },
  451. };
  452. }
  453. if (ev.kind === 'end') {
  454. return {
  455. state: {
  456. ...state,
  457. completed: true,
  458. lastSequence: ev.sequence,
  459. text: ev.text,
  460. },
  461. effect: {
  462. kind: 'replace',
  463. streamId: ev.streamId,
  464. target: ev.target,
  465. text: ev.text,
  466. status: ev.status,
  467. },
  468. };
  469. }
  470. // abort
  471. return {
  472. state: createAnswerStreamState(),
  473. effect: { kind: 'discard', streamId: ev.streamId, reason: ev.reason },
  474. };
  475. }