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