Markdown 渲染与中文乱码修复

Markdown Rendering & Chinese Encoding Fix

🇨🇳 中文 | 🇬🇧 English — 本 Skill 全文档提供中英双语。 This skill provides bilingual documentation throughout.

作者：Yardon | 基于多次实战修复经验

决策树

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

框架项目？
├─ React    → references/framework_adaptation.md
├─ Vue      → references/framework_adaptation.md
├─ Angular  → references/framework_adaptation.md
└─ Svelte   → references/framework_adaptation.md

8 方向快速修复

💡 更多参考：

• 浏览器兼容性矩阵 → browser_support.md
• 无障碍访问（ARIA、键盘快捷键、色对比度）→ accessibility.md
• 修复后验证（11 个测试案例）→ test_cases.md

Fix Pattern Catalog / 修复模式目录

Each pattern follows: Symptom → Root Cause → Fix (1-liner) → Reference 每种模式遵循：症状 → 根因 → 一行修复 → 参考文档

Pattern A: tiktoken U+FFFD Fix / tiktoken U+FFFD 修复

Pattern B: SSE Non-Streaming Fix / SSE 非流式修复

Pattern C: Markdown Not Rendering Fix / Markdown 未渲染修复

Pattern D: Code Block No Highlighting Fix / 代码块无高亮修复

Pattern E: Consecutive Chat No Response Fix / 连续对话无响应修复

Pattern F: Tool Call Output Leak Fix / 工具调用输出泄露修复

Pattern G: Formula/Diagram Not Displaying Fix / 公式/图表不显示修复

Pattern H: Performance Stuttering Fix / 性能卡顿修复

常见错误速查

Quality Checklist / 质量检查清单

Use this checklist to audit any chat UI template or Markdown renderer implementation. 使用此检查清单审计任何聊天 UI 模板或 Markdown 渲染实现。

P0 — Must Pass / 必须通过

• Charset declarations: <meta charset="UTF-8"> in HTML head, Content-Type: text/event-stream; charset=utf-8 in SSE response headers
• TextDecoder utf-8: new TextDecoder('utf-8') explicitly declared (not default-reliant)
• DOMPurify enabled: All innerHTML assignments pass through DOMPurify.sanitize()
• Tool output filtered: cleanToolOutput() applied to all streaming content before rendering
• StreamingMsg ID cleaned: #streamingMsg element has its id attribute removed after each stream completion
• No raw innerHTML: No direct element.innerHTML = userContent calls without sanitization

P1 — Should Pass / 应该通过

• CDN fallback configured: Multiple CDN mirrors configured for Highlight.js, KaTeX, Mermaid, Marked (BootCDN / Staticfile / cdnjs fallback chain)
• Mobile responsive: All layouts adapt to viewport; table wrappers use overflow-x: auto; font sizes scale
• Keyboard shortcuts: Enter to send, Shift+Enter for newline, Ctrl+Enter for send, Escape to cancel/focus
• ARIA live regions: Chat message container has role="log" and aria-live="polite" for screen reader streaming
• Lazy loading: Images use loading="lazy" and decoding="async" attributes

P2 — Nice to Have / 锦上添花

• Dark mode: System-preference dark mode via prefers-color-scheme media query with manual toggle
• Virtual scrolling: For chat histories >50 messages, use virtual list rendering to maintain performance
• CSP headers: Content-Security-Policy headers configured to restrict inline scripts and external resources

Anti-Patterns / 反模式

Common mistakes and their correct alternatives. Each "Don't" is a real-world bug we've encountered. 常见错误及其正确替代方案。每个"不要"都是我们遇到过的真实 Bug。

Design System / 设计系统

v3.0.0 introduces a 6-token design system for consistent visual identity across all templates. v3.0.0 引入 6 令牌设计系统，为所有模板提供一致的视觉识别。

Color Tokens / 色彩标记

:root {
  --bg:      #f8f9fb;  /* page background */
  --surface: #ffffff;  /* card/module surface */
  --fg:      #1a1a2e;  /* primary text */
  --muted:   #6b7280;  /* secondary text / captions */
  --border:  #e5e7eb;  /* subtle borders / dividers */
  --accent:  #4a90d9;  /* blue accent for tech/encoding context */
}

Typography Scale / 字体层级

Spacing Scale / 间距层级

:root {
  --gap-xs:  6px;     /* 6px  — inline gaps */
  --gap-sm:  12px;    /* 12px — compact padding */
  --gap-md:  20px;    /* 20px — standard padding */
  --gap-lg:  32px;    /* 32px — section spacing */
  --gap-xl:  56px;    /* 56px — major section separation */
}

Version History / 版本历史

快速诊断

⚠️ 演示与生产分离：

• assets/index.html 为纯前端示范页面，无需后端即可浏览
• assets/chat_template.html 为生产级聊天模板（SSE 流式消费 + 会话管理），需要后端 SSE 端点 如需持久化对话历史：
• localStorage：存储 {sessionId, messages[]}，刷新后恢复
• 服务端会话管理：用户登录后绑定 session_id，刷新后查询历史
• URL 参数：?session=xxx 可跨标签页共享

# 测试 SSE 原始输出中是否有 � (U+FFFD) — Linux/macOS
curl -s -N -X POST http://127.0.0.1:18765/api/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"message":"hi","session_id":"debug"}' --max-time 30 2>&1 \
  | grep -a -o $'\xef\xbf\xbd' | wc -l

# Windows PowerShell 等价
(Invoke-WebRequest -Uri http://127.0.0.1:18765/api/chat/stream -Method POST `
  -Body '{"message":"hi","session_id":"debug"}' -ContentType "application/json").Content `
  | Select-String -Pattern "\ufffd" | Measure-Object | Select-Object -ExpandProperty Count

# 运行编码诊断脚本（跨平台）
python scripts/diagnose_encoding.py --test-text "你好世界"

参考文档索引

📚 阅读顺序建议

新人入门：
  SKILL.md（你在这里）→ index.html（看示范效果）→ troubleshooting.md（学排查）

乱码排查：
  SKILL.md 决策树 → encoding_fix.md（tiktoken/GBK 双根因）→ backend_sse.md（端点实现）

功能实现：
  chat_template.html（生产级参考）→ markdown_render.md（API 说明）→ performance.md（优化）
  → frontend_sse.md（SSE 消费）→ security.md（上线前安全审计）

演示浏览：
  index.html（无需后端，直接打开浏览器查看 Markdown 渲染效果）

框架集成：
  framework_adaptation.md（React/Vue/Angular/Svelte 四选一）

质量保证：
  test_cases.md（11 个验证）→ accessibility.md（A11y）→ browser_support.md（兼容性矩阵）

⚠️ 内容冲突时以 chat_template.html（生产代码） 和 backend_sse.md（后端示例） 为准。 其余文档为说明和补充用途。

完整模板

• assets/chat_template.html — 生产级聊天界面模板（含 SSE 流式消费）
• assets/index.html — Markdown 渲染效果示范页面（卡片式画廊，点击展开）

安装与使用

安装

# 复制到 OpenClaw skills 目录（当前版本 v3.0.0）
cp -r markdown-renderer-fix ~/.qclaw/skills/

📦 Current version: v3.0.0 — See Version History / 版本历史 for details.

自动触发

当遇到 Markdown 渲染或中文乱码问题时，OpenClaw 根据 SKILL.md 的 description 自动加载本 Skill。

手动诊断

# 全面诊断（环境 + tiktoken + 框架 + 依赖 + 实际 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

快速修复检查清单

• 前端 TextDecoder('utf-8') 已配置 → 见 encoding_fix.md
• 后端 SSE charset=utf-8 已设置 → 见 backend_sse.md
• HTML <meta charset="UTF-8"> 已声明 → 见 encoding_fix.md
• 后端 Agent 输出无 �（print(repr(chunk)) 检查） → 见 encoding_fix.md
• marked.parse() 输入文本无乱码 → 见 markdown_render.md
• #streamingMsg ID 每次完成后清理 → 见 frontend_sse.md
• 工具调用输出被过滤 → 见 markdown_render.md