dsh-dead-links

DSH 插件：Markdown 文档死链检查工具，注册一个 dead_links 工具。纯 ESM、零依赖、无构建、只读不改任何文件。

简介

• 工具名：dead_links
• 能力：用 node:fs 递归遍历目录，按 glob（默认 **/*.md）筛选 Markdown 文件；逐文件按行正则提取 http(s):// 链接（保留行号）；并发受限地逐条检查，先 HEAD（AbortSignal.timeout 超时），遇到 405/403/网络错误 降级 GET（只关心状态码，读完响应体即丢弃）；最终把每条死链的 文件/行号/URL/状态码或错误 折叠进规范 JSON 值返回。
• 行为：永不抛异常。网络类异常一律折进规范值（dead[].status: null + dead[].error）；目录不存在则返回 { ok: false, error: { stage: 'fs', message } }。
• 只读：不修改、不写入任何被扫描的文件。

安装

dsh plugin --profile  add file:./plugins/dsh-dead-links
# 或发布后：
dsh plugin --profile  add dsh-dead-links

参数

参数	类型	必填	默认	说明
dir	string	—	docs	相对工作区根的目录。默认 docs，不存在时回退到工作区根 . 并在结果中注明
glob	string	—	**/*.md	简单通配模式，仅支持 *（段内）与 **（跨段）两种通配，匹配相对 dir 的路径
concurrency	number	—	5	并发检查的 URL 数量，夹取到 1–10
timeoutMs	number	—	10000	单条请求超时（毫秒）

输出字段

规范 JSON 值（ok: true 时）：

{
  "ok": true,
  "dir": "docs",            // 实际扫描的目录（回退后）
  "filesScanned": 12,       // 命中 glob 并扫描的文件数
  "linksFound": 58,         // 提取到的链接出现次数
  "linksChecked": 33,       // 实际检查的唯一 URL 数（按 URL 去重）
  "dead": [                 // 死链列表（每条 = 一次出现位置）
    { "file": "guide.md", "line": 42, "url": "https://gone.invalid/x", "status": 404 },
    { "file": "api.md", "line": 7, "url": "https://nx.invalid/", "status": null, "error": "getaddrinfo ENOTFOUND …" }
  ],
  "durationMs": 2345,
  "truncated": false,       // dead 超过 100 条时截断为 true
  "note": "…"               // 目录回退 / 截断 / 取消等说明，存在时给出
}

ok: false（目录不可用）时：。