Back to Details

ascii-diagram-validator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ASCII Diagram Validator

ASCII图表验证工具

Validate and fix alignment issues in ASCII box-drawing diagrams commonly used in architecture documentation, README files, and code comments.
验证并修复架构文档、README文件和代码注释中常用的ASCII框绘图表的对齐问题。

Overview

概述

ASCII diagrams using box-drawing characters (─│┌┐└┘├┤┬┴┼ and double-line variants ═║╔╗╚╝╠╣╦╩╬) require precise column alignment. This skill provides:
  1. Validation script - Detects misaligned characters with file:line:column locations
  2. Actionable fixes - Specific suggestions for correcting each issue
  3. Multi-file support - Validate individual files or entire directories
使用框绘字符（─│┌┐└┘├┤┬┴┼ 以及双线变体 ═║╔╗╚╝╠╣╦╩╬）的ASCII图表需要精确的列对齐。本工具提供：
  1. 验证脚本 - 检测错位字符并给出文件:行:列位置
  2. 可执行修复建议 - 针对每个问题的具体修正建议
  3. 多文件支持 - 验证单个文件或整个目录

When to Use This Skill

使用场景

Invoke when:
  • Creating or editing ASCII architecture diagrams in markdown
  • Reviewing documentation with box-drawing diagrams
  • Fixing "diagram looks wrong" complaints
  • Before committing docs/ARCHITECTURE.md or similar files
  • When user mentions "ASCII alignment", "diagram alignment", or "box drawing"
在以下场景调用本工具：
  • 在Markdown中创建或编辑ASCII架构图表时
  • 审核包含框绘图表的文档时
  • 解决“图表显示异常”的问题时
  • 提交docs/ARCHITECTURE.md或类似文件之前
  • 当用户提及“ASCII对齐”、“图表对齐”或“框绘字符”时

Supported Characters

支持的字符

Single-Line Box Drawing

单线框绘字符

Corners: ┌ ┐ └ ┘
Lines:   ─ │
T-joins: ├ ┤ ┬ ┴
Cross:   ┼
Corners: ┌ ┐ └ ┘
Lines:   ─ │
T-joins: ├ ┤ ┬ ┴
Cross:   ┼

Double-Line Box Drawing

双线框绘字符

Corners: ╔ ╗ ╚ ╝
Lines:   ═ ║
T-joins: ╠ ╣ ╦ ╩
Cross:   ╬
Corners: ╔ ╗ ╚ ╝
Lines:   ═ ║
T-joins: ╠ ╣ ╦ ╩
Cross:   ╬

Mixed (Double-Single)

混合（双-单线）

╞ ╟ ╤ ╧ ╪ ╫
╞ ╟ ╤ ╧ ╪ ╫

Quick Start

快速开始

Validate a Single File

验证单个文件

bash
/usr/bin/env bash << 'PREFLIGHT_EOF'
uv run ${CLAUDE_PLUGIN_ROOT}/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py docs/ARCHITECTURE.md
PREFLIGHT_EOF
bash
/usr/bin/env bash << 'PREFLIGHT_EOF'
uv run ${CLAUDE_PLUGIN_ROOT}/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py docs/ARCHITECTURE.md
PREFLIGHT_EOF

Validate Multiple Files

验证多个文件

bash
/usr/bin/env bash << 'PREFLIGHT_EOF_2'
uv run ${CLAUDE_PLUGIN_ROOT}/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py docs/*.md
PREFLIGHT_EOF_2
bash
/usr/bin/env bash << 'PREFLIGHT_EOF_2'
uv run ${CLAUDE_PLUGIN_ROOT}/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py docs/*.md
PREFLIGHT_EOF_2

Validate Directory

验证目录

bash
/usr/bin/env bash << 'PREFLIGHT_EOF_3'
uv run ${CLAUDE_PLUGIN_ROOT}/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py docs/
PREFLIGHT_EOF_3
bash
/usr/bin/env bash << 'PREFLIGHT_EOF_3'
uv run ${CLAUDE_PLUGIN_ROOT}/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py docs/
PREFLIGHT_EOF_3

Output Format

输出格式

The script outputs issues in a compiler-like format for easy navigation:
docs/ARCHITECTURE.md:45:12: error: vertical connector '│' at column 12 has no matching character above
  → Suggestion: Add '│', '├', '┤', '┬', or '┼' at line 44, column 12

docs/ARCHITECTURE.md:67:8: warning: horizontal line '─' at column 8 has no terminator
  → Suggestion: Add '┐', '┘', '┤', '┴', or '┼' to close the line
脚本以类编译器的格式输出问题，便于导航：
docs/ARCHITECTURE.md:45:12: error: vertical connector '│' at column 12 has no matching character above
  → Suggestion: Add '│', '├', '┤', '┬', or '┼' at line 44, column 12

docs/ARCHITECTURE.md:67:8: warning: horizontal line '─' at column 8 has no terminator
  → Suggestion: Add '┐', '┘', '┤', '┴', or '┼' to close the line

Severity Levels

严重级别

LevelDescription
errorBroken connections, misaligned verticals
warningUnterminated lines, potential issues
infoStyle suggestions (optional cleanup)
级别描述
error连接断裂、垂直对齐错位
warning未终止的线条、潜在问题
info样式建议（可选清理）

Validation Rules

验证规则

The script checks for:
  1. Vertical Alignment - Vertical connectors (│║) must align with characters above/below
  2. Corner Connections - Corners (┌┐└┘╔╗╚╝) must connect properly to adjacent lines
  3. Junction Validity - T-joins and crosses must have correct incoming/outgoing connections
  4. Line Continuity - Horizontal lines (─═) should terminate at valid endpoints
  5. Box Closure - Boxes should be properly closed (no dangling edges)
脚本检查以下内容：
  1. 垂直对齐 - 垂直连接器（│║）必须与上下字符对齐
  2. 边角连接 - 边角字符（┌┐└┘╔╗╚╝）必须与相邻线条正确连接
  3. 连接点有效性 - T型连接和交叉点必须有正确的进出连接
  4. 线条连续性 - 水平线（─═）应在有效端点终止
  5. 闭合性 - 框体应正确闭合（无悬空边缘）

Exit Codes

退出码

CodeMeaning
0No issues found
1Errors detected
2Warnings only (errors ignored with --warn-only)
代码含义
0未发现问题
1检测到错误
2仅存在警告（使用--warn-only标志时忽略错误）

Integration with Claude Code

与Claude Code集成

When Claude Code creates or edits ASCII diagrams:
  1. Run the validator script on the file
  2. Review any errors in the output
  3. Apply suggested fixes
  4. Re-run until clean
当Claude Code创建或编辑ASCII图表时：
  1. 在文件上运行验证脚本
  2. 查看输出中的错误
  3. 应用建议的修复
  4. 重新运行直到无问题

Example Workflow

示例工作流

bash
/usr/bin/env bash << 'PREFLIGHT_EOF_4'
bash
/usr/bin/env bash << 'PREFLIGHT_EOF_4'

After editing docs/ARCHITECTURE.md

After editing docs/ARCHITECTURE.md

uv run ${CLAUDE_PLUGIN_ROOT}/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py docs/ARCHITECTURE.md
uv run ${CLAUDE_PLUGIN_ROOT}/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py docs/ARCHITECTURE.md

If errors found, Claude Code can read the output and fix:

If errors found, Claude Code can read the output and fix:

docs/ARCHITECTURE.md:45:12: error: vertical connector '│' at column 12 has no matching character above

docs/ARCHITECTURE.md:45:12: error: vertical connector '│' at column 12 has no matching character above

→ Edit line 44, column 12 to add the missing connector

→ Edit line 44, column 12 to add the missing connector

PREFLIGHT_EOF_4
undefined
PREFLIGHT_EOF_4
undefined

Limitations

局限性

  • Detects structural alignment issues, not aesthetic spacing
  • Requires consistent use of box-drawing characters (no mixed ASCII like +---+)
  • Tab characters may cause false positives (convert to spaces first)
  • Unicode normalization not performed (use pre-composed characters)
  • 检测结构对齐问题，不检查美观间距
  • 需要一致使用框绘字符（不支持+---+这类混合ASCII格式）
  • 制表符可能导致误报（先转换为空格）
  • 不执行Unicode归一化（使用预组合字符）

Bundled Scripts

捆绑脚本

ScriptPurpose
scripts/check_ascii_alignment.py
Main validation script
脚本用途
scripts/check_ascii_alignment.py
主验证脚本

Related

相关链接

Troubleshooting

故障排除

IssueCauseSolution
Script not foundPlugin not installedVerify plugin installed with 
claude plugin list
False positives with tabsTab characters misalignConvert tabs to spaces before validation
Mixed ASCII not detectedUsing 
+---+
style		Script only validates Unicode box-drawing chars
Column numbers offUnicode width calculationUse pre-composed characters, avoid combining marks
No issues but looks wrongAesthetic spacing not checkedValidator checks structure, not visual spacing
Exit code 2 unexpectedwarnings only modeUse --warn-only flag to treat warnings as success
Can't find validation errorComplex nested diagramCheck line numbers in output, validate section only
Unicode chars not renderingTerminal font missing glyphsUse font with full Unicode box-drawing support
问题原因解决方案
脚本未找到插件未安装使用
claude plugin list
验证插件是否已安装
制表符导致误报制表符错位验证前将制表符转换为空格
混合ASCII未被检测到使用
+---+
样式		脚本仅验证Unicode框绘字符
列号不正确Unicode宽度计算问题使用预组合字符，避免组合标记
无问题但显示异常未检查美观间距验证器仅检查结构，不检查视觉间距
意外返回退出码2仅警告模式使用--warn-only标志将警告视为成功
找不到验证错误复杂嵌套图表查看输出中的行号，仅验证对应部分
Unicode字符未渲染终端字体缺少字形使用支持完整Unicode框绘字符的字体