add-anchor

Files (1)

• SKILL.md

SKILL.md (first lines)

# add-anchor

为 Markdown 文件的所有标题（h1 ~ h6）添加英文自定义锚点 `{#anchor-id}`，用于目录跳转或跨文档引用。

## 使用方式

### 处理单个文件

```
/add-anchor path/to/file.md
```

### 批量处理目录下所有 Markdown 文件

```
/add-anchor path/to/dir/
```

## 锚点生成规则

### 格式

- 全小写字母
- 单词间用连字符 `-` 连接
- 示例：`## 📋 今日目标` → `## 📋 今日目标 {#today-target}`

### 具体步骤

对每个标题，按以下步骤生成锚点：

1. **提取标题文本**：去除 `#` 前缀和空格，得到纯标题文字
2. **检查已有锚点**：如果标题末尾已有 `{#...}`，则跳过该标题（不修改）
3. **移除不需要的字符**：
   - 移除所有 emoji（如 📋、🎯、✨ 等）
   - 移除中文标点（如：、。，、！？「」【】（）等）
   - 移除数学符号（如 +、=、>、< 等）
   - 移除引号（单引号、双引号）
   - 保留英文连字符 `-` 和撇号 `'`
4. **翻译中文为英文**：将提取出的中文部分翻译为**简短的关键词**，而非完整句子。例如"系统信息收集器"→`system-info`，而非`system-information-collector"
5. **转为锚点格式**：
   - 将英文翻译转为小写
   - 空格替换为连字符 `-`
   - 连续多个连字符合并为一个
   - 首尾连字符去除
6. **追加到标题末尾**：在标题末尾添加 ` {#generated-anchor}`

### 锚点文本去重

如果同一文件内生成相同的锚点，在末尾添加数字后缀：
- 第一个 → `{#my-anchor}`
- 第二个 → `{#my-anchor-2}`
- 第三个 → `{#my-anchor-3}`

## 示例

| 原始标题 | 生成的锚点 |
|---------|-----------|
| `## 📋 今日目标` | `## 📋 今日目标 {#today-target}` |
| `### 安装与配置` | `### 安装与配置 {#installation-and-configuration}` |
| `# 快速开始` | `# 快速开始 {#quick-start}` |
| `## 用户管理 API` | `## 用户管理 API {#user-management-api}` |
| `### 常见问题 (FAQ)` | `### 常见问题 (FAQ) {#faq}` |
| `## 错误处理` | `## 错误处理 {#error-handling}` |
| `## 错误处理 {#error-handling}` | 跳过（已有锚点） |
| `### 练习 1：系统信息收集器` | `### 练习 1：系统信息收集器 {#exercise-1}` |
| `## 📋 今日目标` | `## 📋 今日目标 {#goals}` |

## 处理边界

### 需要处理的标题

- 纯中文标题：`## 用户管理`
- 中英文混合：`## 用户管理 API`
- 含 emoji 的标题：`## 📋 今日目标`
- 含特殊符号的标题：`### 常见问题 (FAQ)`
- 含链接的标题：`## [快速开始](url)` → 提取纯文本 `快速开始`

### 跳过不处理的情况

- 标题末尾已有 `{#...}` 锚点（保留原锚点）
- 不在标题行中的 `#`（如代码块中的 `#` 注释）
- 空标题（只有 `#` 没有文字）
- 锚点引用（`## 标题 {#existing-anchor}` 中的锚点部分）

## 工作流程

### 步骤 1：确认文件范围

- 如果是单个文件路径，直接处理该文件
- 如果是目录路径，使用 Glob 工具查找目录下所有 `*.md` 文件（递归）
- 如果未提供路径，默认扫描当前工作目录下的 `*.md` 文件，并提示用户确认

### 步骤 2：读取文件内容

使用 Read 工具读取文件内容，确认文件是有效的 Markdown 格式。

### 步骤 3：逐行扫描处理

逐行扫描文件，找到所有匹配 `^(#{1,6})\s+(.+)$` 的标题行。对每个匹配的标题行：

1. 检查是否已有 `{#...}` 锚点 → 有则跳过
2. 提取纯文本（去除 markdown 链接语法，只保留文本）
3. 移除 emoji 和不需要的字符，保留下划线、连字符和撇号
4. 翻译中文为英文
5. 生成锚点 ID
6. 检查锚点是否重复
7. 用 Edit 工具替换原标题行

### 步骤 4：使用 Edit 工具修改

每次修改一个标题行，使用 Edit 工具的精确字符串替换功能。

### 步骤 5：报告结果

处理完成后，向用户报告：
- 处理的文件总数
- 每个文件的标题总数、添加锚点数、跳过的标题数
- 特殊情况的说明（如有）

From bd-dxg/my-pi, AGPL-3.0.

More from bd-dxg/my-pi