前言¶

在 DSH 的日常使用中，開發者經常要面對三類本地狀態：本機工具鏈是否可用、智能體運行後留下的臨時目錄能不能刪、機器規則 AGENTS.md 改過以後有沒有留底。手動查工具、翻目錄、改規則文件都能做，但缺少一個統一入口，也容易誤刪。

guo6x/dsh-housekeeper 是一個 DSH web profile 插件，把這幾件事集中到 Web GUI 的 Settings → Plugins → 環境管家 中：工具鏈盤點、緩存候選掃描、兩步清理，以及 AGENTS.md 編輯與備份。下面按“先檢查、再計劃、最後確認”的方式介紹它。

這是什麼¶

核心功能¶

下面介紹三類能力：只讀盤點、受控清理、機器規則編輯。

1. 工具鏈盤點¶

插件自動檢測以下工具的位置和版本：

node
pnpm
git
gh
ffmpeg
Edge
Chrome

這一步只做報告，不創建清理計劃、不刪除文件、不修改機器規則。

2. 緩存掃描¶

掃描 .tmp 和緩存目錄後，面板會展示候選目錄的信息：

• 大小
• 文件數
• mtime
• 4000 文件截斷標記
• 30 天未觸碰高亮
• 點擊展開內容預覽

掃描存在 4000 文件上限；如果目錄文件數很多，看到截斷標記時，不要把列表當作完整清單。

3. 兩步清理¶

先選擇你認識的臨時目錄，再生成清理計劃。清理計劃會列出批准路徑和拒絕路徑。確認前不會刪除文件；確認後執行刪除，刪除前再次檢查白名單和 realpath。

白名單規則：

• 只允許項目 .tmp 目錄和 cache-root 直接子項刪除
• 拒絕 .. 逃逸
• 拒絕符號鏈接逃逸
• 拒絕系統路徑
• 刪除前再次檢查 realpath

清理確認 token：

• 一次性
• 五分鐘後過期
• 用於 housekeeper_clean 工具執行清理

4. AGENTS.md 編輯¶

插件可以讀取和編輯機器規則文件 AGENTS.md。保存時自動備份上一版本，並支持一鍵恢復。

已覈實資料中寫明：規則端點只讀寫 $DSH_HOME/AGENTS.md，路徑固定，上限 64KB。資料中另一處出現 ~/.dsh/AGENTS.md，但未說明兩者等價關係，本文不將其作爲確定路徑。

5. Agent 工具¶

插件提供三個工具：

安裝與啓用¶

從 GitHub 安裝¶

dsh plugin --profile web add github:guo6x/dsh-housekeeper

安裝後，重啓正在運行的 dsh web 進程，然後打開：

Settings → Plugins → 環境管家

看到 Toolchain inventory 部分，即安裝完成。

檢查插件是否安裝¶

dsh plugin --profile web list dsh-housekeeper

本地開發安裝¶

在倉庫目錄中運行：

dsh plugin --profile web add .

典型用法¶

先做只讀盤點¶

先打開面板，做一輪不修改系統的檢查：

1、查看檢測到的 node、pnpm、git、gh、ffmpeg、Edge、Chrome 位置和版本。
2、查看 .tmp 與緩存目錄候選項。
3、點擊某一行預覽內容。
4、不選擇目錄、不生成計劃、不刪除文件。

如果用 Agent 做同樣驗證，可以要求：

運行 housekeeper_report，總結檢測到的工具鏈和最大緩存候選；不要創建清理計劃、不要刪除文件、不要修改機器規則。

再做清理計劃¶

當你確認某些臨時目錄可以清理時：

1、只選擇你能識別的臨時目錄。
2、選擇生成清理計劃。
3、閱讀批准路徑與拒絕路徑。
4、使用計劃對應的一次性確認操作執行刪除。

對應的 Agent 流程是：

1、先請求 housekeeper_report。
2、再請求並審閱 housekeeper_plan。
3、確認無誤後，才允許使用返回的一次性 token 調用 housekeeper_clean。

最後編輯機器規則¶

在面板中修改 AGENTS.md，保存後會自動備份上一版本。如果改錯，可以一鍵恢復。注意該端點有 64KB 上限。

配置¶

掃描根按平臺有默認值。已覈實資料中給出 Windows 默認值：

D:\github
D:\environment\cache

這些掃描根可在面板編輯，並通過環境變量覆蓋。本文不列出其他平臺默認值，因爲已覈實事實未提供。

適用場景與注意¶

適合：

• 需要在 DSH web profile 中檢查本機工具鏈的位置與版本
• 需要清理智能體運行後留下的 .tmp 與緩存目錄，但希望先看計劃再刪除
• 需要編輯 AGENTS.md，並保留上一版本備份

注意：

• 插件以當前 dsh 進程權限運行，安裝前應檢查源碼、許可證與本地權限。
• 已覈實事實寫明：無需賬號、API key 或額外服務；路由僅接受 loopback clients；無遙測、無外部網絡調用。
• 清理白名單隻覆蓋項目 .tmp 目錄和 cache-root 直接子項；系統路徑、.. 逃逸和符號鏈接逃逸會被拒絕。
• 清理 token 一次性且五分鐘過期。
• 掃描有 4000 文件上限；被截斷的目錄不能直接當作完整清單。
• AGENTS.md 上限 64KB；已覈實資料中出現 $DSH_HOME/AGENTS.md 和 ~/.dsh/AGENTS.md 兩種寫法，未說明等價關係，使用前請覈對本地環境。

鏈接¶

• GitHub：https://github.com/guo6x/dsh-housekeeper
• 目錄頁 URL 未在已覈實資料中給出，本文不在此列出。