死链检查器 ZhijiangTang/dsh-dead-links

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（目录不可用）时：{ "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