ascii-diagram

验证 ASCII 图表

Agent 生成的 ASCII 图表经常会出现对齐问题——角落错位、边框不齐、连接线断开。**大模型无法可靠地在脑中计算字符数量。**此技能通过打印和检查的循环来发现并修复对齐问题。

规则

1. **优先使用 Unicode 制表符绘制字符。**角落使用 ┌、┐、└、┘，水平边框使用 ─，垂直边框使用 │，交叉连接处使用 ┬、┴、├、┤、┼。只有在用户明确要求，或目标格式无法渲染 Unicode 时，才退而使用纯 ASCII（+、-、|）。同一张图表中绝不要混用两种风格。
2. 方框的每一行宽度必须完全相同——包括顶部边框、内容行和底部边框。
3. 在较短的内容行末尾补空格，使右侧边框 │ 在每一行都落在同一列。
4. 连接线和箭头应清晰地连接到相应方框的边框。确认所有间隙都是有意留出的。
5. **不要使用制表符。**制表符的显示宽度不可预测，会悄悄破坏对齐。只使用空格。
6. **不要在行尾留下空白。**不可见的行尾空格会导致宽度不一致，虽然看起来正确，实际上却不对。

验证流程

**不要试图在脑中通过计算字符数量来验证。**改用下面的打印和检查循环。

步骤 0：决定是否委派给子 Agent

当图表同时满足以下条件时，通过 Agent 工具将整个验证循环委派给子 Agent： (a) 超过 6 行；(b) 包含多个方框或嵌套／连接布局。该循环会产生大量标尺输出并带来反复迭代，这些内容不适合留在主上下文中。

对于较小的图表（单个方框、简短表格、≤6 行），直接在当前上下文中运行循环——生成子 Agent 比直接处理更慢。

委派时，使用以下模板交接（子 Agent 未加载此技能）：

File: <absolute path>
Lines: <start>-<end>
Task: Run the verification loop in skills/ascii-diagram/SKILL.md steps 1-5. Edit the source file in place.
Report: PASS or FAIL, iteration count, and a one-line summary of fixes. Do not paste the diagram back.

子 Agent 返回后：

• 重新阅读修改过的行，确认总结与实际更改一致——子 Agent 的报告描述的是意图，不一定与差异相符。
• 若失败（子 Agent 达到 3 次迭代上限后仍有问题），决定接受部分修复、提供具体指导后重新委派，或在当前上下文中完成。不要默默将失败视为已完成。

步骤 1：将图表写入临时文件

使用 Write 工具将图表写入临时文件。使用唯一的路径，例如 /tmp/diagram-<context>.txt（将 <context> 替换为与本次会话相关的具体名称，例如 /tmp/diagram-auth-flow.txt），以避免覆盖其他会话的文件。以下所有命令都使用相同的路径。

步骤 2：使用列标尺打印

运行以下 Bash 命令，显示带列编号的图表（将 <path> 替换为临时文件路径）：

awk 'BEGIN{
  ruler1=""; ruler2=""
  for(i=0;i<120;i++){
    ruler1=ruler1 sprintf("%d", int(i/10)%10)
    ruler2=ruler2 sprintf("%d", i%10)
  }
  print "     " ruler1
  print "     " ruler2
}
{printf "%3d: %s\n", NR, $0}' <path>

这会为每一行添加行号，并在顶部显示两行列标尺（十位数和个位数），便于检查角落、边框和连接线是否落在正确的列中。如果图表宽度超过 120 列，请调高循环中的 120。

步骤 3：检查不可见的问题

运行以下检查，发现普通输出中不可见的问题（将 <path> 替换为临时文件路径）：

# Tabs (will break alignment silently)
grep -F $'\t' <path> && echo "FAIL: tabs found" || echo "OK: no tabs"
# Trailing whitespace
grep ' $' <path> && echo "FAIL: trailing spaces found" || echo "OK: no trailing whitespace"

继续之前，请修复所有发现的问题。

步骤 4：目视检查标尺输出

查看打印出的输出并检查：

• 方框宽度一致性：每个方框的右侧边框（│ 或 ┐/┘）是否在每一行都出现在同一列？根据标尺读取列号。
• 顶部／底部边框匹配：底部角落（└/┘）是否与顶部角落（┌/┐）位于同一列？
• 并排对齐：相邻方框的列位置是否一致？
• 连接线：箭头是否确实接触边框字符？

第 5 步：修复并重复

如果发现任何问题：

1. 在图表所在的文件中修复图表（而不是临时文件）。
2. 再次将更新后的图表写入同一个临时文件。
3. 再次使用标尺打印。
4. 重复上述步骤，直到所有检查都通过或达到 3 次迭代——以先发生者为准。如果 3 次迭代后仍有问题，请继续下一步。

常见错误，请留意

• 右边框偏了一列。 在 │ 前多了或少了一个空格，导致右边框所在列与顶部或底部的角不一致。使用标尺验证每一行的结尾是否都在同一列。

  WRONG:                                  CORRECT:
  ┌──────────┐                            ┌──────────┐
  │ hello    │                            │ hello    │
  │ world     │  ← col 13                 │ world    │
  └──────────┘   ← col 12                 └──────────┘
  

• 底边宽度不匹配。 底边的 ─ 比顶边多或少，导致闭合角落落在错误的列。使用标尺计数，不要凭目测。

  WRONG:                                  CORRECT:
  ┌──────────┐  ← col 12                  ┌──────────┐
  │ content  │                            │ content  │
  └─────────┘   ← col 11                  └──────────┘
  

• 并排框之间的间距不齐。 相邻框之间的间距在各行不一致，导致第二个框发生偏移。验证第二个框的角落在每一行是否都位于同一列。

  WRONG:                                  CORRECT:
  ┌───────┐   ┌───────┐                   ┌───────┐   ┌───────┐
  │ box 1 │   │ box 2 │                   │ box 1 │   │ box 2 │
  └───────┘    └───────┘  ← extra         └───────┘   └───────┘
  

• 混用边框绘制样式。 在同一张图中混用 ASCII（+、-、|）和 Unicode（┌、─、┐）字符。选择一种样式并始终保持一致。

  WRONG:                                  CORRECT:
  ┌──────────+  ← ASCII +                 ┌──────────┐
  │ content  │                            │ content  │
  └──────────┘                            └──────────┘
  

• 连接线未接触框边。 箭头或线条与应连接的框之间留有间隙，悬空未接。每条连接线都必须从边框字符处开始，并以边框字符结束。

  WRONG:                                  CORRECT:
  ┌───────┐     ┌───────┐                 ┌───────┐   ┌───────┐
  │ box 1 │  -> │ box 2 │                 │ box 1 │──>│ box 2 │
  └───────┘     └───────┘                 └───────┘   └───────┘
       gap ^  ^ gap                             no gaps