Community影像github.com

unicode-diagrams

使用Unicode方框繪圖字元(┌─┐ │ └─┘ ░ 陰影)繪製架構、系統設計和流程圖,而非純ASCII。當要求文字圖表、ASCII或方框繪圖圖表,或設計文件和README中的圖表時使用。

unicode-diagrams 是什麼?

Unicode Diagrams 是一項 AI 智能體技能,旨在通過 Unicode 方框繪圖字元生成精確、對齊的文字圖表,適用於 Claude Code、Cursor 和 Codex 等平台。它使用 Python 腳本和 `textdiagram.py` 引擎自動化創建架構、系統設計和流程圖,確保每次生成一致且無錯的佈局。此技能強制執行特定樣式規則,如全大寫文字、80 列預設寬度、以及用於元件(含陰影)、標題(雙線)和框架的獨特邊框類型,以保持專業外觀。它支持水平、垂直、彎曲和匯流排箭頭、多段文字、行內標籤以及填充或空心箭頭,完整記錄在 API 中。通過生成 Python 腳本而非手動繪圖,該技能減少了在維護清晰文本圖表(這是版本控制友好的)時的對齊錯誤。這使得它對於需要在不依賴外部圖表工具的情況下快速嵌入 SVG 或圖像的 README、RFC 和內部文件的開發人員來說至關重要。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/rohalrafael/unicode-diagrams/tree/HEAD

Installed? Explore more 影像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Unicode 圖表

使用 Unicode 方框繪圖字元以一種統一的樣式繪製純文字圖表。 始終使用下面的 textdiagram.py 網格引擎構建圖表。不要手動繪製: 手動繪製的圖表會偏離對齊。

樣式規則

  • 在圍欄程式碼區塊中的純文字。沒有 Mermaid、SVG、圖像或表情符號。
  • 寬度:預設為 80 列。要更改,請將 max_width 傳遞給建構函式, 例如 D(max_width=100)。引擎會在更長的行上引發錯誤。
  • **所有文字均為大寫。**引擎會為您處理:在腳本中編寫正常文字。 例外:大小寫會改變意義的單位保持原樣,當您這樣寫時: Hz kHz MHz GHz、kB MB GB TB KiB MiB GiB TiB、 kb Mb Gb Tb kbps Mbps Gbps、ms µs ns。其他單詞,例如 NGINX 或 K8S,會變為大寫。
  • COMPONENT 方框(系統的一部分:服務、客戶端、資料庫、佇列、工作者): 細線 ┌─┐ │ └─┘ 加上一個細 ░ 陰影,向右一列,向下一行。 要對部分進行分組,將一個方框拆分為多個區段:細分隔線 ├───┤、一個框架、一個陰影。
  • TITLE 方框(文件的主標題,每個圖表一個):雙線 ╔═╗ ║ ╚═╝,無陰影。 每行一個項目(名稱、文件類型、版本),每個項目在方框中居中。使用 d.header(...) 製作:引擎將方框居中於整個圖表上方。可選:左側一個元資料方框 (公司、RFC、日期)和右側一個印章方框(狀態)。三個方框高度相同; 標題方框的填充行包含一個居中點 ·。 沒有箭頭可以在標題方框處開始或結束。
  • FRAME 方框(區段標題、備註、呼叫):細線,無陰影。 備註/呼叫:將名稱放在頂部邊框上,如 ┌─ 備註 ───┐。 不要添加圖例:每個圖表中的樣式都相同。
  • 自由文字(d.annotate):沒有方框的簡短說明,在圖表旁邊。很少使用。 線條不得穿過它。
  • 水平箭頭:標籤在線條內,兩側各一個空格:── HTTPS ──▶。 兩端都接觸方框:線條從發送方框的陰影列開始,箭頭頭部接觸接收方框。
  • 垂直箭頭:線條從底部邊框的 ┬ 開始,以 ▼ 結束。標籤位於 線條右側,陰影下方一行。或將標籤切入線條中 (inline=True):線條、空白行、標籤行居中於線條上、空白行、線條。
  • 彎曲箭頭(d.route):任意數量的彎曲,任意方向(▲ ▼ ◀ ▶)。標籤位於 橫向段內,或位於(或者,使用 inline=True,切入)向上/向下段旁邊。 交叉或連接的線條形成一個交點(┼ ├ ┤ ┬ ┴)。線條永遠不會穿過方框。
  • 匯流排(d.fan_out):從一個方框出發的一條線,分成每個目標一個箭頭。 標籤位於共用線條上。
  • 箭頭頭部:填充 ▶ ◀ ▲ ▼ 用於主要流程。空心 ▷ ◁ △ ▽ 用於第二種 關係(非同步、可選、事件)。僅在圖表需要兩種時使用空心, 並在標籤或備註中命名其含義,不要在圖例中。
  • 用流經的內容(協議、事件、資料)標記每個箭頭。
  • 如果不清楚方框的角色:系統部分使用 COMPONENT,主標題使用 TITLE, 其他所有內容使用 FRAME。

工作流程

  1. 在繪製之前列出元件、框架和箭頭。
  2. 將引擎寫入 /tmp/textdiagram/textdiagram.py(完整原始碼在此文件末尾, 準確複製)。每次會話都重新寫入,這樣就不會使用舊版本。
  3. 寫一個簡短的 Python 腳本,匯入引擎並構建圖表。使用 佈局輔助函數放置方框(不要猜測座標):
    • Diagram.x_right_of(a, label) — 用於下一個方框在 a 右側的 x,預留箭頭標籤的空間。
    • Diagram.x_left_of(a, lines, label) — 用於新方框在 a 左側的 x,預留標籤空間。
    • Diagram.y_below(a) — 用於方框在 a 下方的 y。使用內聯標籤:Diagram.y_below(a, lines=N)。
    • Diagram.x_centered_under(a, lines) — 用於方框居中於 a 下方的 x(需要 arrow_v)。
    • 對於路線通道,使用方框的邊緣:a.right + 4、a.bottom + 2。
  4. 運行它。如果引發 DiagramError,按照訊息修復佈局並再次運行。
  5. 將輸出完全按照原樣貼上到程式碼區塊中。不要手動編輯。 要進行更改,請編輯腳本並再次運行。

範例 1:標題、區段、路線

import sys; sys.path.insert(0, "/tmp/textdiagram")
from textdiagram import Diagram as D

d = D()                                                   # max_width=80 是預設值
t = d.header(["Order Platform", "Architecture"],
             left=["Acme Inc", "RFC 9000", "Nov 2026"],
             right=["*~~~~~~~~~*", "Deep Dive", "*~~~~~~~~~*"])
y = t.bottom + 2
cli = d.box(0, y, ["Client"])                             # role="component" 是預設值
gw = d.box(D.x_right_of(cli, "HTTPS"), y, ["Gateway"])
d.arrow_h(cli, gw, "HTTPS")
svc = d.box(gw.x + 16, D.y_below(gw) + 2,                 # 區段:一個方框,一個陰影
            [["Auth"], ["Orders"], ["Billing"]], title="Services")
d.route(gw, "bottom", svc, "top", via=[gw.bottom + 3], label="Calls")  # S 形
cache = d.box(D.x_left_of(svc, ["Cache"], "Reads"), svc.rows[1] - 1, ["Cache"])
d.arrow_h(svc, cache, "Reads", row=svc.rows[1])           # 附加到一個區段
aud = d.box(svc.right + 9, y, ["Audit"])
d.route(svc, "right", aud, "bottom", a_row=svc.rows[0], label="Events")  # 一個彎曲
d.route(svc, "right", cli, "bottom", a_row=svc.rows[2],   # 循環:3 個彎曲
        via=[svc.right + 4, svc.bottom + 2], label="Retry")
print(d.render())

輸出:

┌────────────┐               ╔══════════════════╗            ┌───────────────┐
│  ACME INC  │               ║  ORDER PLATFORM  ║            │  *~~~~~~~~~*  │
│  RFC 9000  │               ║   ARCHITECTURE   ║            │   DEEP DIVE   │
│  NOV 2026  │               ║        ·         ║            │  *~~~~~~~~~*  │
└────────────┘               ╚══════════════════╝            └───────────────┘

┌──────────┐            ┌───────────┐                             ┌─────────┐
│  CLIENT  │── HTTPS ──▶│  GATEWAY  │░                            │  AUDIT  │░
└──────────┘░           └─────┬─────┘░                            └─────────┘░
 ░░░░░▲░░░░░░            ░░░░░│░░░░░░░                             ░░░░▲░░░░░░
      │                       │                                        │
      │                       │                                        │
      │                       └───── CALLS ─────┐                      │
      │                                         │                      │
      │                                         ▼                      │
      │                                 ┌─ SERVICES ────┐              │
      │                                 │  AUTH         │─── EVENTS ───┘
      │          ┌─────────┐            ├───────────────┤░
      │          │  CACHE  │◀─ READS ───│  ORDERS       │░
      │          └─────────┘░           ├───────────────┤░
      │           ░░░░░░░░░░░           │  BILLING      │────┐
      │                                 └───────────────┘░   │
      │                                  ░░░░░░░░░░░░░░░░░   │
      │                                                      │
      └─────────────────────── RETRY ────────────────────────┘

範例 2:匯流排、空心頭部、內聯標籤、自由文字

import sys; sys.path.insert(0, "/tmp/textdiagram")
from textdiagram import Diagram as D

d = D()
t = d.header(["Event Bus", "Design"], left=["Acme Inc", "ADR 12", "Nov 2026"],
             right=["*~~~~~~~*", "Draft", "*~~~~~~~*"])
y = t.bottom + 4
pub = d.box(0, y, ["Publisher"])
s1 = d.box(36, y - 2, ["Billing"])
s2 = d.box(36, y + 4, ["Audit"])
s3 = d.box(36, y + 10, ["Search"])
d.fan_out(pub, [s1, s2, s3], trunk=28, label="Events", head="hollow")  # 匯流排,空心頭部
arc = d.box(D.x_centered_under(pub, ["Archive"]), D.y_below(pub, lines=2), ["Archive"])
d.arrow_v(pub, arc, "Nightly\nbackup", inline=True)       # 標籤切入線條中
d.annotate(46, y + 16, ["At-least-once", "delivery"])     # 自由文字,無方框
print(d.render())

輸出:

┌────────────┐        ╔═════════════╗       ┌─────────────┐
│  ACME INC  │        ║  EVENT BUS  ║       │  *~~~~~~~*  │
│  ADR 12    │        ║    DESIGN   ║       │    DRAFT    │
│  NOV 2026  │        ║      ·      ║       │  *~~~~~~~*  │
└────────────┘        ╚═════════════╝       └─────────────┘

                                    ┌───────────┐
                            ┌──────▷│  BILLING  │░
┌─────────────┐             │       └───────────┘░
│  PUBLISHER  │── EVENTS ───┤        ░░░░░░░░░░░░░
└──────┬──────┘░            │
 ░░░░░░│░░░░░░░░            │
                            │       ┌─────────┐
    NIGHTLY                 ├──────▷│  AUDIT  │░
    BACKUP                  │       └─────────┘░
                            │        ░░░░░░░░░░░
       │                    │
       ▼                    │
 ┌───────────┐              │       ┌──────────┐
 │  ARCHIVE  │░             └──────▷│  SEARCH  │░
 └───────────┘░                     └──────────┘░
  ░░░░░░░░░░░░░                      ░░░░░░░░░░░░


                                              AT-LEAST-ONCE
                                              DELIVERY

API 參考

  • D(max_width=80) — 建立一個圖表;max_width 是列限制。
  • d.box(x, y, lines, role="component"|"frame"|"title", title=None, w=None, align="left") → Box (.x .y .w .h .right .bottom .cx .rows;right/bottom 包含陰影)。 lines 是一個行列表,或一個區段列表(行列表)以拆分方框。 box.rows 保存每個區段的箭頭行。align="center" 居中文字。
  • d.header(title, left=None, right=None, y=0) → 標題 Box。每個參數是一個行列表。 方框在渲染時獲得最終的 x。每個圖表一個標題。
  • d.arrow_h(a, b, label="", row=None, head="filled") — a 和 b 並排;雙向工作。 row 選擇一個區段行 (a.rows[i])。head 是 "filled" 或 "hollow"。
  • d.arrow_v(a, b, label="", head="filled", inline=False) — b 在 a 下方,居中於它之下。 標籤可以有多行("\n")。使用 inline=True 時,使用 Diagram.y_below(a, lines=N) 預留空間。
  • d.route(a, a_side, b, b_side, via=(), label="", label_seg=None, a_row=None, b_row=None, head="filled", inline=False) — a_side 和 b_side 是 "left" "right" "top" "bottom"。線條從 a 的 a_side 離開並進入 b 的 b_side。它有 len(via) + 2 個段,這些段交替橫向和上下,從 離開 a_side 的方向開始。每個 via 值是一個中間段的通道: 上下段用 x,橫向段用 y。via=[] 是一個彎曲,一個值是 兩個彎曲(S 或 U 形),兩個值是三個彎曲(循環)。a_row / b_row 選擇 一個區段行。label_seg 選擇承載標籤的段(從 0 開始)。
  • d.fan_out(a, targets, trunk, a_side="right", b_side="left", label="", head="filled", a_row=None, inline=False) — 一個匯流排。trunk 是共用線條的通道:用於左/右側的 x,用於頂/底部的 y。
  • d.arrow_elbow(a, b, label="", mode="vh"|"hv", head="filled") — 一個彎曲,route 的簡短形式。 vh:離開 a 的底部,轉入 b 的側面。hv:離開 a 的側面, 轉下進入 b 的頂部。方向跟隨 b 的位置。
  • d.annotate(x, y, lines, align="left") → Box(角色 "text")— 自由文字,大寫。 lines 是一個字串("\n" 開始新行)或一個列表。
  • d.text(x, y, s) — 原始文字(不大寫)。
  • d.render() — 返回圖表;放置標題;檢查寬度和寬字元。
  • 引擎在重疊、間隙過小、通道值錯誤或行超過最大寬度時引發 DiagramError。

如果沒有可用的 shell

使用相同的規則手動繪製。然後計算每行的列數並檢查: 右側陰影在方框右側一列;底部陰影行從方框左邊緣右側一列開始 並在陰影列結束;所有方框邊緣對齊。

引擎原始碼:textdiagram.py

"""textdiagram: 在字元網格上繪製對齊的 Unicode 方框圖表。

樣式:
  所有文字均為大寫,除了 KEEP 中的單位。
  COMPONENT 方框:細線 + 向右一列、向下一行的細陰影 (░)。
  TITLE 方框:雙線,無陰影,居中於圖表上方(渲染時放置)。
  FRAME 方框:細線,無陰影(備註,呼叫)。
  標題:標題方框帶可選左側元資料方框和右側印章方框;
  標題方框的填充行包含一個居中點。
  區段:一個方框由細分隔線拆分,整個方框一個陰影。
  水平箭頭:標籤在線條內,兩端都接觸方框:── 標籤 ──▶
  垂直箭頭:標籤在線條右側,陰影下方一行。
  路線:具有任意數量彎曲的箭頭,由通道座標 (via) 設置。
  頭部:填充 (▶) 或空心 (▷)。fan_out:一條線分成多個箭頭。
  向上/向下線上的標籤:在線條旁邊,或切入其中 (inline=True)。
  annotate:無方框的自由文字。
"""
import re
import unicodedata

SHADOW = "░"
MIN_DASH = 2  # 箭頭標籤兩側的短劃線數
HEADER_GAP = 2  # 標題方框之間的列

# 大小寫會改變意義的單位(MB = 位元組,Mb = 位元,ms = 毫秒,MS = 百萬)。
# 一個單詞僅當其完全像其中之一書寫時才被保留。
KEEP = {
    "Hz", "kHz", "MHz", "GHz",
    "kB", "MB", "GB", "TB", "KiB", "MiB", "GiB", "TiB",
    "kb", "Mb", "Gb", "Tb", "kbps", "Mbps", "Gbps",
    "ms", "µs", "ns",
}

# 方框繪圖字元作為臂集合:當兩條箭頭線相遇時,
# 臂被連接到一個交點字元 (┼, ├, ...)。
ARMS = {"─": "LR", "│": "UD", "┌": "RD", "┐": "LD", "└": "RU", "┘": "LU",
        "├": "UDR", "┤": "UDL", "┬": "LRD", "┴": "LRU", "┼": "UDLR"}
BY_ARMS = {frozenset(v): 

…

[為翻譯進行了截斷]

相關技能