1. 术语
# 流式规则(冻结边界与尾部容错规格)
本文档是流式渲染内核的实现规格,同时是验收标准:规则表中的每一条都要有对应的 等价性测试覆盖(见
tests/CodeWF.Avalonia.Content.Tests/Markdown/Streaming/)。 规格变更必须先改本文档再改代码。
1. 术语
| 术语 | 含义 |
|---|---|
| 源码缓冲 | 只追加(append-only)的完整 Markdown 源文本,唯一真相 |
| 冻结边界 | 源码中的一个偏移位置,之后无论到达什么文本,[0, 边界) 区间的解析结果都不会改变 |
| 冻结片段 | 相邻两个冻结边界之间的源码切片,独立解析后不再参与后续解析 |
| 尾部 | 最后一个冻结边界之后的未冻结文本,每步快照都要重解析的部分 |
| 快照 | 某一时刻的完整块模型:冻结块(对象共享)+ 尾部块(临时) |
| 块 key | 块在原始源码中的起始偏移(SourceSpan.Start),跨快照稳定 |
| 代(generation) | 一次 Reset/Complete 开启的新纪元,旧代快照全部作废 |
2. 数据流
Append(chunk) 任意线程
└→ 源码缓冲追加,通知切分器"有新文本"(进行中只置脏标记,不排队)
└→ 后台单工作者醒来:
1. 切分器逐行只扫描新到达文本 → 推进冻结边界
2. 冻结片段各自 Markdig 解析(片段级,偏移映射回原始源码)
3. 尾部 remend 补全后 Markdig 解析,偏移经映射表回到原始偏移,块标记 IsTentative
4. 组装快照(冻结块对象引用跨快照共享),发布
Complete() 流结束
└→ 整篇重解析一次开新代,修正跨片段的全局依赖(链接引用定义/脚注)
Reset(text) 整串替换(兼容现有 Markdown 属性语义)
└→ 清空缓冲、开新代、整篇解析(等价于现有编辑驱动路径)解析在单个后台工作者上串行执行;解析进行中再来的文本只置脏标记,中间版本直接跳过。 解析异常吞掉并保留上一份快照(界面不崩、停更),异常通过事件上抛给宿主。
3. 冻结边界规则
切分器从上次扫描位置起逐行处理新到达文本,在满足规则的行尾推进冻结边界:
3.1 空行规则(核心)
一行只有空白字符(空行)时,若同时满足以下全部条件,则该空行处为冻结边界:
| # | 条件 | 反例 |
|---|---|---|
| 1 | 当前不在围栏代码块内(``` / ~~~ 未闭合) | ```python\nx=1\n\n —— 围栏没闭合,空行不能冻结 |
| 2 | 当前不在数学块内($$ 未闭合) | $$\nx\n\n —— 公式没闭合 |
| 3 | 当前不在 HTML 原始块内(<script>/<pre>/<!--> 等未闭合) |
<div>\n...\n\n |
| 4 | 下一行零缩进(制表符按缩进计) | 空行后接缩进 = 代码块/列表项延续( CommonMark 松散规则) |
| 5 | 下一行不是列表项(任意序号的有序列表同样保守处理) | - a\n\n- b(松散列表,空行拆不开) |
| 6 | 下一行不是引用行(> a\n\n> b 是同一个引用块) |
|
| 7 | 下一行不是链接引用定义/脚注定义([)或定义列表行(:) |
3.2 显式闭合规则
| # | 规则 |
|---|---|
| F1 | 围栏代码块闭合行(与开围栏同字符、长度不小于开围栏)之后可冻结 |
| F2 | 数学块 $$ 闭合行之后可冻结 |
| F3 | ATX 标题行(#…###### + 空格)之后可冻结——标题不允许延续 |
| F4 | 主题分隔线(---、***)之后可冻结 |
3.3 容器上下文抑制(lazy continuation)
自上个空行以来开启了引用/列表容器时,后续顶层样式的行可能仍属于容器
(lazy continuation):> a\nb\n=== 的 setext 仍属于引用、> a\nb\n> c
是同一个引用、- a\ncont\n- c 是同一个列表。因此容器开启期间:
| # | 规则 |
|---|---|
| C1 | setext 下划线冻结被抑制 |
| C2 | 决定性新块冻结(§3.4)被抑制 |
| C3 | 围栏 / ATX 标题 / 主题分隔线仍可冻结(它们能打断容器),但只在零缩进识别——缩进 1-3 的结构行可能是容器内容 |
| C4 | 空行关闭容器上下文,空行规则的判定随之恢复正常 |
3.4 提前冻结(decisive 新块起始)
首字符能唯一决定"新顶层块开始"的完整行,可在该行之前(或行尾)冻结:
| 起始形态 | 冻结点 | 说明 |
|---|---|---|
| 围栏开启(``` / ~~~) | 行首 | 围栏可打断段落与容器;围栏本体留给尾部 |
ATX 标题(#…+ 空格) |
行尾 | 标题不允许延续,整行随边界定型 |
引用行(>) |
行首 | 仅在打断段落时(容器抑制规则同样适用) |
列表项(-/*/+/1./1) + 空格) |
行首 | 有序列表仅 1 可打断段落;2. 属 lazy continuation |
setext 下划线(段落延续时的 ===/---) |
行尾 | 标题在此行完成 |
以上均受 §3.3 容器上下文抑制约束;|(表格行)与数学块不参与提前冻结
(表格可被后续行扩展、数学块不能打断段落),由空行规则兜底。
提前冻结永不冻结"当前最后一个块"的内容(不变量 I2)。
3.4.1 未完成行的提前冻结
以上规则作用于完整行;对文档末尾尚未换行的"未完成行",其已到达的前缀只要具备 决定性(更多文本只可能延续判定、不可能推翻判定),即可把边界提前推进到未完成行 行首——未完成行本体留在尾部继续生长:
| # | 规则 |
|---|---|
| E1 | 挂起空行待判定时:前缀零缩进且已见非空白字符,并满足空行规则安全性 → 冻结于未完成行行首;数字序列必须已见到非数字字符才按标记判定(全数字前缀可能是任意段落文本,继续等待) |
| E2 | 段落延续中(容器未开启):前缀已是决定性新块起始——围栏开启(≥3 字符)、ATX(#×1-6 + 空白)、-/*/+ + 空白、1./1) + 空白、> 行首 → 冻结于未完成行行首 |
| E3 | setext 风险豁免(不冻结,等行结束):首字符为 =、或 -* 后尚无空白(-/--/--- 可能是 setext 下划线,会把上一段落改写为标题)、或 */+/`/~ 尚不满足完整起始形态(可能是行内强调/行内代码的段落延续) |
| E4 | 围栏/数学/HTML 块内、容器或 HTML 块开启期间不适用;全空白前缀(缩进未知,可能是缩进代码续行)不适用 |
E1/E2 的判定依据只使用前缀里已到达的字符,判定成立后追加任何文本都不会推翻
(- 之后的文本仍是列表项、# 之后仍是标题);不满足决定性时保持现状
(等行结束),错误方向只有"少冻结",不会误冻结(不变量 I4 不受影响)。
3.5 边界不变量
| # | 不变量 |
|---|---|
| I1 | 冻结边界单调前进,永不回退 |
| I2 | 永不冻结"当前最后一个块"——尾部至少保留一个未冻结块 |
| I3 | Reset 开新代,边界清零 |
| I4 | 完成前缀解析的等价性:对任意快照,[0, 冻结边界) 区间按片段解析得到的块序列(kind + 映射后源码 span + 内容哈希)必须与整篇解析该前缀得到的对应块序列完全一致 |
I4 是核心验收标准:流式中间结果 ≡ 整篇解析。等价性测试以任意分片 (1/3/7/32/500 字符 + 固定种子随机分片)驱动,每一步快照都断言 I4,同时断言 I1、I2,以及冻结块对象引用跨快照不变(对象共享生效)。
4. 尾部容错(remend)
尾部是用户正在看着的"半截文本",必须尽量呈现为目标形态而非原始残缺语法。 补全只作用于尾部解析的临时文本,绝不写回源码缓冲。
4.1 处理器优先级表
按优先级从小到大执行,每个处理器只处理自己认领的语法:
| 优先级 | 处理器 | 规则 |
|---|---|---|
| 10 | 未完成链接 | [text](url → 补 );[text → 补 ](codewf-md:pending) 占位链接 |
| 20 | 强调补全 | 行内 **/*/_ 开闭数量不配对时补齐闭合符(按奇偶) |
| 30 | 行内代码 | 反引号数量为奇数时补齐 |
| 35 | 删除线 | ~~ 开不闭 → 补 ~~ |
| 40 | 数学 | 未闭合 $$ 补闭合(行内单个 $ 不处理:"价格 $5" 会被错误数学化,误报成本高于收益) |
| 45 | setext 歧义打破 | 尾行只有 1-2 个 =/-(可带空白)且上一非空行有内容时插入零宽空格——半个列表项(如流式刚敲出的 -)会被误判成标题下划线(借鉴 vercel/streamdown remend,Apache-2.0) |
| 50 | 未闭合围栏 | 尾部存在未闭合围栏时,在尾部末尾补齐闭合围栏后正常解析(闭合行长度不小于开围栏;围栏开启期间跳过其余字符级处理器) |
| 60 | 半截 HTML 标签 | 尾部行尾是不完整标签(<di)时剥离该半截标签后再解析 |
处理器以委托注册(RemendHandler(string Name, Func<string, string> Handler, int Priority)),
宿主可增删,零反射。
4.4 开放围栏快速路径
尾部是"以围栏开启行开始、且尚未闭合"的形态时(AI 回答流式代码块的最高频形态), 尾部解析跳过补全与 Markdig,按围栏规则直接构造代码块:
| # | 规则 |
|---|---|
| Q1 | 命中条件:切分器停在围栏内(开围栏行 = 尾部首行,已完整),且尾部末行(可能未完成)尚未构成闭合围栏 |
| Q2 | 末行已是完整闭合围栏(含闭合围栏带尾随文本)时不命中,走常规路径补全后解析 |
| Q3 | 构造产物与常规路径逐字段一致:Lines 逐行剥离开围栏缩进、Info 取围栏后首词、SourceText/ContentHash 按补全形态(尾部 + 换行 + 闭合围栏)、PlainText 为行文本 TrimEnd、块键与常规路径同坐标系 |
| Q4 | 每步快照只做行切分与字符串拼接,不做字符级配对扫描、不构建 Markdig 文档 |
4.2 偏移映射(remend 代价)
补全会插入字符,使临时文本中 Markdig 报告的块偏移漂移。解析前记录临时文本与
原始尾部的公共前缀/插入点,解析后用双指针贪心对齐把块 span 映射回原始源码偏移,
保证块 key 稳定、选区与 UI 状态不漂移。映射不上(补全改变了块结构)时该块整块
标记 IsTentative 并使用临时坐标,下个快照自然修正。
4.3 行为规格
| # | 规格 |
|---|---|
| B1 | 流式过程中出现过的代码块,闭合后不自动折叠(用户正看着的内容不得突然收起) |
| B2 | 尾部解析异常时保留上一份尾部块,不清空 |
| B3 | Complete() 后整篇重解析开新代;跨片段的全局依赖(链接引用定义、脚注编号)此时收敛 |
| B4 | 快照发布频率不高于 UI 帧——同一帧内的多次 Append 合并为一次解析 |
5. 与现有管线的关系
MarkdownRenderScheduler的"合并窗口 + 后台解析 + 版本门控"职责由流式内核的 单工作者 + 置脏协议承接;Markdown属性 setter 语义改为Reset。MarkdownDiffService的块对齐与哈希复用保留,作用对象从"新旧全量模型"变为 "快照冻结块 + 尾部块"的组装结果——冻结块按块 key 直接复用已渲染视觉树, 只有尾部块走 diff 替换。- 编辑器驱动的"中间改写"(光标移到文中间改一个字)等价于
Reset开新代, 走整篇解析 + 现有脏区间窗口 diff,行为与现状一致。
6. 输入节奏(宿主侧,可选)
宿主从真实数据源(LLM API、WebSocket)收到的分片是突发的:一次可能到达数 KB。
直接 Append 会让尾部解析与显示节奏跟着网络抖动。MarkdownStreamPacer
(纯算法、时间由调用方注入、非线程安全、Push/Tick 同线程)插在 Append 之前,
把突发整理成按帧平滑的显示节奏:
| # | 规则 |
|---|---|
| P1 | 释放速率 = max(到达速率滑动平均 0.8/0.2, 积压/目标滞留时长);目标滞留档位 Responsive/Balanced/Smooth = 40/120/200ms |
| P2 | 滞留超过 400ms 的分片强制纳入当帧放行,尾部不饿死 |
| P3 | 释放只在字素簇边界切分:CJK 逐字、代理对与 emoji 组合序列不拆 |
| P4 | 积压超过 4096 字符置直通,下一帧整段放行(粘贴场景不等平滑) |
| P5 | Finish() 后不再接受新文本,剩余积压约 350ms 内排空;IsDrained 后宿主再调 Complete() |
典型接线:到达线程 Push(chunk, now),渲染帧 Tick(now) 并把返回文本
Append 进流式文档。演示台的流式示例即该接线(随机大小分片随机间隔到达 +
16ms 帧释放)。节奏器不参与冻结边界与 remend 的任何不变量,属于纯输入整形。