前言¶

在 DeepSeek Harness Web 裏跑對話時，assistant 的回覆是逐 token 流式輸出的。默認 Markdown 渲染器面對尚未閉合的粗體、代碼圍欄、表格或數學公式時，容易出現閃爍、結構錯亂，或在消息完成瞬間整段 UI 被另一套實現替換。

dsh-better-markdown 是社區維護的 Web 客戶端插件，用 markstream-react 接管對話區 assistant 消息的 Markdown 解析與渲染，並在流式與 settled 狀態共用同一套 renderer。下面介紹它的定位、能力與安裝方式。

這是什麼¶

dsh-better-markdown 由 zerob13 維護，當前 npm 版本爲 0.1.2，許可證 MIT。插件不修改 Harness 源碼，通過 Harness 公開的 client module 與 slot shadowing 注入渲染邏輯。

核心替換範圍是 Web 對話中所有帶流式狀態的 assistant Markdown；plan review、trajectory 等靜態 surface 仍使用 Harness 內置 MarkdownText，不在替換範圍內。

爲什麼換用 markstream-react¶

markstream-react 來自 Simon-He95/markstream-vue monorepo 的 React 版本，本插件只引入 React package，不會帶入 Vue runtime。

與默認鏈路相比，插件側強調以下幾點：

1. 面向流式輸出：可持續處理未閉合的粗體、代碼圍欄、列表、表格和數學表達式，適合 LLM token stream。
2. 減少完成態切換：流式與 settled assistant message 共用 Markstream renderer，避免完成時替換整棵 Markdown UI。
3. 更豐富的 Markdown：支持常用 Markdown、表格、任務列表、引用、鏈接、圖片、KaTeX 數學公式和 Mermaid 圖表。
4. 兼容 Harness 滾動區：關閉不適用於聊天內部滾動容器的 viewport lazy mounting，避免可見內容停留在骨架佔位狀態。
5. 安全邊界明確：原始 HTML 使用 htmlPolicy="escape"；鏈接、圖片和 settled file mention 繼續執行 Harness 的限制策略；Mermaid 使用 strict mode。

核心功能¶

代碼塊由 Markstream MarkdownCodeBlockNode 與 stream-markdown 渲染，使用 Shiki 流式高亮，並保留語言標題、複製和展開操作；reasoning、附件、停止狀態仍保持 Harness 原行爲。

工作原理¶

Assistant token stream
  -> Harness session projection
  -> conversation.chat.node / assistant-step
       |- priority -100: BetterAssistantNodeView
       |                  -> markstream-react  (active)
       |                       `- fenced code -> stream-markdown -> Shiki
       `- priority    0: Harness built-in      (fallback)

低優先級 shadow entry 負責正常渲染；如果插件 renderer 拋錯或被卸載，Harness 原 renderer 仍在 slot 中並自動接管。

安裝與啓用¶

前置條件：DeepSeek Harness Web 可以正常啓動。

從 npm 安裝（推薦）¶

dsh plugin --profile web add dsh-better-markdown
dsh --profile web --dump-config
dsh --profile web

更新插件：

dsh plugin --profile web add dsh-better-markdown@latest

配置輸出應包含：

# == dsh-better-markdown
- id: better-markdown
  name: dsh-better-markdown

打開 Web 後，assistant Markdown 根節點會帶有 data-markdown-renderer="markstream-react" 屬性，可用於確認插件已生效。

從源碼安裝¶

前置條件：Node.js 20+，pnpm 10+。

git clone https://github.com/zerob13/dsh-better-markdown.git
cd dsh-better-markdown
pnpm install
pnpm run check
pnpm run build
dsh plugin --profile web add "$(pwd)"
dsh --profile web --dump-config
dsh --profile web

Windows PowerShell 將 "$(pwd)" 替換爲 (Get-Location).Path。

從 Git 安裝¶

pnpm 10/11 可能要求在 Web profile 的 pnpm-workspace.yaml 中顯式允許構建：

allowBuilds:
  dsh-better-markdown: true

然後執行：

dsh plugin --profile web add git+https://github.com/zerob13/dsh-better-markdown.git
dsh --profile web

建議生產環境固定 commit SHA，而不是長期跟隨默認分支。

移除¶

dsh plugin --profile web remove dsh-better-markdown

卸載會釋放 slot shadow 和 Markstream component policy，Harness 內置 renderer 隨即恢復。

典型用法¶

本插件安裝後即生效，無需額外配置項。在 Web 對話中向 assistant 發送包含 Markdown 的請求即可驗證渲染效果，例如：

• 帶語言標註的 fenced code，觀察 Shiki 流式高亮與複製按鈕；
• $$...$$ 或 $...$ 形式的 KaTeX 數學公式；
• ```mermaid 代碼圍欄中的流程圖或時序圖。

上述內容均走 markstream-react 渲染鏈路；若插件加載失敗，Harness 內置 renderer 會自動回退。

適用場景與注意¶

適合誰

• 經常在 Harness Web 對話裏閱讀長回覆、代碼塊、公式或 Mermaid 圖的用戶；
• 希望流式輸出與完成態視覺一致、減少 Markdown UI 切換的開發者。

兼容性

• DeepSeek Harness 0.1.0-rc.5 及以上；
• React 18 及以上；
• 僅替換 Web conversation 的 assistant-step；
• 舊版 Harness 如果沒有 priority-based slot shadowing，會直接加載失敗，避免出現雙 renderer。

體積與取捨

當前 browser bundle 約 7.40 MB，gzip 約 1.59 MB。Mermaid 與 Shiki 均被打包以保證離線可用；Shiki 使用純 JavaScript 正則引擎與 34 種常用語言的 fine-grained bundle。如果不需要 Mermaid，移除其 dependency 可以明顯減小 bundle，但 Mermaid fence 將無法生成圖形預覽。

安全提示

插件以當前 dsh 進程權限運行，會加載第三方 npm 依賴（markstream-react、mermaid、shiki、katex 等）。安裝前建議閱讀 源碼倉庫 與 MIT 許可證，確認符合你的使用環境要求。

結語¶

dsh-better-markdown 把 DeepSeek Harness Web 對話區的 assistant Markdown 渲染交給 markstream-react，在流式與 settled 狀態保持同一套實現，並內置 Mermaid、KaTeX 與 Shiki 代碼高亮，出錯時可回退到 Harness 內置 renderer。

• 社區目錄：zerob13/dsh-better-markdown
• 源碼與文檔：github.com/zerob13/dsh-better-markdown