dsh-tool-reading-map

English | 中文

A reading_map tool plugin for DeepSeek Harness (dsh). Before the agent edits an unfamiliar codebase, give it a structured, priority-ranked map of the repo instead of letting it wander file by file.

What it does

One model-facing tool, reading_map:

• Priority-ranked file list — config files and entrypoints first, source code before docs, each entry with language, role (config / entrypoint / code / other), line count, size, and a bounded preview. Config and entrypoint files are kept whole.
• Honest coverage account — every run reports how many candidate files existed, how many were kept, which directories were skipped, and which files were dropped for being oversized, binary, minified, or over the file cap. A partial map never pretends to be complete.
• Deterministic — the scan never calls a model. It is cheap, fast, and identical on replay; the agent summarizes from the map itself when it wants prose.

The ranking and skip heuristics are ported from RepoWiki's scanner, battle-tested on thousands of repos.

Install

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

or from npm (once published):

dsh plugin --profile <name> add dsh-tool-reading-map

Boot the profile and the tool appears as reading_map alongside the built-ins.

Tool reference

Parameter	Type	Required	Default	Meaning
path	string	yes	—	Absolute path of the repository root to scan.
max_files	number	no	60	Files kept after priority ranking (config > entrypoint > code > other).
preview_lines	number	no	30	Preview lines kept per non-config, non-entrypoint file.
max_file_size	number	no	204800	Per-file size cap in bytes; larger files are counted as oversized and skipped.

The result is one canonical JSON value: { root, coverage: { candidates, kept, skippedDirs, oversizedCount, oversized, binaryCount, minifiedCount, priorityDropped }, files: [...] }, so it composes cleanly with PTC mode and other tooling.

What gets skipped, in one table:

Skipped	How it is detected
Dependency / build dirs	node_modules, dist, build, vendor, .venv, target, caches, and more (see SKIP_DIRS in src/scanner.ts)
Assets and lock/binary ext	images, media, archives, fonts, compiled artifacts, .map, .min.js, .lock
Oversized files	larger than max_file_size (counted, first three named)
Binary files	NUL byte within the first 8 KiB
Minified source	single line over 1000 chars, or ≤5 non-empty lines with a giant longest line
.gitignore paths	root .gitignore globs (no negation support, by design)

Real output (run against the RepoWiki repo)

Reading map of /path/to/RepoWiki: kept 60/78 candidate files, 15 dirs skipped, 12 dropped by priority.
- [config] .env.example (text, 14 lines)
- [config] frontend/package.json (json, 33 lines)
- [config] frontend/tsconfig.json (json, 22 lines)
- [config] frontend/vite.config.ts (typescript, 20 lines)
- [config] pyproject.toml (toml, 81 lines)
- [config] README.md (markdown, 181 lines)
- [config] src/repowiki/config.py (python, 94 lines)
- [entrypoint] src/repowiki/__main__.py (python, 6 lines)
- [entrypoint] src/repowiki/server/app.py (python, 158 lines)
- [code] frontend/src/App.tsx (tsx, 19 lines)
- [code] frontend/src/components/MermaidDiagram.tsx (tsx, 50 lines)
- [code] frontend/src/components/SettingsModal.tsx (tsx, 79 lines)
… and 48 more in the structured result.

Skipped on this run (the honest part): .git, .venv, dist, frontend/node_modules, every __pycache__, plus 12 lower-priority files dropped past the cap — all named in coverage, never silently missing.

Development

npm install
npm run build     # tsc -> lib/
npm test          # vitest

Layout:

src/
  index.ts    # plugin entry: name / inject / apply
  tool.ts     # reading_map tool definition
  scanner.ts  # the walk, ranking, skip rules, and coverage accounting
test/
  scanner.test.ts

Load it from a checkout during development with a patch overlay (absolute path):

- insert:
    - id: reading-map
      name: /absolute/path/to/dsh-tool-reading-map/lib/index.js

pnpm dsh web --patch ./cordis.dev.yml

License

MIT