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 <name> add file:./plugins/dsh-dead-links
# 或发布后：
dsh plugin --profile <name> 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（目录不可用）时：{ "ok": false, "error": { "stage": "fs", "message": "…" } }。

HEAD 降级 GET、限流并发

• HEAD 优先：先用 HEAD 探测，绝大多数站点对已存在的资源返回 2xx/3xx/4xx，无需下载响应体。
• 降级 GET：当 HEAD 返回 405 Method Not Allowed 或 403 Forbidden（部分站点/网关禁用 HEAD），或 HEAD 本身网络失败时，降级为 GET 复测。GET 只关心状态码：以流式方式读完响应体后立即丢弃，不落盘、不缓冲整包。
• 限流并发：用一个固定大小的 worker 池并发检查，concurrency（默认 5）控制同时在途的请求数，避免对目标站点造成突发压力。
• 去重：同一 URL 出现多次只发起一次网络请求，结果按 URL 缓存后映射回每一处出现位置；linksChecked 即唯一 URL 数，linksFound 为出现总次数。

与未来定时任务搭配

本插件只做「单次扫描」。配合一个跨会话调度器（如未来的 dsh-scheduler：定时器触发 → 空闲时 followup(…, { source: { kind: 'cron' } })，忙碌时 inject() 注入通知），即可实现「每周自动跑一遍 dead_links，把死链清单推给模型审阅/修复」：

1. 调度器在空闲时调用 dead_links（dir/glob 固定指向文档目录）；
2. 工具返回规范 JSON，dead 非空时调度器把结果 inject 进会话，让模型生成修复建议或直接改文档；
3. 全链路只读扫描 + 结构化结果，天然适合作为周期性文档健康检查的探测步骤。

License

MIT