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