仓库阅读地图he-yufeng/dsh-tool-reading-map

dsh-tool-reading-map

一个用于 DeepSeek Harness（dsh）的 reading_map 工具插件。在 agent 编辑一个不熟悉的代码库之前，给它一份结构化的、按优先级排序的仓库地图，而不是让它逐个文件地摸索。

它做什么

一个面向模型的工具，reading_map：

- 按优先级排序的文件列表 —— 配置文件与入口文件优先，源代码先于文档，每个条目包含语言、角色（config / entrypoint / code / other）、行数、大小以及一段有长度限制的预览。配置文件和入口文件会完整保留。
- 诚实的覆盖情况说明 —— 每次运行都会报告存在多少候选文件、保留了多少、跳过了哪些目录，以及哪些文件因过大、二进制、压缩或超出文件数量上限而被丢弃。一份不完整的地图绝不会假装自己完整。
- 确定性 —— 扫描过程从不调用模型。它开销低、速度快，且重放时结果完全一致；当 agent 需要文字描述时，它会根据地图本身进行总结。

排序与跳过启发式规则移植自 RepoWiki 的扫描器，已在数千个仓库上经过实战检验。

安装

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

或从 npm 安装（发布后）：

dsh plugin --profile  add dsh-tool-reading-map

启动该 profile 后，该工具会以内置工具之外的 reading_map 形式出现。

工具参考

| 参数 | 类型 | 必填 | 默认值 | 含义 |
|---|---|---|---|---|
| path | string | 是 | — | 要扫描的仓库根目录的绝对路径。 |
| max_files | number | 否 | 60 | 按优先级排序后保留的文件数（config > entrypoint > code > other）。 |
| preview_lines | number | 否 | 30 | 每个非配置、非入口文件保留的预览行数。 |
| max_file_size | number | 否 | 204800 | 单文件大小上限（字节）；更大的文件会被计为过大并跳过。 |

结果是一个规范的 JSON 值：{ root, coverage: { candidates, kept, skippedDirs, oversizedCount, oversized, binaryCount, minifiedCount, priorityDropped }, files: [...] }，因此它可以与 PTC 模式及其他工具链干净地组合。

哪些内容会被跳过，一张表说明：

| 跳过项 | 检测方式 |
|---|---|
| 依赖 / 构建目录 | node_modules、dist、build、vendor、.venv、target、各类缓存等（参见 src/scanner.ts 中的 SKIP_DIRS） |
| 资源与锁文件/二进制扩展名 | 图片、媒体、归档、字体、编译产物、.map、.min.js、.lock |
| 过大的文件 | 大于 max_file_size（会计数，并列出前三个的名称） |
| 二进制文件 | 前 8 KiB 内出现 NUL 字节 |
| 压缩后的源代码 | 单行超过 1000 个字符，或非空行 ≤5 行且最长行极长 |
| .gitignore 路径 | 根目录 .gitignore 的 glob 模式（按设计不支持否定模式） |

实际输出（针对 RepoWiki 仓库运行）

/path/to/RepoWiki 的阅读地图：保留了 60/78 个候选文件，跳过了 15 个目录，按优先级丢弃了 12 个。
- [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)
… 以及结构化结果中的另外 48 个。

本次运行中跳过的内容（如实说明）：.git、.venv、dist、frontend/node_modules、每个 __pycache__，以及因超出上限而丢弃的 12 个较低优先级文件——全部都在 coverage 中列出，绝不会无声缺失。

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

目录结构：

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

在开发期间，通过补丁覆盖层（绝对路径）从检出目录加载它：
yaml
- insert:
- id: reading-map
name: /absolute/path/to/dsh-tool-reading-map/lib/index.js

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

许可证

MIT