CodeWF.Avalonia / 文档 / 决策记录
决策记录
本文档记录 CodeWF.Avalonia(重点是 Markdown 产品线)的重要设计决策,每条尽量包含: 背景、决策、理由、被否决的方案及否决理由。被否决方案的留档与决策本身同样重要—— 避免后人重走已经走过并放弃的路。实施中发现的新决策与踩坑随做随记。
目录
渲染
D1 渲染产物为真实控件树,而非自绘
- 背景:Markdown 渲染有两条主流路线:自绘(逐行排版录制视觉层,如聊天流式渲染库的做法)与控件树(每块产出 Grid / SelectableTextBlock 等真实控件)。
- 决策:采用控件树路线,每块由
IMarkdownBlockRenderer责任链渲染为真实控件。 - 理由:本库定位是"长文档、全功能"——表格交互、任务列表回写、图片预览、选择协调、导出,这些都依赖真实控件与 hit-testing;控件树让功能密度最高,也让宿主可以用常规 Avalonia 手段定制。
- 否决:自绘逐行渲染管线。它为"逐 token 高频更新 + 低单块开销"而生,单块开销低,但文本选择、可访问性、控件复用都要重造轮子,与本库定位冲突。若未来出现聊天流式场景(短消息、逐 token、重流畅度),再按场景评估,不在本库主线内实施。
D2 HTML 内联表格按原生表格渲染
- 背景:作者粘贴的 HTML 常含
<table>,按原始 HTML 渲染会显示为标签原文。 - 决策:
UseHtmlTables能力将 HTML 表格解析后按原生表格渲染器渲染,与 Markdown 表格视觉一致。 - 理由:真实缺陷修复(公众号/网页粘贴场景高频出现)。
增量与性能
D3 编辑驱动增量:合并窗口 + 后台解析 + 版本门控
- 背景:编辑器场景 Markdown 属性高频变化(连续输入、粘贴),同步解析阻塞 UI。
- 决策:
MarkdownRenderScheduler以 70ms 合并窗口折叠连续变更,后台线程解析,版本号门控丢弃过期结果,完成后回到创建线程回调。 - 理由:把解析成本移出 UI 线程且不放大解析次数;版本门控保证乱序完成不回退。
- 否决:同步解析(打字卡顿);无合并窗口的直接队列(连续输入时解析次数等于击键次数)。
D4 块级 diff + FNV-1a 哈希复用 + 脏区间窗口比较
- 背景:全量重渲染视觉树是大文档卡顿的主因。
- 决策:解析层为每块记录源码 span、纯文本 span、FNV-1a 内容哈希与重块标记;更新时
MarkdownDiffService先做前缀/后缀块对齐,再在脏区间窗口内比较,哈希相同即复用已渲染块;只有受影响区段走ReplaceRenderedBlocks。 - 理由:绝大多数编辑只影响局部;哈希复用让"内容没变的块永不重建视觉树"。
- 否决:无 diff 的全量替换(实现最简单,但大文档每次输入都重建全部控件,实测不可接受);纯文本行级 diff(Markdown 块结构跨行,行级对齐误判率高)。
- 注意:脚注 / TOC / 链接引用定义属于全局依赖,其变化强制全量重渲染——正确性优先于增量。
D5 块虚拟化:WindowedStackPanel + 重块 KeepAlive + 滚动方向锚定
- 背景:大文档(数百块)全部物化时内存与布局开销大(曾实测 1.6MB 文档全量物化内存失控)。
- 决策:基座
WindowedStackPanel只物化视口 ± overscan 的块,索引由调用方维护;块数 ≤ 40 不虚拟化;≥ 200 块时离屏内容延迟创建;代码块/表格/图片/公式/Mermaid 等重块离屏后按 3000dip 高度预算保留(避免滚回来重新高亮/解码/光栅化);滚动方向锚定 1–2 个已量测块防视口跳动。 - 理由:虚拟化解决内存,KeepAlive 解决"滚动即卡";锚定解决物化高度变化导致的视口跳动。
- 否决:
VirtualizingStackPanel(变高项滚动条跳动、索引漂移,实测放弃);无预算上限的全保留(内存回到失控)。
D6 长代码用 TextLayout 样式区间排版,而非逐 token 逻辑树
- 背景:长代码块(≥ 64 行)逐 token 构建
Run逻辑树开销大。 - 决策:
HighlightedCodeTextBlock以 TextLayout 样式区间一次排版着色。 - 否决:逐 token 构建 Inline 逻辑树(对象数与分配都高一个数量级)。
D7 代码高亮主题按实际底色感知亮度选择,而非仅看主题变体
- 背景:代码块底色可能来自半透明合成或自定义主题变体(如 Desert/NightSky),
ActualThemeVariant无法反映真实明暗。 - 决策:按代码块实际渲染底色计算感知亮度选择 DarkPlus/LightPlus。
- 否决:仅看
ActualThemeVariant(半透明背景与自定义变体下误判,文字对比度出错)。
编辑器
D8 WYSIWYG:隐藏语法字符 0.001 字号占位,源码索引不变
- 背景:即时编辑要在富文本呈现下保持光标/选区/IME 与 Markdown 源码索引一致。
- 决策:
MarkdownInlinePresenter(TextPresenter子类)把隐藏的 Markdown 语法字符渲染为 0.001 字号透明占位 run,文本内容本身保持源码原文。 - 理由:光标、选区、IME 预编辑天然对齐源码坐标,不需要双向映射表;预编辑文本还能继承光标处富文本样式。
- 否决:富文本模型与源码模型双向同步(同步 bug 无穷尽,IME 组合期尤甚)。
D9 任务列表勾选回写源码,撤销栈归宿主
- 背景:阅读视图勾选任务列表需要反映到源码,否则下次打开即丢失。
- 决策:
TaskWriteBackRequested事件把新源码交给宿主写回;Viewer 不碰宿主的撤销栈。 - 理由:撤销语义属于编辑器(AvaloniaEdit / LiveEditor 各自不同),库越界代管必然与宿主冲突。
能力包
D10 Mermaid 用 Mermaider 纯 .NET 渲染,不内嵌浏览器
- 决策:
mermaid围栏经 Mermaider 出 SVG,后台线程 + CTS 取消 + 48 图 LRU 缓存 + 明暗主题自动重渲 + 失败回落源码。 - 否决:内嵌 WebView/JS 方案(体积、启动成本、AOT 兼容、进程稳定性全输)。
D11 数学公式用 CSharpMath,已知字形缺失在上游层修复
- 决策:
UseMath()注册 CSharpMath 排版$..$/$$..$$;化学式\ce{}降级为上下标文本。 - 已知问题:上游 CSharpMath 部分字形缺失;宿主侧(Vex)已用自研画布修复,库内以能力包隔离,替换实现不动渲染层。
D12 代码高亮 TextMateSharp,两级 LRU 缓存
- 决策:完整包
CodeHighlighter基于 TextMateSharp.Grammars,grammar 与行高亮结果两级 LRU(32);未注册高亮器时 Lite 降级单色等宽,不抛错。 - 理由:能力可选、降级可用是 Lite 包"仅 Avalonia + Markdig"约束的自然延伸。
主题与本地化
D13 主题双轨制:样式类名 + 资源键,不依赖任何应用主题
- 决策:渲染输出统一挂
MdH1…MdCodeBlock样式类;排版主题是纯资源字典(18 套),经MarkdownTypographyThemeRegistry注册;调色板走ThemeDictionaries;对外暴露*Key设计令牌属性(如EditorBackgroundKey)供宿主把键指向 Semi/Fluent 令牌。 - 理由:编辑器模板资源独立于 Fluent/Simple 应用主题,宿主换肤零耦合;实测与 Semi.Avalonia 混合叠加有回归测试保护。
- 否决:绑定具体主题库 API(生态绑定死锁);只靠隐式样式(宿主覆盖困难)。
D14 I18n:内嵌 JSON + T4 生成键常量
- 决策:Lite 内嵌 en-US / zh-CN / zh-Hant / ja-JP 四语言 JSON,键常量由
Language.ttT4 生成;缺文化回退英文;宿主可实现IMarkdownEditorLocalizer整体替换。 - 否决:resx(AOT 与动态语言切换都别扭);宿主必填翻译(接入成本不可接受)。
流式(进行中)
D15 流式管线:append-only 内核与编辑驱动路径并列,切换以回归为门禁
- 背景:编辑驱动增量(D3/D4)对追加型输入(AI 输出、文件下载、逐段粘贴) 每步都要整篇重解析,成本 O(全文);基线实测 20KB 文档按 4 字符/token 流完 1278ms / 2.5GB 分配(见 基准报告)。
- 决策:新增
MarkdownStreamingDocument(Streaming/ 目录,规格见 流式规则)——只追加源码缓冲为唯一真相、冻结边界只扫新文本、 冻结片段一次解析且块实例跨快照共享、尾部 remend 容错、偏移映射回原始坐标。 Viewer 以StreamingSource附加属性消费快照,快照模型交给现有块级 diff 复用。 - 并列而非立即替换:
Markdown整串属性暂走原调度器,两路径并存; 整串路径切换到流式 Reset 留作后续提交——门禁是阅读位置保存/恢复、 滚动同步、选区这三块对时序敏感的回归测试先补齐。 - 实测:同样 5120 步追加,流式内核 30ms / 105.6MB(42× / 24×)。
- 等价性保障:StreamingEquivalenceTests 矩阵(21 语料 × 固定/随机分片)
- 20 条 remend fixture 数据驱动回放。
- 实施中发现的缺陷与规则(详见流式规则 §3.3/§3.4):
- 容器上下文抑制:lazy continuation 会把顶层样式行吞进引用/列表容器, 容器开启期间抑制 setext 与决定性冻结,结构块只在零缩进识别;
- HTML Type 6 开启期间抑制全部顶层冻结(结构行并入块内,只能空行收尾);
- 数学块/原始 HTML 的单行闭合形态直接在行尾冻结;
- 实施初版"空行后开启"判定读到被提前清理的标志位(三组状态机死代码), 等价性矩阵第一轮即暴露——规格先行的价值实证。
- 否决:立即删除调度器双路径合一(时序敏感回归未补齐前不冒险); 自绘渲染管线(见 D1)。
D16 链接防钓鱼:库层只检测 + 事件,确认 UI 归宿主
- 背景:
[https://github.com](https://evil.example)形态的伪装链接 (文字与目标主机不符)是文档编辑器的高频钓鱼载体。 - 决策:
MarkdownUrlPolicy.IsMisleadingLinkText检测(文字像 URL 但 主机与目标不一致才触发,普通文字链接不误报);LinkClicked事件在打开前 触发并携带RequiresConfirmation标记,宿主置Cancel阻止打开。 - 否决:库内置确认对话框(无法适配宿主的 UI 体系与语言);检测到伪装 直接拒绝打开(误伤合法文档,决定权应归宿主)。
D17 代码块折叠状态按块键存于 Viewer
- 决策:折叠状态字典键 = 块源码起始偏移,存 Viewer 不存控件—— 同文档重渲染、虚拟化回收、主题/字号切换不丢失;更换文档(源码变更) 自动重置。≥8 行才显示折叠按钮。
- 否决:状态存控件 Tag(虚拟化回收即丢);独立的 BlockStateStore 类 (当前只有折叠一个消费者,直接字典即可,出现第二消费者再抽象)。
D18 图片磁盘缓存默认禁用、本地白名单默认不限制
- 决策:
MarkdownImageDiskCache.CacheDirectory由宿主显式设置才启用;SetAllowedLocalImageRoots由宿主显式配置才限制。缓存写入尽力而为 (损坏只表现为未命中),白名单外抛UnauthorizedAccessException走降级显示。 - 理由:库升级不改变既有行为;打开不可信文档时由宿主(Vex/TKCode 式 应用)决定安全边界。
D19 无障碍:真实控件路线的免费收益 + 如实声明边界
- 决策:根
MarkdownViewerAutomationPeer(Document 角色 + 纯文本名称 截断 2000 字符);代码块按钮带语言前缀命名。文本块/按钮基于真实控件 自动获得框架 peer(控件树路线红利,自绘路线需重造)。 - 边界:Avalonia 无公开 TextPattern——读屏可读名称与操作, 文本级光标浏览不可用,文档如实声明不夸大。
配色与排版令牌体系
D20 控件层 8 色编写 + 派生引擎;Markdown 层主题自成体系;规则单文档为唯一事实源
- 背景:Studio 内置 16 套配色每套 Light/Dark 两份 axaml 全手写(含派生色),三处 HTML 原型的令牌快照手工复制已漂移(两库
palette-tokens.cssmd5 不一致);Markdown 侧 18 套主题颜色+排版一体。Vex 原型观感老化,需要换风格并支持用户自定义配色/排版/密度。三方库(Semi.Avalonia、Ursa.Themes.Semi)只读。 - 决策:
- 控件层:用户只编写 8 个基础色(最简 4 色,状态色有全局默认),其余 ~30 个语义键由固定派生规则(透明度烘焙为不透明色)生成,含 Semi 覆写;内置配色定稿 9 套高对比风格、3×3 九宫格目录(石墨/靛蓝/青碧/松绿/天青/琥珀/绯红/紫晶/陶土),直接替换旧 16 套,无兼容(自用)。密度紧凑/正常/宽松三档显式值表。
- Markdown 层:主题自成体系(accent/decoration × 双明暗 + 内置中性阶梯 + 排版相对量),不消费 Studio 令牌;分无缝型/成品型两原型,成品型自带 backdrop/contentSurface 纸面块,对比度对 contentSurface 校验,导出默认剥离 backdrop。定稿 12 套替换现有 18 套。尺寸档(13/15/17)与控件层密度独立不联动。
- 全部规则、常数、数据集中于《配色与排版令牌规则.md》单文档(附录 A 机器可读块),引擎与原型生成器同源解析;快照由生成器产出带版本戳,禁止手写。
- 理由:编写量从 50+ 手写值降到每套 8 色;ink 低透明度派生在明暗两态自动成立(Primer/Linear 同思路);两层解耦使文档主题不受界面配色牵连,仅四个接缝(明暗联动、纸面归属、Mermaid、编辑器 chrome/字号分工);桥接点全在自研库(Studio 令牌文件内覆写 SemiColor*),三方库零改动成立。
- 否决:
- 语义键全手写(26 键 × 2 明暗每套):编写负担大且派生值易失控,退化为编写层/消费层两层模型;
- Markdown 颜色轴跟界面配色走(映射上移进库):与既有"颜色+排版一体"的主题模型(mdnice 系心智)冲突,撤回;
- 密度与文档字号档联动(或加跟随开关):UI 密度动机是省空间、阅读字号是个人偏好,联动互相干扰,且导出会被运行时设置污染;
- 旧配色/主题兼容保留(hidden 组):自用为主,无存量兼容负担,直接替换。
D21 画布中性化:paper/surface 由引擎去色温,换配色不改画布
- 背景:ruleVersion 5 的 surface 按"比 paper 深一档"派生并继承色板色温(如青碧浅色
#EDF7F5),铺满树面板/属性面板/状态栏/代码底后整屏被单一色相浸染,画布从"背景"变成"主题色块";大面积染色同时放大跨色板对比度漂移(深色 Badge/Card 对比度门禁失败的同类病根)。v5 的"色温偏染 ≤ 5%"按单色卡色度度量,未考虑覆盖面,5% 色温铺满面板即是可感知色块。 - 决策:规则升版
ruleVersion 6,新增 §5.1 画布中性化——派生引擎在派生前把 paper/surface 转换为等相对明度的中性灰(色度归零,海拔差保留);附录 A 两键取值降级为编写层声明(色卡展示与明度标定),色温由引擎剥离。色相只保留在 ink、accent、状态色与 selected/hover/accentSoft 等小面积交互态。换界面配色只改变强调与交互态,浅色画布恒为白系、深色画布恒为近黑系。 - 理由:强调色的信号价值来自稀缺性,画布染色既拉平视觉层级又放大对比度漂移;中性画布(Windows 强调色/Fluent/Semi 的通行做法)让 9 套色板的差异集中在强调与交互态,跨色板对比度输入空间减半;引擎层一次性实现,5 处派生副本(共享 palette-rules.js × 3、generate-studio-cs.cjs、StudioPaletteEngine.cs)同步,附录数据与消费端结构零改动。
- 否决:
- 附录 A 逐套手改中性 surface 值:9 套 × 2 态手工维护,未来新增色板仍可能重新引入色温,治标不治本;
- 保留暗色画布低饱和色温(Material You 式表面染色):需要整套 tonal 数学支撑,当前无此投入,且与"换配色不改画布"的用户预期相悖。
流式对照吸收(2026-10-26)
D22 对照 StreamMark / TKCode.Arc 的取舍:吸收运行时工程,不搬渲染内核
- 背景:对照同赛道实现 StreamMark 0.1.0(同源同构:切分/冻结/remend/快照/块键) 与组件库 TKCode.Arc(Markdown 控件为其上 900 行壳),找出可吸收的差距。 本轮确认四件领先项:解析离 UI 线程(本仓库已有)、输出节奏平滑、排版增量、 性能与 AOT 的 CI 门禁;以及若干正确性/性能细节。
- 决策:
- 吸收(已落地,规格见
docs/流式规则.md§3.4.1/§4.4/§6): 输入节奏器MarkdownStreamPacer(算法移植自 StreamMark StreamPacer,MIT, 时间注入、字素簇边界、滞留上限防饿死);未完成行前缀决定性提前冻结(E1-E4); 开放围栏尾部快速路径(跳过补全与 Markdig,逐字段对齐补全后解析——行切片 NewLine 标记、Span 起点含缩进偏移等约定经探针实测锁定);diff 复用判定 ReferenceEquals 短路(冻结前缀 diff 降为 O(新增块数));高亮行级 token 缓存 会话(前缀复用 + 词法状态链延续,对照其 TextMateHighlightSession); 宿主集成 API 面(GetOutline / ScrollToBlock / ScrollToSourceOffset, 对照 Arc Markdown 的宿主 API 清单)。50KB 代码块流式 60× 提速(基准报告)。 - 不搬:StreamMark 的 RaTeX 原生 FFI 路线(Rust 工具链 + 六 RID 分发负担, 托管数学渲染不达标前不启用);SnapshotEdit 整篇替换 LCS(仅编辑器预览场景); 每行一个 Visual 的脏区录制(依赖 Avalonia 12 TextRunCache 不稳定 API)。 TKCode.Arc 的 AtomUI 主题管线(强绑 AtomUI 6.2.8 LGPL + 精确锁版本, 不可移植,Avalonia ThemeVariant + 动态资源已够)。
- 暂缓:spring 动效引擎(约 900 行可整体移植,但当前库内无消费者, 接入流式渐显/平滑滚动属视觉行为变更,需独立设计 + 视觉验收,待需求驱动); 演示台 GDOC 式文档保真(Roslyn 源生成器 + 文档编译诊断 + headless 截图, 价值明确但属演示台基础设施专项)。
- 吸收(已落地,规格见
- 理由:与头部实现同构说明方向正确,差距集中在可独立渐进移植的运行时工程; 渲染内核是本仓库价值所在(StreamMark 与之竞争而非互补),只学 API 划分与 工程约定;库内无消费者的代码不下(spring 引擎宁可等接入点)。
令牌派生的唯一事实源(2026-10-31)
D23 静态令牌只由 Vex 生成器产出;软底收敛与状态色族在规则模块内求解
- 背景:
Tokens/*.axaml长期有两个生成器各写一遍——Vex 的sync_native_design.cjs(读原型palette-rules.js的派生表)与库内generate-studio-cs.cjs(自己实现一套 §3 公式)。谁最后跑谁赢,且两份公式已经漂开:库侧把SemiColorDangerActive填成软底值、徽章字色写死dark ? 黑 : 白(鼠尾草浅底白字 3.56:1 判不出来,因为它对的是纸面不是 accent)。同一时期深底状态按压底停在 4.24:1,根因是软底收敛的深色分支a > 0.40从 0.18 起步即恒假,一次都没步进。 - 决策:
- 文件归属:
Tokens/*.axaml、_index.axaml、ArticleTypographyCatalog.g.cs归 Vex 生成器;库内generate-studio-cs.cjs缩到只产StudioThemeVariants.g.cs与StudioPalettes.g.cs(注册表数据,不含颜色),tokens-template.axaml删除。公式仍不许在任一侧重抄——palette-rules.js模块头已写明唯一事实源是附录 A,Vex 生成器改为纯消费派生键,不再自己 mix 状态色。 - 软底收敛同式化:明暗两态一律向 paper 退(减透明度),下限 3%;退到下限仍不足 4.5:1 时不动底色,改由文字收敛。规则 §3 新增"软底收敛"条目,
StudioPaletteEngine.SoftFor与convergeSoft同式。 - 状态色族不动点:状态色 ↔ 软底 ↔ 按压底互为条件,
statusFamily(引擎侧StatusFamily)迭代至解,字色须对 paper 与自家两档软底同时 ≥4.5:1;--danger-pressed-fg == --status-error,故SemiColorDangerActive取实色、深一档的只是底SemiColorDangerLightActive。 - accent 字色阈值 3:1(规则 §2/§5):accent 是状态色不是正文字色,按 WCAG 1.4.11 判定;正文可读性由 ink/muted 的 4.5:1 守住。附录 A 常数未变,故不递增
ruleVersion,更正记录写入 §5。
- 文件归属:
- 理由:
StudioTokenParityTests逐键逐通道比对静态令牌与引擎输出,只要存在两份公式实现,它就只在"两边都错得一样"时通过;把生成链收敛成一份公式 + 一份数据(原型 JS)+ 一份运行时孪生(C# 引擎),漂移就只剩"引擎没跟住规则"这一种可测失败。本轮实测:9 套 × 明暗校验全绿,八套配色的生成令牌字节不变,仅鼠尾草的状态色/软底按通道 ≤1% 移动。 - 否决:
- 在 Vex 生成器里补一份收敛循环(治标):等于第三处公式副本,正是本次要消灭的东西;
- 深色软底靠加透明度变浓:深色 paper 本就偏暗,状态色往上叠只让字与底一起变暗,实测越叠越不合格;
- 把浅底中明度 accent 压暗到 4.5:1:为过一条误判的阈值牺牲八套配色的品牌位观感,且软底会被同一收敛推平到看不出是一层底色;
- 保留库内模板生成器作为"离线兜底":兜底文件与主文件同键同路径、无冲突提示,正是漂移的成因。