guo6x/dsh-housekeeper

English · DeepSeek Harness 插件

管住 agent 的脏手：工具链台账、缓存一键清理、机器规则（AGENTS.md）随时改，全在 Web GUI 设置面板里完成。零运行时依赖，一条命令安装。

• 📋 工具链台账 —— 自动探测 node/pnpm/git/gh/ffmpeg/Edge/Chrome 的位置与版本，装了什么一目了然
• 🗑️ 诚实缓存清理 —— 扫描 agent 留下的 .tmp 与缓存目录：大小/文件数/修改时间、4000 文件截断标记、30 天未动高亮、点行展开内容预览，勾选即删
• 🛡️ 白名单保护 —— 只允许删「项目 .tmp」与「缓存根直接子目录」；.. 路径逃逸、符号链接逃逸、系统目录一律拒绝，删除前先 realpath 校验
• 📝 机器规则编辑 + 保命 —— 直接读写 ~/.dsh/AGENTS.md，每次保存自动备份上一版，一键恢复；保存即实时生效
• 🌍 可配置 —— 项目/缓存扫描根目录按平台默认（Windows: D:\github / D:\environment\cache），面板里可改，环境变量可覆盖
• 🤖 agent 工具 —— housekeeper_report（台账+磁盘占用报告）与 housekeeper_clean（走同一白名单，最多 10 路径/次）

安装

dsh plugin --profile web add dsh-housekeeper

重启 dsh web 后，设置 → 插件 → 环境管家。

要求：DSH web profile、Node ≥ 22。

安全模型

• 全部路由仅接受回环地址（非 127.0.0.1/::1 一律 403）
• 清理白名单（满足全部条件才允许删除）：
  • 路径位于 <项目根>\<仓库>\ .tmp\ 之下，或 <缓存根>\ 的直接子目录
  • 规范化后不越过白名单根（拒绝 ..）
  • realpath 后仍落在白名单根内（拒绝符号链接逃逸）
  • 白名单根自身与仓库目录自身不可删
• 规则文件只读写 $DSH_HOME/AGENTS.md 单文件，路径不可参数化
• 无遥测、无网络外呼

原理

GUI 设置页 ──fetch──▶ /housekeeper/state|clean|rules（仅回环）──▶ 宿主插件
                         ├─ 探测：候选路径 + PATH 查找 + 版本
                         ├─ 扫描：按规则走查目录，统计大小（4000 文件上限）
                         ├─ 清理：白名单 + realpath 校验后 rm
                         └─ 规则：读写 $DSH_HOME/AGENTS.md（64KB 上限）

开发

pnpm install
node build.mjs         # esbuild → lib/index.js（宿主 ESM）+ lib/client.js（ModuleLoader 包）
node tests/core.mjs    # 白名单/扫描/清理 21 项沙箱单测（无需真实环境）

MIT 协议。问题与想法请提 issue。