思源笔记公式排版规范 (v1.0)

本技能用于确保从外部（如 AI 对话、Markdown 文档、论文）复制过来的技术文档中的 LaTeX 公式，在思源笔记里能正确渲染，避免公式变成纯文本、乱码或报错。

兼容性：本技能在 SiYuan v3.8.0（截至 2026-08-13 的最新发布版）上核验，公式渲染行为与 v3.7.2/v3.7.3 基线一致 —— 下方所有 $$/$ 定界符与逐块渲染规则仍然适用，无需改动。v3.7.3 修复了「用 # 号创建标题块」的缺陷（#18221），v3.8.0 为 AI/数据库/表格等功能的增强版本，未改变公式解析规则；本流程用 Markdown 标题语法写公式块，不受影响。

职责边界：公式的检测、定界符转换、批量修复只在本技能维护。siyuan-kernel-ops 的 Q4 只保留一条指针（定界符 + 间距宏 + 一块一公式），不重复写规则——避免两处各自漂移。反过来，连接内核、块读写与验证套路以 siyuan-kernel-ops 为准。

1. 核心避坑法则（最重要）

思源笔记解析公式的黄金法则：块级公式（多行大公式）必须严格独立成行，且上方和下方必须各空一行。

只要遵守这一条，绝大多数"公式不显示"的问题都能解决。

2. 公式语法区分

3. 常见"翻车"场景与修复标准

当公式显示为乱码、纯文本（如 \text{Attention} 原样显示）或排版错位时，按以下规则检查修复。

❌ 错误写法（会导致渲染失败）

这里的核心公式是 $$ \text{Attention}(Q,K,V) = \text{Softmax}(...) \cdot V $$ 我们来分析一下。

✅ 正确写法（强制修复）

这里的核心公式是：

$$
\text{Attention}(Q,K,V) = \text{Softmax}(...) \cdot V
$$

我们来分析一下。

4. 公式内部断行与空格规则

• 禁止折断：$$ 符号内部，禁止将 \left( \right) 或 \frac{}{} 强行换行，除非是矩阵环境（\begin{matrix}）。普通公式请写在一行内。
• 保留大括号：公式中的 { } 必须成对出现，缺失会导致解析失败。
• 无关空格：LaTeX 公式内部忽略多余空格（如 Q K^T 和 QK^T 一样），但在思源里，符号与文字之间建议不加空格，以免被截断。

5. 手动强制刷新大法（必知）

如果粘贴后公式显示为代码块或纯文本，不需要重新编辑文章，直接操作：

1. 把光标点进那个显示错误的公式块内部。
2. 直接按键盘上的 回车（Enter） 键。
3. 思源会自动重新识别并渲染该公式为漂亮的数学公式。

6. 针对 AI 生成文本的处理规则

当从 Claude / ChatGPT 等工具复制技术文档到思源时，务必执行以下三步：

1. 清除多余空格：检查 $$ 与公式之间是否有多余空格（如 $$ Attention 应改为 $$ \text{Attention}）。
2. 检查换行：确保每一个 $$ 头尾都独占一行。
3. 检查引用：引用块（>）内的公式同样需要遵守上述规则。

附：标准模板（可直接复制使用）

## 标题

正文描述内容。

$$
\text{公式主体}
$$

正文描述内容。

- 列表项，行内公式用 $E=mc^2$ 表示。

7. 程序化批量修复流程（SiYuan Kernel API）

当用户说"处理整篇文档的所有公式 / 让格式变正确"时，用 Kernel API 批量改，比手动点公式快且可校验。连接与验证套路同 siyuan-kernel-ops 技能（端口从 conf.json 的 serverAddrs 现读，token 取 api.token；校验只信 getChildBlocks，不信 getBlockKramdown 缓存）。

检测（先读 live 块）

getChildBlocks(rootId) 返回每个块的 {id, type, markdown}。重点看：

• 含 \[ / \( 的块 → 思源不渲染（只认 $$/$），必然显示为纯文本。这是"格式不正确"最常见根因。
• 含 <sup> 的块 → HTML 上标污染，需还原成 ^{...}。
• 含 \quad / \qquad / \; / \, / \: 的块 → 间距宏，思源 KaTeX 可能整块渲染空白（"一个 $$ 块只放一个公式"），建议移除。

转换规则（逐块）

1. 块级 \[ ... \] → updateBlock(data="$$ ... $$", dataType="markdown", id=块ID)。已验证：把 p 块写成 $$...$$ 后思源会自动把它转成 m 块（真渲染）。m 块即块级公式，无需上下空行。
2. 行内 \( ... \) → 字符串替换 \(→$、\)→$，updateBlock 保持原有 p/l 块类型，行内公式正常。
3. 内部空白归一：re.sub(r'\s+',' ', inner) 折叠换行/多空格为单空格；矩阵/cases 的 \\ 行分隔符保留不变。
4. 被拆断的公式：\[ 在某块、\] 落在紧邻的下一块（常是列表项 - z \]）→ 把两段 inner 拼成一条 $$ merged $$，updateBlock 写回首块，再 deleteBlock 删掉尾块。
5. <sup> 污染：<sup>2 = ...\sum_{i=1}</sup>{d} → ^2 = ...\sum_{i=1}^{d}；<sup>{d} x_i</sup>2 → ^{d} x_i^2（把 </sup> 后的 {d}/2 收进上标）。
6. 间距宏：re.sub(r'\\quad|\\qquad|\\;|\\:|\\,',' ', s) 移除（纯间距，不影响语义）。

校验与收尾

• 写完后 getChildBlocks 断言：全文无 \[ / \( / \] / \quad / <sup> 残留；m 块数量符合预期。
• 调用 /api/ui/reloadUI 让桌面端刷新（否则用户看不到改动）。
• 安全：先 /api/export/exportMdContent 备份；同文档顺序写入，禁止并行；ID 从 getChildBlocks 精确取，绝不按时间戳前缀批量删。

7.1 实战补充坑（2026-08-23 IEEE 754 文档）

• \(..\) 内容里的成对 ^ 会被解析为上标标记：因为思源根本不把 \(...\) 当公式，内容是纯文本，(-1)^{S} ... 2^{E-x} 中两个 ^ 配对 → 存储层变成 <sup>S \times 2</sup>{...}。修复时必须连同定界符一起换成 $..$，只修里面的 ^ 无效（写回后再次被解析）。
• m 块反斜杠转义层级不稳定：同一写法有时存单 \text、有时被吃掉或翻倍。不要信任何"固定要发几个反斜杠"的经验值——写后立刻 getBlockKramdown 校验存储层是否恰好单反斜杠 + ^{} 完整，不对就换转义层级重试（实测单反斜杠直发通常正确）。
• updateBlock 静默丢写：code=0 不代表生效，必须导出/重读探针字符串确认，失败换时间间隔重试。
• 表格单元格里的 \t 序列会被解析成真实 TAB：\times/\text 写入表格 markdown 后变成 TAB+imes/TAB+ext（列表和正文块不受影响）。修复：读 live kramdown，把 TAB 残片拼回 \times/\text{，写后校验存储层无 TAB 且含单反斜杠命令。