Community图像github.com

unicode-diagrams

绘制架构、系统设计和流程图,使用Unicode框线绘制字符(┌─┐ │ └─┘ ░阴影),而非纯ASCII。适用于需要文本图表、ASCII或框线图,或设计文档/README中的图表场景。

unicode-diagrams 是什么?

该技能提供了一种用Unicode框线字符绘制纯文本图表的方法,专为开发者和AI代理设计,用于在代码块中创建架构、系统设计和流程图。它内置了`textdiagram.py`网格引擎,自动处理大写转换、阴影和箭头对齐,确保图表保持对齐并符合统一的风格规则。支持多个平台,如Claude Code、Cursor和Codex,强调使用文本引擎而非手工绘制,以避免错位。该技能包含详细的API参考,支持组件框、标题框、框架、自由文本、水平/垂直/弯曲箭头、总线(fan-out)等,并具有示例和输出格式,用于设计文档、README或任何需要文本图表的场景。它强制使用80列宽度、全大写文本(除非是特定单位),并通过`DiagramError`捕获重叠、间距过小或行超宽等问题。

兼容平台~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)均为大写。
  • 组件框(系统的一部分:服务、客户端、数据库、队列、工作者): 细线 ┌─┐ │ └─┘ 加上一个细 ░ 阴影,位于右侧一列和下方一行。 为了对部件进行分组,将一个框拆分为多个部分:细分隔线 ├───┤,一个边框,一个阴影。
  • 标题框(文档的主标题,每个图表一个):双线 ╔═╗ ║ ╚═╝,无阴影。 每行一项(名称、文档类型、版本),每行在框内居中。使用 d.header(...) 创建:引擎会将框在整个图表上居中。可选:左侧的元框(公司、RFC、日期)和右侧的印章框(状态)。三者高度相同;标题框的填充行包含一个居中点 ·。 箭头不能始于或止于标题框。
  • 框架框(节标题、注释、标注):细线,无阴影。 注释/标注:将名称放在顶部边框,如 ┌─ 注释 ───┐。 请勿添加图例:每个图表的风格都相同。
  • 自由文本(d.annotate):图表旁边的简短说明,无框。请谨慎使用。线条不得穿过它。
  • 水平箭头:标签在线条内部,两侧各一个空格:── HTTPS ──▶。 两端均接触框:线条始于发送框的阴影列,箭头头部接触接收框。
  • 垂直箭头:线条从底部边框的 ┬ 开始,以 ▼ 结束。标签放在线条右侧,位于阴影下方一行。或者将标签切入线条内部(inline=True):线条、空白行、标签行在线条上居中、空白行、线条。
  • 弯曲箭头(d.route):任意数量的弯曲,任意方向(▲ ▼ ◀ ▶)。标签放在一个水平段内部,或者放在垂直段的旁边(或者,使用 inline=True,切入垂直段)。交叉或汇合的线条形成连接点(┼ ├ ┤ ┬ ┴)。线条永远不会穿过框。
  • 总线(d.fan_out):从一个框出发的一条线,分散为指向每个目标的箭头。标签放在共享线上。
  • 箭头头部:实心 ▶ ◀ ▲ ▼ 用于主流。空心 ▷ ◁ △ ▽ 用于第二种关系(异步、可选、事件)。仅当图表需要两种类型时才使用空心,并在标签或注释中说明其含义,不要在单独的图例中说明。
  • 为每个箭头标记流经的内容(协议、事件、数据)。
  • 如果不清楚某个框的角色:系统部件用组件框,主标题用标题框,其他所有用框架框。

工作流程

  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) — 侧面为 "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 中的单位除外。
  组件框:细线 + 细阴影(░),位于右侧一列、下方一行。
  标题框:双线,无阴影,在图表上居中(在渲染时放置)。
  框架框:细线,无阴影(注释、标注)。
  标题:标题框,带有可选的元框(左侧)和印章框(右侧);
  标题框的填充行包含一个居中点。
  节:一个框由细分隔线拆分,整个框有一个阴影。
  水平箭头:标签在线条内部,两端均接触框:── 标签 ──▶
  垂直箭头:标签位于线条右侧,位于阴影下方一行。
  路由:具有任意数量弯曲的箭头,由通道坐标(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): 

…

[已截断以进行翻译]

相关技能