前言¶

在 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