# dsh-tool-reading-map

[English](README.md) | 中文

给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）写的 `reading_map` 工具插件：让 agent 在动一个陌生仓库之前，先拿到一份按优先级排好序的仓库结构地图，而不是一个文件一个文件地乱翻。

## 它做什么

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

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

排序和跳过启发式移植自 [RepoWiki](https://github.com/he-yufeng/RepoWiki) 的 scanner，在几千个真实仓库上磨过。

## 安装

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

或（发布到 npm 后）：

```sh
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 仓库实跑）

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

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

## 本地开发

```sh
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 直接挂载：

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

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

## 许可证

MIT