前言¶

在 DSH 里做架构梳理时，最常见的动作是把一段类结构讲清楚：有哪些类、哪些依赖、继承关系怎么连。现有做法通常要把模型导出到绘图工具里手摆，或者让智能体直接贴一段 Mermaid/PlantUML 代码。前者脱离代码库，后者依赖渲染环境，而且每次结果都不一定稳定。

下面介绍的插件换了一条路径：它不解析源码，而是接收一份 spec.json，输出一个自包含的 HTML 文件，图是内联 SVG 的，支持缩放、主题切换和悬停高亮。插件注册的是文件系统技能 uml-class，实际工作由技能内的 CLI 完成，不添加原生工具、不发起网络请求。

这是什么¶

插件全名 @areaartez51/dsh-uml-class，由 areaartez51 维护，社区目录里归到「客户端」分类。它的定位是一个 skill-only bundle（纯技能包），把 UML 类图的渲染能力挂到 DSH 的技能目录里，让智能体可以自己抽取、生成和校验类图。

它解决的是「类结构 → 可交互图」这一步：输入结构化描述，产出单一 HTML 文件，而不是让智能体在聊天里拼一段无法复现的文本图。

核心功能¶

1. 从一份 spec.json 生成一个独立的 HTML 文件，SVG 内联，没有外部资源依赖。
2. 图页支持缩放、主题切换、节点展开，悬停时高亮对应关系连线。
3. 支持六种关系：inheritance、realization、dependency、association、composition、aggregation，每种有独立端点符号（空心三角、虚线、菱形等）。
4. 支持包（packages）分组，可以用 --package-by auto 让工具按目录或 namespace 自动归组。
5. 除 class 图外，风格化输出还可生成收据文件 <name>.receipt.json，记录工具版本、artifact 的 sha256、类和关系的数量及告警。
6. 布局是确定性的：同一 spec 跑两次，得到的 HTML 逐字节相同。

需要明确边界：插件不解析源码。spec.json 需要人或智能体先读过代码再填写。

安装与启用¶

官方推荐从 GitHub Release 安装，不需要 npm 账号：

dsh plugin --profile desktop add https://github.com/areaartez51/dsh-uml-class/releases/download/v0.20.3/areaartez51-dsh-uml-class-0.20.3.tgz

如果已经有本地归档，可以直接从文件安装：

dsh plugin --profile desktop add C:\path\to\areaartez51-dsh-uml-class-0.20.3.tgz

想从源码自己打归档也可以，在仓库根目录执行 npm pack，会得到 areaartez51-dsh-uml-class-0.20.3.tgz（35 个文件），再用上面的本地归档命令安装。

装完重启一次 DSH，技能 uml-class 就会出现在 desktop profile 的技能目录里。卸载命令如下：

dsh plugin --profile desktop remove @areaartez51/dsh-uml-class

需要 Node.js 版本满足 ^22.19.0 || >=24.0.0（见 package.json 的 engines 字段）。插件是 MIT 许可。

典型用法：从 C# 项目抽取¶

在 C# 项目里，抽取规格这一环可以自动化。进入技能目录后依次执行三条命令：

cd skills/uml-class
node bin/uml.mjs extract csharp /path/to/Assets/Scripts --out spec.json --stats
node bin/uml.mjs render class spec.json out/classes.html
node bin/uml.mjs check out/classes.html

第一步 extract 扫描源码目录生成 spec.json，--stats 输出统计信息。第二步 render class 把规格渲染成 HTML。第三步 check 对产物做一次校验。

几个常用开关：

• --package-by auto：当整个项目只有一个 namespace 时按文件夹分组，否则按 namespace 分组。
• --include / --exclude：接受 glob 模式，用来收窄扫描范围。
• --calls：补充方法内部调用产生的依赖。
• --no-fields / --no-deps：去掉字段依赖、参数依赖这两类连线。

典型用法：直接手写规格¶

非 C# 项目，或者想手动画一张图时，先写一份 spec，然后 validate、render、check：

cd skills/uml-class
node bin/uml.mjs validate examples/payments.json
node bin/uml.mjs render class examples/payments.json out/payments.html
node bin/uml.mjs check out/payments.html

规格的 schema 在 skills/uml-class/schemas/class.schema.json，附带的样例是 skills/uml-class/examples/payments.json。结构大致如下：

{
  "schemaVersion": 1,
  "title": "Модуль оплаты",
  "classes": [
    { "id": "order-service", "name": "OrderService", "fields": ["- repo: OrderRepository"],
      "constructors": ["+ OrderService(repo: OrderRepository)"],
      "methods": ["+ place(order: Order): Receipt"] }
  ],
  "relations": [
    { "from": "order-service", "to": "payment-provider", "kind": "dependency",
      "label": "charge(card, amount)" }
  ],
  "packages": [
    { "id": "commerce", "label": "module: commerce", "classes": ["order-service"] }
  ]
}

字段要点：classes 里用 - 表示私有、+ 表示公开，relation 的 kind 决定端点样式，packages 做分组。渲染时会在 HTML 旁边生成一份 payments.receipt.json，便于校验产物是否被动过。

工作原理¶

渲染链路拆成了几个模块，职责清晰：

1. renderers/model.mjs：解析 JSON 并做校验，错误路径形如 relations[0].to。
2. renderers/layout.mjs：计算层级，继承向下排，同层用重心法排序，坐标是确定性的。
3. renderers/routing.mjs：画正交连线，同层邻居绕过行，相近层级走间隙，远层级寻找空闲竖向通道。
4. renderers/svg.mjs + html.mjs：产出 SVG 和自包含页面。

因为坐标全部由算法决定而非随机，所以两次渲染结果逐字节一致。展开某个节点时其余节点不位移，只有被展开的节点变大，连线重新绘制。

退出码¶

命令行退出码固定，便于智能体判断上次调用是否成功：

• 0：成功。
• 1：规格错误、输入输出错误或校验失败。
• 2：类超过 800 个。
• 3：参数错误。

测试¶

npm test        # node --test --test-isolation=none "skills/uml-class/tests/*.test.mjs"

--test-isolation=none 是必须的：DSH 的沙箱禁止派生子进程，测试只能在同一个进程里跑。测试不启动浏览器，覆盖布局、相邻节点对称性、确定性和外部资源缺失这几项。

适用场景与注意¶

适合的使用场景：已经在代码库里理清了类结构，需要把这份结构固化成可交互的产物；或者在做技术债梳理、模块依赖盘点时，想快速拿到一张可缩放、可高亮的图。

需要注意的地方：

1. 插件以当前 DSH 进程的权限运行。安装前应先检查源码与许可证，确认命令、参数和文件写入路径符合预期。
2. 它不做源码解析，spec.json 必须由人或智能体先读代码再生成，工具默认的 extract 只覆盖 C#。
3. 不支持 PNG/SVG 文件导出，只产出 HTML。
4. 不支持类与自身的关系。
5. 完整 UML（模板、{...} 约束、对象图）不在范围内。
6. 类数量上限 800，超出会以退出码 2 失败。

另外补充一句生态背景：DSH 的理念是「一切皆插件」，上面提到的社区目录是独立站点，与 DeepSeek / 幻方没有官方从属关系，不要把它当作官方应用商店。

结尾¶

这个插件的价值在一个很窄的切口上：把「JSON 规格 → 交互式类图」做成确定性的、不依赖浏览器和网络的本地产出。如果你已经在用 DSH 整理架构，装一条命令，技能 uml-class 就能用；如果要画的图超出它声明的边界，就需要自己评估是否够用。

目录页：https://www.skillhub.cn/plugins/areaartez51/dsh-uml-class
GitHub：https://github.com/areaartez51/dsh-uml-class