dsh-web-mermaid

Readme

<p align="center">
  <img src="logo.png" alt="dsh-web-mermaid logo" width="180" />
</p>

<h1 align="center">dsh-web-mermaid</h1>

<p align="center">
  <strong>把 DeepSeek Harness 聊天里的 Mermaid 代码块，离线渲染成 SVG 流程图的 Web 插件</strong>
</p>

<p align="center">
  <a href="https://github.com/demo007x/dsh-web-mermaid/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-blue" /></a>
  <img alt="mermaid" src="https://img.shields.io/badge/mermaid-11-blue" />
  <img alt="platform" src="https://img.shields.io/badge/DSH-web%20plugin-8250df" />
  <a href="https://github.com/demo007x/dsh-web-mermaid"><img alt="stars" src="https://img.shields.io/github/stars/demo007x/dsh-web-mermaid?style=social" /></a>
</p>

---

## ✨ 功能特性

- **离线渲染**：mermaid 运行时随插件内置，不依赖任何在线 CDN，断网也能用；
- **点击放大**：点击图片弹出「半透明遮罩 + 弹窗」，支持按钮缩放、鼠标左键自由拖拽平移、`Esc` / `×` 关闭；
- **代码 / 图片切换**：默认展示图片，一键切回源码视图；
- **源码语法高亮**：内置轻量 tokenizer，高亮关键字、注释、字符串、箭头连线、数字；
- **主题自适应**：跟随 DSH 浅色 / 深色主题自动重渲染；
- **全图表类型**：支持 flowchart / sequenceDiagram / classDiagram / stateDiagram / erDiagram / gantt / pie 等 mermaid 11 全部图表。

## 🚀 安装

通过 `dsh plugin` 安装到 web profile（会自动写入 `dsh.profile.bundles`），装完**重启 `dsh web`** 生效。

**从 GitHub 安装（推荐）**

```sh
dsh plugin --profile web add github:demo007x/dsh-web-mermaid
dsh web
```

**本地目录 / tarball**

```sh
# 本地目录
dsh plugin --profile web add file:/path/to/dsh-web-mermaid
dsh web

# 或打包成 tarball
cd /path/to/dsh-web-mermaid && pnpm pack
dsh plugin --profile web add ./dsh-web-mermaid-0.1.0.tgz
dsh web
```

卸载：

```sh
dsh plugin --profile web remove dsh-web-mermaid
dsh web
```

## 📖 使用

聊天里直接写 mermaid 代码块：

````markdown
```mermaid
flowchart TD
    A[开始] --> B{是否通过?}
    B -- 是 --> C[结束]
    B -- 否 --> D[重试]
    D --> B
```
````

插件会把代码块渲染成流程图，并提供三个操作（位于代码块横幅 / 图片上）：

- **代码 / 图片切换**：默认展示图片，点按钮在图片与源码之间切换；
- **点击放大**：点图片（或「放大」按钮）打开遮罩弹窗，按钮缩放 + 鼠标左键拖拽平移；
- **源码高亮**：切到「代码」视图查看带语法高亮的 mermaid 源码（「复制」按钮仍可用）。

## ⚙️ 原理

DSH Web 前端的 Markdown 渲染器没有 Mermaid 语法高亮，因此 ` ```mermaid ` 代码块会
被当作普通代码块渲染成 `div.md-code-block`（其横幅显示语言标签 `mermaid`，正文是
`<pre><code>` 源码）。本插件在浏览器里：

1. 观察页面 DOM，找到已经落定的 `mermaid` 代码块（流式输出期间语言标签尚未附加，
   只有回合结束后才会出现，因此不会去渲染未完成的图）；
2. 用 mermaid 把源码渲染成 SVG；
3. 默认用 SVG 展示图片，同时把源码 `<pre>` 隐藏但保留在 DOM 里（「复制」按钮和
   「代码」切换都依赖它）；
4. 在代码块横幅上加「代码 / 图片」切换按钮和「放大」按钮；
5. 用内置的轻量 tokenizer 对 mermaid 源码做语法高亮；
6. 点击图片 /「放大」按钮时，在半透明遮罩上弹出有边界的弹窗，克隆 SVG 并用按钮
   缩放（缩小 / 放大 / 重置）与鼠标左键拖拽平移；拖拽用 transform 平移 + 边界钳制
   （图片不会被完全拖出视野），点遮罩、`Esc` 或 `×` 关闭；
7. 跟随 Web 应用的浅色 / 深色主题自动重渲染（监听 `body[data-ds-dark-theme]`）。

## 📁 目录结构

```
dsh-web-mermaid/
├── package.json          # dsh.bundle（host 侧插入）+ dsh.client（浏览器侧）
├── cordis.patch.yml      # 把本包作为 loader 条目插入 profile
├── index.js              # host（node）半部
├── src/client.js         # 浏览器半部源码（DOM 观察 + mermaid 渲染 + 放大灯箱）
├── build.mjs             # esbuild 打包脚本（产出 lib/client.js）
├── lib/client.js         # 构建产物（被 /plugins/dsh-web-mermaid/client.js 提供）
├── logo.svg / logo.png   # 项目 Logo
└── test/render.test.mjs  # jsdom 冒烟测试
```

## 🧪 开发

```sh
pnpm install
pnpm run build     # 生成 lib/client.js
pnpm test          # jsdom 冒烟测试（验证 bundle 注册 + 渲染管线）
```

## ⚠️ 已知限制

- 渲染发生在客户端（浏览器内），大图可能占用一定内存；错误图会保留源码并显示一行
  渲染失败提示。
- 主题通过「重渲染」适配，切换主题时页面内已渲染的图会重新生成。
- SVG 以 inline 方式注入（非 `<img>`），因此节点点击等交互事件默认未绑定（本插件
  面向静态流程展示）。

## 📄 License

[MIT](./LICENSE) © demo007x