# Fix Table Pipe

> 修复 Markdown 表格渲染问题，包括：(1) Callout 块内表格前缺少空行；(2) LaTeX 行内公式中管道符 $|...|$ 被误解析为表格分隔符（含整行结构已崩坏的修复）；(3) 检测孤立 $ 符号和奇数 $ 数等行结构异常。**自动触发**：每次写入包含表格的文件后，自动检查表格格式是否符合 Obsidian Markdown 规范。手动触发：当用户提到"表格格式错误"、"表格显示异常"、"表格渲染问题"、"Callout 表格"时使用此 skill。

- Skill: `treasoni/fix-table-pipe` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add treasoni/fix-table-pipe`
- Raw SKILL.md: https://api.skillmd.com/api/skills/treasoni/fix-table-pipe/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: treasoni (https://skillmd.com/u/treasoni)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/treasoni/fix-table-pipe

---


# 自动触发机制

## 🔴 强制触发（自动检查）

**每次使用 Write 或 Edit 工具修改包含表格的 .md 文件后，必须执行本技能进行格式检查！**

检查时机：
1. ✅ Write 工具写入包含表格的内容后
2. ✅ Edit 工具修改了表格相关内容后
3. ✅ 任何包含 `| 列名 |` 格式的文件操作后

**工作流程**：
```
[Write/Edit 完成]
      ↓
[检查文件内容是否包含表格]
      ↓
[是] → 执行表格规范检查 → 修复问题 → 写回文件
[否] → 跳过检查
```

# 修复表格渲染问题

## 常见问题类型

### 问题 1：Callout 内表格前缺少空行 ⚠️ 最常见

**症状**：表格显示为纯文本，或列错位、内容丢失

**原因**：Callout 内的表格必须前面有空行才能正确渲染

```markdown
# ❌ 错误 - 表格不会渲染
> **标题**：
> | 列1 | 列2 |
> |-----|-----|
> | A   | B   |

# ✅ 正确 - 表格会正确渲染
> **标题**：
>
> | 列1 | 列2 |
> |-----|-----|
> | A   | B   |
```

**修复方法**：在表格前添加 `>` 空行

### 问题 2：LaTeX 管道符引起列冲突（⚠️ 最隐蔽）

#### 场景 A：单元格内 `$|...|$` 导致多出一列

**症状**：表格列数比预期多，内容被截断

**原因**：`$|x|$` 中的 `|` 被误认为表格分隔符

```markdown
# ❌ 错误
| $|f(x)|$ 的值 | 说明 |

# ✅ 正确
| $\vert f(x) \vert$ 的值 | 说明 |
```

**修复方法**：将 `$|...|$` 转换为 `$\vert...\vert$`

#### 场景 B：`$...|...$` 导致整行结构崩坏 ⚠️ 2026-05-08 新增

**症状**：表格某行的单元格数量与表头不匹配，数据散落在错误列中，整行看起来像"被撕裂"了

**原因**：行内公式如 `$y = |x|$` 中的 `|` 被误解析为表格列分隔符，把原本的一个单元格内容撕成多列

**示例**：

```markdown
# ❌ 错误 - 行结构已崩坏
| $y =            | x   | $             | 偶      | $x \geq 0$ 递增 | -   |

原始意图：| $y = |x|$ | 偶 | $x \geq 0$ 递增 | - |
                  ↑↑↑
             | 被误认作列分隔符
```

**检测方法**（识别已崩坏的行）：
- **`$` 数量异常**：一行中 `$` 出现奇数次（正常应为偶数，成对出现）
- **孤立 `$` 单元格**：某个单元格内容只有单独的 `$` 符号
- **以 `$... ` 开头但无闭合**：某单元格以 `$` 开头，但同一单元格内找不到配对的 `$`

**修复方法**：
1. 找到崩坏的行后，先根据其他行的结构推断该行的正确列数（对照表头）
2. 识别被 `|` 错误分隔的数学表达式碎片（如 `$y = `、`x`、`$` 散落在连续单元格中）
3. 重组碎片为完整表达式，将 `|` 替换为 `\vert`
4. 恢复该行的正确结构

```markdown
# ✅ 修复后
| $y = \vert x \vert$ | 偶 | $x \geq 0$ 递增 | - |  |  |
```

## 工作流程

### 自动检查模式（推荐）

**触发条件**：每次 Write/Edit 包含表格的文件后自动执行

**检查清单**：
- [ ] 识别文件中所有表格（查找 `| 列1 | 列2 |` 模式）
- [ ] 检查表格是否在 Callout 块内（前行有 `>`）
- [ ] 检查 Callout 内表格前是否有空行 `>`
- [ ] 检查表格内容是否包含 `$|...|$` 格式
- [ ] 检查表格行 `$` 数量是否为奇数（行结构崩坏特征）
- [ ] 检查是否有孤立 `$` 单元格（单独占一个单元格的 `$` 符号）
- [ ] 修复所有发现的问题
- [ ] 使用 Edit 工具写回文件

### Step 1：识别问题

1. 检查表格是否在 Callout 块内（行首有 `>`）
2. 检查 Callout 内表格前是否有空行 `>`
3. 检查表格内容是否包含 `$|...|$` 格式
4. **新增**：检查表格行中 `$` 数量是否为奇数（行结构崩坏特征）
5. **新增**：检查是否有孤立 `$` 单元格（单独占一个单元格的 `$` 符号）

### Step 2：修复 Callout 内表格空行问题

**检测规则**：
- 找到 Callout 块内的表格（以 `> |` 开头的行）
- 检查表格前一行是否为空行 `>`
- 如果不是空行，在表格前插入 `>`

**修复示例**：

```markdown
# 修复前
> **逐项转换**：
> | 原来的 | 变成 | 说明 |

# 修复后
> **逐项转换**：
>
> | 原来的 | 变成 | 说明 |
```

### Step 3：修复管道符冲突

#### 场景 A：单元格内有完整的 `$|...|$`

**转换规则**：

| 原始格式 | 转换后 |
|---------|--------|
| `$|expr|$` | `$\vert expr \vert$` |
| `$$|expr|$$` | `$$\vert expr \vert$$` |

**不处理的情况**：
- 已使用 `\vert`：`$\vert f(x) \vert$`
- 已使用 `\left\right`：`$\left| f(x) \right|$`
- 代码块内

#### 场景 B：行结构已崩坏（`$...|...$` 被撕碎）

**检测特征**：
- 该行 `$` 数量为奇数（不成对）
- 连续多个单元格内容碎片组成一个完整数学表达式
- 存在孤立 `$` 单元格（只有 `$` 符号）

**修复步骤**：
1. 对照表头确认正确的列数
2. 识别被 `|` 错误分隔的碎片，重组为完整行内公式
3. 将碎片中的 `|` 替换为 `\vert`
4. 合并碎片到正确的单元格中

**示例**：

```markdown
# 崩坏行（特征：3个 $ 为奇数，有孤立 $ 单元格）
| $y =            | x   | $             | 偶      | $x \geq 0$ 递增 | -   |

# 分析：碎片 "$y = " + "x" + "$" = 原应为 "$y = |x|$"
# 修复：将 | 替换为 \vert
| $y = \vert x \vert$ | 偶 | $x \geq 0$ 递增 | - |  |  |
```

### Step 4：写回文件

使用 Edit 工具更新文件，保持原有缩进和格式。

## 完整示例

### 示例 1：Callout 内表格缺少空行 + 管道符问题

**输入**：
```markdown
> [!example] 例题
> **表格**：
> | $|f(x)|$ 的值 | 说明 |
> |:---:|:---:|
> | 1 | 正常 |
```

**输出**：
```markdown
> [!example] 例题
> **表格**：
>
> | $\vert f(x) \vert$ 的值 | 说明 |
> |:---:|:---:|
> | 1 | 正常 |
```

### 示例 2：行结构已崩坏（`$...|...$` 撕碎整行）

**输入**（Obsidian 渲染后某行错乱，查看源码发现）：
```markdown
| $y =            | x   | $             | 偶      | $x \geq 0$ 递增 | -   |
```
- 特征：`$` 出现 3 次（奇数），有孤立 `$` 单元格
- 分析：碎片 `$y = ` + `x` + `$` → 原应为 `$y = |x|$`

**输出**：
```markdown
| $y = \vert x \vert$ | 偶 | $x \geq 0$ 递增 | - |  |  |
```

## 注意事项

1. **自动检查优先**：每次 Write/Edit 包含表格的文件后，必须执行本技能
2. **优先修复空行问题**：Callout 内表格缺少空行是最常见的问题
3. **保持 Callout 格式**：空行必须是 `>` 而不是完全空行
4. **批量处理**：一次修复文件中所有类似问题

---

## 快速检查命令

在每次 Write/Edit 后，执行以下检查：

```bash
# 检查文件中是否有 Callout 内表格缺少空行
grep -n '> \|' "文件路径.md" | grep -v '^*>$'

# 检查表格行中是否有奇数个 $（行结构崩坏特征）
awk -F'|' '{for(i=1;i<=NF;i++) if($i ~ /\$/){gsub(/[^$]/,"",$i); if(length($i)%2==1) print NR": "$0}}' "文件路径.md"
```

---

## 与其他技能的协同

| 技能 | 协同场景 |
|------|----------|
| mistake-book | 整理错题时，检查错题本中的表格格式 |
| obsidian-markdown | 创建包含表格的笔记时，自动检查表格格式 |
| kaoyan-math-notes | 生成数学笔记时，检查公式表格格式 |

---

*版本: 2.1.0 - 增加行结构崩坏识别（奇数 `$` 检测 + 孤立 `$` 单元格检测），增加 `$...|...$` 导致的整行撕裂修复方案，刷新 description 覆盖新场景*