kongdeqiang
2026-10-12 ed3c2513c35efa714f2a377aef55501dd15d1fec
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
import { marked } from 'marked'
import DOMPurify from 'dompurify'
 
/**
 * 消息正文的 Markdown 渲染。
 *
 * ## 为什么需要「先转义再解析」这个顺序
 *
 * 模型输出是**不可信内容** —— 它可能包含 `<script>`、`<img onerror=...>`
 * 这类原始 HTML。常见做法是「先交给 marked 解析,再用 DOMPurify 清洗」,
 * 但那意味着危险 HTML 至少被解析进过 DOM 一次,清洗规则一旦有疏漏就中招。
 *
 * 这里采用更保守的顺序:
 *   1. 先把原文里的 `& < > " '` 全部转义成实体
 *   2. 再交给 marked 解析成 HTML
 *   3. 最后 DOMPurify 兜底(防御 marked 自身可能引入的问题)
 *
 * 转义后模型写的 `<div>` 变成 `&lt;div&gt;`,marked 只把它当普通文字,
 * 永远不会渲染成标签。代价是模型输出里的原始 HTML 不生效 ——
 * 对聊天场景这正是我们想要的。
 *
 * ## 关于引用编号 [1]
 *
 * Markdown 会把 `[1]` 当成「引用式链接」的语法(后面没有 `:` 定义时
 * 多数实现原样输出,但这属于未定义行为)。为避免依赖这种边界行为,
 * 引用高亮**在 Markdown 渲染完成后**对生成的 HTML 做,并跳过 `<code>`
 * 与 `<pre>` 内部,避免把代码里的数组下标误标成引用。
 */
 
// 语序:GFM(表格、删除线、任务列表)+ 单换行转 <br>(模型输出常靠单换行分段)
marked.setOptions({
  gfm: true,
  breaks: true,
  // 不启用 headerIds / mangle,避免给标题生成 id 造成重复
  headerIds: false,
  mangle: false
})
 
/**
 * 转义 HTML 特殊字符。
 *
 * 必须转义 `&` 否则会与已转义内容二次冲突(`&lt;` 被再次转义成 `&amp;lt;`)。
 */
export function escapeHtml(text) {
  return String(text)
    .replace(/&/g, '&amp;')
    .replace(/</g, '&lt;')
    .replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;')
    .replace(/'/g, '&#39;')
}
 
/**
 * 补全流式过程中未闭合的代码块。
 *
 * 流式输出到一半时,``` 可能只有开始没有结束,此时 marked 会把
 * 后续全部内容当成代码 —— 表现为「回答突然整段变灰卡在代码块里」。
 * 这里在渲染前把围栏补齐,让中间态也看起来正常。
 *
 * 只处理 ``` 围栏;行内 ` 不补(补错反而更乱)。
 */
export function closeUnbalancedFences(text) {
  if (!text) return text
  // 统计行首的 ``` 出现次数(奇数说明未闭合)
  const fences = text.match(/^```/gm)
  if (fences && fences.length % 2 === 1) {
    return text + '\n```'
  }
  return text
}
 
/**
 * 把正文渲染成可安全插入的 HTML。
 *
 * @param {string} raw       模型输出的 Markdown 原文
 * @param {object} [options]
 * @param {boolean} [options.streaming] 是否仍在流式生成(决定要不要补围栏)
 * @param {number}  [options.citationCount] 可用引用编号数量,用于高亮 [1][2]
 * @returns {string} 可交给 v-html 的 HTML 字符串
 */
export function renderMarkdown(raw, options = {}) {
  const { streaming = false, citationCount = 0 } = options
  if (!raw) return ''
 
  let text = raw
  if (streaming) {
    text = closeUnbalancedFences(text)
  }
 
  // 第一步:转义。此后的内容不可能再变成标签。
  const escaped = escapeHtml(text)
 
  // 第二步:Markdown 解析
  let html = marked.parse(escaped)
 
  // 第三步:引用编号高亮(在 HTML 上做,跳过代码块内部)
  if (citationCount > 0) {
    html = highlightCitations(html, citationCount)
  }
 
  // 第四步:清洗兜底
  const safe = DOMPurify.sanitize(html, {
    ALLOWED_TAGS: [
      'p', 'br', 'hr', 'strong', 'em', 'del', 's', 'code', 'pre',
      'blockquote', 'ul', 'ol', 'li', 'a',
      'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
      'table', 'thead', 'tbody', 'tr', 'th', 'td', 'span'
    ],
    ALLOWED_ATTR: ['href', 'title', 'class', 'target', 'rel'],
    // 只允许安全协议,挡住 javascript: / data: 这类伪协议
    ALLOWED_URI_REGEXP: /^(?:https?|mailto):/i
  })
 
  // 第五步:还原代码块里被转义的字符
  return decodeEntitiesInCode(safe)
}
 
/**
 * 还原 `<pre>` / `<code>` 内部被转义的**引号与 &**,但**保留 `<` `>` 的转义**。
 *
 * <h3>为什么需要还原</h3>
 * 为避免模型输出的原始 HTML 被当标签渲染,我们先把整段文本转义
 * (`'` 变 `&#39;`)再交给 marked。浏览器显示时会自动解码实体,
 * 所以**肉眼看到的是正确的**;但 DOM 里的 `innerHTML` 仍是 `&#39;`,
 * 用户**复制代码**时剪贴板拿到的就是 `file.write(&#39;x&#39;)`,
 * 粘进编辑器直接语法错误 —— 代码块正是用来复制的,必须还原。
 *
 * <h3>为什么只还原引号和 &amp;,不还原 &lt; &gt;(关键安全约束)</h3>
 * 这是本函数最需要守住的一条线。曾尝试还原全部五个字符,
 * 结果**引入了 XSS**:把 `&lt;script&gt;` 还原成 `<script>` 后,
 * 它经 v-html 插入 DOM 就变成**真正会执行的标签**。
 * 实测三种载荷全部触发 alert:
 *
 * <pre>
 *   ```html                    →  &lt;script&gt;  还原后真的执行
 *   &lt;script&gt;alert(1)&lt;/script&gt;
 *   ```
 *   &lt;svg onload=alert(1)&gt;     →  同样执行
 *   &lt;img src=x onerror=alert(1)&gt; →  同样执行
 * </pre>
 *
 * 注意 **DOMPurify 挡不住这个**:它默认会剥掉 `<script>` 标签,
 * 但 `<svg onload>` 与 `<img onerror>` 属于它允许的元素 + 它保守处理的事件属性,
 * 而我们的白名单又放开了 `img`(用于消息里的图片)。
 * 唯一可靠的做法是**不生成这些标签** —— 也就是保留 `<` `>` 的转义。
 *
 * <h3>代价</h3>
 * 代码里的 `<` 与 `>` 复制出来仍是 `&lt;` / `&gt;`。
 * 对代码块这是可接受的:C/Python/JS 里的比较运算虽然常见,
 * 但多数人靠**肉眼阅读**代码,而肉眼看到的是浏览器解码后的正确内容。
 * 若要彻底解决,需要让代码块走 textContent 而非 v-html 插入 ——
 * 那是渲染架构级改动,复杂度远高于收益。
 *
 * <h3>为什么要解两层</h3>
 * marked 解析代码块时会把内容当**文本**再转义一次,
 * 我们转义的 `&amp;#39;`(即 `&` + `#39;`)会被它变成 `&amp;amp;#39;`。
 * 因此需要循环解码直到不再变化。
 */
function decodeEntitiesInCode(html) {
  // 只处理不会产生标签的实体
  const inverse = { '&amp;': '&', '&quot;': '"', '&#39;': "'" }
  const decodeOnce = (text) =>
      text.replace(/&amp;|&quot;|&#39;/g, (entity) => inverse[entity] ?? entity)
 
  return html.replace(
    /(<pre\b[^>]*>[\s\S]*?<\/pre>|<code\b[^>]*>[\s\S]*?<\/code>)/gi,
    (block) => {
      // 最多解 3 层,避免异常输入造成死循环。
      // 注意:&amp; 会层层还原,若某层还原出 &lt; 也仅作为文本存在,
      // 不会再被解析成标签(此时已是字符串拼接阶段,不经过 HTML 解析器)。
      for (let i = 0; i < 3; i++) {
        const next = decodeOnce(block)
        if (next === block) {
          break
        }
        block = next
      }
      return block
    }
  )
}
 
/**
 * 高亮正文里的引用编号 `[1]`,但**跳过代码块**。
 *
 * 为什么要跳过:代码里出现 `arr[1]`、`argv[2]` 这类数组下标非常常见,
 * 一律高亮会让代码看起来满是链接色,反而干扰阅读。
 *
 * 实现方式是把 HTML 按 `<code>` / `<pre>` 切成段,只处理段外的部分。
 */
function highlightCitations(html, maxCitation) {
  const parts = html.split(/(<pre[\s\S]*?<\/pre>|<code[\s\S]*?<\/code>)/gi)
  return parts
    .map((part, index) => {
      // 奇数下标是捕获组内容(代码块),原样返回
      if (index % 2 === 1) {
        return part
      }
      return part.replace(/\[(\d{1,2})\]/g, (match, num) => {
        const n = Number(num)
        if (n < 1 || n > maxCitation) {
          // 超出范围的编号不当作引用,保持原样
          return match
        }
        return `<span class="citation-ref" title="引用来源 ${n}">[${n}]</span>`
      })
    })
    .join('')
}