前言¶

DeepSeek Harness（DSH）的 Web 界面以對話爲主。做智能體調試時，常常還需要同時查看當前注入的上下文文檔、項目目錄，以及倉庫的 Git 狀態。

dsh-compass 是一個 DSH Web 插件，由 Happy2Git 維護，許可證爲 MIT，Copyright (c) 2026 DeepSeek。它爲 Web 界面新增右側上下文、文件夾面板和 Git 狀態監控，並提供會話日誌下載動作。

需要先說明一點：npm 發佈版 dsh 無法顯示本插件；需要使用 GitHub 源碼構建的 dsh，或作者 fork。

這是什麼¶

dsh-compass 是 DSH 的 Web 插件。它把目錄瀏覽、注入上下文文檔和只讀 Git 提交圖放進 Web 界面右側，並提供會話日誌下載動作。

它適合需要在對話旁邊核對上下文、文件和倉庫狀態的開發者。

核心能力¶

• 爲 Web 界面新增右側上下文、文件夾面板和 Git 狀態監控。
• 目錄瀏覽帶 git 狀態徽章。
• 注入上下文文檔與壓縮歷史流水即時重投影。
• 上下文展示來源標註、實測佔用條與未讀信號。
• 帶邊框的只讀 Git 提交圖與工作區狀態。
• 面板文件拖入對話。
• 會話日誌下載動作。
• 宿主路由僅限迴環。

安裝前提¶

已覈實信息表明：

• npm 發佈版 dsh 無法顯示本插件。
• 上游 master 源碼構建（≥47f9438）可用。
• npm 發佈版不可用。
• 作者 fork 的默認 web profile 已內置同一面板；若改用本包，需要禁用內置面板行。

安裝與啓用¶

本地 clone 安裝¶

先克隆並構建插件：

git clone https://github.com/Happy2Git/dsh-compass.git
cd dsh-compass
pnpm install
pnpm run build

構建完成後，回到 dsh 的啓動目錄，按路徑安裝：

pnpm dsh plugin --profile web add /path/to/dsh-compass

這種安裝隨 clone 生滅：檢出目錄不能刪除或移動。重新執行 pnpm run build 後，重啓 pnpm dsh web 即可生效。

釘 commit 的 git 安裝¶

如果不在本地保留 clone，可以用釘 commit 的 GitHub 安裝方式：

pnpm dsh plugin --profile web add github:Happy2Git/dsh-compass#<commit-sha>

git 安裝通過 prepare 腳本從源碼構建。pnpm ≥10 會攔截構建腳本，需要放行構建後再繼續安裝。

使用固定 commit 可以明確安裝來源。

作者 fork¶

作者 fork 的默認 web profile 已內置同一面板。若改用 dsh-compass 包，需要禁用內置面板行。

啓動與驗證¶

啓動或重啓 Web 服務：

pnpm dsh web

刷新頁面後，覈對右側出現面板。

也可以通過 POST /dir/list 返回 JSON 驗證 host 路由已掛載：

POST /dir/list
Content-Type: application/json

{
  "path": "<fully-qualified-path>"
}

請求體上限 64 KiB，且必須是 application/json；路徑必須完全限定。

典型用法¶

• 在目錄瀏覽中查看文件，並查看帶 git 狀態徽章的條目。
• 在上下文檔查看注入上下文文檔與壓縮歷史流水。
• 使用來源標註、實測佔用條和未讀信號判斷上下文變化。
• 在 Git 面板查看帶邊框的只讀提交圖與工作區狀態。
• 把面板中的文件拖入對話。
• 使用會話日誌下載動作導出日誌。

卸載¶

pnpm dsh plugin --profile web remove dsh-compass

適用場景與注意¶

適合使用 DSH Web 界面，並在開發調試時需要同時查看上下文、目錄和 Git 狀態的智能體開發者。

注意事項：

• 插件以當前 dsh 進程權限運行；安裝前應檢查源碼和 MIT 許可證。
• npm 發佈版 dsh 無法顯示本插件；需要使用 GitHub 源碼構建的 dsh，或作者 fork。
• 上游 master 源碼構建（≥47f9438）可用；npm 發佈版不可用。
• 宿主路由僅限迴環。
• 請求體上限 64 KiB，且必須是 application/json；路徑必須完全限定。
• 面板只讀：git 命令從不寫入，拖入圖片從不復制進工作區。
• 本地 clone 安裝隨 clone 生滅，檢出目錄不能刪除或移動；重新 build 後重啓 pnpm dsh web 生效。
• git 安裝通過 prepare 腳本從源碼構建；pnpm ≥10 會攔截構建腳本，需要放行構建。
• 作者 fork 的默認 web profile 已內置同一面板；改用本包需禁用內置面板行。

結尾¶

dsh-compass 把 DSH Web 界面右側空間用來集中查看上下文、文件和只讀 Git 狀態，並提供會話日誌下載動作。

項目倉庫：https://github.com/Happy2Git/dsh-compass