前言¶
在 DSH Web 客户端中使用 Pandoc 风格的 $$ 显示数学块时，会遇到解析错误。这会导致公式首行被静默丢弃，或者从第二行到消息结尾的内容被吞掉，最终显示为红色的 KaTeX 报错。而在其他 Markdown 渲染器（如 VS Code）中，这些格式是正常的。
这是什么¶
这是一个由 s11phere 维护的 DSH Web 客户端插件。它的核心作用是修复 DSH Markdown 语法误解析 Pandoc 风格 $$ 公式块的问题：解决首行被静默丢弃、或消息剩余部分被吞掉并显示为报错的问题。它将不规范的公式块形状统一归一化为标准形状。
安装与启用¶
使用以下命令将插件添加到 DSH Web 配置中：
dsh plugin --profile web add <本包目录>
执行命令后，重启 dsh web 并刷新页面即可生效。
核心功能¶
- 修复解析错误：将原本导致静默丢弃首行或吞掉消息剩余部分的语法，调整为 DSH 能正确识别的格式。
- 统一形状：将不规范的公式块形状（如
$$内容开头、$$独占一行收尾等）统一归一化为标准形状（$$独占一行，内容独占一行，$$独占一行）。 - 修复历史消息：支持对会话中已经记录的历史消息进行重新渲染修复，这个过程不会修改 session 数据。
- 临时关闭：支持通过环境变量临时关闭插件。
典型用法¶
标准形状示例：
$$\n独占一行\n$$
行间公式示例：
$$\n\\frac{\\partial}{\\partial y} = 1\n\\quad\\Longrightarrow\\quad\n x = y$$
验证与调试¶
安装完成后，可以通过以下方式验证插件是否正常工作：
- 控制台日志：刷新页面后，浏览器控制台应出现日志：
[dsh-tex-block-normalizer] active: Pandoc-style $$ blocks are normalized before Markdown parsing。 - 调试对象：在浏览器控制台查看
window.__DSH_TEX_BLOCK_NORMALIZER__，其内容应包含{ installed: true, reason: 'installed', stats: { calls, rewrites } }。rewrites数值的增长表示发生了改写操作。 - 历史消息修复：打开此前显示为红色纯文本的历史消息，报错应消失，公式应正常排版。
- 临时禁用：在页面加载前设置
globalThis.__DSH_TEX_BLOCK_NORMALIZER_DISABLE__ = true可临时关闭插件。
适用场景与注意¶
该插件适合需要在 DSH Web 客户端中正常使用 Pandoc 风格数学公式的场景。
注意事项：
* 不处理块引用（> $$）或列表项（- $$）里的 $$。
* 没有收尾 $$ 的块保持原样，因此仍会吞到文件尾。
* 插件依赖 Node.js >= 22.5。
* 插件依赖外部库 @deepseek-ai/dsh-client-ui-primitives。
结尾¶
插件通过简单的文本重写解决了 DSH 在处理特定数学块格式时的解析缺陷。对于遇到公式显示问题的开发者，这是一个低侵入性的解决方案。详细文档与源码可参考下方链接。
