CodeWF.Avalonia 文档
dotnet9
CodeWF.Avalonia / 文档 / 1. 术语

1. 术语

⏱ 预计阅读 10 分钟 适用于 net10.0 同步于 2026-11-08 来源: CodeWF · docs/流式规则.md ✎ 在 GitHub 编辑此页

# 流式规则(冻结边界与尾部容错规格)

本文档是流式渲染内核的实现规格,同时是验收标准:规则表中的每一条都要有对应的 等价性测试覆盖(见 tests/CodeWF.Avalonia.Content.Tests/Markdown/Streaming/)。 规格变更必须先改本文档再改代码。

1. 术语

术语 含义
源码缓冲 只追加(append-only)的完整 Markdown 源文本,唯一真相
冻结边界 源码中的一个偏移位置,之后无论到达什么文本,[0, 边界) 区间的解析结果都不会改变
冻结片段 相邻两个冻结边界之间的源码切片,独立解析后不再参与后续解析
尾部 最后一个冻结边界之后的未冻结文本,每步快照都要重解析的部分
快照 某一时刻的完整块模型:冻结块(对象共享)+ 尾部块(临时)
块 key 块在原始源码中的起始偏移(SourceSpan.Start),跨快照稳定
代(generation) 一次 Reset/Complete 开启的新纪元,旧代快照全部作废

2. 数据流

text
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 的任何不变量,属于纯输入整形。