dsh-better-markdown

<h1 align="center">dsh-better-markdown</h1>

用 <a href="https://www.npmjs.com/package/markstream-react"><code>markstream-react</code></a> 替换 DeepSeek Harness Web 的流式 Markdown 渲染链路。

<a href="https://github.com/zerob13/dsh-better-markdown/blob/master/README.md"><b>中文</b></a> · <a href="https://github.com/zerob13/dsh-better-markdown/blob/master/README_EN.md">English</a>

dsh-better-markdown 是一个 DeepSeek Harness Web 客户端插件。安装后，Web 对话中所有带流式状态的 assistant Markdown 都由 markstream-react 解析和渲染；同一消息流结束后继续使用同一个 renderer，不会在完成瞬间切回另一套 Markdown 实现。

markstream-react 是 Simon-He95/markstream-vue monorepo 提供的 React 版本。本插件在 Harness 中使用的是 React package，不会引入 Vue runtime。

为什么使用 Markstream React

• 面向流式输出：可持续处理尚未闭合的粗体、代码围栏、列表、表格和数学表达式，适合 LLM token stream。
• 减少完成态切换：流式与 settled assistant message 共用 Markstream renderer，避免完成时替换整棵 Markdown UI。
• 更丰富的 Markdown：支持常用 Markdown、表格、任务列表、引用、链接、图片、KaTeX 数学公式和 Mermaid 图表。
• 兼容 Harness 滚动区：关闭不适用于聊天内部滚动容器的 viewport lazy mounting，避免可见内容停留在骨架占位状态。
• 完整 Markstream 代码块：fenced code 由 Markstream MarkdownCodeBlockNode 与 stream-markdown 渲染，使用 Shiki 流式高亮，并保留语言标题、复制和展开操作；reasoning、附件、停止状态仍保持 Harness 原行为。
• 安全边界明确：原始 HTML 使用 htmlPolicy="escape"；链接、图片和 settled file mention 继续执行 Harness 的限制策略；Mermaid 使用 strict mode。

效果截图

Markstream 代码块

图片、链接与 KaTeX 数学公式

Mermaid 图表

功能范围

能力	行为
Assistant streaming Markdown	全部交给 markstream-react
Settled assistant Markdown	继续使用同一个 Markstream renderer
Mermaid	插件内置 [email protected]，无需额外安装
Math	KaTeX inline / display math
Code fences	使用 Markstream MarkdownCodeBlockNode + stream-markdown + Shiki；未知语言回退为可见纯文本
Raw HTML	转义为文本，不注入 DOM
Links and images	仅允许安全的外部协议
Plan review / trajectory 等静态 surface	继续使用 Harness 内置 MarkdownText；这些 surface 没有统一替换 slot

工作原理

插件使用 Harness 公开的 client module 与 slot shadowing，不修改 Harness 源码，也不替换全局 React。

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 中并自动接管。

安装

从 npm 安装（推荐）

前置条件：DeepSeek Harness Web 可以正常启动。

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

从源码安装

前置条件：DeepSeek Harness Web 可以正常启动，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。

配置输出应包含：

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

打开 Web 后，assistant Markdown 根节点会带有：

<div data-markdown-renderer="markstream-react">

直接从 Git 安装

Git dependency 会执行本仓库的 prepare 构建。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

…