he-yufeng/dsh-tool-reading-map

English | 中文

给 DeepSeek Harness（dsh）写的 reading_map 工具插件：让 agent 在动一个陌生仓库之前，先拿到一份按优先级排好序的仓库结构地图，而不是一个文件一个文件地乱翻。

它做什么

只提供一个模型工具 reading_map，但把三件事做扎实：

• 按优先级排好的文件清单：配置文件和入口文件排最前，源码排在文档前。每个条目带语言、角色（config / entrypoint / code / other）、行数、大小和有上限的预览；配置和入口文件保留全文。
• 老实的覆盖账本：每次都报告候选文件数、实际保留数、跳过了哪些目录、哪些文件因为超大 / 二进制 / 压缩混淆 / 超过文件帽被丢掉。不完整的地图绝不装成完整的。
• 纯确定性：扫描全程不调模型，便宜、快、可重放。想要文字总结，agent 自己看着地图说就行。

排序和跳过启发式移植自 RepoWiki 的 scanner，在几千个真实仓库上磨过。

安装

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

或（发布到 npm 后）：

dsh plugin --profile <name> 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	单文件大小上限（字节），超过记为 oversized 并跳过

返回一个规范 JSON：{ root, coverage: { candidates, kept, skippedDirs, oversizedCount, oversized, binaryCount, minifiedCount, priorityDropped }, files: [...] }，可以直接喂给 PTC 模式或其他工具链。

跳过规则一览：

跳过什么	怎么判
依赖 / 构建目录	node_modules、dist、build、vendor、.venv、target、各类 cache（见 src/scanner.ts 的 SKIP_DIRS）
资源与锁定/二进制扩展名	图片、音视频、压缩包、字体、编译产物、.map、.min.js、.lock
超大文件	超过 max_file_size（计数并给出前三个名字）
二进制文件	前 8 KiB 内出现 NUL 字节
压缩混淆源码	单行超 1000 字符，或非空行 ≤5 且最长行占全文一半以上
.gitignore 覆盖的路径	根目录 .gitignore 的 glob（刻意不支持取反规则）

真实输出（对 RepoWiki 仓库实跑）

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)
… 结构化结果里还有另外 48 条。

本轮跳过（诚实的那部分）：.git、.venv、dist、frontend/node_modules、所有 __pycache__，外加 12 个低优先级文件被容量帽丢弃——全部写进 coverage，绝不静默缺席。

本地开发

npm install
npm run build     # tsc 编译到 lib/
npm test          # vitest

目录结构：

src/
  index.ts    # 插件入口：name / inject / apply
  tool.ts     # reading_map 工具定义
  scanner.ts  # 目录遍历、优先级排序、跳过规则与覆盖账本
test/
  scanner.test.ts

开发期用绝对路径的 patch overlay 直接挂载：

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

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

许可证

MIT