Introduction

In the plugin-based ecosystem of DSH (DeepSeek Harness), building agents often requires processing large amounts of document content. If external links in the documentation become invalid, it can degrade the user experience and even affect the retrieval accuracy of the agent. The dsh-dead-links plugin solves this problem by registering a dead_links tool for scanning Markdown documents for dead links.

Plugin Overview

  • Name: dsh-dead-links
  • Function: Dead-link checking tool for Markdown documents
  • Maintainer: ZhijiangTang
  • Category: Network tool
  • License: MIT
  • Core Features: Pure ESM, zero dependencies, build-free, read-only and does not modify any files

Core Features

The tool uses node:fs to recursively traverse a directory, filters Markdown files with a Glob pattern (default **/*.md), and extracts HTTP(S) links using regular expressions. It then checks these links concurrently and returns a structured JSON result.

The specific capabilities include:
1. Markdown Document Dead-Link Scanning: Identifies invalid links in documents.
2. Recursive Traversal and Filtering: Supports specifying a directory and Glob pattern (e.g., **/*.md).
3. Intelligent Checking Strategy: Prefers HEAD requests; automatically falls back to GET requests when encountering 405 (Method Not Allowed), 403 (Forbidden), or network errors.
4. Concurrency Control: The default concurrency is 5 and can be adjusted via the parameter (1-10).
5. Structured Results: Returns JSON data including the file name, line number, URL, status code, or error information.
6. Deduplication: The same URL is requested only once.

Installation and Activation

Install using the DSH plugin management command:

dsh plugin --profile <name> add dsh-dead-links

Usage

When invoking the dead_links tool, use the following parameters to configure the scan scope and strategy:

  • dir: The directory to scan. Default is docs (relative to the workspace root). If the directory does not exist, the tool falls back to the root directory . and notes it in the result.
  • glob: The file matching pattern. Default is **/*.md.
  • concurrency: The number of concurrent requests. Range 1-10. Default is 5.
  • timeoutMs: The timeout for a single request (milliseconds). Default is 10000.

Output Example

The tool returns a normalized JSON value. When ok: true, it includes scan statistics and dead-link details:

{
  "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": "…"
}

When ok: false (usually when the directory is unavailable), the following structure is returned:

{
  "ok": false,
  "error": {
    "stage": "fs",
    "message": "…"
  }
}

Notes

  1. Permission Requirements: Running the plugin requires the filesystem:read (read files) and network:outbound (initiate network requests) permissions.
  2. Dependencies: The plugin depends on the following DeepSeek AI core packages: @deepseek-ai/cordis, @deepseek-ai/dsh-tools, and @deepseek-ai/dsh-llm.
  3. Exception Handling: Network-related exceptions are folded into the normalized value (status: null + the error field) and do not cause the program to throw an unhandled exception and abort.
  4. Read-Only Operations: The plugin only reads file content and does not modify or write to any scanned files.

Summary

dsh-dead-links provides a lightweight, zero-dependency way to maintain documentation health. It feeds the check results back to the agent or developers through structured output, making it suitable for integration into documentation update or periodic inspection workflows.