流式返回中 Markdown 代码块未完成状态的终端渲染

流式返回中 Markdown 代码块未完成状态的终端渲染在开发 AI CLI 命令行工具或终端交互 Agent 时流式输出Streaming Token是保证良好用户体验的标配能力。然而如果你直接将大模型返回的增量 Token 使用process.stdout.write()吐向终端或者交给普通的终端 Markdown 高亮解析器如 Marked-Terminal、Ink 等就会遇到一个令人头疼的现象代码块严重闪烁、样式错乱与断行撕裂。大模型输出 Markdown 代码块是一个渐进的过程首先输出typescript开头标记接着一行行吐出代码正文最后在不知道多少个 Token 之后才吐出闭合的。在这个漫长的流式生成周期里语法解析器始终处于“未闭合的语法树状态”。如果每次收到 Token 都清屏重绘整个终端会像老旧日光灯一样剧烈闪烁如果不做特殊处理代码语法高亮在闭合之前完全失效终端只会输出乱糟糟的纯文本直到最后瞬间突然样式突变。要彻底解决这一问题必须从“流式状态机解析”与“终端差量按行更新”两个底层维度进行协同优化。终端流式 Markdown 渲染的核心痛点在传统的 Web 前端DOM 树具备弹性伸缩能力未闭合的代码块可以通过外层 CSS 盒子实时撑开但在终端字符网格中存在极其严苛的物理限制ANSI 转义字符状态残留语法高亮器通过向字符流中注入 ANSI 颜色码如\x1b[32m代表绿色来着色。如果在行末没有正确重置\x1b[0m下一行的普通文本甚至终端光标都会被污染成绿色。未闭合代码块的词法断裂大多数基于词法分析Lexer的高亮库在遇到单侧时会将整段未闭合内容视为普通未完成行不会触发代码块语意导致整段代码以纯文本输出失去行号和语法着色。光标回退重绘引发的闪烁Flicker为了渲染高亮很多开发者选择在每收到一个 Chunk 时执行 ANSI 清屏指令\x1b[2J或console.clear()再把累积的全部文本重新渲染一遍。这种暴力全量刷新在输出长代码时会引发可怕的高频频闪使人眼极度疲劳。状态机与虚拟闭合修复机制优雅的解决方案是引入流式 Markdown 虚拟补全状态机Virtual Fence Balancer。核心思想非常克制维护一个极其轻量的词法状态追踪当前流式文本中 代码块标记的奇偶性。如果当前处于未闭合代码块内部奇数个 在把文本送入高亮渲染器之前在内存中追加一个虚拟的换行与闭合标记\n\ 。解析器在拿到闭合的代码块结构后能准确进行语法高亮、计算行号与边框渲染输出时通过精确的行缓存比对Line-diff只对已稳定确定的行即遇到了物理换行符\n的完整行执行单向推流对末尾正在生成的行进行行内擦除更新\x1b[2K\r彻底杜绝全屏刷新。TypeScript 渲染引擎核心实现下面展示该流式代码块修复与增量渲染的核心实现代码import hljs from highlight.js; export class StreamMarkdownRenderer { private rawAccumulated ; private committedLineCount 0; private inCodeBlock false; private currentLanguage ; public feed(chunk: string): void { this.rawAccumulated chunk; this.render(); } private render(): void { // 1. 状态机检查当前代码块闭合状态 const lines this.rawAccumulated.split(\n); const isLastLineIncomplete !this.rawAccumulated.endsWith(\n); // 追踪未闭合状态 let codeFenceCount 0; let detectedLang ; for (const line of lines) { const match line.trim().match(/^([a-zA-Z0-9_-]*)/); if (match) { codeFenceCount; if (codeFenceCount % 2 1) { detectedLang match[1] || text; } } } const isOpenCodeBlock codeFenceCount % 2 1; // 2. 提取已经定型的完整行进行稳定输出 // 只有当有换行产生时倒数第二行之前的行才算完全定型 const finalizedLines isLastLineIncomplete ? lines.slice(0, -1) : lines; while (this.committedLineCount finalizedLines.length) { const lineToCommit finalizedLines[this.committedLineCount]; this.outputCommittedLine(lineToCommit, isOpenCodeBlock, detectedLang); this.committedLineCount; } // 3. 对最后一行正在输入的未完成行进行局部高亮或普通字符刷新 if (isLastLineIncomplete) { const activeLine lines[lines.length - 1]; this.outputActiveLine(activeLine, isOpenCodeBlock, detectedLang); } } private outputCommittedLine(line: string, inCode: boolean, lang: string): void { // 如果是代码块起始或结束行 if (line.trim().startsWith()) { process.stdout.write(\x1b[90m${line}\x1b[0m\n); return; } if (inCode lang hljs.getLanguage(lang)) { try { const highlighted hljs.highlight(line, { language: lang }).value; const terminalStyled this.htmlToAnsi(highlighted); process.stdout.write( \x1b[90m│\x1b[0m ${terminalStyled}\x1b[0m\n); return; } catch { // 降级为普通行 } } // 普通文本行 process.stdout.write(${line}\n); } private outputActiveLine(line: string, inCode: boolean, lang: string): void { // 使用 ANSI 控制序列擦除当前行并重新写回避免闪烁 // \r 回到行首\x1b[2K 擦除当前整行 process.stdout.write(\r\x1b[2K); if (inCode) { process.stdout.write( \x1b[90m│\x1b[0m ${line}); } else { process.stdout.write(line); } } // 简易 HTML 转 ANSI生产环境中可接入 ansi-styles 或 cli-highlight private htmlToAnsi(html: string): string { return html .replace(/span classhljs-keyword([\s\S]*?)\/span/g, \x1b[35m$1\x1b[0m) .replace(/span classhljs-string([\s\S]*?)\/span/g, \x1b[32m$1\x1b[0m) .replace(/span classhljs-comment([\s\S]*?)\/span/g, \x1b[90m$1\x1b[0m) .replace(/span classhljs-function([\s\S]*?)\/span/g, \x1b[34m$1\x1b[0m) .replace(/[^]/g, ); // 剥离其余无用标签 } public end(): void { // 流结束时确保输出一个干净的换行 process.stdout.write(\n\x1b[0m); } }实战细节与性能优化在终端中实现高质量渲染还需要注意几个工程细节终端行宽TTY Columns自适应通过process.stdout.columns动态获取当前终端宽度。如果某一行代码超出可视宽度终端会自动换行此时如果继续使用\r\x1b[2K只能擦除最后半截物理行。因此在输出超长行时应当计算折行数或者进行末尾截断省略Truncate。高频 Chunk 的防抖合并Batching大模型在快速吐字时每个 Chunk 可能只有 1~3 个字符1 秒钟可能触发数十次feed。直接频繁操作 TTY I/O 会加剧 CPU 消耗。可以使用一个 16ms约等于 60fps的 microtask 微批处理队列将微小 chunk 聚合后再触发单次渲染。ANSI 状态重置保障在流异常中断或用户按下CtrlC时务必在退出钩子中强制写入\x1b[0m\x1b[?25h重置所有颜色属性并显式恢复终端光标避免把用户的宿主 Shell 搞得无法正常打字。总结CLI 工具的品质往往体现在这些细微的交互打磨上。通过“虚拟补全未闭合反引号”消除词法断裂配合“确定行单向提交 活跃行原地擦除”的渲染策略能够在没有任何重型 UI 框架依赖的前提下在原生终端中实现如丝般顺滑、零闪烁的大模型流式代码输出体验。