前言¶
在 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 在處理特定數學塊格式時的解析缺陷。對於遇到公式顯示問題的開發者，這是一個低侵入性的解決方案。詳細文檔與源碼可參考下方鏈接。
