version: "1.0.0" name: add-anchor description: 为 Markdown 文件的标题添加英文自定义锚点 {#my-anchor}。当用户要求为 Markdown 标题添加锚点、处理 TOC 锚点、或需要标题可跳转链接时使用此命令。支持单文件或整个目录批量处理。

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（如 📋、🎯、✨ 等）
• 移除中文标点（如：、。，、！？「」【】（）等）
• 移除数学符号（如 +、=、>、< 等）
• 移除引号（单引号、双引号）
• 保留英文连字符 - 和撇号 '

1. 翻译中文为英文：将提取出的中文部分翻译为简短的关键词，而非完整句子。例如"系统信息收集器"→system-info，而非`system-information-collector"
2. 转为锚点格式：

• 将英文翻译转为小写
• 空格替换为连字符 -
• 连续多个连字符合并为一个
• 首尾连字符去除

1. 追加到标题末尾：在标题末尾添加 {#generated-anchor}

锚点文本去重

如果同一文件内生成相同的锚点，在末尾添加数字后缀：

• 第一个 → {#my-anchor}
• 第二个 → {#my-anchor-2}
• 第三个 → {#my-anchor-3}

示例

处理边界

需要处理的标题

• 纯中文标题：## 用户管理
• 中英文混合：## 用户管理 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：报告结果

处理完成后，向用户报告：

• 处理的文件总数
• 每个文件的标题总数、添加锚点数、跳过的标题数
• 特殊情况的说明（如有）

重点原则

• 只修改标题行，不修改文件其他内容
• 保留原始格式，包括空格、emoji 的显示位置
• 不覆盖已有锚点，尊重用户手动添加的锚点
• 锚点要简短：锚点应是简短的关键词，而非完整翻译。例如"今日目标"→{#goals}，"系统信息收集器"→{#system-info}，而非完整句子翻译
• 翻译要准确简洁，不要过度翻译英文部分
• 对于纯英文标题，直接使用原文生成锚点（无需翻译）
• 对于中英文混合标题，只翻译中文部分，保留英文原词