前言¶

在 DeepSeek Harness（DSH）裏讓智能體畫圖，常見結果是 SVG 或 HTML 能渲染，但讀者第一眼不知道「該先看哪、結論是什麼」。Archify 一類工具把 JSON 規範接到確定性渲染和門禁上；diagram-design 提供版式與無障礙 SVG。二者都不保證頁面具備完整的「閱讀傢俱」——結論標題、要點、編號閱讀路徑、圖例與說明，並在發佈前被機器校驗。

readable-diagrams 把這一層補全：一份 JSON 規範 → 單文件 HTML，且必須通過結構/無障礙門禁與可讀性門禁，頁面才允許交付。下面介紹它作爲 DSH 工作流插件能做什麼、如何安裝，以及如何按倉庫示例復現渲染與檢查。

這是什麼¶

• 定位：Diagrams a reader understands on first look — one JSON spec to a self-contained HTML page, with a machine-checked comprehension gate。同時可作爲 Claude Code / Codex 的 skill 使用。
• 維護者：倉庫歸屬 bingomu/readable-diagrams；npm 包名爲 dsh-readable-diagrams，當前插件包版本 1.1.0（以 release 標籤安裝爲準）。
• 許可證：MIT；DSH 要求 >=0.2.0，插件 wrapper 需 Node 20+，渲染與門禁腳本需 Python 3.9+，無 npm 運行時依賴、無構建步驟。

社區目錄頁：skillhub.cn 插件條目。該目錄爲獨立社區站點，與 DeepSeek / 幻方無官方從屬關係；DSH 本身遵循「一切皆插件」的擴展方式。

核心功能¶

規範驅動的圖類型與擴展¶

倉庫說明中列出的能力包括：

• 九種 spec 驅動類型：architecture、flow、state、sequence、timeline、tree、layer stack、bar、quadrant。
• 手繪式圖表族：line、scatter、sankey、radar、heatmap、Gantt、Venn、funnel、journey 等，共用同一套版式與門禁。
• 導入 / 導出：Mermaid、draw.io、Excalidraw 導入；SVG、PNG 導出。

完整字段見倉庫內 skills/readable-diagrams/references/spec-schema.md。

兩道門禁（均需通過）¶

生成 HTML 後不得手改頁面；失敗則改 spec、重新渲染、再跑檢查。非零退出即失敗。

comprehension_check.py   title ≤60 · takeaway · caption · numbered reading path ·
                         legend coverage · ≤2 focal accents · node budget ·
                         edge-label coverage · type floors · contrast ·
                         orthogonal connectors · accessible SVG exists
self_check.py            role=img · title first · desc · prefixed ids ·
                         single-file safety · painted content inside viewBox

交互與版式¶

• 懸停高亮、無 JavaScript：懸停節點時其餘變暗、關聯邊高亮；懸停閱讀步驟可對應節點；支持錯峯入場；prefers-reduced-motion 與打印回退爲靜態幀。
• 編輯皮膚：明/暗主題，CJK 排版（12px 下限、中文標籤 register 切換），4px 網格，無陰影。
• 示例：skills/readable-diagrams/examples/ 下八個示例頁，均通過兩道門禁。

項目在 Archify（Apache-2.0）與 diagram-design（MIT）之上，額外定義「可讀性契約」並由 checker 強制執行；設計 token 與連接器語法自 diagram-design 改編並註明出處，見 THIRD_PARTY_NOTICES.md。

安裝與啓用¶

插件以當前 DSH 進程權限運行；安裝前請自行查看倉庫源碼與 MIT 許可證，確認可接受後再添加。

DeepSeek Harness 官方安裝方式（README Install 表）：

dsh plugin --profile desktop add https://github.com/bingomu/readable-diagrams/archive/refs/tags/v1.1.0.tar.gz

也可在 DSH 的 Plugins → Add 頁面填入同一 URL。重啓應用後，skill 會出現在會話目錄中。

其他宿主（非 DSH 正文重點，供對照）：Claude Code 可用 marketplace 或複製 skills/readable-diagrams/；Codex 可複製到 ~/.codex/skills/ 或使用 .codex-plugin/；通用 agent 可讀 SKILL.md 並執行 bash install.sh。

典型用法¶

安裝或取得倉庫內容後，skill 目錄爲 skills/readable-diagrams。下面步驟與 README Quick start 一致：先渲染示例 spec，再跑兩道門禁，最後在瀏覽器打開輸出。

SKILL=skills/readable-diagrams

python3 "$SKILL/scripts/render.py" "$SKILL/examples/architecture.spec.json" -o /tmp/page.html --json
python3 "$SKILL/scripts/self_check.py" /tmp/page.html
python3 "$SKILL/scripts/comprehension_check.py" /tmp/page.html

在本地用瀏覽器打開 /tmp/page.html 即可查看懸停層效果。

最小 spec 示例（architecture 類型，含 meta 與 reading_path）：

{
  "type": "architecture",
  "meta": {
    "title": "一次下單請求如何穿過網關到達數據庫",
    "takeaway": "寫路徑只有一條；風控與通知是旁路。",
    "caption": "從左往右是請求方向，實線同步、虛線異步。",
    "reading_path": ["client", "gateway", "orders", "pg"]
  },
  "nodes": [
    {"id": "client", "label": "客戶端", "kind": "input"},
    {"id": "gateway", "label": "API 網關", "kind": "backend"},
    {"id": "orders", "label": "訂單服務", "kind": "focal"},
    {"id": "pg", "label": "訂單庫", "kind": "store"}
  ],
  "edges": [
    {"from": "client", "to": "gateway", "label": "HTTPS", "variant": "accent"},
    {"from": "gateway", "to": "orders", "label": "POST /orders", "variant": "accent"},
    {"from": "orders", "to": "pg", "label": "寫入", "variant": "accent"}
  ]
}

智能體側操作說明見 skill 內 SKILL.md；貢獻者在 push 前可運行 python3 scripts/check.py（CI 同款：渲染全部 example、跑門禁、解析插件入口）。

適用場景與注意¶

適合：需要在文檔、設計評審或 agent 交付物裏輸出「讀者能按路徑讀完」的架構/流程類圖；希望用腳本門禁約束標題、對比度、正交連接器與 accent 預算，而不是事後人工改 HTML。

注意：

• 門禁失敗是正常反饋，應改 JSON spec 後重新 render.py，不要 patch 生成頁。
• 對比度、節點預算、圖例覆蓋等規則由 comprehension_check.py 與 self_check.py 具體實現；擴展 spec 前先讀 references/ 下說明。
• DSH 插件僅註冊 skill 與 bundle（lib/index.js、cordis.patch.yml）；實際渲染依賴本機 Python 3.9+ 環境。

結尾¶

readable-diagrams 把「人能讀懂」寫成可檢查的契約：一份 JSON、單文件 HTML、兩道 Python 門禁。作爲 DSH 工作流插件，它讓會話裏的製圖步驟有明確交付標準。

• 目錄頁：https://www.skillhub.cn/plugins/bingomu/readable-diagrams
• 源碼與文檔：https://github.com/bingomu/readable-diagrams