前言¶

在 DSH 裏讓模型理解一個本地倉庫，常見做法是反覆讀目錄、搜文件名或手動貼路徑。倉庫一大，上下文容易被無關文件佔滿，模型也不一定能從散落的 package.json 和入口文件名推斷出結構。dsh-compass 是 LIghtJUNction 維護的 DSH 客戶端插件（npm 包名 @lightjunction/dsh-compass），面向 DSH 0.2.1-rc.2，在宿主機本地工作區掃描文件並暴露兩個工具：codebase_map 彙總文件列表、包信息與候選入口；code_tour 按路徑關鍵詞抽取聲明行，便於在已有地圖版本上做一次輕量「導覽」。它不是 AST 索引、引用搜索或 import 圖，也不替代 Git 或 IDE 的全局導航。

這是什麼¶

一句話：爲 DeepSeek Harness 提供 Repository code maps and navigation——即倉庫級代碼地圖與基於路徑的導覽能力。

維護者與來源：GitHub 倉庫 LIghtJUNction/dsh-compass，社區目錄頁 SkillHub 條目（獨立社區站點，與 DeepSeek / 幻方無官方從屬關係）。許可證 MIT（見倉庫 NOTICE 中對上游的說明）。開發要求 Node >=24；README 寫明本地用 Node 26 / TypeScript 5.9.3 開發與測試，Release CI 配置爲 Node 24。

核心功能¶

插件通過 Cordis bundle 註冊工具，每次調用在 宿主機本地 重新掃描（無持久緩存、無自動 prompt 注入）。

codebase_map¶

• 調用 codebase_map({}) 返回：files、packages（JSON 編碼的包摘要）、候選 entryPoints、revision、規範 root、以及是否 truncated。
• 調用 codebase_map({ expectedRevision: "<previous revision>" }) 若地圖已過期則拒絕，避免在陳舊快照上繼續操作。

包元數據會報告 Node 包名、scripts、依賴名；不會執行 scripts。候選入口包括常見的 index/main/app/server 類文件，以及 Cargo.toml、pyproject.toml、go.mod 等——均爲啓發式，不保證是可執行入口。

code_tour¶

• 調用 code_tour({ topic: "auth", expectedRevision: "<map revision>" })：在受支持的源文件中，路徑 字面包含 auth（忽略大小寫）的文件裏抽取聲明行；結果含路徑、行號及地圖 revision。
• 導覽讀完文件後會再次校驗地圖；若已變化會要求重試。最多訪問 20 個匹配文件，每文件最多 15 條聲明行（每行 240 字符），超出會標記截斷。

掃描與 revision 的含義¶

跳過隱藏項、符號鏈接、node_modules、dist、build、target、coverage、vendor 等目錄；不是 Git-ignore 解析器。掃描在達到 1000 個文件、4000 次訪問條目或目錄深度 8 時停止並報告截斷。畸形或不可讀的 package.json 會使操作失敗，而不是靜默編造包數據。單文件讀取上限 256 KiB。

revision 由文件路徑、大小、mtime/ctime 及 package.json 文本指紋而成，不是全倉庫內容哈希，也不是原子文件系統快照。

聲明行啓發式覆蓋常見 JS/TS、Python、Rust、Go、Java 及 C 系擴展；不支持語義化架構推斷或框架自動識別。

安裝與啓用¶

官方說明從 GitHub Release 安裝已構建的 tgz（README 給出的 URL 爲 v0.1.0 資源位置，是否已發佈需以 Release 頁爲準；安裝時使用同一次 Release 附帶的歸檔與 SHA256SUMS）。

dsh plugin --profile headless add https://github.com/LIghtJUNction/dsh-compass/releases/download/v0.1.0/lightjunction-dsh-compass-0.1.0.tgz
dsh headless --dump-config

包內含 DSH bundle patch 與編譯後的 JavaScript，不需要 Pi 依賴。安裝後需 重啓 DSH。若不用 headless profile，將命令中的 profile 名換成你實際使用的即可。

配置 root¶

默認 bundle 配置爲 {}：各工具使用 調用方智能體的工作目錄。若無智能體的 host 調用，必須在配置裏顯式指定 root。若要把工作區固定到本機某路徑，在 profile 的 cordis.patch.yml 中增加：

- id: dsh-compass
  config:
    root: /absolute/local/project

root 必須已存在，在 DSH 宿主機 上通過 Node 文件系統 API 解析。遠程 DSH world 或 sandbox 不會 重定向這些操作：僅適合 宿主機本地項目 啓用；這不是遠程 world 適配器，也不是安全沙箱。

典型用法¶

README 建議的可復現對話示例：向 DSH 提問——「Map this repository, then show a tour of files under src.」

對應工具鏈大致爲：

1. 先調用 codebase_map({}) 拿到 revision 與結構摘要。
2. 再用 code_tour({ topic: "src", expectedRevision: "<上一步 revision>" })（或你關心的路徑片段作爲 topic）查看匹配路徑下的聲明行。

若兩步之間文件系統發生變化，應重新 codebase_map 並更新 expectedRevision。

適用場景與注意¶

適合誰：在 DSH 智能體循環裏，需要快速給模型一份 受控規模 的倉庫鳥瞰（文件列表、包腳本與依賴名、候選入口），並在不建索引的前提下按路徑關鍵詞看一批聲明行時，可在 可信的本地工作區 啓用本插件。

務必知曉：

• 插件以 當前 DSH 進程權限 讀取本地文件；安裝前應自行審閱源碼與 MIT 許可證，確認路徑邊界策略符合你的安全預期。README 說明對普通符號鏈接重定向、no-follow 打開常規文件等有檢查，但 不能 抵禦惡意進程併發替換祖先目錄；應在可信本地環境使用。目標語義爲 Linux/macOS 風格文件系統，Windows 未驗證。
• 無 Pi TUI onboarding 菜單、無框架/約定自動檢測、無語義化 tour 生成；併發讀支持，dispose 時會中止/排空工作並註銷工具。
• 維護者倉庫開發自檢可運行 npm run check（TypeScript、行爲測試與構建；使用真實 Cordis、DSH ToolRuntime 等，無需 live 模型憑證——見 README）。

結尾¶

dsh-compass 把「先畫一張本地倉庫地圖、再按路徑關鍵詞做有限導覽」收成兩個 DSH 工具，適合在 agent 工作目錄或顯式 root 下做結構化摸底，而不是做全倉庫語義搜索。

• 社區目錄：https://www.skillhub.cn/plugins/LIghtJUNction/dsh-compass
• 源碼與 README：https://github.com/LIghtJUNction/dsh-compass