前言¶
DeepSeek Harness (DSH) 采用插件化架构，强调「一切皆插件」。当智能体需要开始编辑一个陌生的代码库时，直接漫无目的地逐个文件读取效率低下且容易遗漏关键信息。dsh-tool-reading-map 插件旨在解决这个问题，它能在编辑前为代理提供一个结构化、按优先级排序的代码库地图，帮助代理快速掌握核心配置与入口点。
插件定位¶
- 名称：
dsh-tool-reading-map - 功能：DSH 代码库阅读地图工具，在智能体编辑代码前提供结构化、优先级排序的地图。
- 维护者：he-yufeng
- 分类：工作流
- 许可证：MIT
核心功能¶
该插件提供名为 reading_map 的工具，具备以下特性：
- 优先级文件列表：扫描结果按优先级排序，顺序为配置文件 > 入口文件 > 源代码 > 其他。每条目包含语言、角色（config/entrypoint/code/other）、行数、大小及有限预览。配置和入口文件保持完整。
- 诚实的覆盖率统计：每次运行都会报告候选文件总数、保留文件数、跳过的目录、因过大/二进制/压缩等原因丢弃的文件。不会假装扫描结果完整。
- 确定性扫描：扫描过程不调用模型，成本低、速度快、可重复执行。智能体可基于生成的地图自行生成摘要文本。
- 配置与入口优先：在排序逻辑中优先处理配置文件和程序入口点。
安装与启用¶
安装前请确保已安装 DSH 并拥有对应 Profile。该插件依赖 @deepseek-ai/dsh-tools (^0.1.5-rc.1)。
dsh plugin --profile <name> add github:he-yufeng/dsh-tool-reading-map
安装完成后，启动 Profile，工具将作为 reading_map 与内置工具并列出现。
工具参数与用法¶
调用 reading_map 工具时，需指定以下参数：
| 参数 | 类型 | 必填 | 默认值 | 含义 |
|---|---|---|---|---|
path |
string | 是 | — | 要扫描的仓库根目录的绝对路径 |
max_files |
number | 否 | 60 | 优先级排序后保留的文件数量 |
preview_lines |
number | 否 | 30 | 非配置、非入口文件每文件保留的预览行数 |
max_file_size |
number | 否 | 204800 | 单文件大小上限（字节），超限文件将被丢弃 |
输出结构¶
工具返回一个规范的 JSON 值，包含 root、coverage（覆盖率统计）和 files（文件列表）字段。
跳过规则¶
插件在扫描时会自动跳过以下内容：
* 依赖与构建目录：如 node_modules、dist、build、vendor、.venv、target、缓存目录等。
* 资源与锁定文件：图片、媒体、压缩包、字体、.map、.min.js、.lock 等。
* 超大文件：超过 max_file_size 的文件。
* 二进制文件：前 8 KiB 包含空字节（NUL）的文件。
* 压缩源码：单行超过 1000 字符，或非空行数 ≤5 且最长行极大的文件。
* .gitignore 路径：根目录 .gitignore 中定义的路径（不支持否定匹配）。
注意事项与生态背景¶
- 权限与风险：插件以当前 DSH 进程的权限运行，请确保来源可信。
- 许可证：代码基于 MIT 许可证开源，可自由使用。
- 来源：该插件源自 RepoWiki 的扫描逻辑与启发式规则。
短结尾¶
dsh-tool-reading-map 为 DeepSeek Harness 提供了在编辑代码前快速建立上下文的能力。通过确定性扫描和诚实的覆盖率报告，它避免了智能体在庞大的代码库中迷失。更多细节请查阅目录页或源码仓库。
