name: check-links description: “审计文档中的死链接。在发布前、文档重构后或运行/consolidate时使用。” allowed-tools: Bash(curl:*), Read, Grep, Glob

扫描 docs/ 目录下的所有 Markdown 文件，检查是否存在损坏的链接。分两轮进行：内部链接（指向文件）和外部链接（HTTP URL）。

使用时机

发布或部署文档之前
重命名、移动或删除文档页面之后
重构 docs/ 目录或导航结构之后
当运行 /consolidate 时（检查 #12）
当用户报告网站上出现 404 错误时

不应使用的时机

仅编辑单个文档时（直接目视检查该文件中的链接即可）
离线时，且只有外部链接检查会受影响时

执行步骤

第 1 轮：内部链接

扫描 docs/ 目录下的每个 .md 文件，查找指向其他文件的 Markdown 链接：[文本](目标.md)、[文本](../路径/文件.md)、[文本](路径/文件.md#锚点)。

对于每个链接：

根据源文件所在目录解析目标路径
在检查文件是否存在之前，去除任何 #锚点 片段
跳过外部 URL（http://、https://、mailto:）
跳过纯锚点（#章节名）——这些是页面内链接
验证目标文件在磁盘上是否存在

收集所有损坏的内部链接，格式如下：

损坏：源文件.md:行号 → 目标.md （文件未找到）

第 2 轮：外部链接

扫描 docs/ 目录下的每个 .md 文件，查找 Markdown 链接语法中的 http:// 和 https:// URL。

对于每个 URL：

发送一个 HTTP HEAD 请求，超时时间为 10 秒
如果 HEAD 失败或返回 405，则重试 GET 请求
记录 HTTP 状态码

报告失败情况，格式如下：

警告：源文件.md:行号 → https://example.com (HTTP 404)
警告：源文件.md:行号 → https://example.com (超时)

不要将外部链接失败视为错误。 网络分区、速率限制和临时中断很常见。报告它们但不使检查失败。

例外情况——跳过以下 URL：

localhost / 127.0.0.1 URL（本地开发服务器）
example.com / example.org（占位符域名）

第 3 轮：图片引用

扫描图片链接：![替代文本](路径/到/图片.png) 和 ![替代文本](images/文件.jpg)。

验证图片文件在磁盘上是否存在。解析规则与内部链接相同。

输出格式

## 链接检查报告

### 内部链接
- 发现 N 个损坏链接（或“全部正常”）
- [损坏链接列表，包含文件:行号和目标]

### 外部链接
- N 个警告（或“全部可达”）
- [失败列表，包含文件:行号、URL 和原因]

### 图片
- N 个缺失图片（或“全部存在”）
- [缺失图片列表，包含文件:行号和目标]

### 摘要
内部链接：N 损坏 / M 总计
外部链接：N 不可达 / M 总计
图片：N 缺失 / M 总计

修复建议

对于损坏的内部链接，提供具体的修复建议：

如果目标文件已重命名，建议新的路径
如果目标文件已删除，建议移除该链接或指向替代文件
如果目标是拼写错误（存在近似匹配），建议更正

对于外部链接，仅作报告。由用户决定是否更新、移除或忽略。

与 /consolidate 集成

当作为 /consolidate 的第 12 项检查被调用时：

运行完整检查（全部 3 轮）
以与其他整合检查相同的格式报告发现的问题
内部损坏链接计为需要修复的问题
外部链接失败计为警告（仅供参考）

质量检查清单

运行检查后：

[ ] 扫描了 docs/ 目录下的所有 .md 文件
[ ] 相对路径解析考虑了子目录（recipes/、blog/）
[ ] 在检查文件存在性之前去除了锚点
[ ] 外部检查使用了超时设置（不会因主机响应慢而挂起）
[ ] 跳过了 localhost/example URL
[ ] 报告区分了错误（内部）和警告（外部）