>NewVFX LLM Chat · Stream Router (流式分流器) 开发者指南<

1. 核心概念：什么是 Stream Router？

Stream Router（流式分流器） 是 NewVFX LLM Chat 内核中的核心架构组件，其设计理念为 “协议即路由”。

作用与用途

在传统的 AI 聊天应用中，AI 输出的 Markdown 代码块（如

javascript` 或 

python`）通常只会被渲染为高亮代码。
但在商业级应用中，AI 经常需要输出图表、流程图、交互式沙盒等复杂结构。Stream Router 的作用是：

1. 拦截与识别：在 AI 流式输出（Streaming）或历史消息加载时，实时拦截特定的 Markdown 代码块语言标识（如

   chart`、

   mermaid`）。

2. 动态路由：根据后台配置的“路由注册表”，将代码块内容精准分发给对应的前端 JS 渲染引擎（如 Chart.js、Mermaid.js）。
3. 解耦扩展：内核代码无需硬编码任何第三方库的渲染逻辑。开发者只需编写独立的前端 JS 模块并在后台注册，即可无限扩展 AI 的输出形态。

2. 工作流程与调用方法

2.1 路由注册表

内核维护了一个全局注册表

NVFX_PIPE_REGISTRY

。管理员可以在后台 [Chat中枢] -> [🔀 流式路由] Tab 中动态添加规则。
配置格式：

语言标识 | 显示名称 | 前端API全局对象名

示例：

mermaid | 流程图 | NVFXMermaid

2.2 内核调用逻辑

当 AI 输出 ““mermaid

 时，内核的增量渲染器（

renderTailElement

）和历史消息分流器（

renderHistoryWithPipes`）会执行以下逻辑：

1. 提取代码块的语言标识（

   lang

   ）和内容（

   codeContent

   ）。

2. 查询

   NVFX_PIPE_REGISTRY[lang]

   获取配置的 API 对象名。

3. 检查

   window[apiName]

   是否存在且具备

   streamUpdate

   方法。

4. 创建一个宿主 DOM 元素（

   hostEl

   ），并调用外部 API。

3. 接口契约 (API Contract)

要开发一个兼容 Stream Router 的前端渲染模块，你必须在

window

全局对象下挂载一个对象，并实现以下核心生命周期函数：

🟢

streamUpdate(hostEl, content, lang)

• 触发时机：流式生成过程中，每当代码块内容发生增量变化时持续调用（高频）。
• 参数：

  • hostEl

    (HTMLElement): 内核为你创建的宿主容器

    <div class="nvfx-pipe-host" data-lang="...">

    。你的所有 DOM 操作必须限制在此容器内。

  • content

    (String): 当前累积的代码块纯文本内容（不含 “` 标记）。

  • lang

    (String): 语言标识（如

    mermaid

    ）。

• 最佳实践：由于是高频调用，建议在此阶段显示“生成中/Loading”的占位符（Overlay），或将内容缓存到

  hostEl

  的自定义属性中，避免在此阶段执行昂贵的渲染计算。

🔵

streamEnd(hostEl)

• 触发时机：AI 输出代码块闭合标记（“`）时调用，标志着该代码块流式传输结束。
• 参数：

  • hostEl

    (HTMLElement): 同上。

• 最佳实践：在此阶段读取缓存的完整内容，执行真正的解析和渲染（如调用

  mermaid.render()

  ），并替换掉 Loading 占位符。

🟡

streamFinalize()

(可选)

• 触发时机：整个 AI 回复流结束、被用户手动中断、或发生网络错误时调用。
• 用途：用于清理全局状态、强制结束所有未完成的渲染队列、释放内存。

4. 开发者实战范例：接入 Mermaid 流程图

假设我们要让 AI 输出的 ““mermaid` 代码块自动渲染为流程图。

第一步：后台注册路由

进入 WordPress 后台 [Chat中枢] -> [🔀 流式路由]，在注册表中添加一行：

mermaid | 流程图 | NVFXMermaid

(保存后，内核将自动识别 ““mermaid

并寻找

window.NVFXMermaid`)

第二步：编写前端 JS 模块

创建一个 JS 文件（需确保在 Chat 主 JS 之后加载），实现

NVFXMermaid

对象：

(function() {
    "use strict";

    // 确保 Mermaid 库已加载 (可通过模块系统或 CDN 引入)
    // <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>

    window.NVFXMermaid = {
        // 缓存正在生成的任务
        _pending: new Map(),

        /**
         * 1. 流式更新阶段 (高频调用)
         */
        streamUpdate: function(hostEl, content, lang) {
            // 如果该容器还未初始化，创建 Loading 遮罩
            if (!this._pending.has(hostEl)) {
                this._pending.set(hostEl, content);
                
                hostEl.style.cssText = 'width:100%;min-height:150px;display:flex;align-items:center;justify-content:center;background:#f8fafc;border:1px dashed #cbd5e1;border-radius:8px;';
                hostEl.innerHTML = `
                    <div style="text-align:center;color:#64748b;font-size:13px;">
                        <div style="font-size:24px;margin-bottom:8px;">⏳</div>
                        <div>流程图生成中...</div>
                    </div>
                `;
            } else {
                // 更新缓存的内容
                this._pending.set(hostEl, content);
            }
        },

        /**
         * 2. 流式结束阶段 (渲染真实图表)
         */
        streamEnd: function(hostEl) {
            const content = this._pending.get(hostEl) || '';
            this._pending.delete(hostEl);

            if (!content.trim()) {
                hostEl.innerHTML = '<div style="color:#ef4444;">流程图数据为空</div>';
                return;
            }

            // 恢复容器样式
            hostEl.style.cssText = 'width:100%;display:flex;justify-content:center;padding:16px 0;';
            
            // 生成唯一 ID 防止冲突
            const id = 'mermaid-' + Math.random().toString(36).substr(2, 9);
            
            try {
                // 调用 Mermaid 渲染
                mermaid.render(id, content, function(svgCode) {
                    hostEl.innerHTML = svgCode;
                });
            } catch (e) {
                hostEl.innerHTML = `<div style="color:#ef4444;font-size:12px;">Mermaid 语法错误: ${e.message}</div>`;
            }
        },

        /**
         * 3. 全局清理 (中断时调用)
         */
        streamFinalize: function() {
            // 清理所有未完成的缓存
            this._pending.clear();
        }
    };

    // 初始化 Mermaid 配置 (适配深色模式)
    if (window.mermaid) {
        mermaid.initialize({ 
            startOnLoad: false, 
            theme: document.documentElement.getAttribute('data-theme') === 'dark' ? 'dark' : 'default' 
        });
    }
})();

第三步：测试效果

在前端对话框中输入以下 Prompt 测试：

“请用 mermaid 语法画一个用户登录的流程图。”

内核行为：

1. AI 开始输出 ““mermaid\ngraph TD…`。
2. 内核拦截到

   mermaid

   ，调用

   NVFXMermaid.streamUpdate()

   ，页面显示“流程图生成中…”。

3. AI 输出完毕，闭合 “`。
4. 内核调用

   NVFXMermaid.streamEnd()

   ，Loading 消失，完美的 SVG 流程图渲染在聊天气泡中。

5. 开发注意事项 (避坑指南)

1. DOM 作用域限制：
   绝对不要使用

   document.body.appendChild

   或全局 ID 选择器来渲染你的组件。内核可能会在同一个页面渲染多个相同的代码块，必须将所有的 DOM 操作限制在传入的

   hostEl

   内部。

2. 防抖与节流：

   streamUpdate

   的调用频率极高（可能每 50ms 一次）。严禁在

   streamUpdate

   中执行如

   JSON.parse

   、DOM 重绘、图表实例化等重计算操作。请将重计算全部推迟到

   streamEnd

   中执行。

3. 容错处理：
   AI 的输出是不稳定的，可能会输出残缺的 JSON 或错误的语法。你的

   streamEnd

   函数必须包含

   try...catch

   块，并在解析失败时向

   hostEl

   输出友好的错误提示（如“数据解析失败”），而不是让整个前端 JS 崩溃。

4. 样式隔离：
   建议使用 Shadow DOM 或严格的 CSS 命名空间（如

   .nvfx-mermaid-host svg {...}

   ），防止第三方库（如 Chart.js/Mermaid）的全局样式污染 Chat 内核的 UI。