# dsh-tool-mermaid

> 仓库名 `dsh-plugin-mermaid`，npm 包名 `dsh-tool-mermaid`。

DeepSeek Harness (dsh) 插件：提供一个 **`mermaid_render`** 工具，让 agent 把 Mermaid 图源码渲染成 SVG 图片。

完全在进程内完成（mermaid 11 + jsdom），**不需要浏览器、不需要联网**。

## 它解决什么问题

dsh 目前没有 Mermaid 渲染工具。模型的回答里只能贴 Mermaid 源码，用户看不到图。
装上这个插件后，agent 写完图会调用 `mermaid_render`，拿到一张可直接嵌进回答的
`data:image/svg+xml` 图片（以及原始 SVG 文本）。

## 工具：`mermaid_render`

| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `code` | string | 是 | Mermaid 图源码（flowchart / sequenceDiagram / classDiagram / pie / stateDiagram / erDiagram ...） |
| `title` | string | 否 | 图的标题，会带进返回结果 |

**返回**（canonical value）：

```json
{
  "format": "svg",
  "title": "可选标题",
  "svg": "<svg ...>...</svg>",
  "width": 127,
  "height": 77,
  "url": "http://127.0.0.1:3080/dsh-mermaid/m1.svg",
  "dataUri": "data:image/svg+xml;base64,..."
}
```

`width`/`height` 来自最终 viewBox（像素）。`url` 是 dsh Web 服务器托管的
绝对 http 地址（Web 聊天的 markdown 渲染器只显示 http(s) 图片，模型把这张
图嵌进回答后用户就能直接看到）；无 Web 服务器时（headless 运行）`url` 缺失，
用 `dataUri` 作为兜底。渲染失败时工具以 `isError` 返回，错误消息包含 Mermaid
解析器给出的行号和期望 token，方便模型自己修图重试。

**模型看到的内容**（render）：一行摘要 + 可嵌入回答的图片
（优先 `![title](<url>)`，无 url 时退回 data URI）+ 原始 SVG（便于保存到文件）。

## 安装

插件是标准 dsh bundle（npm 包 + `dsh.bundle` 声明 + `cordis.patch.yml` 配置层）。
构建产物在 `lib/`（TypeScript 源码在 `src/`），`prepare` 脚本会从源码构建。

### 从 GitHub 安装（推荐）

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

> pnpm ≥10 默认拒绝执行 git 依赖的 `prepare` 构建脚本。首次 `add` 失败时，
> 把 pnpm 提示的包 key 加入 profile 的 `pnpm-workspace.yaml` 的
> `allowBuilds` 一节（参考本仓库 README 的 dsh-side-panel 示例），再重试 `add`。
> 只对源码可信的包授权，并可用 `#<commit>` 锁定版本。

### 从本地目录安装

```sh
git clone git@github.com:sijidoubi/dsh-plugin-mermaid.git
cd dsh-plugin-mermaid
pnpm install   # 运行 prepare，构建 lib/
dsh plugin --profile web add .
dsh web
```

### 卸载

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

## 配置

bundle 默认启用以下配置（可在 profile 的 `cordis.patch.yml` 覆盖整行）：

```yaml
- insert:
    - id: tool-mermaid
      name: dsh-tool-mermaid
      config:
        theme: default        # default | dark | neutral | forest
        securityLevel: strict # strict(默认,消毒标签内 HTML) | loose(原样渲染)
```

## 开发

```sh
pnpm install
pnpm run build          # tsc → lib/(类型声明 + JS 产物)
pnpm test               # node --test 渲染管线单元测试(无需 dsh 运行时)
node demo/run-demo.mjs  # E2E: 用真实 dsh 服务链(SystemPrompt + ToolRuntime)
                        # 挂载本插件, 走 ctx.tools.execute() 完整工具管道
```

## 工作原理与已知限制

- **渲染管线**：mermaid 11 在 Node 里需要 DOM；插件用 jsdom 提供，并补上
  jsdom 缺失的 SVG 文本测量（`getBBox`/`getComputedTextLength`）和 HTML 标签
  测量（`getBoundingClientRect`）。宽度按**逐字符宽度模型**估算（CJK/全角/
  emoji 约 1em，拉丁约 0.5em），高度按行数 × 1.5 行高估算，因此中英文混合
  与多行标签都能装进方框；极端字体下仍可能与浏览器真实渲染有轻微出入。
- **已实测的图类型**：`flowchart`、`sequenceDiagram`、`classDiagram`、`pie`
  渲染正常。强依赖浏览器交互/Canvas 的类型（如部分 `mindmap`/`gantt` 交互）
  可能渲染不完美或报错——遇到时模型应改用已支持的图类型。
- **进程副作用**：首次渲染时会在宿主 Node 进程安装一组 jsdom DOM 全局
  （`window`/`document` 等）。对 dsh 宿主是安全的，但与其它也设置 DOM 全局的
  库同时使用时需注意。
- **串行渲染**：渲染共享 mermaid 模块的全局状态，工具默认排他执行
  （未声明 `isConcurrencySafe`），同一时刻只跑一次渲染。
- **图片显示**：Web 聊天的 markdown 渲染器只显示绝对 http(s) 图片。插件在
  存在 `webServer` 服务时注册 `/dsh-mermaid/<id>.svg` 前缀路由，把每个渲染
  结果发布为 http URL；SVG 保存在进程内存（上限 100 张，超出淘汰最旧），
  **dsh 重启后旧 URL 会 404**，属预期行为——重启后模型会重新渲染。无 Web
  服务器（headless）时退回 `dataUri`，但此类环境没有聊天界面可显示。

> 🔍 配套推荐：搭配 [`dsh-image-zoom`](https://github.com/sijidoubi/dsh-image-zoom) 使用，点击渲染出的图片即可原地放大查看细节。

## License

MIT