前言¶
在 DSH（DeepSeek Harness）的插件化生态中，构建智能体时经常需要处理大量的文档内容。如果文档中的外部链接失效，会降低用户体验，甚至影响代理的检索准确性。dsh-dead-links 插件解决了这一问题，它注册了一个 dead_links 工具，用于对 Markdown 文档进行死链扫描。
插件概况¶
- 名称：dsh-dead-links
- 功能：Markdown 文档死链检查工具
- 维护者：ZhijiangTang
- 分类：联网工具
- 许可证：MIT
- 核心特点：纯 ESM、零依赖、无构建、只读不改任何文件
核心功能¶
该工具通过 node:fs 递归遍历目录，利用 Glob 模式筛选 Markdown 文件（默认 **/*.md），并使用正则提取其中的 HTTP(S) 链接。随后，它会并发检查这些链接，并返回结构化的 JSON 结果。
具体能力包括：
1. Markdown 文档死链扫描：识别文档中的无效链接。
2. 递归遍历与筛选：支持指定目录和 Glob 模式（如 **/*.md）。
3. 智能检查策略：优先使用 HEAD 请求；遇到 405 (Method Not Allowed) 或 403 (Forbidden) 或网络错误时，自动降级为 GET 请求。
4. 并发控制：默认并发数为 5，可通过参数调整（1-10）。
5. 结果结构化：返回包含文件名、行号、URL、状态码或错误信息的 JSON 数据。
6. 去重机制：同一个 URL 只发起一次请求。
安装与启用¶
使用 DSH 插件管理命令安装：
dsh plugin --profile <name> add dsh-dead-links
使用方法¶
调用 dead_links 工具时，可以通过以下参数配置扫描范围与策略：
- dir：扫描目录，默认为
docs（相对于工作区根目录）。如果目录不存在，工具会回退到根目录.并在结果中注明。 - glob：文件匹配模式，默认为
**/*.md。 - concurrency：并发请求数，范围 1-10，默认 5。
- timeoutMs：单条请求超时时间（毫秒），默认 10000。
输出示例¶
工具返回一个规范 JSON 值。当 ok: true 时，包含扫描统计与死链详情：
{
"ok": true,
"dir": "docs",
"filesScanned": 12,
"linksFound": 58,
"linksChecked": 33,
"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,
"note": "…"
}
当 ok: false 时（通常发生在目录不可用），返回如下结构：
{
"ok": false,
"error": {
"stage": "fs",
"message": "…"
}
}
注意事项¶
- 权限要求：运行该插件需要
filesystem:read（读取文件）和network:outbound（发起网络请求）权限。 - 依赖项：插件依赖以下 DeepSeek AI 的核心包：
@deepseek-ai/cordis、@deepseek-ai/dsh-tools、@deepseek-ai/dsh-llm。 - 异常处理：网络类异常会被折叠进规范值（
status: null+error字段），不会导致程序抛出异常中断。 - 只读操作：插件仅读取文件内容，不会修改或写入任何被扫描的文件。
总结¶
dsh-dead-links 提供了一种轻量级、零依赖的方式来维护文档健康度。它通过结构化输出将检查结果反馈给智能体或开发者，适合集成到文档更新或定期巡检的流程中。
