dsh-dead-links: Markdown 文檔死鏈檢查工具

前言¶

在 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 提供了一種輕量級、零依賴的方式來維護文檔健康度。它通過結構化輸出將檢查結果反饋給智能體或開發者，適合集成到文檔更新或定期巡檢的流程中。

項目地址：https://github.com/ZhijiangTang/dsh-dead-links
插件目錄：https://www.skillhub.cn/plugins/ZhijiangTang/dsh-dead-links