ascii-visualizer

ASCII 可视化工具

为架构、工作流、文件树和数据可视化绘制一致、易读的 ASCII 图表。所有输出都能在等宽字体终端中正确显示，无需外部工具。

**核心原则：**将信息编码到结构中，而非装饰中。图表中的每个元素都应传达有意义的信息。

制表符绘图字符参考

此区块有意将多组字符放在一起作为图例。作者 应在每个实际图表中只使用一组；single-set lint 规则会在 生产图表中强制执行此要求。

default:   ┌─┐ │ └─┘  ├─┤ ┬ ┴ ┼
emphasis:  ┏━┓ ┃ ┗━┛  ┣━┫ ┳ ┻ ╋
title:     ╔═╗ ║ ╚═╝  ╠═╣ ╦ ╩ ╬
soft:      ╭─╮ │ ╰─╯
portable:  +-+ | +-+  +-+ + + +
Arrows:    → ← ↑ ↓ ─> <─ ──> <──
Blocks:    █ ▓ ░ ▏▎▍▌▋▊▉
Status:    ● ○ ✓ ✗ ⚠ ◆ ◇ ▶ ▷  ↑↓→ ▓▒░  (closed-set vocab — see rules)

字符集约定（D8：按意图命名）

Token 存放在 tokens.json 中。名称描述用途，而非外观。

字符集	字符	用途
default ─│	普通框和连接线	大多数图表
emphasis ━┃	标题、焦点，吸引视线	关键组件、外框
title ═║	文档标题	仅限 §0 风格的横幅
soft ╭╮╰╯ ─│	状态卡片、环境 UI	差异区块
portable +-|	NO_COLOR / CI / 裸 TTY	回退方案

重命名 codemod（D8）：旧名称 light/heavy/double/rounded/ascii-fallback → 上述新名称。旧名称会继续接受一个次要版本发布周期，并附带警告。

状态符号词汇表

v1 版包含 11 个语义符号（●○✓✗⚠◆◇▶▷ ↑↓→ ▓▒░）。唯一可信来源——参见 rules/status-glyph-vocabulary.md。添加符号的流程见 CONTRIBUTING.md。

图表模式

架构图

┌──────────────┐      ┌──────────────┐
│   Frontend   │─────>│   Backend    │
│   React 19   │      │   FastAPI    │
└──────────────┘      └───────┬──────┘
                              │
                              v
                      ┌──────────────┐
                      │  PostgreSQL  │
                      └──────────────┘

带注释的文件树

src/
├── api/
│   ├── routes.py          [M] +45 -12    !! high-traffic path
│   └── schemas.py         [M] +20 -5
├── services/
│   └── billing.py         [A] +180       ** new file
└── tests/
    └── test_billing.py    [A] +120       ** new file

Legend: [A]dd [M]odify [D]elete  !! Risk  ** New

进度条

[████████░░] 80% Complete
+ Design    (2 days)
+ Backend   (5 days)
~ Frontend  (3 days)
- Testing   (pending)

泳道图 / 时间线图

Backend  ===[Schema]======[API]===========================[Deploy]====>
                |            |                                ^
                |            +------blocks------+             |
                |                               |             |
Frontend ------[Wait]--------[Components]=======[Integration]=+

=== Active work   --- Blocked/waiting   | Dependency

影响范围（同心圆）

            Ring 3: Tests (8 files)
       +-------------------------------+
       |    Ring 2: Transitive (5)      |
       |   +------------------------+   |
       |   |  Ring 1: Direct (3)     |   |
       |   |   +--------------+      |   |
       |   |   | CHANGED FILE |      |   |
       |   |   +--------------+      |   |
       |   +------------------------+   |
       +-------------------------------+

对比表

BEFORE                          AFTER
┌────────────┐                  ┌────────────┐
│  Monolith  │                  │  Service A │──┐
│  (all-in-1)│                  └────────────┘  │  ┌──────────┐
└────────────┘                  ┌────────────┐  ├─>│  Shared  │
                                │  Service B │──┘  │  Queue   │
                                └────────────┘     └──────────┘

可逆性时间线

Phase 1  [================]  FULLY REVERSIBLE    (add column)
Phase 2  [================]  FULLY REVERSIBLE    (new endpoint)
Phase 3  [============....]  PARTIALLY           (backfill)
              --- POINT OF NO RETURN ---
Phase 4  [........????????]  IRREVERSIBLE        (drop column)

关键规则

规则	描述
字体	始终使用等宽字体——制表符绘图字符需要固定宽度
粗细	普通内容使用标准线条，强调内容使用粗线，标题使用双线
箭头	使用 ─>、──>，或使用带 v/^ 表示方向的 │
对齐	在标签右侧补空格，使其与列宽匹配
注释	用 !! 表示风险，用 ** 表示新增，用 [A/M/D] 表示变更类型
宽度	保持在 80 个字符以内，以兼容终端
嵌套	框嵌套最多 3 层，超过后可读性会下降

各模式的适用场景

模式	使用场景
分层框	系统架构、部署拓扑
同心圆	影响范围、影响分析
时间线条	可逆性、迁移阶段
泳道	执行顺序、并行工作流
带注释的树	文件变更清单、目录结构
对比表	跨层一致性、变更前后对比
进度条	状态跟踪、完成度指标

相关技能

• brainstorm — 通过图表传达想法的设计探索
• architecture-patterns — 适合使用 ASCII 图表的系统架构
• code-review-playbook — 带内嵌图表的评审评论