jcode Mermaid 渲染管线重构从全局状态耦合到显式分阶段管道【免费下载链接】jcodeThe most RAM efficient harness项目地址: https://gitcode.com/GitHub_Trending/jcod/jcode本篇技术指南基于 jcode 仓库中的架构决策记录ADRdocs/MERMAID_RENDERING_REDESIGN.md系统讲解终端内 Mermaid 图表渲染的现状痛点、尺寸 API 演进方向与目标管线设计。读者将掌握 jcode 中 Mermaid 渲染从全局状态 线程局部上下文向显式请求对象 分阶段纯数据管道迁移的完整思路包括渲染尺寸的测量式后端、缓存键归一化规则、调度器与注册表职责切分以及迁移计划与验证标准并可通过源码与测试用例逐一验证每项设计。一、问题背景Mermaid 路径为何难以推理jcode 的终端 TUI 需要把 Mermaid 图表渲染为 PNG再通过ratatui-image以 Kitty、Sixel、iTerm2、halfblock 等协议展示在终端中。然而在 crates/jcode-tui-mermaid/src/lib.rs 的 crate 拆分之后lib.rs仍然充当状态中枢渲染、缓存、UI 放置、活跃图表注册、延迟渲染、调试统计与终端图像协议状态全部通过全局状态和副作用耦合在一起。ADR 记录了以下可观察的痛点Markdown 渲染直接决定 Mermaid 行为流式/延迟/侧栏-only 的注册规则由 Markdown 渲染器直接内嵌而非由专门的调度层决定活跃图表是渲染的副作用register_active_diagram在渲染调用内部被触发仅仅是准备 Markdown就会改变 pinned pane 状态。对应实现见 crates/jcode-tui-mermaid/src/mermaid_active.rs 中由LazyLockMutexVecActiveDiagram承载的全局ACTIVE_DIAGRAMS线程局部渲染画像with_preferred_aspect_ratio依赖thread_local!的RENDER_PROFILE_CONTEXT见 crates/jcode-tui-mermaid/src/lib.rs导致缓存键与渲染尺寸受环境上下文影响同一份源码在不同上下文下产生不同结果同一图表多上下文复用聊天内联占位、侧栏图片、pinned pane、流式预览、调试探针五种场景共享底层函数却需要不同行为延迟渲染自成一派自带去重/epoch/全局队列还执行活跃注册加剧竞态风险协议渲染与 PNG 生成混在同一公共面图像协议渲染、PNG 生成、图像状态缓存、视口渲染全部暴露在同一个公共接口上。二、尺寸 API 方向测量代替估算渲染器现已提供由mmdr-size-apifeature 守卫的尺寸 API 路径同时要求环境变量JCODE_MMDR_SIZE_API_AVAILABLE1该路径应成为重构的主路径渲染器应直接向 Mermaid/layout 询问测量得到的 SVG/canvas 尺寸而不是依赖源码文本复杂度估算来决定最终 PNG 尺寸calculate_render_size应降级为请求目标提示request target hint不再是输出尺寸的唯一事实来源旧的 SVG 重定向retarget回退路径仅作为兼容代码保留直到打补丁的渲染器始终可用调试统计应上报render_size_backend并且在测试期望使用尺寸 API 路径而实际不可用时大声失败缓存键应包含归一化后的目标/画像输入而产物应保存尺寸 API 返回的测量输出尺寸。这一方向旨在消除四类典型缺陷宽高比重定向错误、放大模糊、占位高度不匹配、pane 尺寸变化导致的振荡。源码证据feature 与环境变量的真实开关在 crates/jcode-tui-mermaid/Cargo.toml 中可以看到[features] default [mmdr-size-api] renderer [dep:mermaid-rs-renderer] # Enables the renderer size API path. The pinned mmdr tag (v0.3.1) ships the # size API, and build.rs enables it by default; set JCODE_MMDR_SIZE_API_DISABLE1 # to fall back to the legacy SVG-retarget path. mmdr-size-api [renderer]对应的渲染后端选择在 crates/jcode-tui-mermaid/src/lib.rs 中通过render_size_backend()判定当feature mmdr-size-api且mmdr_size_api_available为真时返回mmdr-size-api否则返回svg-retarget-fallback。新路径使用mermaid_rs_renderer::render的measure_svg_dimensions与render_svg_with_dimensions依赖固定 tagv0.3.1的 git 仓库旧路径则通过解析 SVG 根标签的viewBox/width/height并调用retarget_svg_for_png完成重定向实现位于 crates/jcode-tui-mermaid/src/mermaid_svg.rs。新路径的语义值得注意先测量自然内容自适应画布再在保持宽高比的前提下把它装入请求的目标盒子——直接强制目标尺寸会把宽图 letterbox 进约 4:3 的请求盒产生大片透明留白因此该行为刻意镜像了旧retarget_svg_for_png的 fit 语义。当前估算式实现calculate_render_size(node_count, edge_count, terminal_width)crates/jcode-tui-mermaid/src/mermaid_svg.rs展示了文本复杂度估算的局限它以estimate_diagram_size统计节点/边数为复杂度因子0.6~1.1乘以终端像素宽度并夹取到[400, 2400]高度取width * 0.75夹取到[300, 1800]。这正是 ADR 建议降级为请求目标提示的算法。三、目标设计显式分阶段管线重构目标是建立阶段间传递纯数据的显式管线3.1 图表提取Diagram extractionMarkdown 渲染器只负责把围栏 Mermaid 块提取为不可变描述符不再直接改写活跃图表或同步渲染除非调用方显式要求阻塞回退struct DiagramBlock { id: DiagramId, source_hash: u64, source: Arcstr, origin: DiagramOrigin, ordinal: usize, }仓库中的 crates/jcode-tui-mermaid/src/mermaid_model.rs 已落地这一模型DiagramId由source_hash内容等价标识originChat / SidePanel / StreamingPreview / DebugProbeordinal区分同一内容的不同出现位置构成DiagramBlock则持有id与Arcstr源码。3.2 显式渲染请求Explicit render request用一个请求对象取代环境化的with_preferred_aspect_ratio与布尔参数struct RenderRequest { diagram_id: DiagramId, source_hash: u64, source: Arcstr, target: RenderTarget, profile: RenderProfile, priority: RenderPriority, mode: RenderMode, } struct RenderProfile { width_cells: Optionu16, preferred_aspect_per_mille: Optionu16, theme: MermaidTheme, } enum RenderMode { CacheOnly, EnqueueIfMissing, Blocking, }缓存键只由source_hash 归一化 RenderProfile构建绝不依赖线程局部上下文。源码中的DiagramRenderProfile已与此对应crates/jcode-tui-mermaid/src/mermaid_model.rs其cache_key(source_hash)生成DiagramCacheKey包含source_hash、width_cells、preferred_aspect_per_mille、theme四个字段Display输出形如0000000000000abc:w96:a500:TerminalDark。而normalize_aspect_ratio把Optionf32宽高比归一化为每千分位整数过滤掉非有限值与非正数ratio * 1000四舍五入后夹取到[100, 10_000]。该函数与旧RenderProfile::from_preferred_aspect_ratio的桶策略保持一致0.75 → 7501.2345 → 1235NaN/-1 → None并配有单元测试验证。RenderTargetInlineMarkdown / SidePanel / PinnedPane / DebugProbe、RenderPriorityInteractive / Visible / Background、RenderModeCacheOnly / EnqueueIfMissing / Blocking在mermaid_model.rs中均有定义DiagramRenderRequest提供cache_key()方法直接从请求推导缓存键测试render_request_derives_cache_key_from_source_hash_and_profile_only验证键只依赖source_hash profile而非 origin/ordinal/target。3.3 注册表持有活跃状态Registry owns active state引入由 TUI app/session 状态拥有的DiagramRegistry而不是 Mermaid crate 内部的全局向量。其职责追踪当前已准备 transcript/侧栏中可见的图表用 generation id 单独追踪流式预览发布有序列表供 pinned pane 选择每次 prepare pass 原子地清空/更新。渲染应返回RenderArtifact绝不把活跃注册作为副作用。当前 crates/jcode-tui-mermaid/src/mermaid_active.rs 正是 ADR 要改造的对象ACTIVE_DIAGRAMS与STREAMING_PREVIEW_DIAGRAM都是 crate 级全局静态register_active_diagram在渲染路径中被调用并受ACTIVE_DIAGRAMS_MAX 128上限约束见 crates/jcode-tui-mermaid/src/lib.rs。3.4 调度器拥有异步/延迟行为Scheduler owns async/deferred调度器接收显式请求并返回下列状态之一enum RenderStatus { Ready(RenderArtifact), Pending { request_id: RenderRequestId }, Failed(RenderError), ProtocolUnavailable, }规则去重以完整缓存键为依据worker 不得修改活跃注册表worker 完成时只发布MermaidRenderCompleted事件与产物元数据epoch 失效按请求世代generation作用域化除非确有必要不使用全局单一计数器。mermaid_model.rs中的RenderStatus与之对应Ready(RenderArtifact)、Pending { cache_key }、Failed(RenderError)、ProtocolUnavailableRenderArtifact携带cache_key、path、测量得到的width/heightRenderError记录可选cache_key与错误消息。当前实现中全局DEFERRED_RENDER_EPOCH与PENDING_RENDER_REQUESTS正是全局计数器 全局队列的现状见 crates/jcode-tui-mermaid/src/lib.rsADR 建议未来将其作用域化。3.5 放置规划与渲染解耦Placement planner is separateMarkdown/侧栏准备阶段根据RenderStatus与期望放置方式插入占位聊天/侧栏的内联图片占位行侧栏-only 模式的侧边标记渲染失败的错误块延迟/流式渲染的 pending 占位。图像 widget 渲染只消费RenderArtifact PlacementPlan不了解 Mermaid 源码或调度逻辑。现有mermaid_content.rs已提供diagram_placeholder_lines、inline_image_placeholder_lines、error_to_lines、parse_image_placeholder等占位与解析辅助函数可视为放置层的雏形。3.6 公共模块边界推荐的 crate 模块划分模块职责model.rsDiagramId、DiagramBlock、RenderProfile、RenderTarget、RenderArtifact、RenderStatus、错误类型extract.rsMarkdown Mermaid 块提取辅助cache.rs磁盘与内存产物元数据缓存renderer.rs仅负责 Mermaid parse/layout/SVG/PNG 转换scheduler.rs请求队列、worker、去重、完成事件registry.rs活跃/流式图表状态理想情况下归 app 所有placement.rs占位/图像区域规划presenter.rsratatui-image/Kitty/Sixel/iTerm 视口渲染debug.rs从显式事件收集的统计对照当前 crates/jcode-tui-mermaid/src/ 目录mermaid_model.rs模型、mermaid_active.rs活跃状态、mermaid_cache_render.rs缓存渲染、mermaid_content.rs内容/占位、mermaid_inline.rs内联图像、mermaid_runtime.rs协议运行时、mermaid_svg.rsSVG 处理、mermaid_viewport.rs视口渲染、mermaid_widget.rswidget 渲染、mermaid_debug.rs调试统计已呈现出目标模块边界的雏形ADR 的方向是把职责进一步收紧尤其是把活跃状态移出 crate 全局、把 PNG 渲染与协议呈现彻底分开。四、迁移计划渐进式、可回退新增显式模型类型与缓存键归一化测试新增新调度器 API同时保留旧包装器把render_mermaid_sized_internal改造为纯函数式renderer::render_to_png(request) - RenderArtifact把活跃图表写入从渲染函数移到 markdown prepare/app 注册表更新用显式RenderProfile贯通替换所有with_preferred_aspect_ratio调用点把 presenter/图像状态代码与 PNG 渲染代码拆分删除旧布尔包装 API 与线程局部渲染画像。这种先加新 API、旧接口变薄包装、逐个迁移调用点的策略核心收益是每步都可独立验证、可回退避免一次性大重构引入新竞态。五、验证标准缓存键归一化与文件名解析的单元测试注册表更新顺序、流式预览替换、原子清空/更新的单元测试调度器测试去重、缓存命中、缓存未命中 pending、worker 完成、不修改活跃状态Markdown 渲染器测试Mermaid 块产生确定性占位且无全局副作用现有滚动/pinned pane 测试继续通过调试探针能以显式 profile 渲染图表并报告所用确切缓存键。这些标准在仓库中已有大量落地实例缓存键/文件名解析MermaidCache::cache_path生成{hash:016x}_w{width}[_a{aspect}].png格式文件名parse_cache_filename负责回解析含_a宽高比后缀见 crates/jcode-tui-mermaid/src/mermaid_cache_render.rs模型层测试aspect_ratio_normalization_matches_legacy_bucket_policy与cache_key_is_explicit_and_stable直接对应缓存键归一化测试crates/jcode-tui-mermaid/src/mermaid_model.rs跨宽度一致性tests/layout_cache_cross_width_parity.rs 在布局缓存命中后比较跨宽度渲染的像素级一致性且支持JCODE_MMDR_SIZE_API_DISABLE1环境变量下跑旧路径对照tests/layout_cache_pixel_parity.rs 验证缓存命中渲染跨图种类/宽度的像素一致性内存有界性tests/layout_cache_memory_probe.rs 验证 50 次不同渲染下布局缓存保持有界tests/layout_cache_resize_probe.rs 探测 resize 后布局缓存加速效果调试统计debug_stats()上报render_size_backend、cache_entries、deferred_pending、layout_cache_entries/limit/approx_bytes、deferred_epoch、protocoldebug_memory_profile()汇总各缓存上限与字节预算并计算mermaid_working_set_estimate_bytescrates/jcode-tui-mermaid/src/mermaid_debug.rs。六、近期安全重构最小 ROI 切入点在完整迁移之前最高性价比的改动是引入显式请求/状态类型并让旧公共函数变成薄兼容包装器。这样调用点可以一个一个迁移同时避免新增布尔/线程局部行为带来的新缺陷——即先立骨架、再换内脏。从缓存实现看这一判断很合理MermaidCache以(u64, RenderProfile)为键、RENDER_CACHE_MAX 512上限crates/jcode-tui-mermaid/src/mermaid_cache_render.rs并已支持精确 profile 命中与任意 profile 命中两种内存查找CACHE_WIDTH_MATCH_PERCENT 85允许复用不小于请求宽度 85% 的缓存 PNG 以避免放大模糊RENDER_WIDTH_BUCKET_CELLS 4把渲染宽度量化为 4 格桶使 1 格滚动条之类的微小宽度变化复用同一缓存条目。布局层LAYOUT_CACHE_MAX 32以完整Layout节点/边几何 标签文本块约 4 KB 到 75 KB为缓存单元且布局与终端宽度无关——这意味着跨宽度桶的 resize 只需重新光栅化而无需重跑 parselayout。这些机制都与缓存键只含源码哈希 归一化画像、产物记录测量尺寸的目标设计兼容为薄包装改造提供了低风险基础。七、总结Mermaid 渲染重构的本质是把谁渲染、何时渲染、渲染多大、放哪里四件事从隐式全局副作用中剥离变成显式请求、显式调度、显式放置的分阶段管道。尺寸测量取代复杂度估算、缓存键归一化取代线程局部上下文、注册表收归 app 状态、调度器独占异步行为——每一步都有对应的模型类型、缓存机制与测试用例作为落地锚点。对于希望理解或参与 jcode 终端渲染架构的开发者建议从 crates/jcode-tui-mermaid/src/mermaid_model.rs 的显式类型入手配合 crates/jcode-tui-mermaid/src/mermaid_debug.rs 的统计探针观察当前行为再对照 tests/layout_cache_cross_width_parity.rs 等回归测试理解尺寸一致性约束。【免费下载链接】jcodeThe most RAM efficient harness项目地址: https://gitcode.com/GitHub_Trending/jcod/jcode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 jcode Mermaid 渲染管线重构：从全局状态耦合到显式分阶段管道
jcode Mermaid 渲染管线重构从全局状态耦合到显式分阶段管道【免费下载链接】jcodeThe most RAM efficient harness项目地址: https://gitcode.com/GitHub_Trending/jcod/jcode本篇技术指南基于 jcode 仓库中的架构决策记录ADRdocs/MERMAID_RENDERING_REDESIGN.md系统讲解终端内 Mermaid 图表渲染的现状痛点、尺寸 API 演进方向与目标管线设计。读者将掌握 jcode 中 Mermaid 渲染从全局状态 线程局部上下文向显式请求对象 分阶段纯数据管道迁移的完整思路包括渲染尺寸的测量式后端、缓存键归一化规则、调度器与注册表职责切分以及迁移计划与验证标准并可通过源码与测试用例逐一验证每项设计。一、问题背景Mermaid 路径为何难以推理jcode 的终端 TUI 需要把 Mermaid 图表渲染为 PNG再通过ratatui-image以 Kitty、Sixel、iTerm2、halfblock 等协议展示在终端中。然而在 crates/jcode-tui-mermaid/src/lib.rs 的 crate 拆分之后lib.rs仍然充当状态中枢渲染、缓存、UI 放置、活跃图表注册、延迟渲染、调试统计与终端图像协议状态全部通过全局状态和副作用耦合在一起。ADR 记录了以下可观察的痛点Markdown 渲染直接决定 Mermaid 行为流式/延迟/侧栏-only 的注册规则由 Markdown 渲染器直接内嵌而非由专门的调度层决定活跃图表是渲染的副作用register_active_diagram在渲染调用内部被触发仅仅是准备 Markdown就会改变 pinned pane 状态。对应实现见 crates/jcode-tui-mermaid/src/mermaid_active.rs 中由LazyLockMutexVecActiveDiagram承载的全局ACTIVE_DIAGRAMS线程局部渲染画像with_preferred_aspect_ratio依赖thread_local!的RENDER_PROFILE_CONTEXT见 crates/jcode-tui-mermaid/src/lib.rs导致缓存键与渲染尺寸受环境上下文影响同一份源码在不同上下文下产生不同结果同一图表多上下文复用聊天内联占位、侧栏图片、pinned pane、流式预览、调试探针五种场景共享底层函数却需要不同行为延迟渲染自成一派自带去重/epoch/全局队列还执行活跃注册加剧竞态风险协议渲染与 PNG 生成混在同一公共面图像协议渲染、PNG 生成、图像状态缓存、视口渲染全部暴露在同一个公共接口上。二、尺寸 API 方向测量代替估算渲染器现已提供由mmdr-size-apifeature 守卫的尺寸 API 路径同时要求环境变量JCODE_MMDR_SIZE_API_AVAILABLE1该路径应成为重构的主路径渲染器应直接向 Mermaid/layout 询问测量得到的 SVG/canvas 尺寸而不是依赖源码文本复杂度估算来决定最终 PNG 尺寸calculate_render_size应降级为请求目标提示request target hint不再是输出尺寸的唯一事实来源旧的 SVG 重定向retarget回退路径仅作为兼容代码保留直到打补丁的渲染器始终可用调试统计应上报render_size_backend并且在测试期望使用尺寸 API 路径而实际不可用时大声失败缓存键应包含归一化后的目标/画像输入而产物应保存尺寸 API 返回的测量输出尺寸。这一方向旨在消除四类典型缺陷宽高比重定向错误、放大模糊、占位高度不匹配、pane 尺寸变化导致的振荡。源码证据feature 与环境变量的真实开关在 crates/jcode-tui-mermaid/Cargo.toml 中可以看到[features] default [mmdr-size-api] renderer [dep:mermaid-rs-renderer] # Enables the renderer size API path. The pinned mmdr tag (v0.3.1) ships the # size API, and build.rs enables it by default; set JCODE_MMDR_SIZE_API_DISABLE1 # to fall back to the legacy SVG-retarget path. mmdr-size-api [renderer]对应的渲染后端选择在 crates/jcode-tui-mermaid/src/lib.rs 中通过render_size_backend()判定当feature mmdr-size-api且mmdr_size_api_available为真时返回mmdr-size-api否则返回svg-retarget-fallback。新路径使用mermaid_rs_renderer::render的measure_svg_dimensions与render_svg_with_dimensions依赖固定 tagv0.3.1的 git 仓库旧路径则通过解析 SVG 根标签的viewBox/width/height并调用retarget_svg_for_png完成重定向实现位于 crates/jcode-tui-mermaid/src/mermaid_svg.rs。新路径的语义值得注意先测量自然内容自适应画布再在保持宽高比的前提下把它装入请求的目标盒子——直接强制目标尺寸会把宽图 letterbox 进约 4:3 的请求盒产生大片透明留白因此该行为刻意镜像了旧retarget_svg_for_png的 fit 语义。当前估算式实现calculate_render_size(node_count, edge_count, terminal_width)crates/jcode-tui-mermaid/src/mermaid_svg.rs展示了文本复杂度估算的局限它以estimate_diagram_size统计节点/边数为复杂度因子0.6~1.1乘以终端像素宽度并夹取到[400, 2400]高度取width * 0.75夹取到[300, 1800]。这正是 ADR 建议降级为请求目标提示的算法。三、目标设计显式分阶段管线重构目标是建立阶段间传递纯数据的显式管线3.1 图表提取Diagram extractionMarkdown 渲染器只负责把围栏 Mermaid 块提取为不可变描述符不再直接改写活跃图表或同步渲染除非调用方显式要求阻塞回退struct DiagramBlock { id: DiagramId, source_hash: u64, source: Arcstr, origin: DiagramOrigin, ordinal: usize, }仓库中的 crates/jcode-tui-mermaid/src/mermaid_model.rs 已落地这一模型DiagramId由source_hash内容等价标识originChat / SidePanel / StreamingPreview / DebugProbeordinal区分同一内容的不同出现位置构成DiagramBlock则持有id与Arcstr源码。3.2 显式渲染请求Explicit render request用一个请求对象取代环境化的with_preferred_aspect_ratio与布尔参数struct RenderRequest { diagram_id: DiagramId, source_hash: u64, source: Arcstr, target: RenderTarget, profile: RenderProfile, priority: RenderPriority, mode: RenderMode, } struct RenderProfile { width_cells: Optionu16, preferred_aspect_per_mille: Optionu16, theme: MermaidTheme, } enum RenderMode { CacheOnly, EnqueueIfMissing, Blocking, }缓存键只由source_hash 归一化 RenderProfile构建绝不依赖线程局部上下文。源码中的DiagramRenderProfile已与此对应crates/jcode-tui-mermaid/src/mermaid_model.rs其cache_key(source_hash)生成DiagramCacheKey包含source_hash、width_cells、preferred_aspect_per_mille、theme四个字段Display输出形如0000000000000abc:w96:a500:TerminalDark。而normalize_aspect_ratio把Optionf32宽高比归一化为每千分位整数过滤掉非有限值与非正数ratio * 1000四舍五入后夹取到[100, 10_000]。该函数与旧RenderProfile::from_preferred_aspect_ratio的桶策略保持一致0.75 → 7501.2345 → 1235NaN/-1 → None并配有单元测试验证。RenderTargetInlineMarkdown / SidePanel / PinnedPane / DebugProbe、RenderPriorityInteractive / Visible / Background、RenderModeCacheOnly / EnqueueIfMissing / Blocking在mermaid_model.rs中均有定义DiagramRenderRequest提供cache_key()方法直接从请求推导缓存键测试render_request_derives_cache_key_from_source_hash_and_profile_only验证键只依赖source_hash profile而非 origin/ordinal/target。3.3 注册表持有活跃状态Registry owns active state引入由 TUI app/session 状态拥有的DiagramRegistry而不是 Mermaid crate 内部的全局向量。其职责追踪当前已准备 transcript/侧栏中可见的图表用 generation id 单独追踪流式预览发布有序列表供 pinned pane 选择每次 prepare pass 原子地清空/更新。渲染应返回RenderArtifact绝不把活跃注册作为副作用。当前 crates/jcode-tui-mermaid/src/mermaid_active.rs 正是 ADR 要改造的对象ACTIVE_DIAGRAMS与STREAMING_PREVIEW_DIAGRAM都是 crate 级全局静态register_active_diagram在渲染路径中被调用并受ACTIVE_DIAGRAMS_MAX 128上限约束见 crates/jcode-tui-mermaid/src/lib.rs。3.4 调度器拥有异步/延迟行为Scheduler owns async/deferred调度器接收显式请求并返回下列状态之一enum RenderStatus { Ready(RenderArtifact), Pending { request_id: RenderRequestId }, Failed(RenderError), ProtocolUnavailable, }规则去重以完整缓存键为依据worker 不得修改活跃注册表worker 完成时只发布MermaidRenderCompleted事件与产物元数据epoch 失效按请求世代generation作用域化除非确有必要不使用全局单一计数器。mermaid_model.rs中的RenderStatus与之对应Ready(RenderArtifact)、Pending { cache_key }、Failed(RenderError)、ProtocolUnavailableRenderArtifact携带cache_key、path、测量得到的width/heightRenderError记录可选cache_key与错误消息。当前实现中全局DEFERRED_RENDER_EPOCH与PENDING_RENDER_REQUESTS正是全局计数器 全局队列的现状见 crates/jcode-tui-mermaid/src/lib.rsADR 建议未来将其作用域化。3.5 放置规划与渲染解耦Placement planner is separateMarkdown/侧栏准备阶段根据RenderStatus与期望放置方式插入占位聊天/侧栏的内联图片占位行侧栏-only 模式的侧边标记渲染失败的错误块延迟/流式渲染的 pending 占位。图像 widget 渲染只消费RenderArtifact PlacementPlan不了解 Mermaid 源码或调度逻辑。现有mermaid_content.rs已提供diagram_placeholder_lines、inline_image_placeholder_lines、error_to_lines、parse_image_placeholder等占位与解析辅助函数可视为放置层的雏形。3.6 公共模块边界推荐的 crate 模块划分模块职责model.rsDiagramId、DiagramBlock、RenderProfile、RenderTarget、RenderArtifact、RenderStatus、错误类型extract.rsMarkdown Mermaid 块提取辅助cache.rs磁盘与内存产物元数据缓存renderer.rs仅负责 Mermaid parse/layout/SVG/PNG 转换scheduler.rs请求队列、worker、去重、完成事件registry.rs活跃/流式图表状态理想情况下归 app 所有placement.rs占位/图像区域规划presenter.rsratatui-image/Kitty/Sixel/iTerm 视口渲染debug.rs从显式事件收集的统计对照当前 crates/jcode-tui-mermaid/src/ 目录mermaid_model.rs模型、mermaid_active.rs活跃状态、mermaid_cache_render.rs缓存渲染、mermaid_content.rs内容/占位、mermaid_inline.rs内联图像、mermaid_runtime.rs协议运行时、mermaid_svg.rsSVG 处理、mermaid_viewport.rs视口渲染、mermaid_widget.rswidget 渲染、mermaid_debug.rs调试统计已呈现出目标模块边界的雏形ADR 的方向是把职责进一步收紧尤其是把活跃状态移出 crate 全局、把 PNG 渲染与协议呈现彻底分开。四、迁移计划渐进式、可回退新增显式模型类型与缓存键归一化测试新增新调度器 API同时保留旧包装器把render_mermaid_sized_internal改造为纯函数式renderer::render_to_png(request) - RenderArtifact把活跃图表写入从渲染函数移到 markdown prepare/app 注册表更新用显式RenderProfile贯通替换所有with_preferred_aspect_ratio调用点把 presenter/图像状态代码与 PNG 渲染代码拆分删除旧布尔包装 API 与线程局部渲染画像。这种先加新 API、旧接口变薄包装、逐个迁移调用点的策略核心收益是每步都可独立验证、可回退避免一次性大重构引入新竞态。五、验证标准缓存键归一化与文件名解析的单元测试注册表更新顺序、流式预览替换、原子清空/更新的单元测试调度器测试去重、缓存命中、缓存未命中 pending、worker 完成、不修改活跃状态Markdown 渲染器测试Mermaid 块产生确定性占位且无全局副作用现有滚动/pinned pane 测试继续通过调试探针能以显式 profile 渲染图表并报告所用确切缓存键。这些标准在仓库中已有大量落地实例缓存键/文件名解析MermaidCache::cache_path生成{hash:016x}_w{width}[_a{aspect}].png格式文件名parse_cache_filename负责回解析含_a宽高比后缀见 crates/jcode-tui-mermaid/src/mermaid_cache_render.rs模型层测试aspect_ratio_normalization_matches_legacy_bucket_policy与cache_key_is_explicit_and_stable直接对应缓存键归一化测试crates/jcode-tui-mermaid/src/mermaid_model.rs跨宽度一致性tests/layout_cache_cross_width_parity.rs 在布局缓存命中后比较跨宽度渲染的像素级一致性且支持JCODE_MMDR_SIZE_API_DISABLE1环境变量下跑旧路径对照tests/layout_cache_pixel_parity.rs 验证缓存命中渲染跨图种类/宽度的像素一致性内存有界性tests/layout_cache_memory_probe.rs 验证 50 次不同渲染下布局缓存保持有界tests/layout_cache_resize_probe.rs 探测 resize 后布局缓存加速效果调试统计debug_stats()上报render_size_backend、cache_entries、deferred_pending、layout_cache_entries/limit/approx_bytes、deferred_epoch、protocoldebug_memory_profile()汇总各缓存上限与字节预算并计算mermaid_working_set_estimate_bytescrates/jcode-tui-mermaid/src/mermaid_debug.rs。六、近期安全重构最小 ROI 切入点在完整迁移之前最高性价比的改动是引入显式请求/状态类型并让旧公共函数变成薄兼容包装器。这样调用点可以一个一个迁移同时避免新增布尔/线程局部行为带来的新缺陷——即先立骨架、再换内脏。从缓存实现看这一判断很合理MermaidCache以(u64, RenderProfile)为键、RENDER_CACHE_MAX 512上限crates/jcode-tui-mermaid/src/mermaid_cache_render.rs并已支持精确 profile 命中与任意 profile 命中两种内存查找CACHE_WIDTH_MATCH_PERCENT 85允许复用不小于请求宽度 85% 的缓存 PNG 以避免放大模糊RENDER_WIDTH_BUCKET_CELLS 4把渲染宽度量化为 4 格桶使 1 格滚动条之类的微小宽度变化复用同一缓存条目。布局层LAYOUT_CACHE_MAX 32以完整Layout节点/边几何 标签文本块约 4 KB 到 75 KB为缓存单元且布局与终端宽度无关——这意味着跨宽度桶的 resize 只需重新光栅化而无需重跑 parselayout。这些机制都与缓存键只含源码哈希 归一化画像、产物记录测量尺寸的目标设计兼容为薄包装改造提供了低风险基础。七、总结Mermaid 渲染重构的本质是把谁渲染、何时渲染、渲染多大、放哪里四件事从隐式全局副作用中剥离变成显式请求、显式调度、显式放置的分阶段管道。尺寸测量取代复杂度估算、缓存键归一化取代线程局部上下文、注册表收归 app 状态、调度器独占异步行为——每一步都有对应的模型类型、缓存机制与测试用例作为落地锚点。对于希望理解或参与 jcode 终端渲染架构的开发者建议从 crates/jcode-tui-mermaid/src/mermaid_model.rs 的显式类型入手配合 crates/jcode-tui-mermaid/src/mermaid_debug.rs 的统计探针观察当前行为再对照 tests/layout_cache_cross_width_parity.rs 等回归测试理解尺寸一致性约束。【免费下载链接】jcodeThe most RAM efficient harness项目地址: https://gitcode.com/GitHub_Trending/jcod/jcode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考