人工智能AI 应用AI Agent交互助手MCP Clients本地部署【免费下载链接】CodePilotA multi-model AI agent desktop client — connect any AI provider, extend with MCP skills, control from your phone. Built with Electron Next.js.项目地址https://gitcode.com/gh_mirrors/co0dep/CodePilot点击查看免费下载CodePilot 的 Markdown Live Preview 是一套基于 CodeMirror 的所见即所得编辑方案光标所在行始终显示无损的 Markdown 源码其余行则渲染为标题、表格、代码块、Mermaid 图与 KaTeX 公式。本文以仓库中的live-preview-100k.md性能测试夹具为切入点结合生成脚本、核心实现、编辑器集成与单元测试完整还原该功能的架构设计、性能策略与数据不变量读者可据此理解 10 万字符级长文档在 CodeMirror 中保持流畅的原因并掌握 Live Preview 扩展的接入方式与约束。一、live-preview-100k.md一个 100K 字符的 Live Preview 性能夹具src/__tests__/fixtures/md/live-preview-100k.md是仓库为 Markdown Live Preview 准备的性能测试夹具总字符数约 100,000100K。它不是手工撰写的示例文档而是由脚本确定性生成的、模拟真实长文档结构的压力样本用于验证 Live Preview 在 10 万字符文档上的渲染与滚动表现。生成方式generate-live-preview-fixture.mjs夹具由 scripts/generate-live-preview-fixture.mjs 生成文档头部也明确标注了这一点Generated byscripts/generate-live-preview-fixture.mjswith seed0x20260729.脚本的核心逻辑如下let seed 0x20260729; function random() { seed ^ seed 13; seed ^ seed 17; seed ^ seed 5; return (seed 0) / 0x1_0000_0000; }使用xorshift 伪随机数发生器固定种子0x20260729保证每次生成的夹具完全一致、可复现这样测试断言和性能基线才是稳定的生成结果写入src/__tests__/fixtures/md/live-preview-100k.md若常规内容不足 100K 字符脚本会在末尾追加“补充段落”确保总长度达到 100,000 字符的测试目标见脚本 generate-live-preview-fixture.mjs。夹具内容结构200 个 Section 的混合排版夹具由 200 个编号 Section 组成每个 Section 都包含一段中英文混排的说明文字、两个列表项其中一个带行内数学公式。中英文混排的目的用夹具自己的话说是“覆盖实际文档中的排版、选择和输入行为”即检验 Live Preview 对中文输入法IME、英文 token 与混合选择场景的处理。除此之外夹具按照固定节奏周期性混入不同块类型形成一份“排版压力剖面”周期注入内容用途每 4 个 SectionTypeScript 代码块ts验证代码块 widget 渲染与语法内容保持每 10 个 SectionMarkdown 表格\| Type \| Status \| Section \|验证 GFM 表格的列对齐与 cell 文本剥离每 25 个 Section块级数学公式$$...$$验证 KaTeX display 模式渲染每个 Section行内数学$x_n y_n$与链接验证行内 math 与链接 marker 装饰以 Section 4 的代码块为例夹具中的代码刻意用“deterministic viewport load”注释构造了固定长度的函数体模拟真实文档中常见的、长度稳定的代码片段export function section4(value: number) { const value0 value 0; // deterministic viewport load const value1 value 1; // deterministic viewport load // ... 多个变量声明 return value4; }每 25 个 Section 还穿插了块级数学公式如\sum_{i1}^{25} i \frac{25(251)}{2}配合每 10 个 Section 的表格共同覆盖了 CodePilot 文档生态中最常出现的三类富文本块代码、表格、数学。二、夹具反复强调的四条设计不变量通读夹具会发现每段说明文字都在反复强调同几条核心语义它们不是废话而是 Live Preview 设计契约的浓缩也是生成脚本从 generate-live-preview-fixture.mjs 的中英文文案池中随机抽取的“设计要点模板”。归纳起来共四条1. Live Preview keeps the Markdown source lossless while presenting inactive blocksMarkdown 源码必须无损非活动块inactive blocks则以渲染形态呈现。这意味着编辑器的文档模型里永远是纯 Markdown 原文绝不存在一份“渲染后的富文本副本”所有视觉富文本都是基于源码临时生成的装饰层decoration可随时丢弃重建。2. Viewport-bounded decorations keep long documents responsive during scrolling装饰的构建范围被限制在视口visible ranges之内滚动时只处理当前可见区域这是 100K 长文档保持流畅滚动的关键。3. Autosave, undo, and external file conflict handling remain independent of rendering自动保存、撤销、外部文件冲突处理与渲染完全解耦。渲染装饰是“可丢弃的视图层”不会污染撤销历史也不会影响文件保存逻辑。4. 文件内容始终是唯一事实源渲染装饰不能进入撤销历史“文件内容 唯一事实源single source of truth”。渲染装饰只是投影光标所在行必须“恢复原始标记”——当光标进入某个被渲染的块时该块立即回退为原始 Markdown 文本保证编辑永远作用于真实源码。这四条不变量在交接文档 docs/handover/markdown-live-preview-file-tree.md 中被正式记录为“关键不变量”并有对应的数据流图disk source → PreviewPanel.editContent → MarkdownEditor / CodeMirror document → ephemeral decorations/widgets。三、底层实现markdown-live-preview.ts的装饰引擎Live Preview 的全部核心逻辑位于 src/components/editor/markdown-live-preview.ts主要包括三大构件块级 StateField、行内 ViewPlugin、以及统一的原子区间提供器。3.1 可见范围与活动行的判定构建装饰前实现先做两件事markdown-live-preview.tsmergedSpans()把 CodeMirror 报告的多个可见区间viewport 可能被折叠行、固定元素切成多段排序并合并为不相交的 span 列表activeLines()把当前 selection 所在的整行标记为“活动区”。后续所有块级 / 行内装饰的生成都遵守两个过滤条件const isVisible (span: Span) overlapsAny(span, visible); const isActive (span: Span) overlapsAny(span, active);只有“可见且非活动”的节点才会被替换为渲染 widget——这就是“光标所在行恢复原始标记其余内容保持清晰可读”的实现基础。3.2 三种装饰角色replace / mark / atomic实现中通过两个数组累积装饰markdown-live-preview.tsreplace 装饰把**、、#、等标记字符替换为 widget 或直接隐藏例如heading-prefix、emphasis-marker、link-marker、task-checkboxmark 装饰给内容区间套上语义 class如cm-lp-heading cm-lp-h1、cm-lp-strong、cm-lp-linkatomic ranges所有 replace 区间同时注册为原子区间atomic ranges光标在它们中间无法停留只能跨过从而避免“光标落到被隐藏标记内部”的编辑错乱。3.3 块级渲染从语法树到 Widget块级逻辑遍历 Lezer 语法树对FencedCode与Table节点做整块替换markdown-live-preview.ts生成四类 widgetWidget对应块渲染细节CodeBlockWidgetts 等代码围栏卡片式容器头部显示语言名pre code纯文本输出避免二次执行用户代码MermaidWidget动态import(mermaid)securityLevel: strict按darkclass 切换主题失败时降级显示源码TableWidgetGFM 管道表格自实现splitPipeRow解析器支持\|转义inlineText剥离 cell 内的加粗/链接/行内代码标记MathWidget$$...$$块公式使用 KaTeXrenderToStringdisplayMode: true、throwOnError: false、trust: false需要特别说明的是display math 与行内 math 都不属于lezer/markdown基础语法因此实现用“行扫描 正则”补充检测markdown-live-preview.ts 与 markdown-live-preview.ts块公式从$$起始行向后找闭合行行内公式用/(^|[^\\$])\$([^$\n]?)\$/g匹配。夹具中每 25 个 Section 的$$...$$与每 Section 的$x_n y_n$正是为这两条检测路径提供压力样本。3.4 行内渲染标题、强调、链接、图片、任务列表非块级装饰由同一语法树遍历的第二轮处理markdown-live-preview.ts覆盖ATX/Setext 标题隐藏#前缀heading-prefix内容套cm-lp-heading cm-lp-h1..h6frontmatter 的---会被显式排除避免被误判为分隔线或 Setext 标题对应测试用例“keeps frontmatter as source”加粗/斜体/删除线/行内代码隐藏两侧标记内容套cm-lp-strong、cm-lp-emphasis、cm-lp-strikethrough、cm-lp-code链接隐藏[、]与(url)只留下cm-lp-link文本图片则整体替换为img组件带 lazy loading 与 alt 文字说明ImageWidget任务列表[ ]/[x]替换为禁用的 checkbox widgetTaskCheckboxWidgetaria-checked反映勾选态有序任务列表保留序号有序号时用TextWidget显示原数字无序列表的-才被隐藏——测试专门断言了1.前缀必须保留引用块与分隔线替换为│字符---替换为hr。3.5 性能策略StateField 映射 ViewPlugin 重建markdownLivePreview()返回的扩展由三部分拼装markdown-live-preview.ts块级StateField创建时对全文档构建一次块装饰更新时只在 selection 变化或外部值同步时全量重建普通键入只做value.map(transaction.changes)的廉价位置映射——因为“活动行是原始源码”活动块内部根本不需要 widget这保证正常打字延迟与纯编辑器无异行内ViewPlugin基于view.visibleRanges构建在组合输入composition期间冻结装饰并映射composition 结束才重建避免 IME 过程中的抖动对应夹具反复强调的“中英文混排用于覆盖……选择和输入行为”EditorView.atomicRanges提供器把块级装饰与行内装饰的原子区间合并统一约束光标移动。四、无损编辑与外部同步externalMarkdownValueSyncLive Preview 必须保证“源码无损”但编辑器本身是受控组件controlled value磁盘刷新、冲突合并、自动保存恢复都会从外部写入新内容。externalMarkdownValueSyncmarkdown-live-preview.ts实现了这一桥接通过前缀 后缀比对找出新旧字符串的最小差异区间只替换中间部分如hello world!→hello CodePilot!只替换world→CodePilot测试断言只有单个 changed span给事务打上externalMarkdownValueSyncAnnotation注解并标记addToHistory.of(false)即外部同步不进入撤销历史若新旧值相同则返回null避免自回显循环。单元测试 src/tests/unit/markdown-live-preview.test.ts 验证了“应用最小外部 diff 且不增加 undo 步骤”同步后undoDepth保持不变撤销仍回到同步前的用户编辑状态——这正是“渲染装饰不能进入撤销历史”的落地证明。五、编辑器集成MarkdownEditor 与 PreviewPanelLive Preview 通过 src/components/editor/MarkdownEditor.tsx 接入产品其设计要点注释中标注为 “Phase 4 replacement for the rawtextarea”包括5.1 Compartment 化配置编辑器用两个Compartment分别管理主题与Live Preview 选项主题切换走themeCompartment.reconfigure(...)不重建 EditorView因此明暗切换无闪烁、不丢光标文件名变化时通过livePreviewCompartment.reconfigure(...)重新挂载markdownLivePreview({ filename, sessionId })保证相对图片始终解析到当前文件所属 session而不丢失编辑历史。5.2 文件类型门禁只有.md/.mdx后缀才启用 Live Previewfunction isMarkdownFilename(filename: string | undefined): boolean { return !!filename /\.(?:md|mdx)$/i.test(filename); }非 Markdown 文件降级为纯 CodeMirror 编辑这与交接文档“.md/.mdx打开后直接进入 CodeMirror Live Preview不再保留 Edit/Preview 双切换”的产品决策一致。5.3 编辑器配置细节使用minimalSetup无行号、无 fold gutter因为 Live Preview 是文档面而非代码编辑器必须用markdown({ base: markdownLanguage })启用 GFM 扩展语法——注释明确指出默认 CommonMark 会把管道表格解析成段落导致表格失去渲染一致性Mod-s拦截触发onSaveTab 走indentWithTab插入两空格与旧 textarea 行为对齐挂载ResizeObserver观察宿主容器在侧边栏拖拽改变宽度时主动requestMeasure()解决 flex 祖先变宽导致换行测量滞后的边界问题。5.4 与 PreviewPanel 的数据流src/components/layout/panels/PreviewPanel.tsx 通过动态 import 加载 MarkdownEditor并继续持有loadedPath、editContent、dirty 状态、冲突检测与自动保存MarkdownEditor 只接收字符串、通过updateListener回传新值。整个过程不产生第二份富文本数据磁盘文件始终是唯一事实源。六、样式契约globals.css 中的.cm-lp-*Live Preview 的视觉样式集中在 src/app/globals.css[data-markdown-editor]选择器作用域内产品主题契约被单元测试直接断言见 markdown-live-preview.test.ts 的 “product-theme contract”CodeMirror canvas 背景必须与工作区卡片共用--backgroundtoken渲染后的标题用--foreground嵌套的 CodeMirror 语法 span 必须color: inherit防止语法高亮色泄漏进渲染标题代码主题只能影响活动源码的 token不能覆盖文档面或渲染后的标题颜色。同时全局样式表里有layer base { .cm-editor, .cm-editor * { all: revert-layer; } }的 Tailwind v4 preflight 隔离见 MarkdownEditor.tsx 注释且明确不要用 Shadow DOM 包裹否则 token 继承会失效、焦点行为异常。七、测试体系从 POC 到生产契约的三层验证仓库围绕 Live Preview 建立了三层测试POC 层src/tests/unit/live-preview-poc.test.ts验证 Phase 0.A 的装饰模型可行性包括 replace/mark 语义快照、跨节点选区全部还原源码、半开区间half-open ranges不重复装饰跨区间节点、composition 期间冻结并映射装饰、外部同步生成最小中间替换且不增加 undo 深度生产层src/tests/unit/markdown-live-preview.test.ts断言 12 类装饰 kind 齐全heading-prefix、emphasis-marker、strikethrough-marker、math-inline、link-marker、image、task-list-prefix、task-checkbox、table、code-block、mermaid、math-block验证 frontmatter 保持源码、光标进入活动块时该块还原而其他块仍渲染、Mod-f搜索快捷键保留、相对图片解析到/api/files/serve?path...sessionId...契约层结合 docs/handover/markdown-live-preview-file-tree.md 记录的“Markdown 数据流与不变量”保证实现与产品语义一致。八、100K 夹具的价值如何验证 10 万字符的流畅度回到live-preview-100k.md本身——它存在的意义在于把“长文档性能”变成一个可重复验证的命题确定性固定种子0x20260729的 xorshift 保证每次生成的夹具字节一致性能基线可比内容密度200 个 Section 内含 50 个代码块、20 个表格、8 个块公式与 200 组行内公式几乎每个滚动视口都会同时命中块级 widget 与行内装饰压力覆盖充分文案多样性中英文混排文案池覆盖“排版/选择/输入”“无损源码/非活动块”“视口装饰/滚动响应”“自动保存/撤销/冲突”四组关键词即使内容重复也能保证每个视口的文本形态不完全一致工程前提CodeMirror 自带视图虚拟化O(viewport)渲染Live Preview 的视口装饰策略与之一致因此 10 万字符文件的编辑与滚动都不需要应用层额外优化见 MarkdownEditor.tsx 注释。如需复现或扩展这类测试可直接运行生成脚本并按需调整 Section 数量、注入周期或目标字符数当前为 100,000node scripts/generate-live-preview-fixture.mjs生成结果会覆盖写入src/__tests__/fixtures/md/live-preview-100k.md可用于驱动后续的渲染正确性与滚动性能断言。九、总结CodePilot 的 Markdown Live Preview 以“Markdown 源码是唯一事实源、装饰是可丢弃的投影”为总原则通过块级 StateField 与行内 ViewPlugin 的双层装饰架构把视口边界、活动行还原、IME 冻结、外部同步与撤销隔离等复杂约束一一落地。live-preview-100k.md作为 100K 字符的确定性夹具是验证这套引擎在长文档下“源码无损、渲染及时、滚动流畅”的标尺也是后续性能回归测试的稳定基线。对希望在 CodeMirror 上实现 WYSIWYG 编辑的开发者而言markdown-live-preview.ts、MarkdownEditor.tsx 与其配套测试构成了一套可直接借鉴的完整范本。赞分享人工智能AI 应用AI Agent交互助手MCP Clients本地部署【免费下载链接】CodePilotA multi-model AI agent desktop client — connect any AI provider, extend with MCP skills, control from your phone. Built with Electron Next.js.项目地址https://gitcode.com/gh_mirrors/co0dep/CodePilot点击查看免费下载相关推荐CodePilot Live Preview 装饰核心 POC 拆解CodeMirror 6 下 Markdown 渲染/编辑双态的 state 层实现CodePilot Live Preview 装饰核心 POC 拆解CodeMirror 6 下 Markdown 渲染/编辑双态的 state 层实现 本篇人工智能AI 应用AI Agent交互助手MCP Clients本地部署Rich 的 Markdown 终端渲染深度解析从 Markdown 渲染器到 CLI 与源码实现Rich 的 Markdown 终端渲染深度解析从 Markdown 渲染器到 CLI 与源码实现 本篇基于 Rich 官方 API 参考页 markdownMarkwon 嵌套引用块Nested Blockquotes渲染解析从测试夹具到 BlockQuoteSpan 源码实现Markwon 嵌套引用块Nested Blockquotes渲染解析从测试夹具到 BlockQuoteSpan 源码实现 Markwon 是一个不依赖UI组件移动开发上一篇Dagger TypeScript SDKContainerAsServiceOpts 类型全解析——container.asService() 的六个可选参数与引擎侧行为下一篇解决PrimeVue Galleria组件移动端缩略图点击失效的3个关键步骤创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/10 5:16:58 · 阅读 1.2k CodePilot Markdown Live Preview 深入解析：从 100K 夹具到无损源码渲染引擎
人工智能AI 应用AI Agent交互助手MCP Clients本地部署【免费下载链接】CodePilotA multi-model AI agent desktop client — connect any AI provider, extend with MCP skills, control from your phone. Built with Electron Next.js.项目地址https://gitcode.com/gh_mirrors/co0dep/CodePilot点击查看免费下载CodePilot 的 Markdown Live Preview 是一套基于 CodeMirror 的所见即所得编辑方案光标所在行始终显示无损的 Markdown 源码其余行则渲染为标题、表格、代码块、Mermaid 图与 KaTeX 公式。本文以仓库中的live-preview-100k.md性能测试夹具为切入点结合生成脚本、核心实现、编辑器集成与单元测试完整还原该功能的架构设计、性能策略与数据不变量读者可据此理解 10 万字符级长文档在 CodeMirror 中保持流畅的原因并掌握 Live Preview 扩展的接入方式与约束。一、live-preview-100k.md一个 100K 字符的 Live Preview 性能夹具src/__tests__/fixtures/md/live-preview-100k.md是仓库为 Markdown Live Preview 准备的性能测试夹具总字符数约 100,000100K。它不是手工撰写的示例文档而是由脚本确定性生成的、模拟真实长文档结构的压力样本用于验证 Live Preview 在 10 万字符文档上的渲染与滚动表现。生成方式generate-live-preview-fixture.mjs夹具由 scripts/generate-live-preview-fixture.mjs 生成文档头部也明确标注了这一点Generated byscripts/generate-live-preview-fixture.mjswith seed0x20260729.脚本的核心逻辑如下let seed 0x20260729; function random() { seed ^ seed 13; seed ^ seed 17; seed ^ seed 5; return (seed 0) / 0x1_0000_0000; }使用xorshift 伪随机数发生器固定种子0x20260729保证每次生成的夹具完全一致、可复现这样测试断言和性能基线才是稳定的生成结果写入src/__tests__/fixtures/md/live-preview-100k.md若常规内容不足 100K 字符脚本会在末尾追加“补充段落”确保总长度达到 100,000 字符的测试目标见脚本 generate-live-preview-fixture.mjs。夹具内容结构200 个 Section 的混合排版夹具由 200 个编号 Section 组成每个 Section 都包含一段中英文混排的说明文字、两个列表项其中一个带行内数学公式。中英文混排的目的用夹具自己的话说是“覆盖实际文档中的排版、选择和输入行为”即检验 Live Preview 对中文输入法IME、英文 token 与混合选择场景的处理。除此之外夹具按照固定节奏周期性混入不同块类型形成一份“排版压力剖面”周期注入内容用途每 4 个 SectionTypeScript 代码块ts验证代码块 widget 渲染与语法内容保持每 10 个 SectionMarkdown 表格\| Type \| Status \| Section \|验证 GFM 表格的列对齐与 cell 文本剥离每 25 个 Section块级数学公式$$...$$验证 KaTeX display 模式渲染每个 Section行内数学$x_n y_n$与链接验证行内 math 与链接 marker 装饰以 Section 4 的代码块为例夹具中的代码刻意用“deterministic viewport load”注释构造了固定长度的函数体模拟真实文档中常见的、长度稳定的代码片段export function section4(value: number) { const value0 value 0; // deterministic viewport load const value1 value 1; // deterministic viewport load // ... 多个变量声明 return value4; }每 25 个 Section 还穿插了块级数学公式如\sum_{i1}^{25} i \frac{25(251)}{2}配合每 10 个 Section 的表格共同覆盖了 CodePilot 文档生态中最常出现的三类富文本块代码、表格、数学。二、夹具反复强调的四条设计不变量通读夹具会发现每段说明文字都在反复强调同几条核心语义它们不是废话而是 Live Preview 设计契约的浓缩也是生成脚本从 generate-live-preview-fixture.mjs 的中英文文案池中随机抽取的“设计要点模板”。归纳起来共四条1. Live Preview keeps the Markdown source lossless while presenting inactive blocksMarkdown 源码必须无损非活动块inactive blocks则以渲染形态呈现。这意味着编辑器的文档模型里永远是纯 Markdown 原文绝不存在一份“渲染后的富文本副本”所有视觉富文本都是基于源码临时生成的装饰层decoration可随时丢弃重建。2. Viewport-bounded decorations keep long documents responsive during scrolling装饰的构建范围被限制在视口visible ranges之内滚动时只处理当前可见区域这是 100K 长文档保持流畅滚动的关键。3. Autosave, undo, and external file conflict handling remain independent of rendering自动保存、撤销、外部文件冲突处理与渲染完全解耦。渲染装饰是“可丢弃的视图层”不会污染撤销历史也不会影响文件保存逻辑。4. 文件内容始终是唯一事实源渲染装饰不能进入撤销历史“文件内容 唯一事实源single source of truth”。渲染装饰只是投影光标所在行必须“恢复原始标记”——当光标进入某个被渲染的块时该块立即回退为原始 Markdown 文本保证编辑永远作用于真实源码。这四条不变量在交接文档 docs/handover/markdown-live-preview-file-tree.md 中被正式记录为“关键不变量”并有对应的数据流图disk source → PreviewPanel.editContent → MarkdownEditor / CodeMirror document → ephemeral decorations/widgets。三、底层实现markdown-live-preview.ts的装饰引擎Live Preview 的全部核心逻辑位于 src/components/editor/markdown-live-preview.ts主要包括三大构件块级 StateField、行内 ViewPlugin、以及统一的原子区间提供器。3.1 可见范围与活动行的判定构建装饰前实现先做两件事markdown-live-preview.tsmergedSpans()把 CodeMirror 报告的多个可见区间viewport 可能被折叠行、固定元素切成多段排序并合并为不相交的 span 列表activeLines()把当前 selection 所在的整行标记为“活动区”。后续所有块级 / 行内装饰的生成都遵守两个过滤条件const isVisible (span: Span) overlapsAny(span, visible); const isActive (span: Span) overlapsAny(span, active);只有“可见且非活动”的节点才会被替换为渲染 widget——这就是“光标所在行恢复原始标记其余内容保持清晰可读”的实现基础。3.2 三种装饰角色replace / mark / atomic实现中通过两个数组累积装饰markdown-live-preview.tsreplace 装饰把**、、#、等标记字符替换为 widget 或直接隐藏例如heading-prefix、emphasis-marker、link-marker、task-checkboxmark 装饰给内容区间套上语义 class如cm-lp-heading cm-lp-h1、cm-lp-strong、cm-lp-linkatomic ranges所有 replace 区间同时注册为原子区间atomic ranges光标在它们中间无法停留只能跨过从而避免“光标落到被隐藏标记内部”的编辑错乱。3.3 块级渲染从语法树到 Widget块级逻辑遍历 Lezer 语法树对FencedCode与Table节点做整块替换markdown-live-preview.ts生成四类 widgetWidget对应块渲染细节CodeBlockWidgetts 等代码围栏卡片式容器头部显示语言名pre code纯文本输出避免二次执行用户代码MermaidWidget动态import(mermaid)securityLevel: strict按darkclass 切换主题失败时降级显示源码TableWidgetGFM 管道表格自实现splitPipeRow解析器支持\|转义inlineText剥离 cell 内的加粗/链接/行内代码标记MathWidget$$...$$块公式使用 KaTeXrenderToStringdisplayMode: true、throwOnError: false、trust: false需要特别说明的是display math 与行内 math 都不属于lezer/markdown基础语法因此实现用“行扫描 正则”补充检测markdown-live-preview.ts 与 markdown-live-preview.ts块公式从$$起始行向后找闭合行行内公式用/(^|[^\\$])\$([^$\n]?)\$/g匹配。夹具中每 25 个 Section 的$$...$$与每 Section 的$x_n y_n$正是为这两条检测路径提供压力样本。3.4 行内渲染标题、强调、链接、图片、任务列表非块级装饰由同一语法树遍历的第二轮处理markdown-live-preview.ts覆盖ATX/Setext 标题隐藏#前缀heading-prefix内容套cm-lp-heading cm-lp-h1..h6frontmatter 的---会被显式排除避免被误判为分隔线或 Setext 标题对应测试用例“keeps frontmatter as source”加粗/斜体/删除线/行内代码隐藏两侧标记内容套cm-lp-strong、cm-lp-emphasis、cm-lp-strikethrough、cm-lp-code链接隐藏[、]与(url)只留下cm-lp-link文本图片则整体替换为img组件带 lazy loading 与 alt 文字说明ImageWidget任务列表[ ]/[x]替换为禁用的 checkbox widgetTaskCheckboxWidgetaria-checked反映勾选态有序任务列表保留序号有序号时用TextWidget显示原数字无序列表的-才被隐藏——测试专门断言了1.前缀必须保留引用块与分隔线替换为│字符---替换为hr。3.5 性能策略StateField 映射 ViewPlugin 重建markdownLivePreview()返回的扩展由三部分拼装markdown-live-preview.ts块级StateField创建时对全文档构建一次块装饰更新时只在 selection 变化或外部值同步时全量重建普通键入只做value.map(transaction.changes)的廉价位置映射——因为“活动行是原始源码”活动块内部根本不需要 widget这保证正常打字延迟与纯编辑器无异行内ViewPlugin基于view.visibleRanges构建在组合输入composition期间冻结装饰并映射composition 结束才重建避免 IME 过程中的抖动对应夹具反复强调的“中英文混排用于覆盖……选择和输入行为”EditorView.atomicRanges提供器把块级装饰与行内装饰的原子区间合并统一约束光标移动。四、无损编辑与外部同步externalMarkdownValueSyncLive Preview 必须保证“源码无损”但编辑器本身是受控组件controlled value磁盘刷新、冲突合并、自动保存恢复都会从外部写入新内容。externalMarkdownValueSyncmarkdown-live-preview.ts实现了这一桥接通过前缀 后缀比对找出新旧字符串的最小差异区间只替换中间部分如hello world!→hello CodePilot!只替换world→CodePilot测试断言只有单个 changed span给事务打上externalMarkdownValueSyncAnnotation注解并标记addToHistory.of(false)即外部同步不进入撤销历史若新旧值相同则返回null避免自回显循环。单元测试 src/tests/unit/markdown-live-preview.test.ts 验证了“应用最小外部 diff 且不增加 undo 步骤”同步后undoDepth保持不变撤销仍回到同步前的用户编辑状态——这正是“渲染装饰不能进入撤销历史”的落地证明。五、编辑器集成MarkdownEditor 与 PreviewPanelLive Preview 通过 src/components/editor/MarkdownEditor.tsx 接入产品其设计要点注释中标注为 “Phase 4 replacement for the rawtextarea”包括5.1 Compartment 化配置编辑器用两个Compartment分别管理主题与Live Preview 选项主题切换走themeCompartment.reconfigure(...)不重建 EditorView因此明暗切换无闪烁、不丢光标文件名变化时通过livePreviewCompartment.reconfigure(...)重新挂载markdownLivePreview({ filename, sessionId })保证相对图片始终解析到当前文件所属 session而不丢失编辑历史。5.2 文件类型门禁只有.md/.mdx后缀才启用 Live Previewfunction isMarkdownFilename(filename: string | undefined): boolean { return !!filename /\.(?:md|mdx)$/i.test(filename); }非 Markdown 文件降级为纯 CodeMirror 编辑这与交接文档“.md/.mdx打开后直接进入 CodeMirror Live Preview不再保留 Edit/Preview 双切换”的产品决策一致。5.3 编辑器配置细节使用minimalSetup无行号、无 fold gutter因为 Live Preview 是文档面而非代码编辑器必须用markdown({ base: markdownLanguage })启用 GFM 扩展语法——注释明确指出默认 CommonMark 会把管道表格解析成段落导致表格失去渲染一致性Mod-s拦截触发onSaveTab 走indentWithTab插入两空格与旧 textarea 行为对齐挂载ResizeObserver观察宿主容器在侧边栏拖拽改变宽度时主动requestMeasure()解决 flex 祖先变宽导致换行测量滞后的边界问题。5.4 与 PreviewPanel 的数据流src/components/layout/panels/PreviewPanel.tsx 通过动态 import 加载 MarkdownEditor并继续持有loadedPath、editContent、dirty 状态、冲突检测与自动保存MarkdownEditor 只接收字符串、通过updateListener回传新值。整个过程不产生第二份富文本数据磁盘文件始终是唯一事实源。六、样式契约globals.css 中的.cm-lp-*Live Preview 的视觉样式集中在 src/app/globals.css[data-markdown-editor]选择器作用域内产品主题契约被单元测试直接断言见 markdown-live-preview.test.ts 的 “product-theme contract”CodeMirror canvas 背景必须与工作区卡片共用--backgroundtoken渲染后的标题用--foreground嵌套的 CodeMirror 语法 span 必须color: inherit防止语法高亮色泄漏进渲染标题代码主题只能影响活动源码的 token不能覆盖文档面或渲染后的标题颜色。同时全局样式表里有layer base { .cm-editor, .cm-editor * { all: revert-layer; } }的 Tailwind v4 preflight 隔离见 MarkdownEditor.tsx 注释且明确不要用 Shadow DOM 包裹否则 token 继承会失效、焦点行为异常。七、测试体系从 POC 到生产契约的三层验证仓库围绕 Live Preview 建立了三层测试POC 层src/tests/unit/live-preview-poc.test.ts验证 Phase 0.A 的装饰模型可行性包括 replace/mark 语义快照、跨节点选区全部还原源码、半开区间half-open ranges不重复装饰跨区间节点、composition 期间冻结并映射装饰、外部同步生成最小中间替换且不增加 undo 深度生产层src/tests/unit/markdown-live-preview.test.ts断言 12 类装饰 kind 齐全heading-prefix、emphasis-marker、strikethrough-marker、math-inline、link-marker、image、task-list-prefix、task-checkbox、table、code-block、mermaid、math-block验证 frontmatter 保持源码、光标进入活动块时该块还原而其他块仍渲染、Mod-f搜索快捷键保留、相对图片解析到/api/files/serve?path...sessionId...契约层结合 docs/handover/markdown-live-preview-file-tree.md 记录的“Markdown 数据流与不变量”保证实现与产品语义一致。八、100K 夹具的价值如何验证 10 万字符的流畅度回到live-preview-100k.md本身——它存在的意义在于把“长文档性能”变成一个可重复验证的命题确定性固定种子0x20260729的 xorshift 保证每次生成的夹具字节一致性能基线可比内容密度200 个 Section 内含 50 个代码块、20 个表格、8 个块公式与 200 组行内公式几乎每个滚动视口都会同时命中块级 widget 与行内装饰压力覆盖充分文案多样性中英文混排文案池覆盖“排版/选择/输入”“无损源码/非活动块”“视口装饰/滚动响应”“自动保存/撤销/冲突”四组关键词即使内容重复也能保证每个视口的文本形态不完全一致工程前提CodeMirror 自带视图虚拟化O(viewport)渲染Live Preview 的视口装饰策略与之一致因此 10 万字符文件的编辑与滚动都不需要应用层额外优化见 MarkdownEditor.tsx 注释。如需复现或扩展这类测试可直接运行生成脚本并按需调整 Section 数量、注入周期或目标字符数当前为 100,000node scripts/generate-live-preview-fixture.mjs生成结果会覆盖写入src/__tests__/fixtures/md/live-preview-100k.md可用于驱动后续的渲染正确性与滚动性能断言。九、总结CodePilot 的 Markdown Live Preview 以“Markdown 源码是唯一事实源、装饰是可丢弃的投影”为总原则通过块级 StateField 与行内 ViewPlugin 的双层装饰架构把视口边界、活动行还原、IME 冻结、外部同步与撤销隔离等复杂约束一一落地。live-preview-100k.md作为 100K 字符的确定性夹具是验证这套引擎在长文档下“源码无损、渲染及时、滚动流畅”的标尺也是后续性能回归测试的稳定基线。对希望在 CodeMirror 上实现 WYSIWYG 编辑的开发者而言markdown-live-preview.ts、MarkdownEditor.tsx 与其配套测试构成了一套可直接借鉴的完整范本。赞分享人工智能AI 应用AI Agent交互助手MCP Clients本地部署【免费下载链接】CodePilotA multi-model AI agent desktop client — connect any AI provider, extend with MCP skills, control from your phone. Built with Electron Next.js.项目地址https://gitcode.com/gh_mirrors/co0dep/CodePilot点击查看免费下载相关推荐CodePilot Live Preview 装饰核心 POC 拆解CodeMirror 6 下 Markdown 渲染/编辑双态的 state 层实现CodePilot Live Preview 装饰核心 POC 拆解CodeMirror 6 下 Markdown 渲染/编辑双态的 state 层实现 本篇人工智能AI 应用AI Agent交互助手MCP Clients本地部署Rich 的 Markdown 终端渲染深度解析从 Markdown 渲染器到 CLI 与源码实现Rich 的 Markdown 终端渲染深度解析从 Markdown 渲染器到 CLI 与源码实现 本篇基于 Rich 官方 API 参考页 markdownMarkwon 嵌套引用块Nested Blockquotes渲染解析从测试夹具到 BlockQuoteSpan 源码实现Markwon 嵌套引用块Nested Blockquotes渲染解析从测试夹具到 BlockQuoteSpan 源码实现 Markwon 是一个不依赖UI组件移动开发上一篇Dagger TypeScript SDKContainerAsServiceOpts 类型全解析——container.asService() 的六个可选参数与引擎侧行为下一篇解决PrimeVue Galleria组件移动端缩略图点击失效的3个关键步骤创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考