在工作区文件预览中把 Markdown 文件里的 mermaid 代码块渲染成图表,支持点击放大预览。
安装
# GitHub 源码(首次需按提示配置 allowBuilds 构建授权后重试)
dsh plugin --profile web add github:sangaizhi/dsh-plugin-mermaid-markdown
装任何插件都等于在你的机器上跑第三方代码,权限和你本人一样大——能读你的文件、用你的凭据、访问网络,工具审批管不到它。GitHub 来源的插件还会在安装时执行构建脚本——pnpm 默认拦截,所以安装可能停在 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED 或 ERR_PNPM_IGNORED_BUILDS;dsh 会打印出需要添加的确切键名,把它加进该 profile 的 pnpm-workspace.yaml 的 allowBuilds 下,重跑一次即可装上。放行构建本身就是一次信任判断:请只安装可信来源,并尽量锁定 commit(github:owner/repo#sha)。
README
在 DSH 工作区里打开 Markdown 文件时,把其中的 ```mermaid 代码块实时渲染成图表;点击图表可放大预览。
这个插件做什么
- 在 Markdown 文件里渲染 mermaid:打开
.md/.markdown,文档里的 mermaid 代码块显示成 SVG 图表,其余 Markdown 仍由 DSH 内置渲染器渲染(标题、列表、表格、代码块等样式与原来完全一致)。 - 非破坏:它是「扩展优先」的文档渲染器,内置 Markdown 渲染器保留,可在预览工具栏切换回去。
- 点击放大预览:点图表打开全屏放大视图,支持缩放(− / + / 重置;键盘
+-0;Esc或点遮罩关闭)。 - 跟随主题:浅色/深色主题切换时图表自动按对应主题重绘。
对话流里 AI 回复中的 ```mermaid 由你已安装的
dsh-plugin-mermaid-preview负责,本插件不重复注册(避免冲突)。
使用方式
- 刷新 DSH 页面后,在右侧「文件」栏打开一个
.md文件。 - 文档里的 ```mermaid 代码块显示成图表。
- 点击图表 → 打开放大预览;底部工具栏或键盘缩放。
如何安装到 DSH
方式一:命令行直接安装(推荐)
仓库已包含构建好的 client.js,无需再构建:
dsh plugin add github:sangaizhi/dsh-plugin-mermaid-markdown
# 或指定 profile
dsh plugin --profile web add github:sangaizhi/dsh-plugin-mermaid-markdown
需要可复现的话,钉住提交:github:sangaizhi/dsh-plugin-mermaid-markdown#c8e4a9a。装完启用插件、刷新页面。
方式二:GUI 添加本地目录(先 clone)
git clone https://github.com/sangaizhi/dsh-plugin-mermaid-markdown.git
然后在 DSH 侧栏「插件」→「添加插件(Add plugin)」→ 输入克隆下来的目录路径(例如 .../dsh-plugin-mermaid-markdown),启用后刷新页面。
方式三:本地已有源码(开发)
进入插件目录构建一次,再安装:
pnpm install
node build.mjs # 产出 client.js
然后在「插件」→「添加插件」里输入该目录路径,启用后刷新页面。
更新已安装的插件
改了代码后重新构建,再刷新页面(client.js 会被重新加载):
node build.mjs
构建用 esbuild 把 mermaid、markdown-it 打进 client.js;react、react-dom、@deepseek-ai/dsh-client-ui-primitives 声明为外部依赖,运行时由 DSH 提供。
实现逻辑原理
1. 注册「扩展优先」的文档渲染器
文档预览是「按扩展名注册渲染器」的机制:
ctx.documentPreviews.register({ id, extensions: ['md', 'markdown'], priority: 'extension', loading: 'text-pages', ... })——priority: 'extension'让本渲染器排在builtin的内置 Markdown 渲染器之前,自动成为.md的默认渲染器,同时内置渲染器仍作为候选保留。ctx.slots.inject('sidebar.right.tab.document', () => ctx.slots.register({ key: DOCUMENT_ID }, MermaidMarkdownDocument))—— 把正文组件注册到按实现 id 分发的文档插槽。
这两个注册都通过 ctx.effect(...) 绑定插件生命周期,卸载即清理。inject 里声明了 documentPreviews、theme 等硬依赖,保证成员在 apply 时已经就绪。
2. 复用内置 MarkdownText,只接管 mermaid
为了不重做 Markdown 排版,正文组件把 Markdown 按 mermaid 围栏切成若干段:
splitMarkdownSegments用 markdown-it 解析 token,只识别闭合的```mermaid/```mmd围栏(未闭合的围栏留在 Markdown 里,流式时显示源码);- 非 mermaid 片段交给 DSH 内置的
<MarkdownText>渲染(标题/列表/代码块等样式完全一致); - mermaid 片段交给
<MermaidDiagram>渲染。
前置的 YAML frontmatter 由 splitFrontmatter 拆出,单独显示为元数据框。
3. mermaid 渲染核心
mermaid.js:initMermaid(colorScheme)一次性配置 mermaid(securityLevel: 'strict'自带消毒),renderMermaid(id, code)异步返回 SVG 字符串。MermaidDiagram.jsx:防抖后渲染,代码或主题变化时重绘;渲染失败回退为源码 + 错误提示,不会白屏。theme.js:一个极小的外部 store,plugin.js在apply时读取当前主题并监听theme/change,把明暗状态同步给所有图表。
4. 放大预览
MermaidZoomOverlay.jsx 用 createPortal 把全屏浮层挂到 document.body(避免被侧栏裁切),缩放 25%–800% 档位,关闭时恢复页面滚动。
5. 样式与打包
styles.js:以内联<style>注入插件样式(外层内边距、frontmatter 框、图表间距、放大浮层),颜色走--dsw-alias-*主题 token。build.mjs:用 esbuild 把源码打成 DSH 客户端要求的window.__ModuleLoader__.load({ id, factory })模块,react等外部依赖保留为require(...)。
目录结构
mermaid/
├─ package.json # 插件清单(bundle 补丁 + client 声明 + 构建脚本)
├─ cordis.patch.yml # 把插件插入 DSH 的 Loader 补丁
├─ index.js # Host 侧(空实现,渲染全在客户端)
├─ build.mjs # esbuild 打包脚本
├─ client.js # 构建产物(由 build.mjs 生成)
├─ icon.svg / locale/ # 插件图标与显示文案
├─ src/
│ ├─ plugin.js # 客户端 apply:注册渲染器/插槽/主题/样式
│ ├─ definition.js # 注册常量与文档渲染器定义
│ ├─ document.jsx # 文档正文组件(MarkdownText + mermaid)
│ ├─ markdown.js # 纯逻辑:frontmatter 拆分 + mermaid 分段
│ ├─ mermaid.js # mermaid 初始化与渲染
│ ├─ MermaidDiagram.jsx # 单张图:异步渲染 + 错误回退 + 点击放大
│ ├─ MermaidZoomOverlay.jsx # 全屏放大预览
│ └─ theme.js / styles.js # 主题 store / 插件样式
└─ test/ # node:test 纯逻辑单测
已知限制
- 只处理
.md/.markdown文件;独立.mmd文件与对话流交给已安装的dsh-plugin-mermaid-preview。 - 相对图片路径暂不解析(
会显示破图);绝对 URL 正常。 - 复用 DSH 内部
MarkdownText组件,将来 DSH 内部 API 变动时可能需要跟进。
卸载
侧栏「插件」→ 找到本插件 → 停用或卸载。
链接
同类插件
tt-a1i/archify#integrations/deepseek-harness★ 97127
从仓库或系统描述生成经过校验的自包含交互式架构图、流程图、时序图、数据流图和生命周期图。
dream-num/dsh-univer-office★ 728
为 DeepSeek Harness 打造一个真正的办公环境。Univer Office 插件将电子表格、文档、幻灯片、画布、多维表格等汇聚到同一个运行时——数据互联、修改经过校验、变更按版本管理,并以隔离工作树支持多 Agent 协作。
Roland0511/dsh-marktext★ 702
基于 MarkText 内核 muya 的右侧栏所见即所得 Markdown 编辑器:打开 .md 按渲染结果编辑,保存走 ctx.fs 并带版本守卫。
ECNU/EduWork#dsh-knowledge-studio★ 370
基于工作区资料的 Studio,复用 DSH 模型与共享成果服务,制作报告、演示文稿、表格、思维导图、测验、闪卡及音视频。Office 生成需 Python 3.12+ 及相关依赖,并配置 DSH_OFFICE_PYTHON;媒体渲染需 Chromium;本地语音转写另需 whisper.cpp 和模型。
PerryLink/dsh-industry-research★ 219
面向 DeepSeek Harness 的确定性行业研究报告:公司与行业研究流程基于分阶段证据产出结构化、可核验的报告。
joeseesun/qiaomu-ui-learn-dsh★ 85
浏览界面设计参考和交互标本,练习设计测验,并导出 Markdown 学习笔记。
社区评论
评论公开保存在 GitHub Discussions。加载评论会连接 GitHub 和 Giscus;发表内容需要 GitHub 账号。