告别 Markdown 渲染噩梦：一个 Skill 解决前端展示的所有编码与渲染难题

作者: Yardon | GitHub: markdown-renderer-fix | 标签: Markdown, SSE, UTF-8, 前端工程化, RAG

引言：为什么你的 AI 应用总是"看起来不对"

如果你正在构建一个基于大语言模型的应用——无论是 RAG 知识库、AI 助手还是智能文档分析系统——你一定遇到过这些令人抓狂的问题：

• 中文回复变成 ��� 或 锟斤拷
• SSE 流式输出突然中断，第二次提问直接卡住
• Markdown 表格、代码块、数学公式渲染得一塌糊涂
• <function=save_qa_to_knowledge_base> 这样的内部调用泄露到用户界面
• 长文本超过 5000 字后页面卡死

这些问题表面上是"前端小 bug"，实际上涉及前后端 8 个编码转换环节的协同：后端 tiktoken 解码 → Python str → json.dumps 转义 → .encode('utf-8') → HTTP 传输 → 前端 reader.read() → TextDecoder → marked.parse()。任一环节出错，用户看到的就是乱码或格式崩坏。

更致命的是，这些问题往往无法通过单点修复根治。改了一处编码，另一处又出问题；修了 SSE 流式，Markdown 渲染又坏了。开发者陷入"打地鼠"式的无效调试。

这就是 markdown-renderer-fix 诞生的原因——基于多次生产环境实战修复经验，将分散的解决方案系统化、工程化，封装成一个可直接落地的 Skill。

核心架构：8 方向系统排查法

与传统"遇到问题再搜索"的被动修复不同，markdown-renderer-fix 采用决策树驱动的主动排查架构：

看到乱码？
├─ 是 ��� 型？（1 汉字 → 3 个 �）
│ └─ → 方向 A：SSE 流式解码 + tiktoken 单 token 解码
├─ 是 锟斤拷 型？
│ └─ → 方向 B：GBK/UTF-8 混用
└─ 不是乱码，但格式有问题？
├─ Markdown 未渲染 → 方向 C
├─ 代码块无高亮 → 方向 D
├─ 公式/图表不显示 → 方向 E
├─ SSE 流不工作 → 方向 F
├─ 连续对话无响应 → 方向 G
└─ 性能卡顿 → 方向 H

每个方向对应独立的 reference 文档，包含根因分析 → 修复代码 → 验证方法的完整闭环。

技术深度解析：三个典型难题的根治方案

难题一：tiktoken 单 token 解码导致的 ��� 乱码

根因定位：

# ❌ 错误：逐个 token 解码
for tid in tokens:
chunk = enc.decode([tid]) # 中文字符可能被拆成多个 token
# tid=3574 → '�', tid=244 → '�' —— 这就是乱码来源

中文字符在 tiktoken 中通常被编码为 2-3 个 token，单独解码每个 token 会产生不完整的 UTF-8 字节序列，Python 自动替换为 U+FFFD（�）。

根治方案：

# ✅ 正确：一次性全量解码
full_text = enc.decode(tokens) # 所有 token 一起解码，字符边界完整

诊断脚本验证：

python scripts/diagnose_encoding.py –test-text "你好世界"
# 输出：逐 token 解码包含 U+FFFD → 改用 enc.decode(all_tokens)

难题二：SSE 流式输出的"第二次卡住"

根因定位：

前端使用 id="streamingMsg" 标记正在流式输出的消息 DOM，但流完成后未移除该 ID。第二次提问时，新消息仍然查找 #streamingMsg，导致状态混乱、AbortController 未重置。

根治方案：

// 流式完成后的清理逻辑
function onStreamDone() {
const el = document.getElementById('streamingMsg');
if (el) {
el.removeAttribute('id'); // ✅ 关键：必须移除 ID
el.classList.add('msg', 'assistant'); // 转为普通消息
}
abortCtl = new AbortController(); // 重置中断控制器
}

配套机制：

• PING 保活：后端每 15 秒发送 data: [PING]\\n\\n，防止 Nginx/Cloudflare 超时断开
• 超时管理：30 秒无数据自动重连，避免无限等待
• JSON 分块：每个 SSE 事件独立解析，单块损坏不影响整体

难题三：工具调用输出泄露到用户界面

根因定位：

大模型在 function calling 模式下，会将工具调用以 XML 或 JSON 格式输出到文本流中：

<function=save_qa_to_knowledge_base>
<parameter={"question": "…", "answer": "…"}>
</function>
Answer record saved. Record ID: 12345

如果前端不过滤，用户会直接看到这段"内部实现细节"。

根治方案：

function cleanToolOutput(text) {
return text
.replace(/<function=[^>]+>[\\s\\S]*?<\\/function>/gi, '')
.replace(/save_qa_to_knowledge_base/gi, '')
.replace(/Answer record saved\\.?\\s*Record ID:?

\\d+/gi, '')
.replace(/"tool_calls"\\s*:\\s*\\[[\\s\\S]*?\\]/g, '')
.trim();
}

验证方法：

// 浏览器控制台检查
const bubbles = document.querySelectorAll('.msg.assistant .bubble');
bubbles.forEach(b => {
console.assert(!b.textContent.includes('save_qa_to_knowledge_base'), '工具名称泄露');
console.assert(!b.innerHTML.includes('<function='), 'XML 标签泄露');
});

生产级交付：不仅是文档，更是可直接运行的代码

1. 编码诊断脚本：diagnose_encoding.py

一个脚本覆盖环境检测 → JSON 往返 → tiktoken 解码 → SSE 链路 → 实际端点测试的全链路诊断：

# 全面诊断（本地环境 + 框架 + 依赖 + 实际 SSE）
python scripts/diagnose_encoding.py –full

# 测试实际 SSE 端点
python scripts/diagnose_encoding.py –real-sse –endpoint http://127.0.0.1:18765/api/chat/stream

# 指定测试文本
python scripts/diagnose_encoding.py –test-text "你好世界" –full

输出示例：

============================================================
编码环境诊断
============================================================
sys.stdout.encoding: utf-8
locale.getpreferredencoding(): cp936
PYTHONIOENCODING: utf-8

—————————————-
测试文本: 你好世界！Hello World! 🚀
json.dumps: "\\u4f60\\u597d\\u4e16\\u754c\\uff01Hello World! \\ud83d\\ude80"
✅ 往返一致

—————————————-
Token 数量: 12
一次性解码: '你好世界！Hello World! 🚀'
✅ 原文对比
逐 token 解码: '你好��界！Hello World! ���'
包含 U+FFFD: ❌ 是 — 这就是乱码根因!

2. 完整聊天界面模板：chat_template.html

不是示例代码，而是生产级可直接使用的 HTML 文件，包含：

3. 框架适配：React / Vue / Angular / Svelte

不是"原理说明"，而是每个框架的具体集成代码：

// React 示例：useSSE hook
function useSSE(endpoint) {
const [text, setText] = useState('');
const abortRef = useRef(new AbortController());

const send = useCallback(async (message) => {
const res = await fetch(endpoint, {
method: 'POST',
body: JSON.stringify({ message }),
signal: abortRef.current.signal
});
const reader = res.body.getReader();
const decoder = new TextDecoder('utf-8');

while (true) {
const { done, value } = await reader.read();
if (done) break;
const chunk = decoder.decode(value, { stream: true });
// 解析 SSE data: 行…
setText(prev => prev + parsedContent);
}
}, [endpoint]);

return { text, send };
}

安全加固：XSS 防护与 CSP 策略

生产环境必须面对的安全问题：

DOMPurify 净化

const raw = marked.parse(userInput);
const clean = DOMPurify.sanitize(raw, {
ALLOWED_TAGS: ['h1','h2','h3','p','br','ul','ol','li',
'strong','em','a','code','pre','blockquote',
'table','thead','tbody','tr','th','td','img','span','div'],
ALLOWED_ATTR: ['href','src','class','id','target','alt','title'],
ALLOW_DATA_ATTR: false
});
container.innerHTML = clean;

CSP 策略（SSE 必需 connect-src）

<meta http-equiv="Content-Security-Policy"
content="default-src 'self';
script-src 'self' 'unsafe-inline' cdnjs.cloudflare.com cdn.jsdelivr.net;
style-src 'self' 'unsafe-inline' cdnjs.cloudflare.com cdn.jsdelivr.net;
img-src 'self' data:;
connect-src 'self'; <!– SSE 流式请求必需 –>
font-src 'self' cdn.jsdelivr.net;">

8 个验证测试：修复后的质量保证

不是"应该没问题了"，而是可执行的验证清单：

每个测试都提供浏览器控制台可执行的 JavaScript 代码或 curl 命令。

为什么选择 markdown-renderer-fix？

一句话总结：选择 markdown-renderer-fix，你的前端 Markdown 渲染和编码问题从"反复调试"变成"按图索骥"。

快速开始

安装

git clone https://github.com/YardonYan/markdown-renderer-fix.git
cd markdown-renderer-fix

诊断当前项目

python scripts/diagnose_encoding.py –full

使用模板

直接复制 assets/chat_template.html 到你的项目，或根据 references/framework_adaptation.md 集成到你的前端框架。

按现象查文档

结语：工程化思维解决系统性问题

Markdown 渲染和编码问题之所以难以根治，是因为它们不是单一 bug，而是系统性工程问题。tiktoken 的 tokenization 策略、SSE 的流式协议、浏览器的编码处理、Markdown 的渲染管线——这些组件各自独立设计，却在 AI 应用的前端交汇，产生复杂的交互故障。

markdown-renderer-fix 的价值不在于提供了某一段"万能代码"，而在于建立了从现象定位 → 根因分析 → 修复实施 → 验证确认的完整工程化流程。每一次修复都沉淀为可复用的文档和代码，下一次遇到类似问题时，不再是从零开始调试，而是按图索骥、快速解决。

GitHub 仓库 → YardonYan/markdown-renderer-fix

如果你也在构建 AI 应用，被前端展示问题困扰，希望这个 Skill 能让你少走一些弯路。

本文基于多次生产环境实战修复经验编写，所有代码片段均可直接运行。