一句话定位

把 DeepSeek Harness Web 对话里的流式 Markdown 渲染替换成 markstream-react，让助手消息从首个 token 开始就有正确的格式高亮，结束时不会突然换一套渲染器；额外带来数学公式、Mermaid 图表和 Shiki 代码高亮。

核心能力

• 在助手消息还在流式生成时，就按 Markdown、表格、任务列表、引用、图片、链接的最终形态渲染（markstream-react 持续解析未闭合结构）
• 流式输出和已完成的助手消息共用同一个渲染器，避免在流结束瞬间把整段内容切回另一套实现
• 在 fenced code 块上使用 Shiki 做流式高亮，并保留语言标题、复制按钮和展开操作；未知语言回退为可见纯文本
• 渲染 KaTeX 数学公式（行内 + 块级）和 Mermaid 图表（已打包 Mermaid 11，离线可用）
• 跟随 DSH Web 的深色主题（CSS token 亮度 + data-ds-dark-theme + 系统偏好），主题切换时自动重新渲染
• 保留 Harness 原生的图片画廊、文件引用和中断标识

技术实现

• 语言: TypeScript（ESM, "type": "module"），入口用 tsdown 打包
• 关键依赖: markstream-react 0.0.55（核心解析与渲染）、stream-markdown 0.0.16（流式代码块 AST）、shiki 4.4.3 + @shikijs/langs/themes（代码高亮）、katex ^0.18.4（数学公式）、mermaid 11.16.1（图表）
• 架构模式: 客户端单边插件——通过 Harness 的 client-module + slot shadowing API，以 priority: -100 注册到 conversation.chat.node 槽位的 assistant-step key，原始 Harness renderer 仍以 priority: 0 留在槽里作为自动 fallback；同步通过 setCustomComponents 注入 4 个 Markstream 自定义组件（code_block / image / inline_code / link）
• 入口文件: src/index.ts（Cordis host 半边，导出 name + 空 apply() 让 client-module 注册被发现），src/client/index.ts（浏览器半边，真正执行注入），cordis.patch.yml（bundle row）

适用场景

在 DSH Web 对话里，模型经常输出代码、长公式、流程图或大段 Markdown，原生渲染在流式期间会出现格式跳动或完成瞬间整体重排。装上这个插件后，从首个 token 开始就能看到正确排版的代码块、公式和图表，流结束后也不会突然闪一下。如果你经常让模型画架构图、写 LaTeX 公式、或者粘贴大段带格式的代码，这个插件能明显改善可读性。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:zerob13/dsh-better-markdown

配置项

本插件无需额外配置。运行时只读取宿主 DSH 提供的对话节点（block 数组、运行状态、文件引用、国际化函数等），不暴露用户可调的开关或参数；如需禁用，把插件从 dsh 配置里移除即可。

常见问题

Q: 安装后怎么确认插件已经生效？

A: 在 Web 对话里让模型输出任意 Markdown 消息，用浏览器开发工具检查根节点——会看到一个带 data-markdown-renderer="markstream-react" 属性的 div；如果没有这个属性，说明插件没有加载。

Q: 卸载插件后会留下渲染残留吗？

A: 不会。客户端在 effect 析构时会撤销 Markstream component policy 并注销 assistant slot 的低优先级 shadow，原 Harness renderer 会立即接管，不需要额外清缓存。

Q: Plan review、轨迹回放这些面板也会被替换吗？

A: 不会。插件只替换 assistant-step 这一路 Web 对话的 slot；plan review、trajectory 等静态 surface 仍由 Harness 原 MarkdownText 处理。

Q: 需要安装 Mermaid 或 Shiki 吗？

A: 都不需要。插件已经把 Mermaid 11.16.1、Shiki 4.4.3（含 34 种常用语言）打包进 bundle，离线也能用。

Q: 深色模式会自动切换吗？

A: 会。插件通过 DSH shell 的 CSS token 亮度、data-ds-dark-theme 属性和系统深色偏好三层信号判断主题；用户手动切主题后会通过 MutationObserver 在约 80ms 内重新渲染。

Q: 流式输出时遇到不完整的代码块怎么办？

A: markstream-react 专为 LLM token 流设计：未闭合的代码围栏、列表、表格、数学表达式会被持续解析并增量渲染，不会因为格式"暂时不完整"就崩；流结束后同一个 renderer 继续显示，不会切换到另一套实现。

Q: 这个插件安全吗？会执行模型生成的 HTML 吗？

A: 不会。raw HTML 会被强制转义为可见文本（htmlPolicy="escape"）；链接只允许 http:、https:、mailto:；图片只允许 http(s):；Mermaid 在 strict mode 下运行，不存在脚本注入面。

上手难度

入门 — 一条命令安装即用，没有需要填的配置项；不修改宿主文件，卸载即还原。

已知问题与限制

• 浏览器 bundle 较大：当前约 7.40 MB（gzip 约 1.59 MB），因为 Shiki 和 Mermaid 都已打包以保证离线可用；如果不需要 Mermaid，从源码构建时移除该依赖能明显减小体积
• 代码高亮只覆盖 34 种常用语言：未知语言会回退为可见纯文本而不是高亮；可选的 Monaco runtime、D2、Infographic 等 peer 没有打包
• 只替换 assistant-step 这一路：plan review、trajectory 等静态 surface 没有共享替换槽，仍用 Harness 原 renderer；如果以后 Harness 暴露更多 slot，插件需要更新才能覆盖
• 需要 priority-based slot shadowing：DSH < 0.1.0-rc.5 没有这套机制，加载会直接报错而不是"双渲染器共存"，避免出现视觉异常
• 图片加载必须有可用服务：插件不内置图片加载实现，必须由宿主通过 loadImage 回调提供；缺失时点击图片会返回 serviceUnavailable 错误
• DSH 客户端版本约束较紧：peerDependencies 同时锁住 7 个 @deepseek-ai/dsh-client-* 包要 >=0.1.0-rc.5，DSH 主版本升级时插件可能要发新版兼容

dsh-better-markdown

用 markstream-react 替换 DeepSeek Harness Web 的流式 Markdown 渲染链路。

中文 · English

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 图表

功能范围

工作原理

插件使用 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

建议生产环境固定 commit SHA，而不是长期跟随默认分支。

移除

移除插件：

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

卸载会释放 slot shadow 和 Markstream component policy，Harness 内置 renderer 随即恢复。

体积与取舍

• markstream-react: 0.0.55
• mermaid: 11.16.1
• stream-markdown: 0.0.16
• shiki: 4.4.3
• 当前 browser bundle：约 7.40 MB，gzip 约 1.59 MB
• Mermaid 与 Shiki 代码高亮均被打包以保证离线可用；Shiki 使用纯 JavaScript 正则引擎与 34 种常用语言的 fine-grained bundle
• Monaco runtime、D2、Infographic 等可选 peer 没有打包；未知代码语言使用 Markstream 的纯文本回退

如果不需要 Mermaid，移除其 dependency 可以明显减小 bundle，但 Mermaid fence 将无法生成图形预览。

开发

pnpm install
pnpm run check
pnpm run build
pnpm pack --dry-run

维护者发布流程：先让 package.json 版本与 vX.Y.Z tag 保持一致，再发布对应的 GitHub Release。publish.yml 会验证版本、执行测试与构建，并通过 npm trusted publishing 发布公开包；prerelease 不会发布。

主要文件：

• src/client/index.ts：注册 Markstream component policy 和 assistant slot shadow
• src/client/renderer.tsx：assistant node 与 Markdown renderer
• src/client/shiki.ts：单文件插件使用的 fine-grained Shiki bundle
• src/client/styles.css：Harness token 适配
• cordis.patch.yml：插件 bundle row
• tests/plugin.spec.tsx：streaming、fallback、安全与 Mermaid 路由测试

兼容性

• DeepSeek Harness 0.1.0-rc.5 及以上
• React 18 及以上
• 仅替换 Web conversation 的 assistant-step
• 旧版 Harness 如果没有 priority-based slot shadowing，会直接加载失败，避免出现双 renderer

致谢

• DeepSeek Harness
• markstream-vue / markstream-react
• Mermaid

License

MIT