@erzhe-lume

dsh-tool-diagram

Name: dsh-tool-diagram
Availability: InStock
Author: erzhe-lume

DiagramKit — 结构化示意图的排版量尺与自检器：量真实字宽、查溢出/重叠/穿框，每次调用返回「图 + 可执行的修法」。DeepSeek Harness 插件。

Stars: 1
Language: JavaScript
Created: Oct 16, 2026
Updated: Oct 16, 2026

Theme

GitHub repo

Introduction

DiagramKit · dsh-tool-diagram

给 DeepSeek Harness (DSH) 用的结构化示意图插件：量准字宽、验准布局，每条问题连修法一起报回来。

English — A DeepSeek Harness plugin for drawing structured diagrams from a declarative spec. It measures real font metrics (parses the TTF tables itself), checks your hand-placed layout for overflow / overlap / edges crossing boxes / label collisions, and returns the image plus a report where every issue carries an actionable fix. 13 primitives, ~80 ms per diagram at 300 dpi. Covers flowcharts, N-S & PAD diagrams, DFD, E-R, UML use-case & class diagrams, decision trees, fault trees, org charts.

用例图

类图	数据流图	事故树

它解决什么问题

让 agent 画示意图，最费时间的不是"画"，是不知道画对没有：框够不够宽？标签压没压线？箭头穿框了吗？只能渲染出来、盯着看、再改——一轮四步。

DiagramKit 把这一轮压成一次调用：给你图，同时也给你一份结构化报告，每条问题都带修法。

自检发现 1 个错误：
  [error] text_clipped  node=cond lines=3 textH=1.06 boxInnerH=0.54 over=0.52
      → 「A+B>C 且 A+C>B 且 B+C>A ?」被折成 3 行、需要 1.42cm 高，但框只有 0.9cm。
        把框高加到 1.42cm（或宽加到 3.46cm 让它一行放得下），或字号降到 4pt

照着改坐标就行，多数轮次不必再看图。

它不是自动排版引擎。 N-S 图的递归划分、PAD 图的左侧主线，这些布局是学科要求，不该由算法替你决定。所以：at 给了就绝对定位，工具只负责量准和验准。

功能

三个工具

工具	做什么
`diagram_create`	按 spec 画图，返回「内联图 + 自检报告 + 画布尺寸」
`diagram_patch`	增量改图：`move` / `moveby` / `resize` / `set` / `add` / `remove` / `canvas`，不重发整个 spec
`diagram_measure`	只测量与自检，不渲染——想知道"这行字放不放得下"时用它，最便宜的一档

排版量尺：真解析字体，不靠估

自己解析 TTF/OTF 的 head / hhea / hmtx / cmap 四张表取 advance width，零依赖。

这件事在中文里有个容易翻车的地方：“”（）《》，。 这些看着"小"的符号其实是全角 1 em。把 输出“等边三角形” 里的弯引号当半角估，会少算 0.56 cm（22%）——框就装不下了。

顺带还有：

中文折行 + 禁则——不会让一行以 ，。、）】 这类收尾标点开头
自动尺寸——不给 size 就按文字宽高加内边距算，也可以给 minSize 兜底
缺字检测——字体里没有的字符当场报 glyph_missing，而不是渲染出一堆方框

自检：10 类问题，每条都带修法

类型	级别	查什么
`text_overflow`	error	文字比框宽（含不可断行的长串）
`text_clipped`	error	折行后高度装不下
`node_overlap`	error	两个框叠在一起，并给出该挪多少
`edge_through_node`	error	连线穿过第三个框
`outside_canvas`	error	元素超出画布，并给出画布该放多大
`glyph_missing`	error	字体缺字形
`label_collision`	warn	标签互相压、或压住框里的文字
`label_on_edge`	warn	标签压在连线上
`edge_end_on_text`	warn	箭头落点压住框内文字或编号
`near_miss`	warn	两个框贴得比 0.15 cm 还近
`edge_cross`	info	连线交叉数（只统计，不一定要改）

级别语义：error 一定难看/一定错；warn 能看但会扣分；info 供参考。

13 种图元

shape	画出来是什么	典型用途
`rect`	直角矩形	外部实体、E-R 实体、PAD 处理框
`round_rect`	圆角矩形	DFD 加工
`store`	开口矩形，编号在缺口外	数据存储
`ellipse`	椭圆	UML 用例、E-R 属性
`diamond`	菱形	E-R 联系
`actor`	火柴人，名字在下方	UML 参与者
`class_box`	三分栏类框（`\n---\n` 分隔各栏）	UML 类图
`and_gate` / `or_gate`	与门（下平上半圆）/ 或门（上圆下收尖）	事故树 FTA
`box_span`	无边框，只占位和排文字	N-S 图的"条件带""T/F 标记带"
`line_h` / `line_v`	单根线段	N-S 图的分区线、PAD 图的主线
`chevron`	分支符 `<`	PAD 图的条件分支

后四种是专为 N-S 图和 PAD 图加的。这两种图本质上不是"框 + 箭头"，而是"一块区域被反复切分"，没有对应图元就只能退回写代码。

这些元素可以用 "structural": true 标成"版面骨架"——它们天然与别的元素共边、贴靠，不参与重叠判定（否则 N-S 图会被报几十条"重叠"）。

连线：四档精确度，从"随便连"到"我说了算"

手段	效果
什么都不给	两端自动求交，斜线
`fromSide` / `toSide`	从指定边进出，自动夹在边内 → 得到水平/垂直线
`fromPoint` / `toPoint`	锚点写死，最精确
`waypoints`	整条折线自己给，工具完全不路由
`labelAt`	`auto` / `above` / `below` / `left` / `right` / `[x, y]` 手工定位

输出

一切以厘米为单位，画布尺寸直接就是 Word 插图的尺寸，不用再做 px→cm 换算
PNG（默认 300 dpi，可调到 600）+ SVG
既可内联返回（图直接进对话），也可落盘到指定路径
支持 containers：系统边界框、泳道这类外框

安装

cd $env:USERPROFILE\.dsh\profiles\desktop
pnpm add github:erzhe-lume/dsh-tool-diagram

然后把 "dsh-tool-diagram" 加进同一个 package.json 的 dsh.profile.bundles 数组，重启 dsh：

"dsh": { "profile": { "bundles": [
  "@deepseek-ai/dsh-base",
  "@deepseek-ai/dsh-web-app",
  "dshmarket",
  "dsh-tool-diagram"          // ← 加这一行
] } }

首次安装会看到 [ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: sharp@0.34.0——可以忽略。 pnpm 11 默认拦下依赖的安装脚本，而 sharp 的原生二进制走 optionalDependencies，不依赖它。想消掉警告执行 pnpm approve-builds。

本包自带组合包声明（dsh.bundle.patch），所以不需要动 profile 的 cordis.patch.yml。想改默认参数的话，在那里写同 id 的行即可覆盖：

- id: tool-diagram
  name: dsh-tool-diagram
  config:
    dpi: 300
    maxDpi: 600
    maxDiagrams: 32

不装 DSH 也能用

命令行入口是现成的，画图、导出、自检都不依赖 DSH：

node lib/cli.js examples\usecase.json --out usecase.png --dpi 300   # 画图 + 报告
node lib/cli.js examples\broken.json --measure                      # 只测量
node lib/cli.js examples\lib-dfd-l1.json --patch examples\patch-labels.json --out out.png
node lib/cli.js examples\usecase.json --out a.png --svg             # 顺带导出 SVG

快速上手

一个最小例子——画两个加工和一个数据存储：

{
  "canvas": { "w_cm": 12.0, "h_cm": 5.0 },
  "nodes": [
    { "id": "p1", "shape": "round_rect", "num": "1", "text": "读卡与验证密码",
      "at": [3.0, 1.4], "size": [3.4, 1.1] },
    { "id": "p2", "shape": "round_rect", "num": "2", "text": "取款处理",
      "at": [8.6, 1.4], "size": [3.0, 1.1] },
    { "id": "db", "shape": "store", "num": "D1", "text": "中央数据库",
      "at": [6.0, 3.9], "size": [4.0, 0.85] }
  ],
  "edges": [
    { "id": "e1", "from": "p1", "to": "p2", "arrow": "open", "label": "验证通过" },
    { "id": "e2", "from": "p1", "to": "db", "arrow": "both", "label": "读 / 写" }
  ]
}

画布 12.00 × 5.00 cm；节点 3，边 2，连线交叉 0
自检通过：没有发现问题。
用时 84ms
PNG → usecase.png  (1417×591px @ 300dpi, 33.8KB)

同时拿到内联的图、sizeCm: [12.0, 5.0]（Word 里直接按这个宽度插）、以及后续 diagram_patch / diagram_measure 要用的 diagramId。

改图不用重画——按报告的建议打补丁：

[
  { "op": "move",   "node": "db", "to": [6.0, 4.2] },
  { "op": "resize", "node": "p2", "size": [3.4, 1.1] },
  { "op": "set",    "edge": "e2", "label": "读 / 写", "labelAt": "left" }
]

spec 速查

{
  "canvas": { "w_cm": 15.6, "h_cm": 8.3 },   // 可省，省了按内容算
  "style":  { "preset": "se-textbook" },      // se-textbook | uml | dfd
  "nodes": [
    { "id": "uc1", "shape": "ellipse", "text": "验证用户身份",
      "at": [7.8, 3.35],        // 中心点（厘米）；给了就绝对定位
      "size": [5.0, 1.8],       // 可省，省了按文字算
      "num": "1",               // 编号（DFD 加工 / D1 数据存储）
      "textAlign": "left",      // left/right 时 at 变成锚点而不是中心
      "fontPt": 8, "paddingCm": 0.18 }
  ],
  "edges": [
    { "id": "e1", "from": "a1", "to": "uc1", "arrow": "none" },
    { "id": "e2", "from": "uc1", "to": "uc2", "arrow": "open", "dash": true,
      "label": "<<include>>", "labelAt": "right" }
  ],
  "containers": [
    { "id": "g1", "text": "图书管理系统登录模块", "at": [7.8, 6.4], "size": [10.4, 6.0],
      "labelPos": "top_left" }
  ]
}

样式预设

preset	效果
`se-textbook`	黑体 8pt / 标注 7pt / 线宽 1.2pt / 白底黑线——软件工程教材插图风格
`uml`	同上，用例与参与者名字字号略调
`dfd`	加工圆角与存储缺口按 DFD 惯例

字体走文件路径（默认 C:/Windows/Fonts/simhei.ttf），可以换成任意 TTF/OTF/TTC。

适用范围

档	图种
开箱即用	程序流程图、N-S 图、PAD 图、判定树、分层 DFD、E-R 图、UML 用例图/类图/状态图/活动图、系统架构图、部署图、组织架构图、WBS、业务流程图、泳道图、事故树、事件树、临床路径图、诉讼流程图、知识点结构图…
加一两个图元	UML 时序图（要生命线 + 时间轴）、甘特图（时间轴）、思维导图（放射布局）、数据结构指针图、鱼骨图
不适合	数据可视化（折线/柱状/散点/热力——它们的正确性在数据里，不在布局里）、电路原理图、机械制图、建筑平立剖、地图、解剖图、信息图

判断标准有三条，同时满足才值得用：① 离散元素 + 关系连线；② 有容器/层级； ③ 正确性判据是"连对没有、摆开没有"，而不是"画得像不像实物"。

顺带一提：它只对中文做了折行与禁则优化（这是它的主场景）；纯英文排版也能用，但换行规则按空格断词，没有连字符断词。

License

MIT