dsh-tool-reading-map

Readme

# dsh-tool-reading-map

English | [中文](README_CN.md)

A `reading_map` tool plugin for [DeepSeek Harness](https://github.com/deepseek-ai/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](https://github.com/he-yufeng/RepoWiki)'s scanner, battle-tested on thousands of repos.

## Install

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

or from npm (once published):

```sh
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)

```text
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

```sh
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):

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

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

## License

MIT