svgbob-strict-syntax

name	svgbob-strict-syntax
description	svgbob/bob 绘图严格语法规则。Use when: 生成 ```bob 代码块、编写 svgbob ASCII 图、需要在图中显示代码标识符/函数名/路径/括号/下划线/斜杠等编程符号。DO NOT USE FOR: 普通 markdown 文本、不含编程符号的纯文本框图。
argument-hint	描述需要绘制的 bob 图表内容

svgbob 严格语法规则

核心原则

svgbob 将 ( ) _ / * \ < > . : # + - 等 ASCII 符号解释为绘图指令（弧线、对角线、连接线等），而非文本字符。在图中显示编程文本时，必须用双引号 "..." 包裹，强制 svgbob 将其视为纯文本。

强制规则

1. 编程文本必须用 "..." 包裹

所有含 () _ / * \ 的代码标识符、函数名、路径、注释，必须用一层英文双引号包裹：

│  "main()"                     │    ← 函数调用
│  "HAL_GPIO_Init(GPIOA, &cfg)" │    ← 带下划线和括号
│  "Core/Inc/main.h"            │    ← 路径含 /
│  "/* USER CODE BEGIN */"       │    ← C 注释含 * /
│  "void SystemClock_Config();"  │    ← 完整声明
│  配置 "GPIO_PIN_5" 为输出       │    ← 中文+代码混排

2. 禁止嵌套引号

任何位置不允许 "" 嵌套。每个文本段只用一层 "..." 包裹。

3. " 的视觉行为

• 每个 " 占 1 个网格单元但不可见（视觉等同于空格）
• 添加 "..." 后需从相邻空格处借位，维持行宽不变：

  原始: │  HAL_Init()          │   （空格+文本+空格=固定宽度）
  转义: │ "HAL_Init()"         │   （"偷取"了一个前导空格和一个尾部空格）
  

4. \" 转义陷阱

svgbob 将 \" 视为转义引号（字面 "），而非 \ + 关闭引号。如果文本以 \ 结尾：

错误: "C:\path\"       ← \" 被视为转义，引号永不关闭
正确: "C:\path\ "      ← 在 \ 和 " 之间加空格

5. 不需要引号的内容

• 纯字母/数字文本（无特殊符号）：GPIO, UART, 123
• 绘图结构线：│ ─ ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼
• 箭头：→ ← ↓ ↑ ► ◄
• 纯 CJK 文本：配置模式, 初始化, 系统启动

6. 方框线条标准

统一使用 Unicode box-drawing 字符：┌ ┬ ┐ ├ ┼ ┤ └ ┴ ┘ │ ─

树形结构：├── └── │

7. 对齐要求

• 每个 CJK 字符占 2 格显示宽度，需额外补偿 1 个空格
• 所有 │ 必须垂直对齐（相同列位置）
• 参考 svgbob-cjk-alignment Skill 的宽度计算规则

完整示例

┌──────────────────────────────────────────────┐
│         STM32 初始化流程                      │
├──────────────────────────────────────────────┤
│  1. "HAL_Init()"                             │
│  2. "SystemClock_Config()"                    │
│  3. "MX_GPIO_Init()"                          │
│  4. "MX_USART1_UART_Init()"                   │
│  5. "/* USER CODE BEGIN 2 */"                 │
├──────────────────────────────────────────────┤
│  文件结构：                                   │
│  ├──"Core/Src/main.c"                         │
│  ├──"Core/Inc/main.h"                         │
│  └──"Drivers/STM32F1xx_HAL_Driver/"           │
└──────────────────────────────────────────────┘

自动化工具

项目提供 fix_bob_quotes.py 脚本，可自动为已有 bob 图块添加 "..." 转义：

# 预览变更
python .github/skills/svgbob-cjk-alignment/scripts/fix_bob_quotes.py docs/chapter1.md --dry-run

# 原地修改
python .github/skills/svgbob-cjk-alignment/scripts/fix_bob_quotes.py docs/chapter1.md --inplace

脚本特性：

• 框内宽松模式：│ 之间的所有问题字符都引号化
• 框外严格模式：仅引号化明确的编程文本（2+ 字母/数字/CJK + 问题字符）
• 结构字符排除：──, ├, ► 等绘图字符不会被包入引号
• 括号对合并：( 从 Flash 启动) 自动合并为 "( 从 Flash 启动)"
• 幂等执行：可重复运行，先清除旧引号再重新添加