md-link-checker

name	md-link-checker
description	检查 Markdown 文件中的本地和外部链接有效性。当用户需要验证、检查 Markdown 文档或项目的链接可访问性时调用此技能。

English version: SKILL-en.md

Markdown 链接检查 (md-link-checker)

Markdown 链接检查技能依托于本技能目录下的 scripts/check_links.py 脚本，提供对 Markdown 文本中本地文件路径与外部网络 URL 的连通性验证能力。该工具兼容标准 Markdown 语法及 HTML 图片标签，并具备针对反爬虫策略的自动重试机制。

适用场景

基于用户的不同排查需求，该技能可覆盖单文件精准检测、目录级别批量扫描以及全项目深度排查等多种实际业务场景，确保文档外链与内部引用的准确性。排查任务通常包含如下维度：

• 验证特定 Markdown 文件的链接连通性；
• 批量扫描指定目录下所有 Markdown 文件的链接有效性；
• 全局排查项目内所有 Markdown 文件的外部网络地址或本地相对路径。

执行指南

通过终端直接调用 Python 脚本即可发起自动化检测任务，系统将根据传入参数动态调整检查范围与目标链接类型。

参数说明

脚本提供灵活的参数配置接口，支持精确控制检查目标与策略。详细参数配置如表格所示：

参数名称	简写	选项范围	默认值	功能描述
--file	-f	文件路径	项目 README.md	指定要检查的单个 Markdown 文件路径。
--dir	-d	目录路径	无	递归检查指定目录及其子目录下的所有 Markdown 文件。
--all	-a	无	否	全量检查项目内的所有 Markdown 文件。
--type	-t	local, external, all	local	指定需要检查的链接类型。

常用命令示例

针对常见的排查任务，可参考以下标准命令组合快速启动检测流程：

# 注意：LLM 在执行命令前，请先使用文件路径相关工具确认本技能目录的绝对路径，并将其替换到 <SKILL_DIR> 中。

# 检查单个文件的所有链接
python3 <SKILL_DIR>/scripts/check_links.py -f path/to/file.md -t all

# 检查特定目录的本地链接
python3 <SKILL_DIR>/scripts/check_links.py -d docs

# 全量检查项目所有链接
python3 <SKILL_DIR>/scripts/check_links.py -a -t all

# 仅检查项目的外部网络链接
python3 <SKILL_DIR>/scripts/check_links.py -a -t external

注意事项

执行排查任务时，需关注检测报告的生成位置以及工具对特殊用法的兼容性特征。注意事项清单如下：

• 脚本执行完成后，详细的检测结果将直接输出到控制台。如果需要保存日志，可通过大模型或用户手动使用重定向（如追加 > link_check_report.txt）输出到文件。
• 链接解析模块不仅支持标准 Markdown 链接，同时也兼容 HTML <img> 标签的 src 属性解析。
• 针对外部网络资源的探测，内置了应对 403 、 404 等状态码的智能容错与重试逻辑，以降低误报率。