mcpField
A
ascii-diagram-validator

ascii-diagram-validator

github.com/terrylica文档处理1214 次安装1 天前更新
代码仓库

关于 ascii-diagram-validator

用于检查和修复 Unicode 框线字符 ASCII 图表对齐问题的技能，面向编写或审阅架构文档的开发者。脚本支持单文件、多文件和目录，并提供具体问题位置与修正建议。

主要功能

  1. 01检测垂直对齐与连接问题
  2. 02检查角点、交叉点和线段
  3. 03报告文件、行与列位置
  4. 04为问题提供修复建议
  5. 05支持文件和目录批量检查

适用场景

  1. 01提交架构文档前检查图表
  2. 02修复 README 中的框线图
  3. 03审阅代码注释里的结构图

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/terrylica/cc-skills --skill ascii-diagram-validator

安装后在 Claude Code 中输入/ascii-diagram-validator确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
evolution-log.md
INTEGRATION_GUIDE.md
SCRIPT_DESIGN_REPORT.md
scripts/
check_ascii_alignment.py

详细介绍

ASCII 图表验证器

验证并修复架构文档、README 文件和代码注释中常见的 ASCII 框线图表对齐问题。

自我演进技能：此技能会在使用过程中不断改进。如果指令有误、参数发生偏移，或需要采用变通方法，请立即修复此文件，不要拖延。仅针对真实、可复现的问题进行更新。

概述

使用框线字符（─│┌┐└┘├┤┬┴┼ 和双线变体 ═║╔╗╚╝╠╣╦╩╬）绘制的 ASCII 图表要求列精确对齐。此技能提供：

  1. 验证脚本 - 检测未对齐字符并标出文件、行号和列号
  2. 可操作的修复建议 - 提供修正每个问题的具体建议
  3. 多文件支持 - 验证单个文件或整个目录

何时使用此技能

在以下情况调用：

  • 在 Markdown 中创建或编辑 ASCII 架构图表
  • 审阅包含框线图表的文档
  • 修复“图表看起来不对”的问题反馈
  • 提交 docs/ARCHITECTURE.md 或类似文件之前
  • 用户提到“ASCII 对齐”“图表对齐”或“框线绘制”时

支持的字符

单线框线字符
Corners: ┌ ┐ └ ┘
Lines:   ─ │
T-joins: ├ ┤ ┬ ┴
Cross:   ┼
双线框线字符
Corners: ╔ ╗ ╚ ╝
Lines:   ═ ║
T-joins: ╠ ╣ ╦ ╩
Cross:   ╬
混合（双线-单线）
╞ ╟ ╤ ╧ ╪ ╫

快速入门

验证单个文件
/usr/bin/env bash << 'PREFLIGHT_EOF'
uv run "$(cc-plugin-root doc-tools)/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py" docs/ARCHITECTURE.md
PREFLIGHT_EOF
验证多个文件
/usr/bin/env bash << 'PREFLIGHT_EOF_2'
uv run "$(cc-plugin-root doc-tools)/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py" docs/*.md
PREFLIGHT_EOF_2
验证目录
/usr/bin/env bash << 'PREFLIGHT_EOF_3'
uv run "$(cc-plugin-root doc-tools)/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py" docs/
PREFLIGHT_EOF_3

输出格式

脚本会以类似编译器的格式输出问题，便于快速定位：

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
严重级别
级别说明
error连接断裂、垂直线未对齐
warning线条未闭合、潜在问题
info样式建议（可选清理）

验证规则

脚本会检查：

  1. 垂直对齐 - 垂直连接线（│║）必须与其上方或下方的字符对齐
  2. 拐角连接 - 拐角（┌┐└┘╔╗╚╝）必须与相邻线条正确连接
  3. 交汇处有效性 - T 形连接和交叉处必须具有正确的进入和离开连接
  4. 线条连续性 - 水平线（─═）应在有效端点处终止
  5. 框线闭合 - 框线应正确闭合（不得有悬空边缘）

退出代码

代码含义
0未发现问题
1检测到错误
2仅有警告（使用 --warn-only 时忽略错误）

与 Claude Code 集成

Claude Code 创建或编辑 ASCII 图表时：

  1. 对文件运行验证脚本
  2. 检查输出中的所有错误
  3. 应用建议的修复
  4. 重新运行，直到验证通过
工作流示例
/usr/bin/env bash << 'PREFLIGHT_EOF_4'
# After editing docs/ARCHITECTURE.md
uv run "$(cc-plugin-root doc-tools)/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py" docs/ARCHITECTURE.md

# 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
# → Edit line 44, column 12 to add the missing connector
PREFLIGHT_EOF_4

限制

  • 检测结构性对齐问题，不检查视觉间距
  • 要求一致使用框线字符（不能混用 +---+ 之类的 ASCII 字符）
  • 制表符可能导致误报（请先转换为空格）
  • 不执行 Unicode 规范化（请使用预组合字符）

随附脚本

脚本用途
scripts/check_ascii_alignment.py主要验证脚本

相关内容

故障排除

问题原因解决方案
找不到脚本未安装插件使用 claude plugin list 确认插件已安装
制表符导致误报制表符字符造成错位验证前将制表符转换为空格
未检测到混合 ASCII 字符使用 +---+ 样式脚本仅验证 Unicode 制表框线字符
列号不准确Unicode 宽度计算使用预组合字符，避免组合标记
没有问题但看起来不对未检查美观间距验证器检查结构，不检查视觉间距
意外的退出码 2仅警告模式使用 --warn-only 标志，将警告视为成功
找不到验证错误复杂的嵌套图表检查输出中的行号，仅验证相关部分
Unicode 字符无法显示终端字体缺少字形使用完整支持 Unicode 制表框线字符的字体

执行后反思

此技能完成后，请在结束前检查：

  1. 命令是否成功？ — 如果没有，请修正导致失败的指令或错误表。
  2. 参数或输出是否发生变化？ — 如果底层工具的接口有所变化，请相应更新用法示例和参数表。
  3. 是否需要变通处理？ — 如果你不得不临时采用其他方法（不同的标志、额外步骤），请更新此 SKILL.md，避免下次调用时需要采用相同的变通方法。

仅当问题确实存在且可复现时才进行更新，不要更新推测性问题。

评论

支持 Markdown