前言¶

在 DSH 插件場景裏，架構說明、流程說明、時序說明常常需要從代碼倉庫裏整理出來，再交給團隊查看和分享。dsh-archify 提供的是一個 agent 技能：用 JSON 規格生成架構圖、流程圖、時序圖、數據流圖與生命週期圖，並輸出獨立 HTML。

它的做法是先形成規格文件，再執行校驗和交付。下面介紹它的功能、安裝方式、典型用法和注意事項。

該插件由 GongYuanCaiJi 維護，許可證爲 MIT。它移植自 tt-a1i/archify v2.14.0；官方 DSH 包 @tt-a1i/archify-dsh@0.1.0 與它同源同版本。技能本體 archify/ 與 examples/ 逐字保留，只適配了 dsh 的打包與命名。

定位¶

• 輸入：JSON 規格，一個 JSON 規格對應一種圖型。
• 輸出：獨立 HTML，也支持 PNG、SVG、WebM，以及 1200×630 分享卡片。
• 驗收：提交前跑 validate，確定性校驗給出 9 項驗收（showcase）或基礎驗收（standard）。
• 主題：支持深淺主題；視覺預設包括 classic（默認）、signal-flow、blueprint、editorial。

核心功能¶

五種圖型：

architecture
workflow
sequence
dataflow
lifecycle

每個 JSON 規格對應其中一種圖型。

可驗證交付：

validate
showcase: 9 項驗收
standard: 基礎驗收

提交前跑 validate，用確定性校驗給出驗收結果。

多格式導出：

HTML
PNG
SVG
WebM
1200×630 分享卡片

Mermaid 輸入：

flowchart
sequenceDiagram
stateDiagram

粘貼 Mermaid 內容後，可轉爲 Archify JSON，再進行美化。

架構對比：

compare
Before / Delta / After

compare 兩份快照，輸出 Before / Delta / After 三態 HTML。

安裝與啓用¶

先確認環境要求：

Node.js: ^22.19.0 || >=24.0.0
dsh: 0.1.0-rc.6

確認環境後，從 GitHub 安裝：

dsh plugin --profile <你的 profile> add github:GongYuanCaiJi/dsh-archify

安裝時會通過 prepare 腳本把 archify/ 暫存爲 skills/。如果 pnpm 攔下構建步驟，在 profile 的 pnpm-workspace.yaml 裏把本包加進 allowBuilds，再重跑一次：

pnpm-workspace.yaml -> allowBuilds 中加入 dsh-archify

從本地目錄安裝時，先克隆並安裝依賴，再交給 dsh 添加：

git clone https://github.com/GongYuanCaiJi/dsh-archify.git
cd dsh-archify && npm install
dsh plugin --profile <你的 profile> add ../dsh-archify

這裏的 npm install 用於觸發 prepare 腳本，把技能文件暫存到 skills/。

典型用法¶

讓 agent 按名字加載技能：

Use the archify skill to map this repository's runtime architecture.

如果希望得到更完整的交付要求，可以給出這段提示：

Show 8–12 core components, one primary path, external dependencies, and trust boundaries.
Put supporting detail in cards instead of adding more edges.
After delivery, return the exact workspace paths of the specification JSON and the HTML artifact.

一個示例流程是先寫 runtime.architecture.json，再執行校驗和交付：

node bin/archify.mjs validate architecture runtime.architecture.json --quality showcase
node bin/archify.mjs deliver architecture runtime.architecture.json runtime.html --quality showcase

經過上面的步驟後，交付 runtime.html。

產物打開注意¶

shell 命令生成的文件不會自動出現在 Web 端的 Produced Files 欄。

需要讓 agent 返回規格 JSON 與 HTML 工件的精確工作區路徑，再從工作區打開。上游官方 DSH 包同樣如此。

安全與許可¶

安全姿態：

• 無遙測
• 無網絡客戶端
• 無憑據處理
• 無後臺服務
• 沒有 install / postinstall / preinstall 生命週期鉤子，僅 prepare 用於暫存技能文件

許可證爲 MIT。

上游 tt-a1i/archify 的版權爲：

Copyright (c) 2026 tt-a1i (Archify)
Copyright (c) 2025 Cocoon AI

本移植的版權爲：

Copyright (c) 2026 GongYuanCaiJi (dsh port)

插件以當前 dsh 進程權限運行。安裝前應檢查源碼與許可證。

包信息與測試限制¶

包信息如下：

version: 0.1.0
type: module
main: ./lib/index.js
engines.node: ^22.19.0 || >=24.0.0
dsh.bundle.patch: ./cordis.patch.yml

測試限制：scripts/run-skill-tests.mjs 會跳過 19 個無法在移植倉庫運行的技能測試，包括：

• 18 個綁定上游倉庫根目錄網站/發佈文件的測試
• 1 個依賴 ajv devDependency 的 generate-validators.test.mjs

卸載¶

卸載命令：

dsh plugin --profile <你的 profile> remove dsh-archify

鏈接¶

GitHub 倉庫：

https://github.com/GongYuanCaiJi/dsh-archify

如需從目錄頁查找，請在當前使用的 DSH 插件目錄中搜索：

dsh-archify