Preface

DeepSeek Harness (DSH) adopts a plugin-based architecture and emphasizes the idea that “everything is a plugin.” When an agent starts editing an unfamiliar codebase, directly reading files one by one without a clear direction is inefficient and prone to missing key information. The dsh-tool-reading-map plugin aims to solve this problem. Before editing, it provides the agent with a structured, priority-ordered map of the codebase, helping the agent quickly grasp the core configuration and entry points.

Plugin Positioning

  • Name: dsh-tool-reading-map
  • Function: A DSH codebase reading map tool that provides a structured, priority-ordered map before an agent edits code.
  • Maintainer: he-yufeng
  • Category: Workflows
  • License: MIT

Core Features

This plugin provides a tool named reading_map with the following features:

  1. Prioritized file list: The scan results are sorted by priority in the following order: configuration files > entry files > source code > other files. Each item includes the language, role (config/entrypoint/code/other), line count, size, and a bounded preview. Configuration files and entry files are kept in full.
  2. Honest coverage statistics: Each run reports the total number of candidate files, retained files, skipped directories, and files dropped due to reasons such as being too large, binary, or compressed. It does not falsely present the scan results as complete.
  3. Deterministic scanning: The scanning process does not call a model, so it is low-cost, fast, and repeatable. The agent can generate its own summary text based on the generated map.
  4. Configuration and entry priority: The sorting logic prioritizes configuration files and program entry points.

Installation and Enablement

Before installing, make sure DSH is installed and the corresponding Profile is available. This plugin depends on @deepseek-ai/dsh-tools (^0.1.5-rc.1).

dsh plugin --profile <name> add github:he-yufeng/dsh-tool-reading-map

After installation, start the Profile. The tool will then appear alongside the built-in tools as reading_map.

Tool Parameters and Usage

When calling the reading_map tool, you need to specify the following parameters:

Parameter Type Required Default Description
path string Yes — Absolute path to the root directory of the repository to scan
max_files number No 60 Number of files retained after priority sorting
preview_lines number No 30 Number of preview lines retained per non-configuration and non-entry file
max_file_size number No 204800 Maximum size limit for a single file (bytes); files exceeding the limit are dropped

Output Structure

The tool returns a well-formed JSON value containing the root, coverage (coverage statistics), and files (file list) fields.

Skip Rules

During scanning, the plugin automatically skips the following content:

  • Dependencies and build directories: such as node_modules, dist, build, vendor, .venv, target, cache directories, etc.
  • Assets and lock files: images, media files, archives, fonts, .map, .min.js, .lock, etc.
  • Oversized files: files larger than max_file_size.
  • Binary files: files containing a NUL byte in the first 8 KiB.
  • Compressed source files: files with a single line exceeding 1000 characters, or files with non-empty lines ≤5 and an extremely long maximum line.
  • .gitignore paths: paths defined in the root .gitignore file (negated matches are not supported).

Notes and Ecosystem Context

  • Permissions and risks: The plugin runs with the permissions of the current DSH process. Please ensure that the source is trusted.
  • License: The code is open source under the MIT License and can be used freely.
  • Origin: This plugin is derived from the scanning logic and heuristic rules of RepoWiki.

Short Ending

dsh-tool-reading-map gives DeepSeek Harness the ability to quickly establish context before editing code. Through deterministic scanning and honest coverage reporting, it helps prevent agents from getting lost in large codebases. For more details, see the catalog page or the source repository.