前言¶
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 提供了在編輯代碼前快速建立上下文的能力。通過確定性掃描和誠實的覆蓋率報告，它避免了智能體在龐大的代碼庫中迷失。更多細節請查閱目錄頁或源碼倉庫。
