前言¶

在 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