前言¶

在 DSH Web 里看模型回复时，行间公式有时会整段变成红色纯文本，悬停还能看到 KaTeX 的 ParseError。同一段 Markdown 在 VS Code 预览里却正常。常见原因是模型按 Pandoc 习惯写 $$：开栏与首行公式在同一行、收尾 $$ 贴在最后一行末尾。DSH 的 Markdown 语法对这类形状处理不当，会静默丢掉首行，或未闭合的 $$ 把后面正文、表格乃至后续公式都吞进一个数学节点，最终 KaTeX 报错。下面介绍社区插件 dsh-tex-block-normalizer（维护者 TianzeLuo，分类：工作流），它在解析前把后几种写法归一成 DSH 能正确接受的「$$ 独占一行」形式，且不改动 session 里已保存的原文。

这是什么¶

dsh-tex-block-normalizer 是面向 DSH Web 客户端的插件：在 Markdown 解析之前，对 Pandoc 风格的 $$ display-math 块做换行归一化，只移动 $$ 的换行位置，块内 TeX 内容一字不改。归一化发生在渲染阶段，历史消息无需重发即可在刷新后正常显示。

• 目录页：https://www.skillhub.cn/plugins/TianzeLuo/dsh-tex-block-normalizer
• 源码与说明：https://github.com/TianzeLuo/dsh-tex-block-normalizer
• 许可证：MIT（见仓库 README）
• 当前包版本（package.json）：0.1.0

症状与 DSH 接受的形状¶

模型常写出如下行间公式（开栏 $$ 与内容同行、正文跨行、收尾 $$ 贴在末行）：

$$\frac{\partial}{\partial y} = 1
\quad\Longrightarrow\quad
x = y$$

在 DSH 中可能出现：首行被当成 info 字符串静默丢弃；$$ 块未闭合时从第二行到消息末尾被吞掉；KaTeX 收到整段非 TeX 文本后报 ParseError: ... Can't use function '$' in math mode ...，界面显示为红色纯文本。

README 中对照 DSH 0.1.7-rc.1 的归纳如下（插件目标是把后三行对应写法搬成第一行那种）：

核心功能¶

1. 渲染前归一化：将上述有问题的 $$ 布局统一为「开栏、收尾 $$ 各独占一行」，块内公式文本不变。
2. 历史消息可用：不修改 session 数据，仅影响当前 Web 端的 Markdown 渲染路径。
3. 可观测与可关闭：控制台有一次激活日志；可通过全局对象查看是否安装及改写次数；支持加载前禁用。
4. 配套审计脚本：可用仓库内脚本对任意 Markdown 做归一化前后对照（使用与 DSH 一致的语法与 KaTeX 相关链路，见下文验证一节）。

实现细节、根因分析与边界条件见仓库 docs/（如 root-cause.md、how-it-works.md、limitations.md）。

安装与启用¶

插件以当前 dsh 进程权限运行，安装前请自行审阅源码与 MIT 许可证。安装命令须使用本包所在目录，不要凭插件名拼接未在文档中出现的 github:owner/repo 形式。

在已获取插件目录的前提下执行：

dsh plugin --profile web add <本包目录>

然后重启 dsh web 并刷新浏览器页面。

验证是否生效¶

1. 刷新后，浏览器控制台应出现一次：
   [dsh-tex-block-normalizer] active: Pandoc-style $$ blocks are normalized before Markdown parsing
2. 在开发者工具中查看 __DSH_TEX_BLOCK_NORMALIZER__，期望形如 { installed: true, reason: 'installed', stats: { calls, rewrites } }；rewrites 增长表示确有改写。
3. 打开此前报错的 history 消息，红色纯文本应消失，公式正常排版。
4. 临时关闭：在页面加载前设置 globalThis.__DSH_TEX_BLOCK_NORMALIZER_DISABLE__ = true。
5. 命令行审计本地 Markdown（归一化前后对照）：

node scripts/audit-markdown.mjs <file.md>

（需在插件仓库内、且已按 README 安装开发依赖时使用。）

典型用法与适用场景¶

适用：经常在 DSH Web 里阅读含行间公式的模型输出；模型习惯 Pandoc 式 $$ 换行；希望在不改上游 DSH 的前提下先恢复可读渲染。

不必指望插件处理的情况（README「限制」一节）：

• 块引用或列表项内的 $$（例如 > $$a、- $$a）不处理。
• 完全没有收尾 $$ 的块保持原样，仍可能吞到文件尾。
• 依赖 React.memo 的内层 .type 等 React 内部细节；取不到时插件安静变为 no-op，不拖垮界面。

社区插件目录（SkillHub）与 DeepSeek / 幻方无官方从属关系；DSH 生态强调「一切皆插件」，本包是工作流类补充之一。

开发与测试（可选）¶

若需改归一化逻辑或贡献补丁，仓库 README 给出：

npm install     # 仅测试用的 parser / katex devDependencies
npm test        # 21 项：归一化用例 + 打包产物 + DSH 语法验收
npm run build   # 改过 lib/normalize.js 后重新生成 lib/client.js

运行环境要求 Node >=22.5（见 package.json engines）。

结尾¶

dsh-tex-block-normalizer 针对 DSH Web 对 Pandoc 风格 $$ 的误解析，用最小改动的换行归一化恢复 KaTeX 渲染，对已有会话记录同样有效。安装使用官方 README 中的 dsh plugin --profile web add <本包目录>，并按控制台与 __DSH_TEX_BLOCK_NORMALIZER__ 自检。

• 插件目录：https://www.skillhub.cn/plugins/TianzeLuo/dsh-tex-block-normalizer
• GitHub：https://github.com/TianzeLuo/dsh-tex-block-normalizer